e8ba2f3f32
examples/openai_realtime_brain/ -- the canonical foreign-language OpenAI Realtime brain (Python, ~150 lines, websockets lib only). Not in CI (zero-non-Rust-dev-deps dev loop per AGENTS.md). Mirrors the slice-2 echo_brain pattern and proves the protocol is language-agnostic. Hand-rolled against the spec §4.2 mapping rather than using the openai Python SDK: the SDK is unused by the wire-shape (both sides are plain WSS), so dropping it removes a dep that the plan skeleton imported but never called. session.update is sent with turn_detection=null (S4) matching the Rust brain. LEARNING.md gains 5 new pointers under a Slice 3 heading: async-trait in trait objects, the translator pure-function layer, additive protocol extension via #[serde(other)], the FOB-boundary side-channel mpsc, and the WS subprotocol handshake (openai_client.rs). README.md gains the Slice 3 dev loop section (mock mode without an OpenAI key, real-OpenAI mode, and the Python brain alternative). .gitignore learns about __pycache__/*.pyc (the Python brains aren't in CI but byte-compiled artifacts should never be tracked).
53 lines
2.2 KiB
Markdown
53 lines
2.2 KiB
Markdown
# 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.
|