Make this Space the single home: latest app + engine + CLI

- app.py: BBH branding, experience.usc.edu download instructions, in-memory redaction
- redactors/: canonical engine (PII + grades passes, verify-before-write)
- redact_stars.py: command-line tool (single/batch)
- README: single-home model + what-to-edit-where
- remove Dockerfile + src/ template clutter (Streamlit SDK runs app.py)

Dockerfile

@@ -1,20 +0,0 @@
-FROM python:3.13.5-slim
-
-WORKDIR /app
-
-RUN apt-get update && apt-get install -y \
-    build-essential \
-    curl \
-    git \
-    && rm -rf /var/lib/apt/lists/*
-
-COPY requirements.txt ./
-COPY src/ ./src/
-
-RUN pip3 install -r requirements.txt
-
-EXPOSE 8501
-
-HEALTHCHECK CMD curl --fail http://localhost:8501/_stcore/health
-
-ENTRYPOINT ["streamlit", "run", "src/streamlit_app.py", "--server.port=8501", "--server.address=0.0.0.0"]

README.md

@@ -11,22 +11,54 @@ license: agpl-3.0
 
 # STARS Report Redactor
 
-Student-facing web front end for the Summer Scholars / BBHCourseReg STARS
-redactor. Upload a USC STARS Degree Progress Report PDF; it removes personal
-information (name, ID, address, sport) and grades (replaced with pass/fail
-markers, GPA blanked) **in memory** and returns a redacted copy. The uploaded
-file is never written to disk or stored.
+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
 
-Set a Space **secret** named `APP_PASSPHRASE` to the access phrase. The app
-refuses to run without it.
+Set a Space **secret** named `APP_PASSPHRASE` to the access phrase (Space →
+Settings → Variables and secrets). The app refuses to run without it.
+
+## Run locally
+
+```bash
+pip install -r requirements.txt
+
+# web app:
+streamlit run app.py                 # set APP_PASSPHRASE in your env first
 
-## Contents
+# 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
+```
 
-This Space is a deployment bundle. `app.py` + `requirements.txt` + the
-`redactors/` package (a copy of the canonical package in
-`internal-tools/redaction/redactors/` of the main repo). If the redaction logic
-changes there, re-copy `redactors/` here.
+## Notes
 
-Licensed AGPL-3.0 because it uses MuPDF/PyMuPDF.
+- 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.

app.py

@@ -21,7 +21,7 @@ st.set_page_config(page_title="STARS Report Redactor", page_icon="🛡️",
 
 st.title("🛡️ STARS Report Redactor")
 st.caption("Remove your personal information and grades from a USC STARS "
-           "Degree Progress Report before sharing it with the Summer Scholars team.")
+           "Degree Progress Report before sharing it with the BUAI Builder Hub (BBH).")
 
 with st.expander("What this does and how your file is handled", expanded=True):
     st.markdown(
@@ -34,6 +34,15 @@ with st.expander("What this does and how your file is handled", expanded=True):
         "Please share only if you consent."
     )
 
+with st.expander("How to download your STARS report (PDF)"):
+    st.markdown(
+        "1. Go to **experience.usc.edu** and open **My Academics**.\n"
+        "2. Open your **STARS** (Degree Progress) report.\n"
+        "3. Click the **red Print button** at the top of the report.\n"
+        "4. In the print dialog, set the destination to **Save as PDF** and save the file.\n"
+        "5. Upload that saved PDF below."
+    )
+
 # --- access gate -----------------------------------------------------------
 if not PASSPHRASE:
     st.error("This app isn't configured yet (no access phrase set). "
@@ -41,7 +50,7 @@ if not PASSPHRASE:
     st.stop()
 
 entered = st.text_input("Access phrase", type="password",
-                        help="Provided to you by the Summer Scholars team.")
+                        help="Provided to you by the BBH team.")
 if entered.strip() != PASSPHRASE:
     if entered:
         st.warning("That access phrase isn't right. Please try again.")
@@ -49,10 +58,10 @@ if entered.strip() != PASSPHRASE:
 
 # --- redaction flow --------------------------------------------------------
 consent = st.checkbox(
-    "I consent to share my redacted STARS report with the Summer Scholars team.")
+    "I consent to share my redacted STARS report with the BUAI Builder Hub (BBH).")
 
 uploaded = st.file_uploader(
-    "Upload your STARS report (the PDF you downloaded from my.usc.edu)",
+    "Upload your STARS report (the PDF you saved from experience.usc.edu)",
     type=["pdf"], accept_multiple_files=False)
 
 if uploaded is not None and not consent:
@@ -85,13 +94,14 @@ if uploaded is not None and consent:
 
     elif status == "SKIPPED":
         st.error("This PDF looks like a **scan** (it has no text layer), so it "
-                 "can't be redacted here. Please upload the PDF you download "
-                 "directly from my.usc.edu rather than a scanned/printed copy.")
+                 "can't be redacted here. Please use the PDF you save via the "
+                 "**Print → Save as PDF** steps above on experience.usc.edu, "
+                 "rather than a scanned or photographed copy.")
     else:
         st.error("The redaction could not be fully verified, so **no file was "
                  "produced**. Please contact the team — and do not share the "
                  "original in the meantime.")
 
 st.divider()
-st.caption("Internal tool of the Summer Scholars / BBHCourseReg project. "
+st.caption("Internal tool of the BUAI Builder Hub (BBH) / BBHCourseReg project. "
            "Processing happens in memory; no files are stored.")

redact_stars.py

@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+"""
+redact_stars.py — Bulletproof, structure-faithful redaction for USC STARS
+Degree Progress Reports (single- or double-column, any student).
+
+One tool, two redaction passes, chosen with --redact:
+
+    --redact all      (default)  remove PII *and* redact grades
+    --redact pii                 remove PII only
+    --redact grades              redact grades only
+
+Both passes run on the same in-memory document and are gated by a single
+verification step, so a file is only written once it is proven clean for the
+selected passes.  Output filenames encode the mode so a partial redaction can
+never be mistaken for a complete one:
+
+    all     -> REDACTED_<name>.pdf
+    pii     -> REDACTED-PII_<name>.pdf
+    grades  -> REDACTED-GRADES_<name>.pdf
+
+PII pass:    student ID, roster + diploma name, mailing address, sport/team.
+Grade pass:  each grade -> basis + pass/fail token (Lp/Lf/Pp/Pn); keeps
+             IN/IX, RG, TR, W, CR/NC, flags; neutralizes GPA/POINTS figures.
+
+How it stays faithful & bulletproof: it TRULY removes the target glyphs
+(PyMuPDF apply_redactions) and re-inserts width-preserving monospace filler, so
+the fixed-width columns are preserved and the originals are gone — not covered.
+
+Usage:
+  python3 redact_stars.py INPUT.pdf [-o OUT] [--redact all|pii|grades]
+                                    [--dry-run] [--tag]
+  python3 redact_stars.py FOLDER    [-o OUT_FOLDER] [--redact ...]
+"""
+import argparse
+import os
+import re
+import sys
+
+try:
+    import fitz  # PyMuPDF
+except ImportError:
+    sys.exit("PyMuPDF is required:  pip install pymupdf --break-system-packages")
+
+from redactors import common, pii, grades, engine
+
+MODE_PREFIX = {
+    frozenset({"pii", "grades"}): "REDACTED_",
+    frozenset({"pii"}): "REDACTED-PII_",
+    frozenset({"grades"}): "REDACTED-GRADES_",
+}
+
+
+def _default_out(in_path, modes, out_dir=None):
+    base = os.path.basename(in_path)
+    base = re.sub(r"^DONOTSHARE[_-]*", "", base, flags=re.IGNORECASE)
+    base = re.sub(r"^REDACTED[A-Z-]*_", "", base, flags=re.IGNORECASE)  # no stacking
+    total = engine.existing_modes(in_path) | set(modes)   # cumulative state
+    d = out_dir if out_dir else os.path.dirname(in_path)
+    return os.path.join(d, MODE_PREFIX[frozenset(total)] + base)
+
+
+def process_one(in_path, out_path, modes, tag=False):
+    """Redact one report for the selected passes (file in -> file out). Returns
+    a status dict and NEVER writes a file that fails verification."""
+    doc = fitz.open(in_path)
+    try:
+        res = engine.redact_doc(doc, modes, tag=tag,
+                                existing=engine.existing_modes(in_path))
+        res["file"] = in_path
+        res["out"] = out_path
+        res["modes"] = modes
+        if res["status"] in ("REDACTED", "REVIEW"):
+            doc.save(out_path, garbage=4, deflate=True, clean=True)
+    finally:
+        doc.close()
+    return res
+
+
+def _print_one(res):
+    print(f"\n=== {os.path.basename(res['file'])}  [{'+'.join(sorted(res['modes']))}] ===")
+    for k, v in res.get("pii", {}).items():
+        print(f"  {k:24s}: {v!r}")
+    if res.get("pii_note"):
+        print(f"  {res['pii_note']}")
+    if res.get("grades"):
+        g = res["grades"]
+        print(f"  grades redacted: {g['grades_replaced']}  |  "
+              f"GPA/POINTS figures: {g['gpa_replaced']}  |  "
+              f"course rows seen: {g['course_rows']}")
+    label = {"REDACTED": "OK (verified clean)", "REVIEW": "OK — needs human review",
+             "SKIPPED": "SKIPPED", "FAILED": "FAILED"}[res["status"]]
+    print(f"  -> {label}: {res['reason'] or res['out']}")
+    for tok, pages in res["fragments"]:
+        print(f"     review: name fragment {tok!r} still appears on page(s) {pages}")
+    for h in res.get("hard", []):
+        print(f"     !! {h}")
+
+
+def run_batch(in_dir, out_dir, modes, tag=False):
+    os.makedirs(out_dir, exist_ok=True)
+    results = []
+    for name in sorted(os.listdir(in_dir)):
+        if not name.lower().endswith(".pdf"):
+            continue
+        if name.upper().startswith("REDACTED_"):   # already fully redacted -> skip
+            continue
+        src = os.path.join(in_dir, name)
+        try:
+            r = process_one(src, _default_out(src, modes, out_dir), modes, tag=tag)
+        except Exception as e:      # unexpected -> report, keep going
+            r = {"file": src, "modes": modes, "status": "FAILED",
+                 "reason": f"error: {e}", "pii": {}, "grades": {},
+                 "fragments": [], "hard": []}
+        _print_one(r)
+        results.append(r)
+
+    order = ["REDACTED", "REVIEW", "SKIPPED", "FAILED"]
+    counts = {s: sum(1 for r in results if r["status"] == s) for s in order}
+    print("\n" + "=" * 60 + "\nBATCH SUMMARY  [redact: " + "+".join(sorted(modes)) + "]")
+    for s in order:
+        print(f"  {s:9s}: {counts[s]}")
+    print(f"  outputs in: {out_dir}")
+    return results
+
+
+def _dry_run(path, modes):
+    d = fitz.open(path)
+    if not common.has_text_layer(d):
+        print("No text layer (scanned image) — not viable for this tool.")
+        return
+    if "pii" in modes:
+        values = pii.detect(d)
+        print("Detected identifiers:" if values else "No identifiers detected.")
+        for k, v in values.items():
+            print(f"  {k:24s}: {v!r}")
+    if "grades" in modes:
+        _, gm = grades.build_findings(d)
+        print(f"Grades to redact: {gm['grades_replaced']}  |  "
+              f"GPA/POINTS figures: {gm['gpa_replaced']}  |  "
+              f"course rows: {gm['course_rows']}")
+
+
+def main():
+    ap = argparse.ArgumentParser(
+        description="Bulletproof redaction of USC STARS report(s): PII and/or grades.")
+    ap.add_argument("input", help="a STARS report PDF, or a folder of them")
+    ap.add_argument("-o", "--output",
+                    help="output file (single) or output folder (batch)")
+    ap.add_argument("--redact", choices=["all", "pii", "grades"], default="all",
+                    help="what to redact (default: all = PII + grades)")
+    ap.add_argument("--dry-run", action="store_true",
+                    help="print what would be redacted and exit (writes nothing)")
+    ap.add_argument("--tag", action="store_true",
+                    help="use [REDACTED-*] labels instead of X filler for PII")
+    args = ap.parse_args()
+
+    modes = {"pii", "grades"} if args.redact == "all" else {args.redact}
+
+    if os.path.isdir(args.input):
+        out_dir = args.output or os.path.join(args.input, "REDACTED")
+        run_batch(args.input, out_dir, modes, tag=args.tag)
+        return
+
+    if args.dry_run:
+        _dry_run(args.input, modes)
+        return
+
+    res = process_one(args.input, args.output or _default_out(args.input, modes),
+                      modes, tag=args.tag)
+    _print_one(res)
+    if res["status"] == "FAILED":
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

src/streamlit_app.py

@@ -1,40 +0,0 @@
-import altair as alt
-import numpy as np
-import pandas as pd
-import streamlit as st
-
-"""
-# Welcome to Streamlit!
-
-Edit `/streamlit_app.py` to customize this app to your heart's desire :heart:.
-If you have any questions, checkout our [documentation](https://docs.streamlit.io) and [community
-forums](https://discuss.streamlit.io).
-
-In the meantime, below is an example of what you can do with just a few lines of code:
-"""
-
-num_points = st.slider("Number of points in spiral", 1, 10000, 1100)
-num_turns = st.slider("Number of turns in spiral", 1, 300, 31)
-
-indices = np.linspace(0, 1, num_points)
-theta = 2 * np.pi * num_turns * indices
-radius = indices
-
-x = radius * np.cos(theta)
-y = radius * np.sin(theta)
-
-df = pd.DataFrame({
-    "x": x,
-    "y": y,
-    "idx": indices,
-    "rand": np.random.randn(num_points),
-})
-
-st.altair_chart(alt.Chart(df, height=700, width=700)
-    .mark_point(filled=True)
-    .encode(
-        x=alt.X("x", axis=None),
-        y=alt.Y("y", axis=None),
-        color=alt.Color("idx", legend=None, scale=alt.Scale()),
-        size=alt.Size("rand", legend=None, scale=alt.Scale(range=[1, 150])),
-    ))