# TripThread CLI: Multi-Intent Extraction from Voice Logs

## PURPOSE
A command-line tool that takes a voice-assistant conversation log (the kind of
exchange in OpenAI's UK demo: "is the food all right for a vegan?", "email me a
list of restaurants", "what's the weather like in Morocco in September?") and
splits it into a clean, per-thread task table. Each open request becomes a row
with an intent, a destination or entity, a status, and the utterance that
created it — so the assistant's promise to "email a list of places" is trackable
instead of lost in chat history.

## WHY THIS MATTERS
The transcript's headline capability is that ChatGPT voice "can now hold multiple
bits of information at once" and let you change plans while the conversation
keeps moving. That only works if something downstream can enumerate those
threads. Students learn that conversational memory is a data-modelling problem:
intent classification, entity slots, and thread lifecycle (open, updated,
fulfilled, abandoned).

## HOW TO BUILD
1. `click` command group with subcommands `ingest`, `threads`, `export`.
2. Read transcripts as JSONL (`{"ts", "speaker", "text"}`) into a Pandas frame.
3. Rule-based intent pass (travel, email, weather, dietary, translation) with a
   swappable hook where an LLM classifier would go.
4. Merge later utterances into the existing open thread when the entity matches
   ("no less than 150 pounds" updates the guitar-sale thread).
5. `export --format csv` writes the thread table for a planner or CRM.

```python
df = pd.read_json(path, lines=True)
df["intent"] = df["text"].map(classify_intent)   # deterministic stub
threads = (df[df.speaker == "user"]
           .assign(entity=lambda d: d["text"].map(extract_entity))
           .query("intent != 'chit_chat'")
           .sort_values("ts"))
```

## WHEN TO USE IN PRODUCTION
Use it to audit voice-agent sessions: did the agent actually send the email it
promised, did the user's plan change get recorded, how many intents per call.
Also useful for QA sampling and for handing off a live call to a human. Do NOT
use it when the conversation is genuinely single-intent (a one-shot translation
request), when a richer agent framework already owns conversation state, or as a
source of truth for legal records without a human review step.

## HOW IT HELPS STUDENTS
Pandas joins and reshaping, Click packaging, regex entity extraction, and the
habit of separating "classify" from "act". It is the least glamorous and most
transferable skill set in the whole video.

## STARTER CODE
See `starter/main.py`: a Click CLI with a deterministic classifier stub and a
CSV export path.
