# absentdaemon-ctrl/kosmosxproject architecture

> Architecture diagram of the GitHub repository absentdaemon-ctrl/kosmosxproject, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/absentdaemon-ctrl/kosmosxproject
- Repository: https://github.com/absentdaemon-ctrl/kosmosxproject

## Overview

KOS-MOS is a desktop AI assistant whose primary workflow is voice input → speech recognition → LLM planning and tool calls → spoken response. Tool execution is mediated by safety checks, user confirmation, verification, and persistent task/audit records. The README documents launching the assistant and configuring Groq/HuggingFace credentials; sampled runtime wiring clarifies the voice, UI, tool, and storage paths. Some tool/API details and UI assets were not sampled, so those branches are represented at their supported directory level.

Main entry points: [`src/kos_mos/tools/registry.py`](https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/tools/registry.py) (Tool Registry), [`src/kos_mos/voice/pipeline.py`](https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/voice/pipeline.py) (Voice Pipeline), [`src/kos_mos/__main__.py`](https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/__main__.py) (Desktop App), [`src/kos_mos/mcp/loader.py`](https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/mcp/loader.py) (MCP Tool Loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop and Voice"]
  node_app["Desktop App<br/>[__main__.py]"]
  node_voice["Voice Pipeline<br/>[pipeline.py]"]
  node_capture["Audio Capture<br/>[audio_capture.py]"]
  node_stt["Speech Recognition<br/>[stt.py]"]
  node_tts["Speech Output<br/>[tts.py]"]
end

subgraph group_reasoning["Reasoning"]
  node_llm["Groq LLM Adapter<br/>[groq_adapter.py]"]
  node_config["Runtime Settings<br/>[config.py]"]
end

subgraph group_tools["Tool Execution"]
  node_registry["Tool Registry<br/>[registry.py]"]
  node_computer["Computer Control<br/>[computer.py]"]
  node_desktop_tools["Desktop Tools"]
  node_api_tools["Information APIs"]
  node_mcp_loader["MCP Tool Loader<br/>[loader.py]"]
  node_mcp_client["MCP Client<br/>[client.py]"]
  node_mcp_tool["MCP Tool Adapter<br/>[tool.py]"]
end

subgraph group_guardrails["Safety and Verification"]
  node_policy["Safety Policy<br/>[policy.py]"]
  node_confirmation["User Confirmation<br/>[confirmation.py]"]
  node_verification["Result Verification<br/>[manager.py]"]
end

subgraph group_persistence["Persistence and Telemetry"]
  node_profiler["Performance Profiler<br/>[profiler.py]"]
  node_session["Session and Tasks<br/>[session.py]"]
  node_audit["Audit Log<br/>[audit.py]"]
  node_database[("SQLite Store<br/>[database.py]")]
end

node_user(("User"))

node_user -->|"starts assistant"| node_app
node_app -->|"starts pipeline"| node_voice
node_app -->|"sets UI callbacks"| node_confirmation
node_user -.->|"speaks requests"| node_voice
node_voice -->|"captures audio"| node_capture
node_voice -->|"transcribes speech"| node_stt
node_voice -->|"requests responses"| node_llm
node_voice -->|"dispatches calls"| node_registry
node_voice -->|"speaks replies"| node_tts
node_voice -->|"cancels pending"| node_confirmation
node_voice -->|"records completion"| node_session
node_voice -->|"tracks stages"| node_profiler
node_llm -->|"loads settings"| node_config
node_registry -->|"evaluates risk"| node_policy
node_registry -->|"requests approval"| node_confirmation
node_registry -->|"requests verification"| node_verification
node_registry -->|"logs execution"| node_audit
node_registry -->|"records execution"| node_session
node_registry -->|"registers tools"| node_computer
node_registry -->|"registers tools"| node_desktop_tools
node_registry -->|"registers tools"| node_api_tools
node_mcp_loader -->|"connects server"| node_mcp_client
node_mcp_loader -->|"wraps tools"| node_mcp_tool
node_mcp_loader -->|"registers tools"| node_registry
node_mcp_tool -->|"calls remote tool"| node_mcp_client
node_session -->|"reads and writes"| node_database
node_audit -->|"appends events"| node_database
node_app -->|"loads MCP tools"| node_mcp_loader

click node_app "https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/__main__.py"
click node_voice "https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/voice/pipeline.py"
click node_capture "https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/voice/audio_capture.py"
click node_stt "https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/voice/stt.py"
click node_tts "https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/voice/tts.py"
click node_llm "https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/llm/groq_adapter.py"
click node_config "https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/config.py"
click node_profiler "https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/profiler.py"
click node_registry "https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/tools/registry.py"
click node_computer "https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/tools/computer.py"
click node_desktop_tools "https://github.com/absentdaemon-ctrl/kosmosxproject/tree/main/src/kos_mos/tools"
click node_api_tools "https://github.com/absentdaemon-ctrl/kosmosxproject/tree/main/src/kos_mos/tools/apis"
click node_mcp_loader "https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/mcp/loader.py"
click node_mcp_client "https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/mcp/client.py"
click node_mcp_tool "https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/mcp/tool.py"
click node_policy "https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/safety/policy.py"
click node_confirmation "https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/safety/confirmation.py"
click node_verification "https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/verification/manager.py"
click node_session "https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/storage/session.py"
click node_audit "https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/storage/audit.py"
click node_database "https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/storage/database.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_voice,node_capture,node_stt,node_tts,node_user toneBlue
class node_llm,node_config toneAmber
class node_registry,node_computer,node_desktop_tools,node_api_tools,node_mcp_loader,node_mcp_client,node_mcp_tool toneMint
class node_policy,node_confirmation,node_verification toneRose
class node_profiler,node_session,node_audit,node_database toneIndigo
```

## Components

### Desktop and Voice

- [Desktop App](https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/__main__.py): `src/kos_mos/__main__.py`
- [Voice Pipeline](https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/voice/pipeline.py): `src/kos_mos/voice/pipeline.py`
- [Audio Capture](https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/voice/audio_capture.py): `src/kos_mos/voice/audio_capture.py`
- [Speech Recognition](https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/voice/stt.py): `src/kos_mos/voice/stt.py`
- [Speech Output](https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/voice/tts.py): `src/kos_mos/voice/tts.py`

### Reasoning

- [Groq LLM Adapter](https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/llm/groq_adapter.py): `src/kos_mos/llm/groq_adapter.py`
- [Runtime Settings](https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/config.py): `src/kos_mos/config.py`

### Tool Execution

- [Tool Registry](https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/tools/registry.py): `src/kos_mos/tools/registry.py`
- [Computer Control](https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/tools/computer.py): `src/kos_mos/tools/computer.py`
- [Desktop Tools](https://github.com/absentdaemon-ctrl/kosmosxproject/tree/main/src/kos_mos/tools): `src/kos_mos/tools`
- [Information APIs](https://github.com/absentdaemon-ctrl/kosmosxproject/tree/main/src/kos_mos/tools/apis): `src/kos_mos/tools/apis`
- [MCP Tool Loader](https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/mcp/loader.py): `src/kos_mos/mcp/loader.py`
- [MCP Client](https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/mcp/client.py): `src/kos_mos/mcp/client.py`
- [MCP Tool Adapter](https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/mcp/tool.py): `src/kos_mos/mcp/tool.py`

### Safety and Verification

- [Safety Policy](https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/safety/policy.py): `src/kos_mos/safety/policy.py`
- [User Confirmation](https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/safety/confirmation.py): `src/kos_mos/safety/confirmation.py`
- [Result Verification](https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/verification/manager.py): `src/kos_mos/verification/manager.py`

### Persistence and Telemetry

- [Performance Profiler](https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/profiler.py): `src/kos_mos/profiler.py`
- [Session and Tasks](https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/storage/session.py): `src/kos_mos/storage/session.py`
- [Audit Log](https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/storage/audit.py): `src/kos_mos/storage/audit.py`
- [SQLite Store](https://github.com/absentdaemon-ctrl/kosmosxproject/blob/main/src/kos_mos/storage/database.py): `src/kos_mos/storage/database.py`

### Other components

- **User**

## Connections

- User → Desktop App: starts assistant
- Desktop App → Voice Pipeline: starts pipeline (evidence: `src/kos_mos/__main__.py`)
- Desktop App → User Confirmation: sets UI callbacks (evidence: `src/kos_mos/__main__.py`)
- User → Voice Pipeline: speaks requests
- Voice Pipeline → Audio Capture: captures audio (evidence: `src/kos_mos/voice/pipeline.py`)
- Voice Pipeline → Speech Recognition: transcribes speech (evidence: `src/kos_mos/voice/pipeline.py`)
- Voice Pipeline → Groq LLM Adapter: requests responses (evidence: `src/kos_mos/voice/pipeline.py`)
- Voice Pipeline → Tool Registry: dispatches calls (evidence: `src/kos_mos/voice/pipeline.py`)
- Voice Pipeline → Speech Output: speaks replies (evidence: `src/kos_mos/voice/pipeline.py`)
- Voice Pipeline → User Confirmation: cancels pending (evidence: `src/kos_mos/voice/pipeline.py`)
- Voice Pipeline → Session and Tasks: records completion (evidence: `src/kos_mos/voice/pipeline.py`)
- Voice Pipeline → Performance Profiler: tracks stages (evidence: `src/kos_mos/voice/pipeline.py`)
- Groq LLM Adapter → Runtime Settings: loads settings (evidence: `src/kos_mos/llm/groq_adapter.py`)
- Tool Registry → Safety Policy: evaluates risk (evidence: `src/kos_mos/tools/registry.py`)
- Tool Registry → User Confirmation: requests approval (evidence: `src/kos_mos/tools/registry.py`)
- Tool Registry → Result Verification: requests verification (evidence: `src/kos_mos/tools/registry.py`)
- Tool Registry → Audit Log: logs execution (evidence: `src/kos_mos/tools/registry.py`)
- Tool Registry → Session and Tasks: records execution (evidence: `src/kos_mos/tools/registry.py`)
- Tool Registry → Computer Control: registers tools (evidence: `src/kos_mos/tools/__init__.py`)
- Tool Registry → Desktop Tools: registers tools (evidence: `src/kos_mos/tools/__init__.py`)
- Tool Registry → Information APIs: registers tools (evidence: `src/kos_mos/tools/__init__.py`)
- MCP Tool Loader → MCP Client: connects server (evidence: `src/kos_mos/mcp/loader.py`)
- MCP Tool Loader → MCP Tool Adapter: wraps tools (evidence: `src/kos_mos/mcp/loader.py`)
- MCP Tool Loader → Tool Registry: registers tools (evidence: `src/kos_mos/mcp/loader.py`)
- MCP Tool Adapter → MCP Client: calls remote tool (evidence: `src/kos_mos/mcp/tool.py`)
- Session and Tasks → SQLite Store: reads and writes (evidence: `src/kos_mos/storage/session.py`)
- Audit Log → SQLite Store: appends events (evidence: `src/kos_mos/storage/audit.py`)
- Desktop App → MCP Tool Loader: loads MCP tools (evidence: `src/kos_mos/__main__.py`)
