Slice 3 — OpenAI Realtime brain: swap echo for the brain (#4)

2026-07-01 22:25:09 +00:00
parent 2f3f92ec6b
commit c30a45232d
36 changed files with 7227 additions and 20 deletions
--- a/examples/openai_realtime_brain/README.md
+++ b/examples/openai_realtime_brain/README.md
@@ -0,0 +1,52 @@
+# OpenAI Realtime reference brain — Python (slice-3 spec §7.5)
+
+A Python implementation of the slice-3 OpenAI Realtime brain — the canonical
+foreign-language brain demo, hand-rolled from the documented tap protocol
+([`docs/superpowers/specs/2026-06-30-slice-3-realtime-brain-design.md`](../../docs/superpowers/specs/2026-06-30-slice-3-realtime-brain-design.md)).
+
+## Why
+
+Proves the slice-3 tap protocol extension is language-agnostic. A Python
+script speaking JSON-via-WSS matches the OpenAI-Realtime-related portions of
+the spec without depending on Rust code paths. Same rationale as slice-2's
+Python echo brain — the project's `examples/` dir is the home for canonical
+foreign-language brain demos.
+
+The structure mirrors the Rust `rutster-brain-realtime` crate: a WS server
+(the tap side the core dials into) bridged bidirectionally to a WS client
+(the OpenAI Realtime side). The event mapping is the spec §4.2 table verbatim.
+
+## Run
+
+```bash
+pip install -r requirements.txt
+OPENAI_API_KEY=sk-... python examples/openai_realtime_brain/openai_realtime_brain.py
+```
+
+The Python brain binds the tap WS server on `RUTSTER_BRAIN_BIND` (default
+`127.0.0.1:8082`). The rutster binary, started normally (`cargo run`), dials
+out to `RUTSTER_TAP_URL` (default `ws://127.0.0.1:8082/realtime` — set
+`RUTSTER_TAP_URL=ws://127.0.0.1:8082` to match the Python brain's bind).
+
+Other env vars:
+
+| Var | Default | Purpose |
+|---|---|---|
+| `OPENAI_API_KEY` | (required) | OpenAI auth |
+| `RUTSTER_BRAIN_BIND` | `127.0.0.1:8082` | host:port for the tap WS server |
+| `OPENAI_REALTIME_MODEL` | `gpt-4o-realtime` | OpenAI model query-param |
+| `OPENAI_REALTIME_VOICE` | `alloy` | Voice passed in `session.update` |
+
+## Dependencies
+
+Only `websockets>=12.0` — both the tap-side server and the OpenAI-side client
+speak plain WSS, so the `openai` Python SDK is not needed (the spec §4.2
+mapping is explicit enough to hand-roll against the wire). This is a
+deliberate simplification over the slice-3 plan skeleton, which imported the
+SDK but never used it.
+
+## Not in CI
+
+Per AGENTS.md's "no Python in the dev loop" rule. The slice-3 integration
+test uses `rutster-brain-realtime --features=mock` — the in-process Rust
+mock — not this Python file.