# gaurshalendra2412/axi-runtime architecture

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

- Interactive diagram: https://gitdiagram.com/gaurshalendra2412/axi-runtime
- Repository: https://github.com/gaurshalendra2412/axi-runtime

## Overview

AXI is a runtime that keeps an AI agent’s editable state consistent across multi-step work. The principal flow is: a user request and current state go to a model; AXI parses the proposed delta, checks and completes it under graph rules, commits accepted changes, and returns the exact state for the next step. The Python engine also includes constrained decoding, scope and grounding logic, diagnostics, and a ledger. Experiment runners cover local and hosted models, long sessions, and ARC-style tasks. Some links below reflect README descriptions because the orchestration source is only partially excerpted.

Main entry points: [`python/axi/experiments/agent_loop.py`](https://github.com/gaurshalendra2412/axi-runtime/blob/main/python/axi/experiments/agent_loop.py) (Agent loop), [`python/axi/experiments/api_llm.py`](https://github.com/gaurshalendra2412/axi-runtime/blob/main/python/axi/experiments/api_llm.py) (Model adapters), [`python/axi/experiments/gemini_arc.py`](https://github.com/gaurshalendra2412/axi-runtime/blob/main/python/axi/experiments/gemini_arc.py) (ARC experiments), [`python/axi/engine/cico_parser.py`](https://github.com/gaurshalendra2412/axi-runtime/blob/main/python/axi/engine/cico_parser.py) (Delta parser)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Agent interaction"]
  node_loop["Agent loop<br/>[agent_loop.py]"]
  node_model_adapters["Model adapters<br/>[api_llm.py]"]
end

subgraph group_runtime["State runtime"]
  node_parser["Delta parser<br/>[cico_parser.py]"]
  node_decoder["Constrained decoder<br/>[cico_decoder.py]"]
  node_gate["Graph gate<br/>[gate.py]"]
  node_grounding["Rule completion<br/>[grounding.py]"]
  node_scope["Scope filtering<br/>[scope.py]"]
  node_answer["State response<br/>[answer.py]"]
end

subgraph group_support["Runtime support"]
  node_ledger[("State ledger<br/>[ledger.py]")]
  node_diagnostics["Diagnostics<br/>[diagnostics.py]"]
  node_pager["State paging<br/>[pager.py]"]
  node_gpu_mask["GPU token mask<br/>[gpu_mask.py]"]
end

subgraph group_experiments["Experiments"]
  node_task_generators["Graph tasks<br/>[scope_tasks.py]"]
  node_long_runs["Long-run experiments<br/>[million.py]"]
  node_arc_runs["ARC experiments<br/>[gemini_arc.py]"]
  node_replay["Replay results"]
  node_resumable["Resumable runs<br/>[resumable.py]"]
end

node_user(("User request"))
node_model(("AI model"))

node_user -->|"submits request"| node_loop
node_loop -->|"requests proposal"| node_model
node_model -->|"returns delta"| node_loop
node_loop -->|"parses proposal"| node_parser
node_loop -->|"checks delta"| node_gate
node_loop -->|"completes rules"| node_grounding
node_loop -->|"filters changes"| node_scope
node_loop -.->|"records state"| node_ledger
node_loop -->|"reports outcomes"| node_diagnostics
node_loop -->|"returns exact state"| node_answer
node_model_adapters -->|"calls hosted model"| node_model
node_model_adapters -->|"serves generation"| node_loop
node_decoder -->|"builds token mask"| node_gpu_mask
node_task_generators -->|"parses ideal deltas"| node_parser
node_long_runs -.->|"runs agent steps"| node_loop
node_arc_runs -->|"uses model adapter"| node_model_adapters
node_arc_runs -->|"uses resumable runs"| node_resumable
node_replay -->|"reads run results"| node_loop

click node_loop "https://github.com/gaurshalendra2412/axi-runtime/blob/main/python/axi/experiments/agent_loop.py"
click node_model_adapters "https://github.com/gaurshalendra2412/axi-runtime/blob/main/python/axi/experiments/api_llm.py"
click node_parser "https://github.com/gaurshalendra2412/axi-runtime/blob/main/python/axi/engine/cico_parser.py"
click node_decoder "https://github.com/gaurshalendra2412/axi-runtime/blob/main/python/axi/engine/cico_decoder.py"
click node_gate "https://github.com/gaurshalendra2412/axi-runtime/blob/main/python/axi/engine/gate.py"
click node_grounding "https://github.com/gaurshalendra2412/axi-runtime/blob/main/python/axi/engine/grounding.py"
click node_scope "https://github.com/gaurshalendra2412/axi-runtime/blob/main/python/axi/engine/scope.py"
click node_answer "https://github.com/gaurshalendra2412/axi-runtime/blob/main/python/axi/engine/answer.py"
click node_ledger "https://github.com/gaurshalendra2412/axi-runtime/blob/main/python/axi/engine/ledger.py"
click node_diagnostics "https://github.com/gaurshalendra2412/axi-runtime/blob/main/python/axi/engine/diagnostics.py"
click node_pager "https://github.com/gaurshalendra2412/axi-runtime/blob/main/python/axi/engine/pager.py"
click node_gpu_mask "https://github.com/gaurshalendra2412/axi-runtime/blob/main/python/axi/engine/gpu_mask.py"
click node_task_generators "https://github.com/gaurshalendra2412/axi-runtime/blob/main/python/axi/experiments/scope_tasks.py"
click node_long_runs "https://github.com/gaurshalendra2412/axi-runtime/blob/main/python/axi/experiments/million.py"
click node_arc_runs "https://github.com/gaurshalendra2412/axi-runtime/blob/main/python/axi/experiments/gemini_arc.py"
click node_replay "https://github.com/gaurshalendra2412/axi-runtime/blob/main/python/axi/experiments/million_hard_result.py"
click node_resumable "https://github.com/gaurshalendra2412/axi-runtime/blob/main/python/axi/experiments/resumable.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_loop,node_model_adapters,node_user toneBlue
class node_parser,node_decoder,node_gate,node_grounding,node_scope,node_answer toneAmber
class node_ledger,node_diagnostics,node_pager,node_gpu_mask toneMint
class node_task_generators,node_long_runs,node_arc_runs,node_replay,node_resumable toneRose
class node_model toneIndigo
```

## Components

### Agent interaction

- [Agent loop](https://github.com/gaurshalendra2412/axi-runtime/blob/main/python/axi/experiments/agent_loop.py): `python/axi/experiments/agent_loop.py`
- [Model adapters](https://github.com/gaurshalendra2412/axi-runtime/blob/main/python/axi/experiments/api_llm.py): `python/axi/experiments/api_llm.py`

### State runtime

- [Delta parser](https://github.com/gaurshalendra2412/axi-runtime/blob/main/python/axi/engine/cico_parser.py): `python/axi/engine/cico_parser.py`
- [Constrained decoder](https://github.com/gaurshalendra2412/axi-runtime/blob/main/python/axi/engine/cico_decoder.py): `python/axi/engine/cico_decoder.py`
- [Graph gate](https://github.com/gaurshalendra2412/axi-runtime/blob/main/python/axi/engine/gate.py): `python/axi/engine/gate.py`
- [Rule completion](https://github.com/gaurshalendra2412/axi-runtime/blob/main/python/axi/engine/grounding.py): `python/axi/engine/grounding.py`
- [Scope filtering](https://github.com/gaurshalendra2412/axi-runtime/blob/main/python/axi/engine/scope.py): `python/axi/engine/scope.py`
- [State response](https://github.com/gaurshalendra2412/axi-runtime/blob/main/python/axi/engine/answer.py): `python/axi/engine/answer.py`

### Runtime support

- [State ledger](https://github.com/gaurshalendra2412/axi-runtime/blob/main/python/axi/engine/ledger.py): `python/axi/engine/ledger.py`
- [Diagnostics](https://github.com/gaurshalendra2412/axi-runtime/blob/main/python/axi/engine/diagnostics.py): `python/axi/engine/diagnostics.py`
- [State paging](https://github.com/gaurshalendra2412/axi-runtime/blob/main/python/axi/engine/pager.py): `python/axi/engine/pager.py`
- [GPU token mask](https://github.com/gaurshalendra2412/axi-runtime/blob/main/python/axi/engine/gpu_mask.py): `python/axi/engine/gpu_mask.py`

### Experiments

- [Graph tasks](https://github.com/gaurshalendra2412/axi-runtime/blob/main/python/axi/experiments/scope_tasks.py): `python/axi/experiments/scope_tasks.py`
- [Long-run experiments](https://github.com/gaurshalendra2412/axi-runtime/blob/main/python/axi/experiments/million.py): `python/axi/experiments/million.py`
- [ARC experiments](https://github.com/gaurshalendra2412/axi-runtime/blob/main/python/axi/experiments/gemini_arc.py): `python/axi/experiments/gemini_arc.py`
- [Replay results](https://github.com/gaurshalendra2412/axi-runtime/blob/main/python/axi/experiments/million_hard_result.py): `python/axi/experiments/million_hard_result.py`
- [Resumable runs](https://github.com/gaurshalendra2412/axi-runtime/blob/main/python/axi/experiments/resumable.py): `python/axi/experiments/resumable.py`

### Other components

- **User request**
- **AI model**

## Connections

- User request → Agent loop: submits request (evidence: `README.md`)
- Agent loop → AI model: requests proposal (evidence: `README.md`)
- AI model → Agent loop: returns delta (evidence: `README.md`)
- Agent loop → Delta parser: parses proposal (evidence: `python/axi/experiments/agent_loop.py`)
- Agent loop → Graph gate: checks delta (evidence: `README.md`)
- Agent loop → Rule completion: completes rules (evidence: `README.md`)
- Agent loop → Scope filtering: filters changes (evidence: `python/axi/experiments/cascade.py`)
- Agent loop → State ledger: records state
- Agent loop → Diagnostics: reports outcomes (evidence: `python/axi/experiments/agent_loop.py`)
- Agent loop → State response: returns exact state (evidence: `README.md`)
- Model adapters → AI model: calls hosted model (evidence: `python/axi/experiments/api_llm.py`)
- Model adapters → Agent loop: serves generation (evidence: `python/axi/experiments/agent_loop.py`)
- Constrained decoder → GPU token mask: builds token mask (evidence: `python/axi/engine/gpu_mask.py`)
- Graph tasks → Delta parser: parses ideal deltas (evidence: `python/axi/experiments/scope_tasks.py`)
- Long-run experiments → Agent loop: runs agent steps
- ARC experiments → Model adapters: uses model adapter (evidence: `python/axi/experiments/gemini_arc.py`)
- ARC experiments → Resumable runs: uses resumable runs (evidence: `python/axi/experiments/gemini_arc.py`)
- Replay results → Agent loop: reads run results (evidence: `python/axi/experiments/million_hard_result.py`)