STARSRedacter / README.md
tanzilhussain's picture
Update README.md
c1ec955 verified
|
Raw History Blame Contribute Delete
6.92 kB

A newer version of the Streamlit SDK is available: 1.67.0

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

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:

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