# PlainTalk Voice Studio: A Plain-Language Session Dashboard

## PURPOSE
A Streamlit dashboard that scores how hard a voice assistant's replies are to
understand, and shows what a plain-language rewrite would look like. It exists
because of one exchange in OpenAI's UK demo: the model says ChatGPT voice is a
"bidirectional, full-duplex conversational partner", the user answers "That's a
lot of tech jargon. Can you simplify that?", and the retelling becomes "it's
like chatting to a mate". This tool turns that moment into a repeatable
accessibility check over a whole session log.

## WHY THIS MATTERS
The transcript's most human feature is not the duplex audio — it is the offer to
re-explain at the listener's level. Comprehension is measurable: word length,
sentence length, and jargon density. Students learn that "explain it simply"
can be a metric with a threshold and a chart, not a vibe, and that a dashboard
is what convinces a non-technical stakeholder to act.

## HOW TO BUILD
1. Streamlit multipage layout: upload session JSONL, filter by speaker/turn.
2. Derive readability features with pure Python: mean words per sentence, share
   of words longer than 8 characters, jargon hits from a terms list
   ("full-duplex", "bidirectional", "bidirectional audio", "tokens").
3. A deterministic `simplify()` stub stands in for the model rewrite; each row
   shows original vs. simplified side by side.
4. Plotly line chart of jargon density across the session, plus a bar chart of
   turns flagged as too dense.
5. Cache parsed logs with `@st.cache_data`.

```python
st.metric("Jargon density", f"{row.jargon_per_100:.1f}/100 words",
          delta=row.jargon_per_100 - baseline)
fig = px.line(df, x="turn", y="jargon_per_100", color="speaker",
              title="Comprehension risk over the session")
st.plotly_chart(fig, use_container_width=True)
```

## WHEN TO USE IN PRODUCTION
Use it to QA voice assistants for accessibility, to tune system prompts so
replies stay at a target reading level, to prepare transcripts for public sector
or health communication, and to demonstrate accessibility compliance. Do NOT use
it as the only evaluation of translation quality, to judge tone or empathy, or
as an automated rewriter that ships text to users without review — a plain
rewrite can silently change meaning, which is why the side-by-side view exists.

## HOW IT HELPS STUDENTS
Dataframes and feature engineering, Streamlit state, Plotly charting, caching
for cost, and the habit of pairing every metric with the raw evidence that
produced it.

## STARTER CODE
See `starter/main.py` for the runnable Streamlit skeleton with the readability
features, the deterministic simplify stub, and the Plotly charts.
