How ricardomsanti/antagon works
Antagon is a local, terminal-based voice and text sparring partner. The user’s thoughts are captured into a transcript, structured as an argument map, reviewed and explicitly approved, then challenged by a selected persona; intensity and depth control the challenge. The TUI drives session orchestration, while the voice engine handles local transcription, barge-in, and speech playback. The README also documents persona creation and optional Unbound models. Some subsystem links are based on README or module documentation because their implementation was not sampled.
Main entry points: controller.py Session controller · engine.py Voice engine · app.py Terminal UI · client.py Ollama client
Components 19
Session interaction
- Terminal UI
antagon/tui/app.py - Session controller
antagon/session/controller.py - Session state
antagon/session/state.py
Argument and debate
- Argument mapping
antagon/llm/argument_map.py - Contrast engine
antagon/contrast.py
Voice pipeline
- Voice engine
antagon/voice/engine.py - Speech detection
antagon/voice/vad.py - Speech recognition
antagon/voice/stt.py - Speech synthesis
antagon/voice/tts.py
Persona management
- Persona sheets
personas - Persona roster
antagon/personas.py - Persona forge UI
antagon/tui/forge.py - Persona authoring
antagon/persona_forge.py
Local runtime
- Configuration
antagon/config.py - Ollama client
antagon/llm/client.py
Other components
- User
- Ollama
- Microphone and speakers
- Unbound model
Connections 24
- User → Terminal UI: type thoughts
- User → Microphone and speakers: speak
- Microphone and speakers → Voice engine: audio input
- Terminal UI → Session controller: drive session
- Session controller → Session state: update session
- Session controller → Configuration: read settings
- Session controller → Persona roster: load roster
- Persona roster → Persona sheets: read sheets
- Session controller → Argument mapping: structure transcript
- Argument mapping → Ollama client: request map
- Session controller → Contrast engine: draft challenge
- Contrast engine → Ollama client: request reply
- Ollama client → Ollama: chat requests
- Terminal UI → Voice engine: consume voice events
- Voice engine → Speech detection: detect speech
- Voice engine → Speech recognition: transcribe audio
- Voice engine → Speech synthesis: synthesize replies
- Voice engine → Microphone and speakers: play audio
- Terminal UI → Persona forge UI: open forge
- Persona forge UI → Persona authoring: author persona
- Persona authoring → Ollama client: generate sheet
- Persona forge UI → Session controller: install persona
- Persona authoring → Persona sheets: write sheet
- Contrast engine → Unbound model: optional model