Architecture

System Architecture

High-Level Runtime

flowchart LR
    ArchMain["main.py"] --> ArchBootstrap["Bootstrap"]
    ArchBootstrap --> ArchRuntime["Async Runtime"]
    ArchBootstrap --> ArchEvents["Event Buses"]
    ArchBootstrap --> ArchLifecycle["Lifecycle"]
    ArchRuntime --> ArchVoice["Voice Pipeline"]
    ArchRuntime --> ArchVision["Vision Auto-Capture"]
    ArchRuntime --> ArchCognition["Cognition"]
    ArchRuntime --> ArchWebUI["WebUI"]
    ArchVision --> ArchDiagnostics["Diagnostics"]
    ArchDiagnostics --> ArchWebUI
    ArchCognition --> ArchPersistence["Persistence"]

Voice Pipeline

flowchart LR
    VoiceWake["Wakeword"] --> VoiceCapture["Capture"]
    VoiceCapture --> VoiceSTT["STT"]
    VoiceSTT --> VoiceTranscript["Transcript"]
    VoiceTranscript --> VoiceConversation["Conversation"]
    VoiceConversation --> VoiceResponse["Response"]
    VoiceResponse --> VoiceTTS["TTS"]
    VoiceTTS --> VoiceSpeaker["Speaker"]

WakewordManager owns the microphone only while the runtime mode is idle. When runtime moves into listening, transcribing, thinking, speaking, or cooldown, the wakeword PyAudio stream is closed so STT can own capture without wakeword backlog or stream-draining conflicts. After wakeword detection, the wakeword stream is closed before the listen/STT handoff.

Vision Pipeline

flowchart LR
    Camera["CameraManager"] --> FrameStore["FrameStore"]
    Camera --> Analyzer["VisionAnalyzer"]
    Analyzer --> Metrics["Image Metrics"]
    Analyzer --> FaceReady["face_ready"]
    Camera --> Detector["FaceDetector"]
    Detector --> FacePayload["face_detection"]
    Metrics --> Diagnostics["DiagnosticsManager"]
    FacePayload --> Diagnostics
    Diagnostics --> WebUI["/vision WebUI"]

The vision pipeline is implemented as an experimental local camera pipeline. VisionAutoCapture keeps a periodic capture loop when enabled, and CameraManager may keep the camera session open while that loop is active.

Cognition and Persistence

• ResponseGenerator routes text through local commands, personality commands, or the configured LLM provider.
• MemoryManager extracts and filters durable facts before persistence.
• SQLite stores conversations, memories, events, logs, and command metadata.
• FaceRepository exists as a persistence layer for future face enrollment/recognition, but enrollment and identity matching are not active yet.

Observability

• The WebUI reads diagnostics snapshots, runtime state, event-bus metrics, and SQLite repositories.
• The /vision page reads compact diagnostics and renders image quality, face detection counters, reject reasons, and bounding boxes over the latest snapshot.
• Endpoints stay read-only; operational changes happen through voice commands or direct database access.

Core Responsibilities

Source Code Structure

Startup and Bootstrap Flow

Startup begins in cosmo/main.py:

import asyncio
from cosmo.core.bootstrap.bootstrap import bootstrap

if __name__ == "__main__":
    asyncio.run(bootstrap.start())

Listener registration happens through import side effects in bootstrap.py.

Shutdown sets lifecycle.running = False, emits system_shutdown on the sync bus, calls async_runtime.shutdown(), and logs completion.