# i3t4an/kadath architecture

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

- Interactive diagram: https://gitdiagram.com/i3t4an/kadath
- Repository: https://github.com/i3t4an/kadath

## Overview

KADATH evolves complete agent genomes through a locked, measured competition: the user configures a goal and run, approves an Architect-built benchmark, and the kernel creates and executes a population in isolated epochs. Grading informs selection and post-grade mutation; Git lineage and stored evidence preserve the run. Organisms use the vendored smolagents framework and may receive approved browser or worker capabilities. The README establishes the principal workflow and kernel responsibilities; sampled code confirms selected runtime interfaces and imports, but does not expose the full grading, selection, or recovery implementation.

Main entry points: [`kadath/engine.py`](https://github.com/i3t4an/kadath/blob/main/kadath/engine.py) (Run kernel), [`seed/smolagents/src/smolagents/agents.py`](https://github.com/i3t4an/kadath/blob/main/seed/smolagents/src/smolagents/agents.py) (Code agent), [`seed/organism.py`](https://github.com/i3t4an/kadath/blob/main/seed/organism.py) (Organism entrypoint), [`kadath/cli.py`](https://github.com/i3t4an/kadath/blob/main/kadath/cli.py) (Terminal interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_control["Run control"]
  node_cli["Terminal interface<br/>[cli.py]"]
  node_engine["Run kernel<br/>[engine.py]"]
  node_benchmark["Architect benchmark<br/>[specialists.py]"]
end

subgraph group_evolution["Evolution loop"]
  node_grader["Grader specialist<br/>[specialists.py]"]
  node_tweaker["Tweaker and Birther<br/>[specialists.py]"]
  node_population["Population selection<br/>[engine.py]"]
  node_genomes[("Genome lineage<br/>[gitstore.py]")]
  node_mutations["Genome mutation<br/>[mutations.py]"]
  node_evidence[("Artifacts and evidence<br/>[artifacts.py]")]
  node_state[("Run state store<br/>[store.py]")]
end

subgraph group_runtime["Organism runtime"]
  node_organism["Organism entrypoint<br/>[organism.py]"]
  node_runtime_contract["Epoch runtime<br/>[kadath_runtime.py]"]
  node_container_entry["Container entrypoint"]
end

subgraph group_operations["Execution services"]
  node_executor["Agent executor<br/>[executors.py]"]
  node_containers["Isolated containers<br/>[containers.py]"]
  node_browser["Browser capability<br/>[browsers.py]"]
  node_worker["Worker broker<br/>[worker_broker.py]"]
  node_workers["Worker execution<br/>[workers.py]"]
end

subgraph group_framework["Agent framework"]
  node_agent["Code agent<br/>[agents.py]"]
  node_models["Model adapters<br/>[models.py]"]
  node_tools["Tools<br/>[tools.py]"]
  node_memory[("Agent memory<br/>[memory.py]")]
  node_local_exec["Python executor"]
  node_remote_exec["Remote executor"]
  node_monitoring["Agent monitoring<br/>[monitoring.py]"]
end

node_user(("User"))

node_user -->|"configures run"| node_cli
node_cli -->|"starts run"| node_engine
node_engine -->|"requests benchmark"| node_benchmark
node_user -->|"approves benchmark"| node_benchmark
node_engine -->|"records lineage"| node_genomes
node_engine -->|"runs epoch"| node_executor
node_executor -->|"isolates organism"| node_containers
node_containers -->|"starts organism"| node_organism
node_organism -->|"uses runtime"| node_runtime_contract
node_organism -->|"runs agent"| node_agent
node_agent -->|"calls model"| node_models
node_agent -->|"dispatches tools"| node_tools
node_agent -->|"records steps"| node_memory
node_agent -->|"reports activity"| node_monitoring
node_agent -->|"uses executor"| node_local_exec
node_agent -->|"uses executor"| node_remote_exec
node_engine -->|"grades attempts"| node_grader
node_grader -->|"scores population"| node_population
node_population -->|"selects performers"| node_tweaker
node_tweaker -->|"guides mutation"| node_mutations
node_engine -->|"retains evidence"| node_evidence
node_engine -->|"stores run state"| node_state
node_engine -.->|"enables capability"| node_browser
node_engine -.->|"enables workers"| node_worker
node_worker -->|"dispatches work"| node_workers
node_engine -.->|"starts container"| node_container_entry

click node_cli "https://github.com/i3t4an/kadath/blob/main/kadath/cli.py"
click node_engine "https://github.com/i3t4an/kadath/blob/main/kadath/engine.py"
click node_benchmark "https://github.com/i3t4an/kadath/blob/main/kadath/specialists.py"
click node_grader "https://github.com/i3t4an/kadath/blob/main/kadath/specialists.py"
click node_tweaker "https://github.com/i3t4an/kadath/blob/main/kadath/specialists.py"
click node_population "https://github.com/i3t4an/kadath/blob/main/kadath/engine.py"
click node_genomes "https://github.com/i3t4an/kadath/blob/main/kadath/gitstore.py"
click node_mutations "https://github.com/i3t4an/kadath/blob/main/kadath/mutations.py"
click node_evidence "https://github.com/i3t4an/kadath/blob/main/kadath/artifacts.py"
click node_state "https://github.com/i3t4an/kadath/blob/main/kadath/store.py"
click node_organism "https://github.com/i3t4an/kadath/blob/main/seed/organism.py"
click node_runtime_contract "https://github.com/i3t4an/kadath/blob/main/seed/kadath_runtime.py"
click node_container_entry "https://github.com/i3t4an/kadath/blob/main/seed/container_entrypoint.py"
click node_executor "https://github.com/i3t4an/kadath/blob/main/kadath/executors.py"
click node_containers "https://github.com/i3t4an/kadath/blob/main/kadath/containers.py"
click node_browser "https://github.com/i3t4an/kadath/blob/main/kadath/browsers.py"
click node_worker "https://github.com/i3t4an/kadath/blob/main/kadath/worker_broker.py"
click node_workers "https://github.com/i3t4an/kadath/blob/main/kadath/workers.py"
click node_agent "https://github.com/i3t4an/kadath/blob/main/seed/smolagents/src/smolagents/agents.py"
click node_models "https://github.com/i3t4an/kadath/blob/main/seed/smolagents/src/smolagents/models.py"
click node_tools "https://github.com/i3t4an/kadath/blob/main/seed/smolagents/src/smolagents/tools.py"
click node_memory "https://github.com/i3t4an/kadath/blob/main/seed/smolagents/src/smolagents/memory.py"
click node_local_exec "https://github.com/i3t4an/kadath/blob/main/seed/smolagents/src/smolagents/local_python_executor.py"
click node_remote_exec "https://github.com/i3t4an/kadath/blob/main/seed/smolagents/src/smolagents/remote_executors.py"
click node_monitoring "https://github.com/i3t4an/kadath/blob/main/seed/smolagents/src/smolagents/monitoring.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_cli,node_engine,node_benchmark,node_user toneBlue
class node_grader,node_tweaker,node_population,node_genomes,node_mutations,node_evidence,node_state toneAmber
class node_organism,node_runtime_contract,node_container_entry toneMint
class node_executor,node_containers,node_browser,node_worker,node_workers toneRose
class node_agent,node_models,node_tools,node_memory,node_local_exec,node_remote_exec,node_monitoring toneIndigo
```

## Components

### Run control

- [Terminal interface](https://github.com/i3t4an/kadath/blob/main/kadath/cli.py): `kadath/cli.py`
- [Run kernel](https://github.com/i3t4an/kadath/blob/main/kadath/engine.py): `kadath/engine.py`
- [Architect benchmark](https://github.com/i3t4an/kadath/blob/main/kadath/specialists.py): `kadath/specialists.py`

### Evolution loop

- [Grader specialist](https://github.com/i3t4an/kadath/blob/main/kadath/specialists.py): `kadath/specialists.py`
- [Tweaker and Birther](https://github.com/i3t4an/kadath/blob/main/kadath/specialists.py): `kadath/specialists.py`
- [Population selection](https://github.com/i3t4an/kadath/blob/main/kadath/engine.py): `kadath/engine.py`
- [Genome lineage](https://github.com/i3t4an/kadath/blob/main/kadath/gitstore.py): `kadath/gitstore.py`
- [Genome mutation](https://github.com/i3t4an/kadath/blob/main/kadath/mutations.py): `kadath/mutations.py`
- [Artifacts and evidence](https://github.com/i3t4an/kadath/blob/main/kadath/artifacts.py): `kadath/artifacts.py`
- [Run state store](https://github.com/i3t4an/kadath/blob/main/kadath/store.py): `kadath/store.py`

### Organism runtime

- [Organism entrypoint](https://github.com/i3t4an/kadath/blob/main/seed/organism.py): `seed/organism.py`
- [Epoch runtime](https://github.com/i3t4an/kadath/blob/main/seed/kadath_runtime.py): `seed/kadath_runtime.py`
- [Container entrypoint](https://github.com/i3t4an/kadath/blob/main/seed/container_entrypoint.py): `seed/container_entrypoint.py`

### Execution services

- [Agent executor](https://github.com/i3t4an/kadath/blob/main/kadath/executors.py): `kadath/executors.py`
- [Isolated containers](https://github.com/i3t4an/kadath/blob/main/kadath/containers.py): `kadath/containers.py`
- [Browser capability](https://github.com/i3t4an/kadath/blob/main/kadath/browsers.py): `kadath/browsers.py`
- [Worker broker](https://github.com/i3t4an/kadath/blob/main/kadath/worker_broker.py): `kadath/worker_broker.py`
- [Worker execution](https://github.com/i3t4an/kadath/blob/main/kadath/workers.py): `kadath/workers.py`

### Agent framework

- [Code agent](https://github.com/i3t4an/kadath/blob/main/seed/smolagents/src/smolagents/agents.py): `seed/smolagents/src/smolagents/agents.py`
- [Model adapters](https://github.com/i3t4an/kadath/blob/main/seed/smolagents/src/smolagents/models.py): `seed/smolagents/src/smolagents/models.py`
- [Tools](https://github.com/i3t4an/kadath/blob/main/seed/smolagents/src/smolagents/tools.py): `seed/smolagents/src/smolagents/tools.py`
- [Agent memory](https://github.com/i3t4an/kadath/blob/main/seed/smolagents/src/smolagents/memory.py): `seed/smolagents/src/smolagents/memory.py`
- [Python executor](https://github.com/i3t4an/kadath/blob/main/seed/smolagents/src/smolagents/local_python_executor.py): `seed/smolagents/src/smolagents/local_python_executor.py`
- [Remote executor](https://github.com/i3t4an/kadath/blob/main/seed/smolagents/src/smolagents/remote_executors.py): `seed/smolagents/src/smolagents/remote_executors.py`
- [Agent monitoring](https://github.com/i3t4an/kadath/blob/main/seed/smolagents/src/smolagents/monitoring.py): `seed/smolagents/src/smolagents/monitoring.py`

### Other components

- **User**

## Connections

- User → Terminal interface: configures run (evidence: `README.md`)
- Terminal interface → Run kernel: starts run (evidence: `kadath/cli.py`)
- Run kernel → Architect benchmark: requests benchmark (evidence: `README.md`)
- User → Architect benchmark: approves benchmark (evidence: `README.md`)
- Run kernel → Genome lineage: records lineage (evidence: `README.md`)
- Run kernel → Agent executor: runs epoch (evidence: `README.md`)
- Agent executor → Isolated containers: isolates organism (evidence: `kadath/containers.py`)
- Isolated containers → Organism entrypoint: starts organism (evidence: `README.md`)
- Organism entrypoint → Epoch runtime: uses runtime (evidence: `seed/organism.py`)
- Organism entrypoint → Code agent: runs agent (evidence: `README.md`)
- Code agent → Model adapters: calls model (evidence: `seed/smolagents/src/smolagents/agents.py`)
- Code agent → Tools: dispatches tools (evidence: `seed/smolagents/src/smolagents/agents.py`)
- Code agent → Agent memory: records steps (evidence: `seed/smolagents/src/smolagents/agents.py`)
- Code agent → Agent monitoring: reports activity (evidence: `seed/smolagents/src/smolagents/agents.py`)
- Code agent → Python executor: uses executor (evidence: `seed/smolagents/src/smolagents/agents.py`)
- Code agent → Remote executor: uses executor (evidence: `seed/smolagents/src/smolagents/agents.py`)
- Run kernel → Grader specialist: grades attempts (evidence: `README.md`)
- Grader specialist → Population selection: scores population (evidence: `README.md`)
- Population selection → Tweaker and Birther: selects performers (evidence: `README.md`)
- Tweaker and Birther → Genome mutation: guides mutation (evidence: `README.md`)
- Run kernel → Artifacts and evidence: retains evidence (evidence: `README.md`)
- Run kernel → Run state store: stores run state (evidence: `README.md`)
- Run kernel → Browser capability: enables capability (evidence: `README.md`)
- Run kernel → Worker broker: enables workers (evidence: `README.md`)
- Worker broker → Worker execution: dispatches work (evidence: `kadath/worker_broker.py`)
- Run kernel → Container entrypoint: starts container