# abuzar-ansarii/ultron architecture

> Architecture diagram of the GitHub repository abuzar-ansarii/ultron, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abuzar-ansarii/ultron
- Repository: https://github.com/abuzar-ansarii/ultron

## Overview

Ultron AI is a voice-first desktop assistant: a user speaks or types a directive, the runtime interprets it, dispatches workstation actions, and presents results through its interface or speech. Its capabilities span system control, proactive context monitoring, gesture input, IoT, web research, and persistent memory. The graph shows the documented workflow and sampled/indexed call relationships; many individual action implementations were not sampled, so their internal dispatch paths are not inferred.

Main entry points: [`main.py`](https://github.com/abuzar-ansarii/ultron/blob/main/main.py) (Conversation Runtime), [`ui.py`](https://github.com/abuzar-ansarii/ultron/blob/main/ui.py) (Desktop Interface), [`actions/screen_processor.py`](https://github.com/abuzar-ansarii/ultron/blob/main/actions/screen_processor.py) (Screen Processing), [`core/action_loader.py`](https://github.com/abuzar-ansarii/ultron/blob/main/core/action_loader.py) (Action Loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Assistant Runtime"]
  node_main["Conversation Runtime<br/>[main.py]"]
  node_action_loader["Action Loader<br/>[action_loader.py]"]
  node_plugin_loader["Plugin Loader<br/>[plugin_loader.py]"]
  node_config[("Configuration<br/>[config_manager.py]")]
end

subgraph group_interaction["User Interaction"]
  node_ui["Desktop Interface<br/>[ui.py]"]
  node_wake["Wake Word<br/>[wake_word.py]"]
  node_stt["Speech Recognition<br/>[stt.py]"]
  node_tts["Speech Synthesis<br/>[tts.py]"]
  node_audio_devices["Audio Devices<br/>[audio_devices.py]"]
  node_task_animator["HUD Animation<br/>[task_animator.py]"]
end

subgraph group_capabilities["Workstation Capabilities"]
  node_tools["Workstation Tools"]
  node_self_evolution["Self Evolution<br/>[self_evolution.py]"]
  node_chronos["Proactive Monitor"]
  node_gesture["Gesture Control<br/>[gesture_control.py]"]
  node_workspace["Workspace Modes"]
  node_iot["IoT Control<br/>[iot_overlord.py]"]
  node_screen["Screen Processing"]
  node_audio_matrix["Audio Control<br/>[audio_matrix.py]"]
end

subgraph group_knowledge["Knowledge and AI"]
  node_search["Web Search<br/>[web_search.py]"]
  node_memory[("Assistant Memory<br/>[memory_manager.py]")]
  node_cerebro[("Cerebro Graph<br/>[cerebro_graph.py]")]
  node_llm["LLM Client<br/>[llm_client.py]"]
  node_gemini["Gemini Services<br/>[gemini.py]"]
end

subgraph group_interfaces["Remote Interfaces"]
  node_telegram["Telegram Control<br/>[telegram_bot.py]"]
  node_dashboard["Web Dashboard<br/>[server.py]"]
end

node_user(("User"))
node_llm_service{{"LLM Providers"}}
node_gemini_service{{"Gemini API"}}
node_telegram_service{{"Telegram API"}}

node_user -->|"directs"| node_ui
node_user -->|"speaks to"| node_wake
node_wake -.->|"wakes"| node_main
node_stt -.->|"transcribes for"| node_main
node_ui -->|"submits directives"| node_main
node_main -->|"loads actions"| node_action_loader
node_main -->|"loads plugins"| node_plugin_loader
node_action_loader -.->|"dispatches tools"| node_tools
node_self_evolution -->|"hot-loads actions"| node_action_loader
node_self_evolution -->|"hot-loads plugins"| node_plugin_loader
node_main -->|"updates memory"| node_memory
node_main -->|"processes screen"| node_screen
node_main -->|"invokes search"| node_search
node_screen -->|"analyzes with"| node_gemini
node_screen -->|"uses audio controls"| node_audio_matrix
node_search -->|"uses grounding"| node_gemini
node_llm -->|"requests completion"| node_llm_service
node_gemini -.->|"calls"| node_gemini_service
node_main -->|"reads settings"| node_config
node_ui -->|"uses memory"| node_memory
node_ui -->|"uses speech"| node_tts
node_ui -->|"selects devices"| node_audio_devices
node_ui -->|"uses wake word"| node_wake
node_ui -->|"animates HUD"| node_task_animator
node_tts -->|"uses devices"| node_audio_devices
node_main -->|"initializes control"| node_telegram
node_telegram -->|"polls and sends"| node_telegram_service
node_main -.->|"connects dashboard"| node_dashboard
node_main -->|"starts monitoring"| node_chronos
node_main -.->|"offers gesture tool"| node_gesture
node_main -.->|"dispatches workspace mode"| node_workspace
node_main -.->|"dispatches room control"| node_iot
node_main -.->|"supports graph recall"| node_cerebro

click node_main "https://github.com/abuzar-ansarii/ultron/blob/main/main.py"
click node_action_loader "https://github.com/abuzar-ansarii/ultron/blob/main/core/action_loader.py"
click node_plugin_loader "https://github.com/abuzar-ansarii/ultron/blob/main/core/plugin_loader.py"
click node_tools "https://github.com/abuzar-ansarii/ultron/tree/main/actions"
click node_self_evolution "https://github.com/abuzar-ansarii/ultron/blob/main/actions/self_evolution.py"
click node_chronos "https://github.com/abuzar-ansarii/ultron/blob/main/actions/chronos_predictive.py"
click node_gesture "https://github.com/abuzar-ansarii/ultron/blob/main/actions/gesture_control.py"
click node_workspace "https://github.com/abuzar-ansarii/ultron/blob/main/actions/workspace_matrix.py"
click node_iot "https://github.com/abuzar-ansarii/ultron/blob/main/actions/iot_overlord.py"
click node_screen "https://github.com/abuzar-ansarii/ultron/blob/main/actions/screen_processor.py"
click node_audio_matrix "https://github.com/abuzar-ansarii/ultron/blob/main/actions/audio_matrix.py"
click node_search "https://github.com/abuzar-ansarii/ultron/blob/main/actions/web_search.py"
click node_memory "https://github.com/abuzar-ansarii/ultron/blob/main/memory/memory_manager.py"
click node_cerebro "https://github.com/abuzar-ansarii/ultron/blob/main/memory/cerebro_graph.py"
click node_llm "https://github.com/abuzar-ansarii/ultron/blob/main/core/llm_client.py"
click node_gemini "https://github.com/abuzar-ansarii/ultron/blob/main/core/gemini.py"
click node_config "https://github.com/abuzar-ansarii/ultron/blob/main/memory/config_manager.py"
click node_ui "https://github.com/abuzar-ansarii/ultron/blob/main/ui.py"
click node_wake "https://github.com/abuzar-ansarii/ultron/blob/main/core/wake_word.py"
click node_stt "https://github.com/abuzar-ansarii/ultron/blob/main/core/stt.py"
click node_tts "https://github.com/abuzar-ansarii/ultron/blob/main/core/tts.py"
click node_audio_devices "https://github.com/abuzar-ansarii/ultron/blob/main/core/audio_devices.py"
click node_task_animator "https://github.com/abuzar-ansarii/ultron/blob/main/core/task_animator.py"
click node_telegram "https://github.com/abuzar-ansarii/ultron/blob/main/core/telegram_bot.py"
click node_dashboard "https://github.com/abuzar-ansarii/ultron/blob/main/dashboard/server.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_main,node_action_loader,node_plugin_loader,node_config,node_user toneBlue
class node_ui,node_wake,node_stt,node_tts,node_audio_devices,node_task_animator toneAmber
class node_tools,node_self_evolution,node_chronos,node_gesture,node_workspace,node_iot,node_screen,node_audio_matrix,node_gemini_service,node_telegram_service toneMint
class node_search,node_memory,node_cerebro,node_llm,node_gemini toneRose
class node_telegram,node_dashboard,node_llm_service toneIndigo
```

## Components

### Assistant Runtime

- [Conversation Runtime](https://github.com/abuzar-ansarii/ultron/blob/main/main.py): `main.py`
- [Action Loader](https://github.com/abuzar-ansarii/ultron/blob/main/core/action_loader.py): `core/action_loader.py`
- [Plugin Loader](https://github.com/abuzar-ansarii/ultron/blob/main/core/plugin_loader.py): `core/plugin_loader.py`
- [Configuration](https://github.com/abuzar-ansarii/ultron/blob/main/memory/config_manager.py): `memory/config_manager.py`

### User Interaction

- [Desktop Interface](https://github.com/abuzar-ansarii/ultron/blob/main/ui.py): `ui.py`
- [Wake Word](https://github.com/abuzar-ansarii/ultron/blob/main/core/wake_word.py): `core/wake_word.py`
- [Speech Recognition](https://github.com/abuzar-ansarii/ultron/blob/main/core/stt.py): `core/stt.py`
- [Speech Synthesis](https://github.com/abuzar-ansarii/ultron/blob/main/core/tts.py): `core/tts.py`
- [Audio Devices](https://github.com/abuzar-ansarii/ultron/blob/main/core/audio_devices.py): `core/audio_devices.py`
- [HUD Animation](https://github.com/abuzar-ansarii/ultron/blob/main/core/task_animator.py): `core/task_animator.py`

### Workstation Capabilities

- [Workstation Tools](https://github.com/abuzar-ansarii/ultron/tree/main/actions): `actions`
- [Self Evolution](https://github.com/abuzar-ansarii/ultron/blob/main/actions/self_evolution.py): `actions/self_evolution.py`
- [Proactive Monitor](https://github.com/abuzar-ansarii/ultron/blob/main/actions/chronos_predictive.py): `actions/chronos_predictive.py`
- [Gesture Control](https://github.com/abuzar-ansarii/ultron/blob/main/actions/gesture_control.py): `actions/gesture_control.py`
- [Workspace Modes](https://github.com/abuzar-ansarii/ultron/blob/main/actions/workspace_matrix.py): `actions/workspace_matrix.py`
- [IoT Control](https://github.com/abuzar-ansarii/ultron/blob/main/actions/iot_overlord.py): `actions/iot_overlord.py`
- [Screen Processing](https://github.com/abuzar-ansarii/ultron/blob/main/actions/screen_processor.py): `actions/screen_processor.py`
- [Audio Control](https://github.com/abuzar-ansarii/ultron/blob/main/actions/audio_matrix.py): `actions/audio_matrix.py`

### Knowledge and AI

- [Web Search](https://github.com/abuzar-ansarii/ultron/blob/main/actions/web_search.py): `actions/web_search.py`
- [Assistant Memory](https://github.com/abuzar-ansarii/ultron/blob/main/memory/memory_manager.py): `memory/memory_manager.py`
- [Cerebro Graph](https://github.com/abuzar-ansarii/ultron/blob/main/memory/cerebro_graph.py): `memory/cerebro_graph.py`
- [LLM Client](https://github.com/abuzar-ansarii/ultron/blob/main/core/llm_client.py): `core/llm_client.py`
- [Gemini Services](https://github.com/abuzar-ansarii/ultron/blob/main/core/gemini.py): `core/gemini.py`

### Remote Interfaces

- [Telegram Control](https://github.com/abuzar-ansarii/ultron/blob/main/core/telegram_bot.py): `core/telegram_bot.py`
- [Web Dashboard](https://github.com/abuzar-ansarii/ultron/blob/main/dashboard/server.py): `dashboard/server.py`

### Other components

- **User**
- **LLM Providers**
- **Gemini API**
- **Telegram API**

## Connections

- User → Desktop Interface: directs (evidence: `README.md`)
- User → Wake Word: speaks to (evidence: `README.md`)
- Wake Word → Conversation Runtime: wakes (evidence: `main.py`)
- Speech Recognition → Conversation Runtime: transcribes for
- Desktop Interface → Conversation Runtime: submits directives (evidence: `main.py`)
- Conversation Runtime → Action Loader: loads actions (evidence: `main.py`)
- Conversation Runtime → Plugin Loader: loads plugins (evidence: `main.py`)
- Action Loader → Workstation Tools: dispatches tools (evidence: `actions/self_evolution.py`)
- Self Evolution → Action Loader: hot-loads actions (evidence: `actions/self_evolution.py`)
- Self Evolution → Plugin Loader: hot-loads plugins (evidence: `actions/self_evolution.py`)
- Conversation Runtime → Assistant Memory: updates memory (evidence: `main.py`)
- Conversation Runtime → Screen Processing: processes screen (evidence: `main.py`)
- Conversation Runtime → Web Search: invokes search (evidence: `main.py`)
- Screen Processing → Gemini Services: analyzes with (evidence: `actions/screen_processor.py`)
- Screen Processing → Audio Control: uses audio controls (evidence: `actions/screen_processor.py`)
- Web Search → Gemini Services: uses grounding (evidence: `actions/web_search.py`)
- LLM Client → LLM Providers: requests completion (evidence: `core/llm_client.py`)
- Gemini Services → Gemini API: calls
- Conversation Runtime → Configuration: reads settings (evidence: `main.py`)
- Desktop Interface → Assistant Memory: uses memory (evidence: `ui.py`)
- Desktop Interface → Speech Synthesis: uses speech (evidence: `ui.py`)
- Desktop Interface → Audio Devices: selects devices (evidence: `ui.py`)
- Desktop Interface → Wake Word: uses wake word (evidence: `ui.py`)
- Desktop Interface → HUD Animation: animates HUD (evidence: `ui.py`)
- Speech Synthesis → Audio Devices: uses devices (evidence: `core/tts.py`)
- Conversation Runtime → Telegram Control: initializes control (evidence: `main.py`)
- Telegram Control → Telegram API: polls and sends (evidence: `core/telegram_bot.py`)
- Conversation Runtime → Web Dashboard: connects dashboard (evidence: `main.py`)
- Conversation Runtime → Proactive Monitor: starts monitoring (evidence: `main.py`)
- Conversation Runtime → Gesture Control: offers gesture tool
- Conversation Runtime → Workspace Modes: dispatches workspace mode
- Conversation Runtime → IoT Control: dispatches room control
- Conversation Runtime → Cerebro Graph: supports graph recall