# Turn-taking (/conversation)

Turn-taking is the difference between an agent that feels like a phone tree
and one that feels like a person. Cuelo breaks it into four questions. Each one
is answered by a **controller**, a small model listening to the call:

| Question                                    | Signal             | Configured by             |
| ------------------------------------------- | ------------------ | ------------------------- |
| Has the caller finished their turn?         | `turn_end`         | `turns.controller`        |
| Is the caller interrupting the agent?       | `interrupt`        | `turns.barge_in_detector` |
| Is the caller only backchanneling ("yeah")? | `user_backchannel` | `turns.barge_in_detector` |
| Should the agent say "mhm" now?             | `backchannel`      | `turns.backchannel_model` |

A **policy** turns those signals into actions:

<SignalsDiagram />

Splitting listening from deciding means you can swap a model without touching
the rules, or change the rules without retraining anything.

## The default stack [#the-default-stack]

```yaml title="config.cuelo"
turns:
  controller: turn-1-mini # end of turn: ~140 ms after the caller stops
  barge_in: true # the caller can interrupt the agent...
  barge_in_detector: maai # ...but "yeah" and "mhm" don't stop it
  backchannel: true # the agent says "mhm" while the caller talks
  backchannel_model: maai # timed by MaAI
  backchannel_hold: 1200 # ms to wait after a "mhm" before replying
```

The MaAI parts need the `maai` extra (PyTorch). Without it, Cuelo falls back
to the small backchannel detector and a VAD rule. Weights download on first
use, or ahead of time with `cuelo models pull --all`.

## Choosing a stack [#choosing-a-stack]

| Goal                       | `controller`  | `barge_in_detector`    | `backchannel_model` | Notes                                    |
| -------------------------- | ------------- | ---------------------- | ------------------- | ---------------------------------------- |
| Most natural (default)     | `turn-1-mini` | `maai`                 | `maai`              | ~1 GB per process. ~5 calls per process. |
| Many calls per machine     | `turn-1-mini` | `backchannel-detector` | `vad`               | ~160 MB. ~60 calls per process.          |
| Non-English                | `smart-turn`  | `backchannel-detector` | `vad`               | Smart Turn v3 is multilingual.           |
| Simplest, most predictable | `vad`         | `vad`                  | `vad`               | Fixed silences. Robotic on pauses.       |
| Full duplex (research)     | `maai`        | `maai`                 | `maai`              | One model for turns and interruptions.   |

The per-process numbers were measured on an M3 Pro. Run `cuelo machine check`
for yours.

## In this section [#in-this-section]

<Cards>
<Card title="End of turn" href="/conversation/end-of-turn">
Answering fast without cutting people off.
</Card>

<Card title="Interruptions" href="/conversation/interruptions">
Stopping for "wait, no", but not for "yeah".
</Card>

<Card title="Backchannels" href="/conversation/backchannels">
An agent that says "mhm" at the right moment.
</Card>

<Card title="Custom turn-taking" href="/conversation/custom">
Your own controllers and policy in `src/turns.py`.
</Card>
</Cards>