README.md

---
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

```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`.

## 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.