# ahmadfauzi34/ai_agent_builder architecture

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

- Interactive diagram: https://gitdiagram.com/ahmadfauzi34/ai_agent_builder
- Repository: https://github.com/ahmadfauzi34/ai_agent_builder

## Overview

ai_agent_builder is deterministic math/graph execution and research infrastructure with Rust as the reference runtime and host-facing WASM, Node, and Python interfaces. The principal workflow is to define layers and graph inputs, build and bind an executable plan, run it, then inspect traces or verify execution evidence; workspace and resolution facilities manage related runtime identity and review state. Math programs, evolutionary optimization, semantic ingress, and proof-oriented evidence are distinct capabilities. Several links reflect README-documented boundaries; unsampled implementations are represented at their known directory paths, and uncertain wiring is omitted.

Main entry points: [`src/agent.rs`](https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/src/agent.rs) (Layer and graph builder), [`src/registry.rs`](https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/src/registry.rs) (Layer registry), [`src/graph/multi_input_graph.rs`](https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/src/graph/multi_input_graph.rs) (Multi-input ingress), [`src/workspace_ops.rs`](https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/src/workspace_ops.rs) (Workspace operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_graph["Graph execution"]
  node_agent["Layer and graph builder<br/>[agent.rs]"]
  node_ingress["Multi-input ingress"]
  node_graphverify["Candidate verification"]
  node_mutation["Graph mutation"]
  node_layers["Trainable layers"]
end

subgraph group_math["Math and optimization"]
  node_mathprogram["Versioned math programs<br/>[program.rs]"]
  node_mathkernels["Math kernels<br/>[numeric.rs]"]
  node_optimizer["Evolution strategies"]
end

subgraph group_runtime["Runtime state and proof"]
  node_registry["Layer registry<br/>[registry.rs]"]
  node_protocol["Runtime protocol<br/>[protocol.rs]"]
  node_workspace["Agent workspace<br/>[workspace.rs]"]
  node_workspaceops["Workspace operations<br/>[workspace_ops.rs]"]
  node_auth["Authorization<br/>[authorization.rs]"]
  node_effective["Effective specifications<br/>[effective_spec.rs]"]
  node_evidence["Runtime evidence"]
  node_resolution["Resolution workflow"]
  node_contracts["Runtime contracts<br/>[contracts.rs]"]
  node_state["Layer state records<br/>[state_record.rs]"]
  node_inventory["Contract inventory<br/>[inventory.rs]"]
end

subgraph group_hosts["Host interfaces"]
  node_rust["Rust reference runtime<br/>[lib.rs]"]
  node_node["Node host<br/>[node.mjs]"]
  node_python["Python facade<br/>[facade.py]"]
  node_ffi["Python ABI<br/>[lib.rs]"]
end

node_user(("External consumer"))

node_user -->|"calls runtime"| node_rust
node_user -->|"uses host"| node_node
node_user -->|"uses facade"| node_python
node_python -->|"calls ABI"| node_ffi
node_agent -->|"initializes layers"| node_registry
node_agent -->|"encodes packets"| node_protocol
node_ingress -->|"builds graph plan"| node_agent
node_ingress -->|"validates contracts"| node_protocol
node_registry -->|"decodes run steps"| node_protocol
node_registry -->|"dispatches layers"| node_layers
node_mathprogram -->|"uses kernels"| node_mathkernels
node_workspaceops -->|"updates workspace"| node_workspace
node_workspaceops -->|"builds graph"| node_agent
node_workspaceops -->|"initializes layers"| node_registry
node_evidence -->|"checks authority"| node_auth
node_evidence -->|"uses specification"| node_effective
node_evidence -->|"records runtime state"| node_workspace
node_resolution -.->|"reviews specification"| node_effective
node_graphverify -.->|"verifies graph inputs"| node_ingress
node_mutation -.->|"rechecks candidates"| node_graphverify
node_optimizer -.->|"optimizes objectives"| node_mathprogram
node_rust -->|"exports capabilities"| node_mathprogram
node_rust -->|"exports ingress"| node_ingress
node_inventory -->|"catalogs contracts"| node_registry
node_contracts -->|"defines agent contracts"| node_agent
node_layers -->|"records weights"| node_state

click node_rust "https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/src/lib.rs"
click node_node "https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/hosts/node/node.mjs"
click node_python "https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/ffi/burn_research_ffi/facade.py"
click node_ffi "https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/ffi/src/lib.rs"
click node_agent "https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/src/agent.rs"
click node_ingress "https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/src/graph/multi_input_graph.rs"
click node_graphverify "https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/src/graph/graph_candidate_verification.rs"
click node_mutation "https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/src/graph/graph_mutation_transaction.rs"
click node_layers "https://github.com/ahmadfauzi34/ai_agent_builder/tree/main/src/layers"
click node_registry "https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/src/registry.rs"
click node_protocol "https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/src/protocol.rs"
click node_workspace "https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/src/workspace.rs"
click node_workspaceops "https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/src/workspace_ops.rs"
click node_auth "https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/src/authorization.rs"
click node_effective "https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/src/effective_spec.rs"
click node_evidence "https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/src/evidence/runtime_resolution_evidence.rs"
click node_resolution "https://github.com/ahmadfauzi34/ai_agent_builder/tree/main/src/resolution"
click node_mathprogram "https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/src/math/program.rs"
click node_mathkernels "https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/src/math/numeric.rs"
click node_optimizer "https://github.com/ahmadfauzi34/ai_agent_builder/tree/main/src/es"
click node_contracts "https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/src/contracts.rs"
click node_state "https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/src/layers/state_record.rs"
click node_inventory "https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/src/registry/runtime_contract/inventory.rs"

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_agent,node_ingress,node_graphverify,node_mutation,node_layers toneBlue
class node_mathprogram,node_mathkernels,node_optimizer toneAmber
class node_registry,node_protocol,node_workspace,node_workspaceops,node_auth,node_effective,node_evidence,node_resolution,node_contracts,node_state,node_inventory toneMint
class node_rust,node_node,node_python,node_ffi toneRose
class node_user toneIndigo
```

## Components

### Graph execution

- [Layer and graph builder](https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/src/agent.rs): `src/agent.rs`
- [Multi-input ingress](https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/src/graph/multi_input_graph.rs): `src/graph/multi_input_graph.rs`
- [Candidate verification](https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/src/graph/graph_candidate_verification.rs): `src/graph/graph_candidate_verification.rs`
- [Graph mutation](https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/src/graph/graph_mutation_transaction.rs): `src/graph/graph_mutation_transaction.rs`
- [Trainable layers](https://github.com/ahmadfauzi34/ai_agent_builder/tree/main/src/layers): `src/layers`

### Math and optimization

- [Versioned math programs](https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/src/math/program.rs): `src/math/program.rs`
- [Math kernels](https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/src/math/numeric.rs): `src/math/numeric.rs`
- [Evolution strategies](https://github.com/ahmadfauzi34/ai_agent_builder/tree/main/src/es): `src/es`

### Runtime state and proof

- [Layer registry](https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/src/registry.rs): `src/registry.rs`
- [Runtime protocol](https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/src/protocol.rs): `src/protocol.rs`
- [Agent workspace](https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/src/workspace.rs): `src/workspace.rs`
- [Workspace operations](https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/src/workspace_ops.rs): `src/workspace_ops.rs`
- [Authorization](https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/src/authorization.rs): `src/authorization.rs`
- [Effective specifications](https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/src/effective_spec.rs): `src/effective_spec.rs`
- [Runtime evidence](https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/src/evidence/runtime_resolution_evidence.rs): `src/evidence/runtime_resolution_evidence.rs`
- [Resolution workflow](https://github.com/ahmadfauzi34/ai_agent_builder/tree/main/src/resolution): `src/resolution`
- [Runtime contracts](https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/src/contracts.rs): `src/contracts.rs`
- [Layer state records](https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/src/layers/state_record.rs): `src/layers/state_record.rs`
- [Contract inventory](https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/src/registry/runtime_contract/inventory.rs): `src/registry/runtime_contract/inventory.rs`

### Host interfaces

- [Rust reference runtime](https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/src/lib.rs): `src/lib.rs`
- [Node host](https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/hosts/node/node.mjs): `hosts/node/node.mjs`
- [Python facade](https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/ffi/burn_research_ffi/facade.py): `ffi/burn_research_ffi/facade.py`
- [Python ABI](https://github.com/ahmadfauzi34/ai_agent_builder/blob/main/ffi/src/lib.rs): `ffi/src/lib.rs`

### Other components

- **External consumer**

## Connections

- External consumer → Rust reference runtime: calls runtime (evidence: `README.md`)
- External consumer → Node host: uses host (evidence: `README.md`)
- External consumer → Python facade: uses facade (evidence: `README.md`)
- Python facade → Python ABI: calls ABI (evidence: `README.md`)
- Layer and graph builder → Layer registry: initializes layers (evidence: `src/agent.rs`)
- Layer and graph builder → Runtime protocol: encodes packets (evidence: `src/agent.rs`)
- Multi-input ingress → Layer and graph builder: builds graph plan (evidence: `src/graph/multi_input_graph.rs`)
- Multi-input ingress → Runtime protocol: validates contracts (evidence: `src/graph/multi_input_graph.rs`)
- Layer registry → Runtime protocol: decodes run steps (evidence: `src/registry.rs`)
- Layer registry → Trainable layers: dispatches layers (evidence: `src/registry.rs`)
- Versioned math programs → Math kernels: uses kernels (evidence: `src/math/program.rs`)
- Workspace operations → Agent workspace: updates workspace (evidence: `src/workspace_ops.rs`)
- Workspace operations → Layer and graph builder: builds graph (evidence: `src/workspace_ops.rs`)
- Workspace operations → Layer registry: initializes layers (evidence: `src/workspace_ops.rs`)
- Runtime evidence → Authorization: checks authority (evidence: `src/evidence/runtime_resolution_evidence.rs`)
- Runtime evidence → Effective specifications: uses specification (evidence: `src/evidence/runtime_resolution_evidence.rs`)
- Runtime evidence → Agent workspace: records runtime state (evidence: `src/evidence/runtime_resolution_evidence.rs`)
- Resolution workflow → Effective specifications: reviews specification
- Candidate verification → Multi-input ingress: verifies graph inputs
- Graph mutation → Candidate verification: rechecks candidates
- Evolution strategies → Versioned math programs: optimizes objectives
- Rust reference runtime → Versioned math programs: exports capabilities (evidence: `src/lib.rs`)
- Rust reference runtime → Multi-input ingress: exports ingress (evidence: `src/lib.rs`)
- Contract inventory → Layer registry: catalogs contracts (evidence: `src/registry/runtime_contract.rs`)
- Runtime contracts → Layer and graph builder: defines agent contracts (evidence: `src/contracts.rs`)
- Trainable layers → Layer state records: records weights (evidence: `src/layers/embedding.rs`)