README.md

metadata

title: STARS Report 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
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

Run locally

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.

Maintenance TODO

• Admin "delete + purge by ID" script. Students can request deletion by their report ID. Removing <ID>.pdf from the dataset takes it out of the current tree, but the blob remains in git history until purged. Build a small admin script that deletes the file and rewrites/purges history (or uses super_squash_history) so a deletion request is fully honored.
• Replace the contact placeholder (CONTACT in app.py) with the real BBH inbox once it exists — 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.
• 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.