# alibaba/atrex-kernel-agent architecture

> Architecture diagram of the GitHub repository alibaba/atrex-kernel-agent, 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/alibaba/atrex-kernel-agent
- Repository: https://github.com/alibaba/atrex-kernel-agent

## Overview

Atrex Kernel Agent turns an evaluator-owned operator into an optimized GPU kernel through a single orchestrated workflow: the supervisor establishes baselines, runs coding-agent episodes in isolated worktrees, checks correctness and performance, and promotes only verified candidates. Supporting branches provide sandboxed hardware execution and recovery, plugin-based GPU Wiki retrieval, and profiling tools. The README documents the workflow and capabilities; connections for unsampled subsystems are limited to documented relationships.

Main entry points: [`long_horizon/campaign.py`](https://github.com/alibaba/atrex-kernel-agent/blob/main/long_horizon/campaign.py) (Campaign supervisor), [`long_horizon/session.py`](https://github.com/alibaba/atrex-kernel-agent/blob/main/long_horizon/session.py) (Episode engine), [`tools/sandbox.py`](https://github.com/alibaba/atrex-kernel-agent/blob/main/tools/sandbox.py) (Sandbox execution), [`orchestrator/optimize.py`](https://github.com/alibaba/atrex-kernel-agent/blob/main/orchestrator/optimize.py) (Optimization CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_supervision["Campaign supervision"]
  node_entry["Optimization CLI<br/>[optimize.py]"]
  node_campaign["Campaign supervisor<br/>[campaign.py]"]
end

subgraph group_episodes["Agent episodes"]
  node_episode["Episode engine<br/>[session.py]"]
  node_agent_session["Agent session adapter<br/>[main_adapter.py]"]
  node_agent_backends["Agent backends<br/>[adapter.py]"]
  node_git_workspace["Git-isolated workspace<br/>[git_episode.py]"]
end

subgraph group_verification["Verification and policy"]
  node_correctness["Correctness evaluation"]
  node_verification["Candidate verification<br/>[verifier.py]"]
  node_policy["Acceptance policy"]
  node_numerical["Numerical probes"]
end

subgraph group_execution["Execution and recovery"]
  node_sandbox["Sandbox execution<br/>[sandbox.py]"]
  node_hardware["Hardware configuration<br/>[hardware.py]"]
  node_recovery["Environment recovery"]
  node_durable_state[("Durable recovery state<br/>[durable_state.py]")]
end

subgraph group_knowledge["Knowledge and profiling"]
  node_plugins["Plugin runtime<br/>[registry.py]"]
  node_wiki_adapter["GPU Wiki plugin<br/>[adapter.py]"]
  node_wiki_retrieval["GPU Wiki retrieval<br/>[query_nl.py]"]
  node_profiling["GPU profiling tools"]
end

node_operator(("Operator owner"))

node_operator -->|"starts task"| node_entry
node_entry -->|"starts campaign"| node_campaign
node_campaign -->|"runs episodes"| node_episode
node_episode -->|"runs session"| node_agent_session
node_agent_session -->|"normalizes output"| node_agent_backends
node_episode -->|"uses worktree"| node_git_workspace
node_campaign -->|"checks candidate"| node_correctness
node_campaign -->|"verifies performance"| node_verification
node_campaign -->|"enforces acceptance"| node_policy
node_campaign -->|"runs probes"| node_numerical
node_episode -->|"executes isolated"| node_sandbox
node_sandbox -->|"targets hardware"| node_hardware
node_sandbox -->|"reports failures"| node_recovery
node_recovery -->|"persists handoff"| node_durable_state
node_campaign -->|"loads plugins"| node_plugins
node_plugins -.->|"registers adapter"| node_wiki_adapter
node_wiki_adapter -.->|"queries knowledge"| node_wiki_retrieval
node_campaign -->|"profiles kernels"| node_profiling

click node_entry "https://github.com/alibaba/atrex-kernel-agent/blob/main/orchestrator/optimize.py"
click node_campaign "https://github.com/alibaba/atrex-kernel-agent/blob/main/long_horizon/campaign.py"
click node_episode "https://github.com/alibaba/atrex-kernel-agent/blob/main/long_horizon/session.py"
click node_agent_session "https://github.com/alibaba/atrex-kernel-agent/blob/main/long_horizon/main_adapter.py"
click node_agent_backends "https://github.com/alibaba/atrex-kernel-agent/blob/main/orchestrator/agent_runtime/adapter.py"
click node_git_workspace "https://github.com/alibaba/atrex-kernel-agent/blob/main/long_horizon/git_episode.py"
click node_correctness "https://github.com/alibaba/atrex-kernel-agent/blob/main/reference/atrex_bench_test_kernel.py"
click node_verification "https://github.com/alibaba/atrex-kernel-agent/blob/main/long_horizon/verifier.py"
click node_policy "https://github.com/alibaba/atrex-kernel-agent/blob/main/orchestrator/optimization_policy.py"
click node_numerical "https://github.com/alibaba/atrex-kernel-agent/blob/main/long_horizon/remote_numerical.py"
click node_sandbox "https://github.com/alibaba/atrex-kernel-agent/blob/main/tools/sandbox.py"
click node_hardware "https://github.com/alibaba/atrex-kernel-agent/blob/main/orchestrator/hardware.py"
click node_recovery "https://github.com/alibaba/atrex-kernel-agent/blob/main/orchestrator/environment_recovery.py"
click node_durable_state "https://github.com/alibaba/atrex-kernel-agent/blob/main/orchestrator/durable_state.py"
click node_plugins "https://github.com/alibaba/atrex-kernel-agent/blob/main/plugin_runtime/registry.py"
click node_wiki_adapter "https://github.com/alibaba/atrex-kernel-agent/blob/main/plugins/gpu-wiki/adapter.py"
click node_wiki_retrieval "https://github.com/alibaba/atrex-kernel-agent/blob/main/gpu-wiki/tools/query_nl.py"
click node_profiling "https://github.com/alibaba/atrex-kernel-agent/tree/main/tools/ncu_helpers"

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_entry,node_campaign toneBlue
class node_episode,node_agent_session,node_agent_backends,node_git_workspace toneAmber
class node_correctness,node_verification,node_policy,node_numerical toneMint
class node_sandbox,node_hardware,node_recovery,node_durable_state toneRose
class node_plugins,node_wiki_adapter,node_wiki_retrieval,node_profiling,node_operator toneIndigo
```

## Components

### Campaign supervision

- [Optimization CLI](https://github.com/alibaba/atrex-kernel-agent/blob/main/orchestrator/optimize.py): `orchestrator/optimize.py`
- [Campaign supervisor](https://github.com/alibaba/atrex-kernel-agent/blob/main/long_horizon/campaign.py): `long_horizon/campaign.py`

### Agent episodes

- [Episode engine](https://github.com/alibaba/atrex-kernel-agent/blob/main/long_horizon/session.py): `long_horizon/session.py`
- [Agent session adapter](https://github.com/alibaba/atrex-kernel-agent/blob/main/long_horizon/main_adapter.py): `long_horizon/main_adapter.py`
- [Agent backends](https://github.com/alibaba/atrex-kernel-agent/blob/main/orchestrator/agent_runtime/adapter.py): `orchestrator/agent_runtime/adapter.py`
- [Git-isolated workspace](https://github.com/alibaba/atrex-kernel-agent/blob/main/long_horizon/git_episode.py): `long_horizon/git_episode.py`

### Verification and policy

- [Correctness evaluation](https://github.com/alibaba/atrex-kernel-agent/blob/main/reference/atrex_bench_test_kernel.py): `reference/atrex_bench_test_kernel.py`
- [Candidate verification](https://github.com/alibaba/atrex-kernel-agent/blob/main/long_horizon/verifier.py): `long_horizon/verifier.py`
- [Acceptance policy](https://github.com/alibaba/atrex-kernel-agent/blob/main/orchestrator/optimization_policy.py): `orchestrator/optimization_policy.py`
- [Numerical probes](https://github.com/alibaba/atrex-kernel-agent/blob/main/long_horizon/remote_numerical.py): `long_horizon/remote_numerical.py`

### Execution and recovery

- [Sandbox execution](https://github.com/alibaba/atrex-kernel-agent/blob/main/tools/sandbox.py): `tools/sandbox.py`
- [Hardware configuration](https://github.com/alibaba/atrex-kernel-agent/blob/main/orchestrator/hardware.py): `orchestrator/hardware.py`
- [Environment recovery](https://github.com/alibaba/atrex-kernel-agent/blob/main/orchestrator/environment_recovery.py): `orchestrator/environment_recovery.py`
- [Durable recovery state](https://github.com/alibaba/atrex-kernel-agent/blob/main/orchestrator/durable_state.py): `orchestrator/durable_state.py`

### Knowledge and profiling

- [Plugin runtime](https://github.com/alibaba/atrex-kernel-agent/blob/main/plugin_runtime/registry.py): `plugin_runtime/registry.py`
- [GPU Wiki plugin](https://github.com/alibaba/atrex-kernel-agent/blob/main/plugins/gpu-wiki/adapter.py): `plugins/gpu-wiki/adapter.py`
- [GPU Wiki retrieval](https://github.com/alibaba/atrex-kernel-agent/blob/main/gpu-wiki/tools/query_nl.py): `gpu-wiki/tools/query_nl.py`
- [GPU profiling tools](https://github.com/alibaba/atrex-kernel-agent/tree/main/tools/ncu_helpers): `tools/ncu_helpers`

### Other components

- **Operator owner**

## Connections

- Operator owner → Optimization CLI: starts task (evidence: `README.md`)
- Optimization CLI → Campaign supervisor: starts campaign (evidence: `README.md`)
- Campaign supervisor → Episode engine: runs episodes (evidence: `README.md`)
- Episode engine → Agent session adapter: runs session (evidence: `long_horizon/session.py`)
- Agent session adapter → Agent backends: normalizes output (evidence: `long_horizon/main_adapter.py`)
- Episode engine → Git-isolated workspace: uses worktree (evidence: `long_horizon/campaign.py`)
- Campaign supervisor → Correctness evaluation: checks candidate (evidence: `README.md`)
- Campaign supervisor → Candidate verification: verifies performance (evidence: `README.md`)
- Campaign supervisor → Acceptance policy: enforces acceptance (evidence: `README.md`)
- Campaign supervisor → Numerical probes: runs probes (evidence: `README.md`)
- Episode engine → Sandbox execution: executes isolated (evidence: `README.md`)
- Sandbox execution → Hardware configuration: targets hardware (evidence: `README.md`)
- Sandbox execution → Environment recovery: reports failures (evidence: `README.md`)
- Environment recovery → Durable recovery state: persists handoff (evidence: `orchestrator/environment_recovery.py`)
- Campaign supervisor → Plugin runtime: loads plugins (evidence: `README.md`)
- Plugin runtime → GPU Wiki plugin: registers adapter
- GPU Wiki plugin → GPU Wiki retrieval: queries knowledge
- Campaign supervisor → GPU profiling tools: profiles kernels (evidence: `README.md`)