Spaces:
Sleeping
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
6.92 kB
| 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 `<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: | |
| ```bash | |
| 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](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. | |