# Barge-In Turn-Taking Simulator

## PURPOSE
Estimate how a full-duplex voice assistant behaves when people talk over each other and over the model. The video stresses that the new model "can be interrupted, can listen while it speaks, and even when we all talk at once". This SimPy project simulates a multi-speaker session: several user speakers arrive on independent schedules, the assistant starts a response, and barge-in events preempt it. The output is a table of interruption counts, latency to yield and response completion rates.

## WHY THIS MATTERS
Full duplex changes the failure modes of a voice agent. Instead of a lost turn, the risk is the assistant talking over a person or dropping a half-finished answer. The clip's "Wait, wait" moment is exactly the design problem this simulator measures: how fast does the model stop, and how much of the answer survives? Students get a numeric feel for concurrency instead of guessing.

## HOW TO BUILD
1. Model speakers and the assistant as `simpy` processes on one environment.
2. Give the assistant a `response_duration` resource and each speaker a mean inter-arrival time.
3. When a speaker barges in mid-response, release the assistant resource and log the elapsed time.
4. Run many seeded replications with `numpy`-driven sampling and aggregate with `pandas`.
Key snippet:

```python
def assistant(env, out, response_time):
    while True:
        if out["speaking"]:
            yield env.timeout(response_time)      # full duplex: keeps talking
            out["completed"] += 1
        yield env.timeout(0.1)

def barge_in(env, out, at):
    yield env.timeout(at)
    if out["speaking"]:
        out["barge_ins"] += 1
        out["yield_latency"].append(env.now)
```

## WHEN TO USE IN PRODUCTION
Use it before shipping any realtime voice feature: sizing concurrency per pod, setting a barge-in threshold, or tuning how much context to keep after an interruption. Do NOT use simulation to replace load testing against the real model — it gives you comparative trade-offs, not absolute latency of a specific vendor.

## HOW IT HELPS STUDENTS
They learn discrete-event simulation, resource contention, reproducibility with seeds, and how to turn a qualitative product claim into a measurable metric.

## STARTER CODE
`starter/main.py` builds the environment, the three processes above and a seeded replication loop that prints a summary DataFrame. Inter-arrival and response times are stubs marked `# TODO` for real telemetry.
