engine/CONVERSATION_NOTES.md

# Live Brain + Conversation Notes

This phase keeps the controller training-free and model-agnostic. The real model
lives behind `modal_app/brain_modal.py`; local code only asks for `BrainSignals`
and generated replies.

## Flow

1. The text stream feeds incremental word groups plus an optional silence flag.
2. `Conversation` sends the current dialogue prefix and newest user chunk to
   `LiveBrainPanel.step_all()`.
3. Modal computes per-agent surprise, hidden vector, readiness, and `p_end`.
4. `WhenToSpeakController` arbitrates `SILENT`, `BACKCHANNEL`, `TAKE_FLOOR`, or
   `INTERRUPT`.
5. On `TAKE_FLOOR` or `INTERRUPT`, `Conversation` calls Modal `generate()` and
   splices the short investor reply into the dialogue.

The sample pitch deliberately includes a weak claim: "ten thousand stores and
zero churn after launching last week." The expected demo behavior is an investor
interrupt or floor-take near that claim, with the generated line recorded in
`eval/conversation_log.json`.

Run the real text-streamed demo with:

```text
uv run modal run modal_app/brain_modal.py
```

## Modal

The live brain tries `nvidia/Llama-3.1-Nemotron-Nano-4B-v1.1` first and falls
back to `Qwen/Qwen2.5-3B-Instruct`. We keep `HF_HOME=/cache` on a Modal Volume so
weights persist across runs.

## Recorded Demo

The committed `eval/conversation_log.json` was produced by:

```text
uv run modal run modal_app/brain_modal.py
```

Latest measured run: `nvidia/Llama-3.1-Nemotron-Nano-4B-v1.1` on `NVIDIA A10`.
Total wall time was 49.1 s because the run included Modal container/model startup.

At step 3 the controller interrupted the planted weak claim. The winning agent
was `ruthless_skeptic` with urge 1.47 and readiness 0.67. At step 7 the panel now
takes the floor at turn end.

```text
Ruthless Skeptic: Zero churn after one week is not churn data.
Vision Optimist: Show cohorts, paid conversion, and retention.
```

Generation caveat: Nemotron-Nano produced malformed text for these two `generate()`
calls, so `eval/conversation_log.json` records `reply_source: "fallback"` for both.
The timing signals and controller decisions are still real Modal/Nemotron outputs;
the fallback only guards the spoken text until the generator prompt/model is improved.