How crushn8r/gopod works
1. Overall shape
- This repo is a local-first robot session engine built around Wire-Pod and split into two main concerns:
- goverlord/gomads/ = the domain logic and device/robot interaction layers.
- goverlord/runtime/ = the pruned, interview-scoped execution path used for the GOPOD demo and safety wrappers.
2. External control plane: Wire-Pod
- The system is not a standalone app; it attaches to Wire-Pod as the robot server and intent router.
- The wake phrase and custom intent path are handled by Wire-Pod, which then execs out to a Python runner for the GOPOD_YOURSELF flow.
- README also shows the robot control API boundary: assume behavior control → say_text → release behavior control.
3. Intent entrypoint and contract boundary
- goverlord/runtime/wire-pod/wirepod_intents/gopod_yourself_001/ is the intent scaffold.
- It contains:
- the intent definition JSON,
- intent docs and operator phrase maps,
- armed-mode and transport-rule contract docs,
- a gopod_yourself_dry_run.py script for the intent path.
- This directory is the main handoff boundary between Wire-Pod and the GOPOD session logic.
4. Low-level input subsystem
- goverlord/gomads/low_level/input_gomad/ handles push-to-talk / keypad routing.
- Key files:
- input_event_logic.py
- contracts/input_contract.py
- input_routes.json
- wiring/input_bridge.py
- README ties this to the numpad controls:
- KP1 routes to Doc,
- KP2 routes to Pip,
- KP0 x3 exits.
5. Robot interface subsystem
- goverlord/gomads/low_level/robot_interface_gomad/ is the robot-facing speech/expression layer.
- It includes:
- robot_speech_logic.py
- code/robot_expression_parser_001.py
- contracts/robot_interface_contract.py
- robot_interface_config.json
- wiring/robot_interface_bridge.py
- This is the translation layer from session intent/output into robot-safe speech and expression commands.
6. Robot I/O safety and text hygiene
- goverlord/runtime/robot/robot_io/ is a separate safety boundary around outbound speech text.
- Components include:
- robot_safe_packet_guard.py
- outbound_text_filter_001.py
- text_replacement_filter.py
- goverlord/runtime/prelaunch/replacement_rules_001.json supplies prelaunch text substitutions.
- Architecturally, this layer prevents raw model output from going directly to the robot.
7. Voice verification and TTS status
- goverlord/runtime/voice/ contains the local audio verification/support pieces:
- audio_proof_ladder_001.py
- gopod_audio_execution_verifier_001.py
- local_tts_voice_registry_001/interview_status_kokoro_announcer_001.py
- test_gopod_audio_execution_verifier_001.py
- This is not the main STT/LLM engine; it is the runtime verification and announcement layer around voice execution.
8. End-to-end live session flow
- The README’s live path is:
- Wire-Pod wake phrase
- custom intent match
- exec into GOPOD runner
- PTT loop
- local STT with Vosk
- local LLM with Ollama
- Wire-Pod SDK speech back to the robot
- The repo itself mainly contains the contract, bridge, and safety layers for that flow rather than the full live runner.
9. Two-robot session model
- The system treats the robots as role-separated endpoints:
- Doc = doctrine/canonical speaker
- Pip = confused sidekick / audience proxy
- The routing logic in the input and robot-interface layers is what maps the active key/intent to the correct voice persona.
10. Repo boundaries and what is external
- This repo deliberately depends on external runtime pieces:
- Wire-Pod for intent dispatch and robot API control,
- Ollama for local LLM generation,
- Vosk for local STT,
- the actual live interview runner is described as living in the external Wire-Pod tree.
- That separation is important for the architecture diagram: this repo is the GOPOD control/scaffold layer, not the full robot stack.
11. Documentation as architecture
- The many README.md and contract files are part of the design itself.
- They define expected behavior for the bridges, intent boundaries, and robot-safe execution rules.
- In practice, they act like a specification layer for the runtime code.
12. Utility / ops support
- goshot.sh is a repo snapshot utility.
- Its presence reinforces that this codebase is being managed as a stateful engineering artifact with repeatable capture of the current truth, not just an application source tree.
Main entry points: README.md Goverlord README · gopod_audio_execution_verifier_001.py Audio verifier · input_event_logic.py Input logic · robot_speech_logic.py Speech logic
Components 25
Repo overview
Top-level docs and snapshot tooling
- README · Primary repository overview and live flow description
README.md - Goverlord README · Subsystem-level documentation for the goverlord tree
goverlord/README.md - goshot.sh · Snapshot and state-capture helper
goshot.sh
Input routing
Push-to-talk and keypad routing into the session
- Input logic · Push-to-talk and keypad event routing logic
goverlord/gomads/low_level/input_gomad/input_event_logic.py - Input bridge · Wiring layer into input routing
goverlord/gomads/low_level/input_gomad/wiring/input_bridge.py - Input contract · Expected input behavior and interface contract
goverlord/gomads/low_level/input_gomad/contracts/input_contract.py
Robot interface
Speech and expression translation for robot-safe output
- Speech logic · Robot-facing speech orchestration
goverlord/gomads/low_level/robot_interface_gomad/robot_speech_logic.py - Expr parser · Parses robot expression and marker signals
goverlord/gomads/low_level/robot_interface_gomad/code/robot_expression_parser_001.py - Robot bridge · Wiring layer into robot interface logic
goverlord/gomads/low_level/robot_interface_gomad/wiring/robot_interface_bridge.py - Robot contract · Robot interface expectations and boundary rules
goverlord/gomads/low_level/robot_interface_gomad/contracts/robot_interface_contract.py
Robot safety
Outbound text guarding and replacement before robot speech
- Safe guard · Protects robot I/O from unsafe outbound packets
goverlord/runtime/robot/robot_io/robot_safe_packet_guard.py - Text filter · Outbound text filtering for robot-safe speech
goverlord/runtime/robot/robot_io/outbound_text_filter_001.py - Replacement filter · Applies text substitutions before robot output
goverlord/runtime/robot/robot_io/text_replacement_filter.py - Rules · Prelaunch text replacement rules
goverlord/runtime/prelaunch/replacement_rules_001.json
Voice runtime
Verification and local TTS status support
- Audio verifier · Checks local audio execution path
goverlord/runtime/voice/gopod_audio_execution_verifier_001.py - Proof ladder · Audio proof and verification staging
goverlord/runtime/voice/audio_proof_ladder_001.py - TTS announcer · Local TTS status and announcement support
goverlord/runtime/voice/local_tts_voice_registry_001/interview_status_kokoro_announcer_001.py
Wire-Pod intent
Intent scaffold and contract boundary for GOPOD Yourself
- GOPOD intent · Intent definition and handoff boundary into GOPOD Yourself
goverlord/runtime/wire-pod/wirepod_intents/gopod_yourself_001/gopod_yourself_intent_001.json - Dry run · Executable path used by the intent scaffold
goverlord/runtime/wire-pod/wirepod_intents/gopod_yourself_001/gopod_yourself_dry_run.py - Armed mode · Behavior-control and armed-mode contract
goverlord/runtime/wire-pod/wirepod_intents/gopod_yourself_001/gopod_armed_mode_contract_001.md - Transport rules · Intent transport and execution constraints
goverlord/runtime/wire-pod/wirepod_intents/gopod_yourself_001/do_not_invent_transport_rules_001.md - Phrase map · Operator phrases mapped to intent actions
goverlord/runtime/wire-pod/wirepod_intents/gopod_yourself_001/operator_phrase_map_001.md
External runtime
Dependencies and control plane outside this repository
- Wire-Pod · Robot server and intent router outside this repository
- Ollama · Local LLM runtime used by the live session
- Vosk · Local speech-to-text runtime used by the live session
Connections 27
- README → Wire-Pod: describes control plane · Repository overview frames Wire-Pod as the session entry and robot API boundary
- README → Input logic: documents ptt flow · Top-level README describes keypad and push-to-talk routing
- README → Safe guard: documents safety · Top-level README explains outbound robot text safety
- GOPOD intent → Dry run: executes · The intent scaffold hands off to the dry-run executable
- Wire-Pod → GOPOD intent: dispatches intent · Wire-Pod matches the wake phrase and launches the GOPOD intent path
- Armed mode → Dry run: constrains · Armed-mode rules shape allowed behavior in the runner
- Transport rules → Dry run: constrains · Transport rules define how the intent path may move data
- Phrase map → GOPOD intent: maps phrases · Operator phrase mappings feed the intent boundary
- Input bridge → Input logic: routes events · Bridge connects raw keypad events to routing logic
- Input contract → Input logic: defines contract · Input behavior is governed by the contract layer
- Input logic → Robot bridge: selects persona · Input routing chooses the downstream robot-facing persona path
- Robot bridge → Speech logic: invokes · Bridge hands session output to robot speech logic
- Robot contract → Speech logic: defines contract · Robot interface expectations constrain speech handling
- Expr parser → Speech logic: parses markers · Expression parsing supports robot-safe output formatting
- Speech logic → Safe guard: emits text · Robot speech output passes into the safety boundary
- Rules → Replacement filter: supplies rules · Prelaunch substitutions feed the replacement filter
- Safe guard → Text filter: filters · Safety guard invokes outbound text filtering
- Text filter → Replacement filter: rewrites · Outbound text is normalized through replacement rules
- Replacement filter → Wire-Pod: returns speech · Sanitized text is ready for robot-side delivery through Wire-Pod
- Proof ladder → Audio verifier: feeds checks · Verification ladder supports execution verification
- TTS announcer → Audio verifier: announces status · Voice registry status output is part of verification support
- Audio verifier → Vosk: verifies via · Live audio path depends on local speech recognition support
- Audio verifier → Ollama: verifies via · Live session verification assumes local model execution
- Goverlord README → Input bridge: documents subsystem · Goverlord documentation frames the low-level input subsystem
- Goverlord README → Robot bridge: documents subsystem · Goverlord documentation frames the robot interface subsystem
- Goverlord README → Safe guard: documents safety · Goverlord documentation frames robot I/O safety as a boundary
- Goverlord README → GOPOD intent: documents handoff · Goverlord documentation references the Wire-Pod intent boundary