Spaces:

---

buai-builder-hub

/

STARSRedacter

like 0

Running

A few notes below, split into "tightening up around informed consent" and "smaller layout suggestions." The second group is
mostly about reducing visual clutter, so it's more a matter of taste (I leave it to you). The first group is kind of important to do before we ship.

Tightening up around informed consent

1. Consent before we touch the file. Right now the app redacts the upload as
soon as it's dropped in, and the consent box only applies to the submit-to-BBH step. My worry is that means we are
actually operating on the student file (to redact it) before we have consent.

I actually love the "try it and preview your redacted file first" idea and don't
want to lose it. The change I'd suggest is really just about sequencing.
Ideally a user would first check the consent box, then upload their report and
preview it (that's your nice preview step), then we process it, and finally they
confirm submission. That way they've consented before we ever touch their file —
which is just good, responsible practice when we're asking people to share
something personal. In practice, it means the redaction waits until the consent
box is checked, the way the earlier version did.

2. Grade wording — this one matters for accuracy. In a couple of places (the
TL;DR especially) we say grades are "never stored." That's not quite what we do —
we replace each letter grade with a pass/fail marker, and we do keep that
marker. Could you make sure everywhere grades are mentioned (TL;DR, consent box,
and the illustration) says something like "letter grades are replaced with a
simple pass/fail marker" rather than implying grades disappear entirely? The
consent box is ok already; it's mainly the TL;DR that overstates. Being
precise here really matters for making sure students are giving truly informed
consent.

3. Two lines I'd like back in the consent box. When the box got trimmed, two
sentences dropped that I'd like to keep — I think they're important to promoting
informed consent from users: "Only share if you're okay with that." (at the end
of the point about potential identifiability) and "We never keep your original."

4. The screenshots and the sample link. Rendering images in Streamlit is
sometimes tricky! I think the issue is that the code is looking for
images/what_we_keep.png and images/what_we_dont_keep.png, but the files you
committed are explanationSS1/2/3.png in the repo root — so it can't find them.
Good news: the images themselves are fine and already in the repo, so it's just a
matter of pointing KEEP_DONT_KEEP_IMAGES at the actual filenames. Same idea for
the sample report — SAMPLE_REPORT_URL is still the example.com/TODO
placeholder, so the "View a sample" button doesn't go anywhere yet; we can wire
it to the exampleRedactedStars.pdf you uploaded. That said, I have some
suggestions below about reworking these images, so maybe take a look at those first before bothering to fix this.

Smaller layout suggestions (mostly just decluttering)

First off — I really like the new TL;DR. Nice addition!

Something to consider with layout: the app also works
on phones, where everything stacks into a single tall column — so trimming
clutter makes a real difference on mobile.

• Intro: building on Adel's suggestion last week about saying a bit more
  about who we are and why, maybe something like: "BUAI Builder Hub (BBH) is a
  group of USC students building tools to improve the student experience. Right
  now, we're working on tools to make degree planning, course registration, and
  picking classes easier. To do that, we need your help sourcing STARS reports —
  so we can develop tools that are actually useful to you." (In particular, I'd also swap "test
  against our tool" for "develop tools that are actually useful" — feels less
  like we're treating people as test data. 😃 )
• Move the "what we keep / don't keep" graphic above the passphrase — it's
  the reassurance that makes someone comfortable proceeding, so it's nice to have
  before we ask for the passphrase.
• Hide the passphrase once it's entered. This one's a little tricky in
  Streamlit, because the whole script re-runs top to bottom every time anything
  on the page is touched — so you can't just "remove" the box after the fact. The
  trick is to store a flag in st.session_state once the correct passphrase is
  entered (e.g. st.session_state["authed"] = True), and then only draw the
  input when that flag isn't set (if not st.session_state.get("authed"): ...).
  On the re-run after a successful entry, the box simply isn't drawn, so it
  disappears cleanly.
• Headers / aesthetics: purely a look-and-feel thing, but the page has a lot
  of section headers, which breaks it into a lot of little chunks — trimming a
  few would help it flow. "See a full example" is the low-hanging fruit: it's
  currently a header + a line of text + a button + a caption, and it could just
  be one line, e.g. "Curious what a finished redacted report looks like? [View a
  sample redacted report]" (and we can drop the "opens in a new tab" note). That would streamline things a lot visually.
• Expanders: with the TL;DR doing the quick-summary job so well, the expanders
  could go a little deeper rather than repeat it. "How do I get my STARS
  report?" is great — definitely keep it. The two privacy ones overlap with the
  TL;DR, so maybe merge them into a single "Who sees my report, and how is it
  protected?"
• Removal section: since you really only need it after submitting, maybe fold
  it into the "your code" block that appears after submission. For anyone who
  submitted on an earlier visit and comes back later, a small link in the page
  footer — or a compact expander at the very bottom, something like "Submitted
  before and want it removed?" — would let them find it without having to upload
  again.
• Images: Adel's cartoon-style illustration idea is a great direction here.
  The current screenshots get a little cramped and hard to read when they're
  shrunk down (because the original STARS reports were low res);
  a cleaner "what we remove vs. what we keep" cartoon would pop more
  and stay legible at any size. I pasted a sample prompt and an example image in
  Slack that could give you a starting point. With the redesign above, it would also be immediately visible
  before the passphrase, giving the page a more professional/friendly look.

Testing your changes locally

Once you fix the image/PDF links, the easiest way to confirm they work is to run
the app locally:

1. In the STARSRedacter folder: python3 -m venv .venv then
   source .venv/bin/activate (if your prompt also shows a conda (base), run
   conda deactivate first so it doesn't shadow the venv).
2. pip install -r requirements.txt
3. APP_PASSPHRASE=test streamlit run app.py — a browser tab opens; type test
   at the prompt.
4. Upload a sample STARS PDF and check that the screenshots render and the sample
   link opens.

Thank you for being brave enough to share your work for feedback — this is
exactly the kind of collaborative, iterative environment we're looking for. Great
job! Ping me when you've made a pass and I'll gladly take another look.