--- 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 `.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_.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 --dry-run # preview python admin/purge_submission.py # 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.