# Barge-In Simulator — Turn-Taking Model for Duplex Voice

## PURPOSE
GPT Live's headline promise is that you can interrupt the assistant "even while
you're talking". That is a scheduling problem, not a prompt problem. This SimPy
prototype models the conversation from the ad as a discrete-event system: a human
talker and an assistant talker, each holding an utterance for some duration, with an
end-of-turn detector that must decide when the human has finished. The simulator
compares three barge-in policies — `never` cut the assistant, `immediate` cut on any
human speech, and `threshold` cut only after N ms of sustained human speech — and
reports yield latency, wasted assistant speech and false-cut rate.

## WHY THIS MATTERS
The video shows hesitation ("hesitate, interrupt me") and interruption as ordinary,
frequent events. In a real duplex agent, cutting too eagerly makes the assistant feel
twitchy; cutting too late makes it talk over people. Simulation lets students tune
that trade-off cheaply, before touching any audio hardware.

## HOW TO BUILD
1. `pip install -r requirements.txt` (SimPy + NumPy).
2. Create a SimPy `Environment` and an `InterruptionController` that owns the three
   policies and a `threshold` in seconds.
3. Model each human utterance as a process that speaks for a drawn duration, then a
   `turn_gap`; emit an `interrupt` event if the human resumes inside the gap.
4. Track metrics per policy and print a comparison table (seeded for reproducibility).

Key snippet (from `starter/main.py`):
```python
def should_cut(self, spoken_ms: float) -> bool:
    if self.policy == "never":
        return False
    if self.policy == "immediate":
        return spoken_ms > 0
    return spoken_ms >= self.threshold_ms      # threshold policy

def human(env, ctrl, rng):
    while True:
        yield env.timeout(rng.uniform(0.8, 3.0) * 1000)   # speaking_ms
        yield env.timeout(rng.uniform(80, 400))            # inter-turn gap
        ctrl.observe_gap(env.now, rng)
```

## WHEN TO USE IN PRODUCTION
Use it to pick an end-of-turn threshold and to regression-test a duplex agent's
turn-taking under different speaking speeds before a live pilot. Do NOT use it to
predict exact production latency — it is a coarse queueing abstraction with synthetic
distributions, not an acoustic or network model.

## HOW IT HELPS STUDENTS
Students learn event-driven simulation, seeded reproducibility, and how to turn a
qualitative UX promise ("you can interrupt me") into measurable engineering trade-offs.

## STARTER CODE

`starter/main.py` is a SimPy discrete-event model of barge-in turn-taking:

- `Metrics` — collects interrupted turns, wasted agent speech, and talk-over time.
- `InterruptionController` — decides when a human speaker cuts in.
- `human_talker(env, ctrl, ...)` — the simulated speaker process.
- `run_policy(policy, seed=7, turns=40)` — runs one policy with a fixed seed.
- `main()` — compares the stub baseline against the interruption-aware policy.

Run it:

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

The `# TODO` markers cover the real acoustic/network latency distributions that replace
the synthetic ones used here.
