# xdzy-td/aetheris-aiengine architecture

> Architecture diagram of the GitHub repository xdzy-td/aetheris-aiengine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xdzy-td/aetheris-aiengine
- Repository: https://github.com/xdzy-td/aetheris-aiengine

## Overview

Aetheris is an agentic remote-sensing analysis service: a user submits a question and imagery, the controller plans and executes specialist tools, then returns an answer with evidence and confidence. A separate SAT-OS API adds answerability checks, evidence classification, falsification, verification, and certificates around the analysis pipeline. The repository also contains a modular hardening pipeline and several user interfaces. Edges reflect README statements and shown or indexed references; some module internals are unsampled, so uncertain calls are omitted.

Main entry points: [`controller/planner.py`](https://github.com/xdzy-td/aetheris-aiengine/blob/main/controller/planner.py) (Agentic Planner), [`pipeline/services/sat_pipeline.py`](https://github.com/xdzy-td/aetheris-aiengine/blob/main/pipeline/services/sat_pipeline.py) (SAT-OS Orchestrator), [`interfaces/api/app.py`](https://github.com/xdzy-td/aetheris-aiengine/blob/main/interfaces/api/app.py) (FastAPI), [`interfaces/ui/console.py`](https://github.com/xdzy-td/aetheris-aiengine/blob/main/interfaces/ui/console.py) (Text Console)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_api["FastAPI<br/>[app.py]"]
  node_console["Text Console<br/>[console.py]"]
  node_voice["Voice I/O"]
  node_sat_api["SAT-OS Routes<br/>[sat_routes.py]"]
end

subgraph group_controller["Agentic Controller"]
  node_planner["Agentic Planner<br/>[planner.py]"]
  node_llm["LLM Planner<br/>[llm_planner.py]"]
  node_ollama["Ollama Client<br/>[ollama_client.py]"]
  node_policy["Policy Engine<br/>[policy.py]"]
  node_executor["Tool Executor<br/>[executor.py]"]
  node_registry["Tool Registry<br/>[tool_registry.py]"]
  node_memory[("Routing Memory<br/>[memory.py]")]
  node_audit[("Audit Trail<br/>[audit_log.py]")]
  node_artifacts[("Artifact Store<br/>[artifacts.py]")]
  node_models[("Model Registry<br/>[model_registry.py]")]
end

subgraph group_analysis["Imagery Analysis"]
  node_specialists["Specialist Tools"]
  node_imagery["Imagery I/O<br/>[_imagery.py]"]
  node_preprocessing["Image Preprocessing"]
  node_confidence["Confidence Scoring"]
end

subgraph group_pipeline["Pipeline Services"]
  node_sat_pipeline["SAT-OS Orchestrator<br/>[sat_pipeline.py]"]
  node_sat_stages["Evidence &amp; Verification"]
  node_pipeline_service["Aetheris Pipeline<br/>[pipeline.py]"]
  node_contracts["Result Contracts<br/>[contracts.py]"]
end

node_user(("Analyst"))
node_external_ollama(("Ollama Service"))

node_user -->|"submits query"| node_api
node_user -->|"submits query"| node_console
node_api -->|"routes requests"| node_planner
node_console -->|"shares wiring"| node_planner
node_planner -->|"requests plans"| node_llm
node_llm -->|"requests completion"| node_ollama
node_ollama -->|"sends requests"| node_external_ollama
node_planner -->|"validates plan"| node_policy
node_planner -->|"executes plan"| node_executor
node_planner -->|"loads tools"| node_registry
node_executor -->|"invokes tools"| node_specialists
node_specialists -->|"uses imagery I/O"| node_imagery
node_planner -->|"scores results"| node_confidence
node_planner -->|"records execution"| node_audit
node_planner -->|"uses routing memory"| node_memory
node_planner -->|"stores artifacts"| node_artifacts
node_planner -->|"resolves models"| node_models
node_user -->|"submits SAT query"| node_sat_api
node_sat_api -->|"runs analysis"| node_sat_pipeline
node_sat_pipeline -->|"runs inner pipeline"| node_pipeline_service
node_sat_pipeline -->|"classifies and verifies"| node_sat_stages
node_sat_pipeline -->|"builds request"| node_contracts
node_pipeline_service -->|"returns module results"| node_contracts
node_api -.->|"supports preprocessing"| node_preprocessing
node_voice -.->|"provides voice input"| node_api

click node_api "https://github.com/xdzy-td/aetheris-aiengine/blob/main/interfaces/api/app.py"
click node_console "https://github.com/xdzy-td/aetheris-aiengine/blob/main/interfaces/ui/console.py"
click node_voice "https://github.com/xdzy-td/aetheris-aiengine/tree/main/interfaces/voice"
click node_planner "https://github.com/xdzy-td/aetheris-aiengine/blob/main/controller/planner.py"
click node_llm "https://github.com/xdzy-td/aetheris-aiengine/blob/main/controller/llm_planner.py"
click node_ollama "https://github.com/xdzy-td/aetheris-aiengine/blob/main/controller/ollama_client.py"
click node_policy "https://github.com/xdzy-td/aetheris-aiengine/blob/main/controller/policy.py"
click node_executor "https://github.com/xdzy-td/aetheris-aiengine/blob/main/controller/executor.py"
click node_registry "https://github.com/xdzy-td/aetheris-aiengine/blob/main/controller/tool_registry.py"
click node_memory "https://github.com/xdzy-td/aetheris-aiengine/blob/main/controller/memory.py"
click node_audit "https://github.com/xdzy-td/aetheris-aiengine/blob/main/controller/audit_log.py"
click node_artifacts "https://github.com/xdzy-td/aetheris-aiengine/blob/main/controller/artifacts.py"
click node_models "https://github.com/xdzy-td/aetheris-aiengine/blob/main/controller/model_registry.py"
click node_specialists "https://github.com/xdzy-td/aetheris-aiengine/tree/main/specialists"
click node_imagery "https://github.com/xdzy-td/aetheris-aiengine/blob/main/specialists/_imagery.py"
click node_preprocessing "https://github.com/xdzy-td/aetheris-aiengine/tree/main/preprocessing"
click node_confidence "https://github.com/xdzy-td/aetheris-aiengine/tree/main/confidence"
click node_sat_api "https://github.com/xdzy-td/aetheris-aiengine/blob/main/interfaces/api/sat_routes.py"
click node_sat_pipeline "https://github.com/xdzy-td/aetheris-aiengine/blob/main/pipeline/services/sat_pipeline.py"
click node_sat_stages "https://github.com/xdzy-td/aetheris-aiengine/tree/main/pipeline/modules"
click node_pipeline_service "https://github.com/xdzy-td/aetheris-aiengine/blob/main/pipeline/services/pipeline.py"
click node_contracts "https://github.com/xdzy-td/aetheris-aiengine/blob/main/pipeline/schemas/contracts.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_api,node_console,node_voice,node_sat_api toneBlue
class node_planner,node_llm,node_ollama,node_policy,node_executor,node_registry,node_memory,node_audit,node_artifacts,node_models toneAmber
class node_specialists,node_imagery,node_preprocessing,node_confidence toneMint
class node_sat_pipeline,node_sat_stages,node_pipeline_service,node_contracts toneRose
class node_user,node_external_ollama toneIndigo
```

## Components

### User Interfaces

- [FastAPI](https://github.com/xdzy-td/aetheris-aiengine/blob/main/interfaces/api/app.py): `interfaces/api/app.py`
- [Text Console](https://github.com/xdzy-td/aetheris-aiengine/blob/main/interfaces/ui/console.py): `interfaces/ui/console.py`
- [Voice I/O](https://github.com/xdzy-td/aetheris-aiengine/tree/main/interfaces/voice): `interfaces/voice`
- [SAT-OS Routes](https://github.com/xdzy-td/aetheris-aiengine/blob/main/interfaces/api/sat_routes.py): `interfaces/api/sat_routes.py`

### Agentic Controller

- [Agentic Planner](https://github.com/xdzy-td/aetheris-aiengine/blob/main/controller/planner.py): `controller/planner.py`
- [LLM Planner](https://github.com/xdzy-td/aetheris-aiengine/blob/main/controller/llm_planner.py): `controller/llm_planner.py`
- [Ollama Client](https://github.com/xdzy-td/aetheris-aiengine/blob/main/controller/ollama_client.py): `controller/ollama_client.py`
- [Policy Engine](https://github.com/xdzy-td/aetheris-aiengine/blob/main/controller/policy.py): `controller/policy.py`
- [Tool Executor](https://github.com/xdzy-td/aetheris-aiengine/blob/main/controller/executor.py): `controller/executor.py`
- [Tool Registry](https://github.com/xdzy-td/aetheris-aiengine/blob/main/controller/tool_registry.py): `controller/tool_registry.py`
- [Routing Memory](https://github.com/xdzy-td/aetheris-aiengine/blob/main/controller/memory.py): `controller/memory.py`
- [Audit Trail](https://github.com/xdzy-td/aetheris-aiengine/blob/main/controller/audit_log.py): `controller/audit_log.py`
- [Artifact Store](https://github.com/xdzy-td/aetheris-aiengine/blob/main/controller/artifacts.py): `controller/artifacts.py`
- [Model Registry](https://github.com/xdzy-td/aetheris-aiengine/blob/main/controller/model_registry.py): `controller/model_registry.py`

### Imagery Analysis

- [Specialist Tools](https://github.com/xdzy-td/aetheris-aiengine/tree/main/specialists): `specialists`
- [Imagery I/O](https://github.com/xdzy-td/aetheris-aiengine/blob/main/specialists/_imagery.py): `specialists/_imagery.py`
- [Image Preprocessing](https://github.com/xdzy-td/aetheris-aiengine/tree/main/preprocessing): `preprocessing`
- [Confidence Scoring](https://github.com/xdzy-td/aetheris-aiengine/tree/main/confidence): `confidence`

### Pipeline Services

- [SAT-OS Orchestrator](https://github.com/xdzy-td/aetheris-aiengine/blob/main/pipeline/services/sat_pipeline.py): `pipeline/services/sat_pipeline.py`
- [Evidence & Verification](https://github.com/xdzy-td/aetheris-aiengine/tree/main/pipeline/modules): `pipeline/modules`
- [Aetheris Pipeline](https://github.com/xdzy-td/aetheris-aiengine/blob/main/pipeline/services/pipeline.py): `pipeline/services/pipeline.py`
- [Result Contracts](https://github.com/xdzy-td/aetheris-aiengine/blob/main/pipeline/schemas/contracts.py): `pipeline/schemas/contracts.py`

### Other components

- **Analyst**
- **Ollama Service**

## Connections

- Analyst → FastAPI: submits query (evidence: `README.md`)
- Analyst → Text Console: submits query (evidence: `README.md`)
- FastAPI → Agentic Planner: routes requests (evidence: `interfaces/api/app.py`)
- Text Console → Agentic Planner: shares wiring
- Agentic Planner → LLM Planner: requests plans (evidence: `controller/planner.py`)
- LLM Planner → Ollama Client: requests completion (evidence: `controller/llm_planner.py`)
- Ollama Client → Ollama Service: sends requests (evidence: `controller/ollama_client.py`)
- Agentic Planner → Policy Engine: validates plan (evidence: `controller/planner.py`)
- Agentic Planner → Tool Executor: executes plan (evidence: `controller/planner.py`)
- Agentic Planner → Tool Registry: loads tools (evidence: `controller/planner.py`)
- Tool Executor → Specialist Tools: invokes tools (evidence: `README.md`)
- Specialist Tools → Imagery I/O: uses imagery I/O (evidence: `specialists/_imagery.py`)
- Agentic Planner → Confidence Scoring: scores results (evidence: `controller/planner.py`)
- Agentic Planner → Audit Trail: records execution (evidence: `controller/planner.py`)
- Agentic Planner → Routing Memory: uses routing memory (evidence: `controller/planner.py`)
- Agentic Planner → Artifact Store: stores artifacts (evidence: `interfaces/api/app.py`)
- Agentic Planner → Model Registry: resolves models (evidence: `controller/planner.py`)
- Analyst → SAT-OS Routes: submits SAT query (evidence: `interfaces/api/sat_routes.py`)
- SAT-OS Routes → SAT-OS Orchestrator: runs analysis (evidence: `interfaces/api/sat_routes.py`)
- SAT-OS Orchestrator → Aetheris Pipeline: runs inner pipeline (evidence: `pipeline/services/sat_pipeline.py`)
- SAT-OS Orchestrator → Evidence & Verification: classifies and verifies (evidence: `pipeline/services/sat_pipeline.py`)
- SAT-OS Orchestrator → Result Contracts: builds request (evidence: `pipeline/services/sat_pipeline.py`)
- Aetheris Pipeline → Result Contracts: returns module results (evidence: `pipeline/services/pipeline.py`)
- FastAPI → Image Preprocessing: supports preprocessing
- Voice I/O → FastAPI: provides voice input