Update app.py

.gitattributes

@@ -33,3 +33,7 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+explanationSS1.png filter=lfs diff=lfs merge=lfs -text
+explanationSS2.png filter=lfs diff=lfs merge=lfs -text
+explanationSS3.png filter=lfs diff=lfs merge=lfs -text
+exampleRedactedStars.pdf filter=lfs diff=lfs merge=lfs -text

app.py

@@ -3,10 +3,21 @@ Streamlit front end for the STARS report redactor (student-facing).
 
 Privacy design: the uploaded PDF is redacted entirely IN MEMORY via
 `engine.redact_bytes` and is never written to the server's disk. Only the
-redacted copy is offered back to the student for download; nothing is stored.
+redacted copy is offered back to the student for download; nothing is stored
+unless the student explicitly chooses to submit it to BBH.
 
 Deployment: Hugging Face Space (Streamlit SDK). Set a Space secret named
 APP_PASSPHRASE to the access phrase before going live.
+
+Page layout (top to bottom):
+    1) What is BBH, and why are we doing this
+    2) Access code
+    3) Screenshots - what we keep / don't keep
+    4) Link to a full sample redacted STARS report
+    5) Try it yourself - upload & see
+    6) Consent form check (only required to SHARE your redacted copy)
+    7) Your code (shown after you submit)
+    8) Removal link
 """
 import os
 import uuid
@@ -23,6 +34,18 @@ DELETE_FORM_URL = (                                 # "delete my report" request
     "https://docs.google.com/forms/d/e/"
     "1FAIpQLScSpM1ov0dMEXhT3hHhsWmIByu-j1myQYnNvRv7C0FNUW81eg/viewform"
 )
+# TODO: swap in the real link once you have a sample redacted STARS report to
+# point to. Leaving this as a placeholder for now — st.link_button below opens
+# it in a new tab automatically, no extra wiring needed once the URL is real.
+SAMPLE_REPORT_URL = "https://example.com/TODO-sample-redacted-stars-report"
+
+# TODO: drop your screenshot files into an `images/` folder in this Space repo
+# (next to app.py) and update the filenames/captions below. Add or remove rows
+# as needed — the layout adapts to however many images are listed here.
+KEEP_DONT_KEEP_IMAGES = [
+    ("images/what_we_keep.png", "What stays in your redacted report"),
+    ("images/what_we_dont_keep.png", "What gets stripped out before anything is stored"),
+]
 
 # --- submission storage (a private HF Dataset in the org) -------------------
 # In-app submission switches on automatically once these Space secrets are set:
@@ -68,10 +91,12 @@ st.markdown(
     html, body, [class*="css"], .stMarkdown, p, li { font-family: 'Inter', system-ui, sans-serif; }
     h1, h2, h3 { font-family: 'Newsreader', Georgia, serif !important; color: #990000; letter-spacing: .2px; }
     h1 { border-bottom: 3px solid #FFCC00; padding-bottom: .35rem; }
-    .stButton > button, .stDownloadButton > button {
+    .stButton > button, .stDownloadButton > button, .stLinkButton > a {
         background-color: #990000; color: #ffffff; border: 0; font-weight: 600; border-radius: 8px;
     }
-    .stButton > button:hover, .stDownloadButton > button:hover { background-color: #7a0000; color: #FFCC00; }
+    .stButton > button:hover, .stDownloadButton > button:hover, .stLinkButton > a:hover {
+        background-color: #7a0000; color: #FFCC00;
+    }
     div[data-testid="stExpander"] { border: 1px solid #ece2cc; border-radius: 8px; }
     div[data-testid="stExpander"] summary { font-weight: 600; color: #990000; }
     </style>
@@ -95,22 +120,64 @@ st.markdown(
     unsafe_allow_html=True,
 )
 
-# ---------------------------------------------------------------- the ask ----
-st.title("Help us build better tools for USC students")
+# ============================================================================
+# 1) WHAT IS BBH, AND WHY ARE WE DOING THIS
+# ============================================================================
+st.title("Please Share Your STARS Report to Support Our Student Tool!")
 
 st.markdown(
-    "BBH (the **BUAI Builder Hub**) is hard at work building tools to make "
-    "**degree planning, course registration, and picking classes** way less of "
-    "a headache. One thing we all agree on: actually **making sense of your "
-    "STARS report** is a pain.\n\n"
-    "**You can help.** We're putting together a set of STARS reports to build "
-    "against. Upload yours below — we'll strip out the sensitive "
-    "stuff (**your name, address, student ID, and grades**) right here, and only "
-    "ever keep the **redacted** version."
+    "**BUAI Builder Hub** is working on creating tools to support students in "
+    "**degree planning, course registration, and picking classes**. We need your "
+    "help sourcing STARS reports to test against our tool!\n\n"
+    "It takes 2 minutes. Upload your STARS report and we'll strip out all "
+    "sensitive info."
 )
 
-# ------------------------------------------------------------------- Q & A ----
-st.subheader("Quick questions you might have")
+# A skimmable recap for anyone who won't read every section below.
+with st.container(border=True):
+    st.markdown("**📌 TL;DR**")
+    st.markdown(
+        "- Your **name, USC ID, address, grades, and GPA** are never stored — "
+        "only a de-identified copy, and only if you choose to share it.\n"
+        "- Only **BBH student developer teams** can ever access it. Private, "
+        "access-controlled, never sold or made public.\n"
+        "- You can **try the tool and see your redacted file first** — sharing "
+        "it with BBH is a separate, optional step.\n"
+        "- Changed your mind later? You can request that we **delete your report** "
+        "anytime using the code we give you.\n"
+        "- Takes about **two minutes**, start to finish."
+    )
+
+# ============================================================================
+# 2) ACCESS CODE
+# ============================================================================
+if not PASSPHRASE:
+    st.error("This app isn't set up yet (no passphrase configured). Ping the team.")
+    footer()
+    st.stop()
+
+st.markdown("### Enter your access code")
+entered = st.text_input("Passphrase", type="password")
+st.caption("If you're a USC student using this, whoever referred you should've "
+           "shared a passphrase.")
+if entered.strip() != PASSPHRASE:
+    if entered:
+        st.warning("Hmm, that's not it — double-check with whoever sent you here.")
+    footer()
+    st.stop()
+
+# ============================================================================
+# 3) SCREENSHOTS — WHAT WE KEEP & DON'T KEEP
+# ============================================================================
+st.markdown("### What we keep — and what we don't")
+
+cols = st.columns(len(KEEP_DONT_KEEP_IMAGES))
+for col, (path, caption) in zip(cols, KEEP_DONT_KEEP_IMAGES):
+    with col:
+        try:
+            st.image(path, caption=caption, use_container_width=True)
+        except Exception:
+            st.info(f"(Add `{path}` to the Space repo to show this screenshot.)")
 
 with st.expander("Wait — are my grades going in a database?"):
     st.markdown(
@@ -126,27 +193,22 @@ with st.expander("Who actually sees my report?"):
         "the USC student experience. Your redacted report is kept somewhere "
         "**private and access-controlled** (not public, never for sale), and used "
         "only to build and test those tools. Whoever works with it agrees not to "
-        "try to figure out who anyone is. (See the consent box below for the "
-        "honest caveat on why we still can't *totally* promise anonymity.)"
+        "try to figure out who anyone is. (See the consent section further down "
+        "for the honest caveat on why we still can't *totally* promise anonymity.)"
     )
 
-with st.expander("I changed my mind — can you delete my report?"):
-    st.markdown(
-        "Totally fine — we get it! When you submit, we give you a **report ID**. "
-        f"Pop it into [this quick form]({DELETE_FORM_URL}) and we'll remove your "
-        "report.\n\n"
-        "⚠️ **Save that ID somewhere safe.** Your report is stored with **no name "
-        "attached**, so the ID is the *only* way we can find it. If you lose it, we "
-        "won't be able to delete your report."
-    )
+# ============================================================================
+# 4) LINK TO A FULL SAMPLE REDACTED STARS REPORT
+# ============================================================================
+st.markdown("### See a full example")
+st.markdown("Curious what a finished redacted report actually looks like end to end?")
+st.link_button("📄 View a sample redacted STARS report", SAMPLE_REPORT_URL)
+st.caption("Opens in a new tab.")
 
-with st.expander("Why should I bother?"):
-    st.markdown(
-        "You'd be helping build tools that make planning your degree and getting "
-        "into the classes you need way less painful — for you *and* everyone after "
-        "you. It takes about two minutes, and your personal info and grades get "
-        "stripped out before anything is stored. That's it."
-    )
+# ============================================================================
+# 5) TRY IT YOURSELF — UPLOAD & SEE
+# ============================================================================
+st.markdown("### Try it yourself")
 
 with st.expander("How do I even get my STARS report?"):
     st.markdown(
@@ -158,81 +220,20 @@ with st.expander("How do I even get my STARS report?"):
         "or scan won't work.)"
     )
 
-st.markdown("### Ready? Let's do it 👇")
-
-# --------------------------------------------------------------- pass gate ----
-if not PASSPHRASE:
-    st.error("This app isn't set up yet (no passphrase configured). Ping the team.")
-    footer()
-    st.stop()
-
-entered = st.text_input("Passphrase", type="password")
-st.caption("If you're a USC student using this, whoever referred you should've "
-           "shared a passphrase.")
-if entered.strip() != PASSPHRASE:
-    if entered:
-        st.warning("Hmm, that's not it — double-check with whoever sent you here.")
-    footer()
-    st.stop()
-
-# ------------------------------------------------------- consent + upload ----
-with st.expander("📋 Please read this before you upload  —  what you're agreeing to",
-                 expanded=True):
-    st.markdown(
-        "- **This is totally voluntary.** You don't have to do it, and you can "
-        "close this page anytime. No penalty, no hard feelings.\n"
-        "- **What we keep:** only the **redacted** version of your STARS report — "
-        "the file this tool hands back after removing your personal info.\n"
-        "- **What's removed before anything is stored:** your **name, USC ID, "
-        "mailing address, sport/team**, every **letter grade** (each becomes a "
-        "simple pass/fail marker), and your **GPA**.\n"
-        "- **What stays in the file:** your **major/minor, the courses and terms "
-        "on your record, and your degree-progress details** — that's the part "
-        "we're actually building with.\n"
-        "- **Can people tell it's you?** We want to be upfront: possibly. We "
-        "remove your name, ID, grades, and GPA, but we **keep your major(s), "
-        "minor, and the list of classes you've taken** — that's the part we build "
-        "with. If your combination is unusual (say you're the only person at USC "
-        "double-majoring in BUAI and Anthropology), someone who sees the file "
-        "could figure out it's yours. They still **won't** see your grades, GPA, "
-        "or student ID — but they might know the report belongs to you. Only share "
-        "if you're okay with that.\n"
-        "- **Your original file never sticks around.** It's handled right here in "
-        "the page's memory, **never written to disk**, and **automatically "
-        "discarded the moment you close this tab**. If you hit **Submit**, we save "
-        "**only the redacted copy** to a **private BBH archive**, tagged with a "
-        "random ID we show you (keep it — that's how you can ask us to delete your "
-        "report later). We never keep your original.\n"
-        "- **How we use it:** to build and test tools that help USC students plan "
-        "degrees and register for classes, and — because it's de-identified — "
-        "possibly for research about the student experience. We won't sell it or "
-        "try to identify you.\n"
-        f"- **Changed your mind later?** It's your record and your call — you can "
-        f"ask us to delete your redacted report anytime via our "
-        f"[deletion form]({DELETE_FORM_URL}), using the report ID we give you at "
-        "submission. Because we store it with **no name attached**, that ID is the "
-        "only way to find your file, so please keep it — if it's lost, we can't "
-        "identify your report to delete it."
-    )
-
-consent = st.checkbox(
-    "I've read the above and I'm good with sharing my **redacted** STARS report.")
-
 uploaded = st.file_uploader(
     "Upload your STARS report (the PDF you saved from experience.usc.edu)",
     type=["pdf"], accept_multiple_files=False)
 st.caption("🔒 Your upload is handled in memory only and is discarded the moment "
-           "you close this tab.")
+           "you close this tab. You can preview and download your redacted file "
+           "below — to share it, you must click submit further down the page.")
 
-if uploaded is not None and not consent:
-    st.info("Check the consent box above and you're good to go.")
-
-if uploaded is not None and consent:
+if uploaded is not None:
     # Redact ONCE per uploaded file and cache the exact result. Streamlit reruns
-    # the whole script on every click, so without caching, clicking Submit would
-    # re-run redaction and upload a freshly-recomputed file — not the same bytes
-    # the student downloaded and reviewed. One redaction, one UID, reused for the
-    # download filename and the database submission so they always match.
+    # the whole script on every click, so without caching, checking the consent
+    # box or clicking Submit would re-run redaction and upload a freshly
+    # -recomputed file — not the same bytes the student downloaded and reviewed.
+    # One redaction, one UID, reused for the download filename and the database
+    # submission so they always match.
     file_key = getattr(uploaded, "file_id", None) or f"{uploaded.name}:{uploaded.size}"
     if st.session_state.get("uid_key") != file_key:
         with st.spinner("Scrubbing your info…"):
@@ -244,6 +245,7 @@ if uploaded is not None and consent:
         st.session_state["uid"] = uuid.uuid4().hex[:8].upper()
         st.session_state["res"] = res
         st.session_state["out"] = out
+        st.session_state["submitted"] = False
 
     res = st.session_state["res"]
     out = st.session_state["out"]
@@ -265,33 +267,9 @@ if uploaded is not None and consent:
         st.download_button("⬇️ Download my redacted report", data=out,
                            file_name=f"REDACTED_{uid}.pdf",
                            mime="application/pdf")
-        st.caption(f"Saved as `REDACTED_{uid}.pdf` — that code is your report ID. "
-                   "Open it to check it looks right, then submit below.")
-
-        st.divider()
-        if _submissions_enabled():
-            st.markdown("**Share it with BBH**")
-            if st.button("📤 Submit my redacted report"):
-                try:
-                    _upload_submission(out, uid)
-                    st.success("Submitted — thank you so much! 🎉")
-                    st.warning(
-                        f"**Your report ID is `{uid}`.**\n\n"
-                        "**Save this now** (screenshot it, write it down — whatever "
-                        "works). Your report is stored with **no name attached**, so "
-                        "this ID is the **only** way to delete it later. If you lose "
-                        "it, we can't find your report to remove it."
-                    )
-                    st.markdown(
-                        f"Changed your mind? Fill out our "
-                        f"[deletion form]({DELETE_FORM_URL}) with this ID.")
-                except Exception:
-                    st.error("Submission didn't go through — sorry! Your redacted "
-                             "file is still available above; please try submitting "
-                             "again in a moment.")
-        else:
-            st.caption("Direct submission is unavailable right now — you can still "
-                       "download your redacted file above.")
+        st.caption(f"Saved as `REDACTED_{uid}.pdf` — take a look and make sure it "
+                   "looks right. Sharing it with BBH is a separate, optional step "
+                   "below.")
 
     elif status == "SKIPPED":
         st.error("This looks like a **scan or photo** (no text in it), so it can't "
@@ -310,4 +288,101 @@ if uploaded is not None and consent:
                  f"better safe than sorry. Please email {CONTACT_EMAIL}, and "
                  "don't share the original in the meantime.")
 
-footer()
+# ============================================================================
+# 6) CONSENT FORM CHECK — only needed to SHARE your redacted copy with BBH
+# ============================================================================
+have_valid_redaction = bool(
+    uploaded is not None
+    and st.session_state.get("out")
+    and st.session_state.get("res", {}).get("status") in ("REDACTED", "REVIEW")
+)
+
+if have_valid_redaction:
+    st.markdown("### Want to share it with BBH?")
+    st.caption("Totally optional — you've already got your redacted file above. "
+               "This part is only about whether you'd like to contribute a copy "
+               "to BBH's project.")
+
+    with st.expander("Sharing Consent Acknowledgement", expanded=True):
+        st.markdown(
+            "- **Submitting is voluntary.** You don't have to do it, and you can "
+            "close this page anytime.\n"
+            "- **What we'd keep:** only the **redacted** version of your STARS "
+            "report — the file this tool just handed you after removing your "
+            "personal info.\n"
+            "- **What's removed before anything is stored:** your **name, USC ID, "
+            "mailing address, sport/team**, every **letter grade** (each becomes a "
+            "simple pass/fail marker), and your **GPA**.\n"
+            "- **What stays in the file:** your **major/minor, the courses and "
+            "terms on your record, and your degree-progress details**.\n"
+            "- **Identifiability:** We remove your name, ID, grades, and GPA, but "
+            "we **keep your major(s), minor, and the list of classes you've "
+            "taken**. If your combination is unusual (e.g. the only USC student "
+            "double-majoring in BUAI and Anthropology), someone who sees the file "
+            "could figure out it's yours. They still **won't** see your grades, "
+            "GPA, or student ID.\n"
+            "- **Your original file is never saved.** It's handled right here in "
+            "the page's memory, **never written to disk**, and **automatically "
+            "discarded the moment you close this tab**. If you submit, we save "
+            "**only the redacted copy** to a **private BBH archive**, tagged with "
+            "a random code we show you. You can use this code to request that "
+            "your report be removed anytime.\n"
+            "- **How we use it:** to build and test tools that help USC students "
+            "plan degrees and register for classes, and — because it's "
+            "de-identified — possibly for research about the student experience. "
+            "We won't sell it or try to identify you.\n"
+            "- **Want to remove your report?** You can ask us to delete your "
+            "redacted report anytime, using the code we give you at submission."
+        )
+
+    consent = st.checkbox(
+        "I've read the above and I consent to sharing my **redacted** STARS "
+        "report with BBH.")
+
+    if not consent:
+        st.info("Check the box above if you'd like to submit your redacted copy.")
+    else:
+        st.markdown("**Share it with BBH**")
+        if _submissions_enabled():
+            if st.button("📤 Submit my redacted report"):
+                try:
+                    _upload_submission(st.session_state["out"], st.session_state["uid"])
+                    st.session_state["submitted"] = True
+                    st.success("Submitted — thank you so much! 🎉")
+                except Exception:
+                    st.error("Submission didn't go through — sorry! Your redacted "
+                             "file is still available above; please try submitting "
+                             "again in a moment.")
+        else:
+            st.caption("Direct submission is unavailable right now — you can still "
+                       "download your redacted file above.")
+
+# ============================================================================
+# 7) YOUR CODE
+# ============================================================================
+if st.session_state.get("submitted"):
+    st.markdown("### Your code")
+    st.warning(
+        f"**Your report ID is `{st.session_state['uid']}`.**\n\n"
+        "**Save this code now** (screenshot it, write it down — whatever works). "
+        "Your report is stored with **no name attached**, so this ID is the "
+        "**only** way to delete it later. If you lose it, we can't find your "
+        "report to remove it."
+    )
+
+# ============================================================================
+# 8) REMOVAL LINK
+# ============================================================================
+st.markdown("### Requesting removal of your report?")
+st.markdown(
+    "When you submit, we give you a **report ID code** (see above). Fill out the "
+    "form below with your code, and we'll remove your report."
+)
+st.link_button("🗑️ Request removal", DELETE_FORM_URL)
+st.caption(
+    "⚠️ Save your report ID somewhere safe. Your report is stored with **no name "
+    "attached**, so the ID is the *only* way we can find it. If you lose it, we "
+    "won't be able to delete your report."
+)
+
+footer()

exampleRedactedStars.pdf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:98d2ee7ff5bcc0f26906776bba511aa88e630083daa817be01ffcff4fd528c59
+size 278654