STARSRedacter / README.md
tanzilhussain's picture
Update README.md
c1ec955 verified
|
Raw History Blame Contribute Delete
6.92 kB
---
title: Eclipse - STARS Redactor
emoji: ๐ŸŒ™
colorFrom: red
colorTo: gray
sdk: streamlit
app_file: app.py
pinned: false
license: agpl-3.0
---
# STARS Report Redactor
Web tool for the **BUAI Builder Hub (BBH) / BBHCourseReg** project. A student
uploads their USC STARS Degree Progress Report PDF; it removes personal
information (name, ID, address, sport) and grades (each grade replaced with a
pass/fail marker, GPA figures blanked) **entirely in memory** and returns a
redacted copy. The uploaded file is never written to disk or stored.
**This repository is the single home for the redaction tool**: the web app,
the redaction engine, and the command-line tool all live here together. Pushing
to this repo automatically rebuilds and redeploys the live Space.
## What to edit where
| File / folder | What it is | Edit it for |
|---|---|---|
| `app.py` | the Streamlit web UI | look & wording of the web app |
| `redactors/` | the redaction engine | redaction logic / behavior |
| `redact_stars.py` | the command-line tool (batch/single) | CLI features |
| `admin/` | admin tools, run locally, never by the Space | deletion requests |
| `DELETION.md` | why + how to fully delete a student's report | deletion policy |
| `requirements.txt` | Python dependencies | adding a package |
| `README.md` | this file (the top YAML configures the Space) | docs / Space config |
Deploying is automatic: commit and `git push` to this repo, and the Space
rebuilds. There are no copies to keep in sync.
## Configuration
**Space secrets** (Space โ†’ Settings โ†’ Variables and secrets):
| Secret | Purpose |
|---|---|
| `APP_PASSPHRASE` | access phrase; the app refuses to run without it |
| `HF_TOKEN` | Write token to the submissions dataset; enables the Submit button |
| `SUBMISSIONS_REPO` | *(optional)* override the default dataset repo id |
**Editable constants** (top of `app.py`; temporary values, update in one place
if they change):
| Constant | Current value | Used for |
|---|---|---|
| `CONTACT_EMAIL` | `buaibuilderhub@gmail.com` | general questions shown in the app |
| `DELETE_FORM_URL` | a Google Form link | students' "delete my report" requests |
| `SUBMISSIONS_REPO` | `buai-builder-hub/redacted-stars-submissions` | where submissions are stored |
## Upload guardrails
The app takes files from the public internet, so an upload has to clear several
checks before it is redacted. All three are constants at the top of `app.py`,
and each produces a plain-language message telling the student what to do next.
| Constant | Value | Rejects | Checked |
|---|---|---|---|
| `ALLOWED_UPLOAD_EXTENSIONS` | `.pdf` | a file that isn't named like a PDF | in `app.py`, on the filename |
| `PDF_MAGIC` | `%PDF-` | a file *renamed* to `.pdf` that isn't one | in `app.py`, in the first 1 KB of the bytes |
| `MAX_UPLOAD_MB` | 10 MB | a file far bigger than any report | in `app.py`, before the bytes reach the engine |
| `MAX_PAGES` | 15 pages | a document far longer than a report | in `engine.redact_bytes`, before any redaction work |
| `MAX_PROCESSING_SECONDS` | 30 s | a file that is pathologically slow to process | between pages and passes, during redaction |
PDFs are the only accepted type, and that is checked twice: the uploader filters
on the filename, and the app then looks for the `%PDF-` header in the actual
bytes, so a file of any other kind renamed to `.pdf` is still refused.
The size values are deliberately generous. A real STARS report is a text PDF of
about five pages, usually well under 1 MB, and redacts in one to two seconds,
so a legitimate student has roughly an order of magnitude of headroom on every
limit, while a file that is none of those things is refused cheaply.
The engine *enforces* limits but never *chooses* them: `redact_bytes` takes
`max_pages` and `time_limit` and defaults both to off. The hosted app passes
real values; `redact_stars.py` passes none, because an admin running a local
batch is not a denial-of-service risk.
## Run locally
```bash
pip install -r requirements.txt
# web app:
streamlit run app.py # set APP_PASSPHRASE in your env first
# command line (single file, folder batch, or preview):
python redact_stars.py report.pdf # PII + grades
python redact_stars.py a_folder/ -o out/ # batch
python redact_stars.py report.pdf --redact pii # PII only
python redact_stars.py report.pdf --dry-run # show, write nothing
```
## Submissions
On "Submit," the app saves the **redacted** file to a private HF Dataset
(`buai-builder-hub/redacted-stars-submissions`) as `<ID>.pdf` and shows the
student that ID. Enabled by Space secrets `HF_TOKEN` (a Write token) and,
optionally, `SUBMISSIONS_REPO`.
The report ID is **32 hex characters** (16 random bytes from `secrets`, set by
`REPORT_ID_BYTES` in `app.py`). It is a bearer token in the coat-check sense:
the only thing linking a student to their stored report, and the only thing
needed to request its deletion, so it is sized to make both guessing a valid ID
and a collision between two students infeasible. The app shows it in a
copy-to-clipboard box, and it is also in the downloaded filename
(`REDACTED_<ID>.pdf`) so a student has a second copy.
## Deleting a report
A student can request deletion with their report ID. Because the dataset is
version-controlled, removing the file is **not** enough on its own; the earlier
commit still holds it. Use the admin script, which deletes the file *and* purges
the history:
```bash
export HF_TOKEN=hf_... # a WRITE token
python admin/purge_submission.py <REPORT_ID> --dry-run # preview
python admin/purge_submission.py <REPORT_ID> # do it
```
**[DELETION.md](DELETION.md) has the full rationale, the usage details, and what
the purge costs.** Read it before running the script for the first time.
## Maintenance TODO
- **Replace the contact placeholder** (`CONTACT_EMAIL` in `app.py`) with the real
BBH inbox once it exists, since the deletion ID needs somewhere to go.
## Notes
- Redaction is not perfect anonymization: major, terms, and the course list
remain, which can be identifying in a small program. This is disclosed to
students in the app before they consent.
- The redaction passes are anchored to the STARS template, so they find the
fields the report is *designed* to carry and nothing else. `redactors/residual.py`
additionally scans the redacted text for an email address, phone number, or
labelled date of birth and shows anything it finds to the student as a
"please double-check this" note. It is **advisory only**: it never blocks,
alters, or withholds the file; a person makes the final call.
- Scanned/image-only PDFs have no text layer and are skipped (they can't be
redacted here); use the PDF saved from experience.usc.edu.
- Licensed AGPL-3.0 because it uses MuPDF/PyMuPDF.