# VoiceTurn CLI — Voice Conversation Analytics

## PURPOSE
The GPT Live ad tells the model to "hesitate, interrupt me... even while you're
talking", then rattles off a messy, overlapping conversation covering dates, Metro
line 8 disruptions and a hairdresser appointment. This project turns a raw
turn-by-turn voice transcript (the same `>>` speaker-turn format used in the video's
captions) into hard numbers: how often speakers interrupt, where hesitation and
false starts cluster, how long the assistant takes to correct itself, and which
topics were actually actioned. It is a Click command-line tool built on Pandas.

## WHY THIS MATTERS
Barge-in is only useful if you can *measure* it. Before tuning a duplex voice agent
you need a baseline: interruptions per minute, self-corrections per turn, and intent
coverage. This CLI produces that baseline from plain text, so students can evaluate
voice conversations the same way they would evaluate a dataset.

## HOW TO BUILD
1. `pip install -r requirements.txt` (Click + Pandas).
2. Parse the transcript with a small regex that splits on the `>>` marker and tags
   each turn as `interviewer` (no memorable facts) or `assistant`.
3. Detect events with keyword rules: interruptions ("wait", "sorry", "don't"),
   corrections ("not 1898", "actually", "opened in 1900"), actions ("appointment"),
   and topics (Paris / Metro line 8 / Eiffel Tower).
4. Aggregate with Pandas and print a summary table; add a `--json` flag.

Key snippet (from `starter/main.py`):
```python
turns = parse_turns(text)                     # -> DataFrame[speaker, text]
events = turns.assign(
    correction=turns.text.str.contains(r"not \d{4}|actually", case=False),
    action=turns.text.str.contains(r"appointment|set for", case=False),
)
summary = events.groupby("speaker").agg(turns=("text", "size"),
                                        corrections=("correction", "sum"))
```

## WHEN TO USE IN PRODUCTION
Use it in voice-agent regression pipelines: run the same scripted call script every
release and diff the metrics, or triage recorded calls for barge-in rates. Do NOT use
it as a real-time component — it is offline batch analysis over transcripts, not a
streaming detector, and keyword rules will not survive free-form human speech.

## HOW IT HELPS STUDENTS
Students learn text parsing with regex, tidy DataFrame aggregation, and Click command
design — and they finish with a genuinely useful, deterministic analytics tool rather
than another toy endpoint.

## STARTER CODE

`starter/main.py` is a Click-based CLI that turns raw call transcripts into turn metrics:

- `parse_turns(text)` — splits a call log into a tidy pandas DataFrame of turns.
- `classify(turns)` — tags each turn by intent/regex rule.
- `summarize(tagged)` — aggregates latency and interruption counts per session.
- `cli()` / `analyze(path, as_json)` — the command entry point and output rendering.

Run it:

```bash
pip install -r requirements.txt
python starter/main.py --help
python starter/main.py analyze sample_call.txt --json
```

The `# TODO` markers cover the remaining classification rules and the CSV export path.
