373bdaf1d4
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).
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).
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
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.