How rcbyron/hey-athena-client works
1. What this repository is
- hey-athena-client is a Python 3 voice-assistant framework, not a single-purpose app.
- Its architecture is built around a small core runtime plus pluggable “modules” that respond to spoken/text commands.
2. Primary runtime flow
- The usual loop is: capture audio input → speech-to-text (athena/stt.py) → intent/command handling in the brain (athena/brain.py) → module/task dispatch → text-to-speech output (athena/tts.py) and/or side effects.
- The assistant’s wake-word / trigger phrase is driven by athena/keyphrases.txt and the input pipeline.
3. Core orchestration boundary
- athena/brain.py appears to be the central coordinator for interpreting input and selecting actions.
- athena/mods.py is the module loader/registry layer, responsible for discovering available modules and making them available at runtime.
- athena/apis.py is the runtime registry for API helper objects used by modules.
4. Module architecture
- Modules live under athena/modules/active/ and are the main extension mechanism.
- Each active module groups one or more tasks; tasks match user text and execute actions.
- The abstraction is defined in athena/classes/module.py and athena/classes/task.py, with response/input helper types in athena/classes/response.py and athena/classes/input_field.py.
5. How commands are represented
- The repository models commands as pattern-matching tasks rather than a global intent graph.
- This makes each module self-contained: a module owns its own triggers, priority, and action logic.
- Module priority and task priority determine which action wins when multiple patterns match.
6. Built-in capabilities
- The bundled active modules show the assistant’s intended feature set: conversation, music, shop, Twitter, Uber, SMS texting, Google search, voice browsing, geolocation, Wolfram queries, and basic control modules.
- These modules are examples/reference implementations for adding new capabilities.
7. API/service integration layer
- athena/api_library/ contains reusable service adapters, such as geo_info_api.py, ifttt_api.py, sms_text_api.py, user_api.py, and voice_browse_api.py.
- These are not modules themselves; they are utility/service clients that modules call.
- The README also implies external integrations like IFTTT, Google, Twitter, Uber, and Wolfram Alpha.
8. State, configuration, and user-specific data
- athena/settings.py and athena/user_config.py hold configuration boundaries between framework defaults and user-specific settings.
- This is important architecturally because modules can rely on runtime configuration, credentials, and user preferences without hardcoding them into module logic.
9. I/O and media assets
- athena/data/media/ contains audio prompts and response sounds, such as beeps and error/test audio.
- These assets support the conversational UX and are part of the assistant’s feedback loop after speech recognition or action execution.
10. Browser automation support
- athena/chrome/ packages platform-specific Chromedriver binaries.
- This indicates that some modules use Selenium-driven browser automation, especially for voice browsing or web interaction, and that this capability is treated as a deployment/runtime dependency.
11. Passive modules are a planned boundary
- athena/modules/passive/ exists as a separate namespace, but the README describes passive modules as “soon-to-be implemented.”
- The intended architectural split is between active, user-triggered tasks and passive, event/schedule-triggered tasks.
12. Support services inside the package
- athena/log.py centralizes logging behavior.
- athena/__main__.py suggests the package is executable as a module, while setup.py and MANIFEST.in package it for distribution.
13. Quality and verification
- Tests under athena/tests/ cover audio, microphone, dependency, and input behavior.
- The test layout reflects the main runtime risks: audio stack, hardware access, and environment dependencies.
14. Documentation and generated artifacts
- docs/ is a Sphinx documentation site with API docs and user guides.
- docs/html/ is generated output and not part of the runtime architecture, but it mirrors the package structure and confirms the public surfaces of core, API library, and active modules.
15. Diagram-friendly summary
- A clean architecture diagram would show:
- user audio/text input at the edge,
- STT/TTS as the speech boundary,
- a central brain and module registry in the core,
- active modules as pluggable command handlers,
- API library adapters feeding external services,
- config/logging/media as supporting infrastructure.
Main entry points: api_library API library · task.py Task base · brain.py Brain · module.py Module base
Components 34
Core runtime
Assistant loop, orchestration, and shared abstractions
- Speech to text · Audio capture and transcription boundary
athena/stt.py - Brain · Central command interpretation and action selection
athena/brain.py - Module loader · Discovers and registers available modules
athena/mods.py - API registry · Shared API helper objects exposed to modules
athena/apis.py - Text to speech · Voice output and spoken feedback
athena/tts.py - Module base · Module lifecycle and metadata contract
athena/classes/module.py - Task base · Pattern-matching command unit
athena/classes/task.py - Response type · Response payload and output shaping
athena/classes/response.py - Input field · Structured user input helper
athena/classes/input_field.py
Extensions
Pluggable active modules and passive namespace
- Active modules · User-triggered command handlers
athena/modules/active - Conversation · Dialogue and conversational behavior
athena/modules/active/conversation.py - Music · Music and media actions
athena/modules/active/music.py - Google · Search and web lookup actions
athena/modules/active/google.py - Voice browse · Browser-driven voice interaction
athena/modules/active/voice_browse.py - SMS text · Text messaging actions
athena/modules/active/sms_text.py - Geo info · Location and geolocation actions
athena/modules/active/geo_info.py - Twitter · Social posting and retrieval
athena/modules/active/twitter.py - Uber · Ride booking actions
athena/modules/active/uber.py - Wolfram · Computational query actions
athena/modules/active/wolfram.py - Control · Assistant control and runtime commands
athena/modules/active/athena_control.py - Hello world · Reference example module
athena/modules/active/hello_world.py
Service adapters
Reusable API clients used by modules
- API library · Reusable integration clients for modules
athena/api_library - Geo API · Geolocation service client
athena/api_library/geo_info_api.py - IFTTT API · Webhook and automation client
athena/api_library/ifttt_api.py - SMS API · SMS gateway client
athena/api_library/sms_text_api.py - User API · User profile and preference client
athena/api_library/user_api.py - Browse API · Browser automation client
athena/api_library/voice_browse_api.py
Support assets
Configuration, media, browser binaries, and logs
- Settings · Framework defaults and runtime settings
athena/settings.py - User config · User-specific configuration and credentials
athena/user_config.py - Keyphrases · Wake-word and trigger phrase list
athena/keyphrases.txt - Media assets · Prompts and response sounds
athena/data/media - Chromedriver · Bundled browser automation drivers
athena/chrome - Logging · Central logging behavior
athena/log.py
Docs & tests
Verification and documentation surfaces
- Tests · Audio, input, mic, and dependency checks
athena/tests
Connections 30
- Speech to text → Brain: transcribed input · Speech input is handed to the command brain
- Keyphrases → Speech to text: wake phrase · Trigger phrases gate the input pipeline
- Brain → Module loader: resolve modules · Brain asks the registry for available handlers
- Brain → API registry: use APIs · Brain exposes runtime helpers to command handlers
- Brain → Text to speech: speak output · Brain routes responses to speech output
- Module loader → Active modules: load · Loader discovers active modules at runtime
- Active modules → Module base: implements · Modules follow the shared module contract
- Active modules → Task base: contains tasks · Modules are composed of pattern-matching tasks
- Task base → Response type: returns · Tasks produce structured responses
- Module base → Settings: reads · Modules depend on framework configuration
- Module base → User config: reads · Modules depend on user-specific settings
- Conversation → Task base: defines · Representative task-driven module behavior
- Music → Task base: defines · Music commands are implemented as tasks
- Google → Task base: defines · Search actions are implemented as tasks
- Voice browse → Task base: defines · Browser automation commands are implemented as tasks
- Voice browse → Chromedriver: drives · Voice browsing relies on bundled browser binaries
- SMS text → SMS API: calls · SMS module uses the SMS adapter
- Geo info → Geo API: calls · Geolocation module uses the geo adapter
- Twitter → IFTTT API: calls · Social actions can route through automation services
- Uber → Browse API: calls · Ride workflows may use browser automation helpers
- Wolfram → API library: uses · Computational queries rely on service adapters
- API library → User API: includes · Shared adapter package contains user client
- API library → Browse API: includes · Shared adapter package contains browse client
- API library → IFTTT API: includes · Shared adapter package contains IFTTT client
- API library → Geo API: includes · Shared adapter package contains geo client
- API library → SMS API: includes · Shared adapter package contains SMS client
- Text to speech → Media assets: plays · Speech output uses bundled prompts and sounds
- Logging → Brain: logs · Runtime logging supports orchestration and diagnostics
- Tests → Speech to text: covers · Tests exercise audio and transcription boundaries
- Tests → Module loader: covers · Tests exercise environment and dependency behavior