Spaces:
Sleeping
Download README.md from buai-builder-hub/STARSRedacter: direct link, hf CLI and curl.
- Browser
- Download file 6.92 kB
-
https://huggingface.co/spaces/buai-builder-hub/STARSRedacter/resolve/main/README.md
- Command line
-
hf download hf://spaces/buai-builder-hub/STARSRedacter/README.md
-
curl -L -o README.md https://huggingface.co/spaces/buai-builder-hub/STARSRedacter/resolve/main/README.md
A newer version of the Streamlit SDK is available: 1.67.0
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_EMAILinapp.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.pyadditionally 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.