# Conversation Quality Dashboard — Streaming Voice Eval in Streamlit

## PURPOSE
The demo's best moment is a correction: the assistant says "the Paris Metro opened in
1900, not 1898" — fixing a date mid-conversation — then immediately reports "no
disruptions on line 8" and "hairdresser appointment set for 5:00 PM", all while the
speakers switch between French and English. This project turns those observable
behaviours into a Streamlit + Plotly dashboard over a scored conversation log, so a
team can see at a glance how a voice agent handles fact corrections, task completion,
interruption and multilingual turns across many sessions.

## WHY THIS MATTERS
The video sells "a complete conversational partner"; shipping one requires measuring
it. A dashboard makes the qualitative claims from the demo quantitative: correct-answer
rate, self-correction rate, task success, barge-in handling, and language coverage —
the scorecard a voice team reviews each release.

## HOW TO BUILD
1. `pip install -r requirements.txt` (Streamlit + Plotly + Pandas).
2. Define an evaluation schema: one row per turn with `session_id`, `language`
   (`fr`/`en`), `intent` (fact / transit / booking / chitchat), `scored_ok`, and
   `latency_ms`. Seed a deterministic synthetic frame so the app runs offline.
3. Put it in `st.session_state` with a sidebar `st.selectbox` filter for language and
   `st.slider` for minimum latency.
4. Render Plotly charts: a bar of pass rate by intent, a histogram of latency, and a
   line of correction rate per session.

Key snippet (from `starter/main.py`):
```python
filtered = df[(df.language.isin(chosen_langs)) & (df.latency_ms <= max_latency)]
pass_rate = filtered.groupby("intent").scored_ok.mean().reset_index()
st.plotly_chart(px.bar(pass_rate, x="intent", y="scored_ok", title="Pass rate by intent"))
```

## WHEN TO USE IN PRODUCTION
Use it as the shared scorecard for voice-agent regressions: point it at the eval log
your CI job writes and every release gets a visual diff of quality, not just a pass/
fail. Do NOT treat it as the source of truth for individual sessions — it aggregates
scores produced upstream, so a bug in the scorer silently becomes a pretty chart.

## HOW IT HELPS STUDENTS
Students learn to define an evaluation schema before building charts, to keep ETL
deterministic for demos, and to design dashboards that answer a concrete question
("did this release get better at correction and booking?") rather than showing
decoration.

## STARTER CODE

`starter/main.py` is a Streamlit + Plotly evaluation dashboard:

- `load_eval_log(seed=30, n_sessions=40)` — deterministic ETL producing the eval frame
  (correction rate, booking success, latency percentiles).
- `main()` — builds the Streamlit layout and the Plotly figures.

Run it:

```bash
pip install -r requirements.txt
streamlit run starter/main.py
```

The `# TODO` markers cover swapping the seeded generator for a real eval-log loader
and adding per-release drill-downs.
