# mlc-ai/tirx-harness architecture

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

- Interactive diagram: https://gitdiagram.com/mlc-ai/tirx-harness
- Repository: https://github.com/mlc-ai/tirx-harness

## Overview

TIRx Harness supports agent-driven GPU-kernel authoring, compiler inspection, simulation/checking, and remote execution. The README also describes workload contracts and a knowledge base; the tree shows a wiki-fetch skill but not workload or benchmark-server implementation. The graph includes documented capabilities at the subsystem level and limits detailed wiring to relationships supported by the sampled source and README.

Main entry points: [`tirx_harness/src/tirx_harness/numsim/api.py`](https://github.com/mlc-ai/tirx-harness/blob/main/tirx_harness/src/tirx_harness/numsim/api.py) (NumSim API), [`tirx_harness/frontend-rs/src/analyze/frontend.rs`](https://github.com/mlc-ai/tirx-harness/blob/main/tirx_harness/frontend-rs/src/analyze/frontend.rs) (TIRx frontend), [`evolution/setup.py`](https://github.com/mlc-ai/tirx-harness/blob/main/evolution/setup.py) (Run preparation), [`tirx_harness/src/tirx_harness/numsim/checker_runner.py`](https://github.com/mlc-ai/tirx-harness/blob/main/tirx_harness/src/tirx_harness/numsim/checker_runner.py) (Checker runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Kernel authoring"]
  node_skills["Skills and references"]
  node_contracts["Workload contracts"]
end

subgraph group_compiler["Compiler frontend"]
  node_frontend["TIRx frontend<br/>[frontend.rs]"]
  node_analysis["Static analysis<br/>[mod.rs]"]
  node_registry["Operation registry<br/>[registry.rs]"]
  node_emitter["Kernel emitter<br/>[mod.rs]"]
end

subgraph group_analysis["Simulation and analysis"]
  node_nums_api["NumSim API<br/>[api.py]"]
  node_transpiler["NumSim transpiler<br/>[frontend.py]"]
  node_bindings["Host bindings<br/>[bindings.py]"]
  node_engine["Simulation engine<br/>[kernel_engine.rs]"]
  node_checkers["Correctness checkers<br/>[checkers.py]"]
  node_checker_runner["Checker runner<br/>[checker_runner.py]"]
  node_reports["Run reports<br/>[report.py]"]
end

subgraph group_evolution["Agent preparation"]
  node_setup["Run preparation<br/>[setup.py]"]
  node_prompts["Agent prompts<br/>[render.py]"]
  node_guards["Worktree guards<br/>[guards.py]"]
end

subgraph group_remote["Remote execution"]
  node_remote_client["Remote client<br/>[kcoral_remote.py]"]
  node_remote_tools["Remote tool runners<br/>[kcoral_tool.py]"]
  node_worker["Remote worker"]
end

node_agent(("Programming agent"))
node_tirx["TIRx-lite DSL"]
node_benchmark["Benchmark server"]
node_gpu["GPU execution environment"]

node_agent -->|"authors kernels"| node_tirx
node_agent -->|"consults"| node_skills
node_agent -->|"follows workload"| node_contracts
node_tirx -->|"submits IR"| node_frontend
node_frontend -->|"analyzes"| node_analysis
node_frontend -->|"dispatches operations"| node_registry
node_frontend -->|"emits kernel"| node_emitter
node_agent -->|"runs simulation"| node_nums_api
node_nums_api -->|"translates kernel"| node_transpiler
node_nums_api -->|"normalizes inputs"| node_bindings
node_nums_api -->|"executes simulation"| node_engine
node_nums_api -->|"runs checks"| node_checker_runner
node_checker_runner -->|"dispatches checks"| node_checkers
node_checker_runner -->|"produces report"| node_reports
node_agent -->|"prepares run"| node_setup
node_setup -->|"renders guidance"| node_prompts
node_setup -->|"configures protections"| node_guards
node_setup -.->|"configures remote runs"| node_remote_client
node_remote_client -.->|"submits benchmark"| node_benchmark
node_remote_tools -.->|"dispatches tools"| node_worker
node_worker -.->|"runs GPU work"| node_gpu
node_worker -.->|"returns results"| node_benchmark

click node_skills "https://github.com/mlc-ai/tirx-harness/tree/main/skills/tirx-wiki"
click node_frontend "https://github.com/mlc-ai/tirx-harness/blob/main/tirx_harness/frontend-rs/src/analyze/frontend.rs"
click node_analysis "https://github.com/mlc-ai/tirx-harness/blob/main/tirx_harness/frontend-rs/src/analyze/mod.rs"
click node_registry "https://github.com/mlc-ai/tirx-harness/blob/main/tirx_harness/frontend-rs/src/registry.rs"
click node_emitter "https://github.com/mlc-ai/tirx-harness/blob/main/tirx_harness/frontend-rs/src/emit/mod.rs"
click node_nums_api "https://github.com/mlc-ai/tirx-harness/blob/main/tirx_harness/src/tirx_harness/numsim/api.py"
click node_transpiler "https://github.com/mlc-ai/tirx-harness/blob/main/tirx_harness/src/tirx_harness/numsim/transpiler/frontend.py"
click node_bindings "https://github.com/mlc-ai/tirx-harness/blob/main/tirx_harness/src/tirx_harness/numsim/bindings.py"
click node_engine "https://github.com/mlc-ai/tirx-harness/blob/main/tirx_harness/src/tirx_harness/numsim/engine-rs/src/kernel_engine.rs"
click node_checkers "https://github.com/mlc-ai/tirx-harness/blob/main/tirx_harness/src/tirx_harness/numsim/checkers.py"
click node_checker_runner "https://github.com/mlc-ai/tirx-harness/blob/main/tirx_harness/src/tirx_harness/numsim/checker_runner.py"
click node_reports "https://github.com/mlc-ai/tirx-harness/blob/main/tirx_harness/src/tirx_harness/numsim/report.py"
click node_setup "https://github.com/mlc-ai/tirx-harness/blob/main/evolution/setup.py"
click node_prompts "https://github.com/mlc-ai/tirx-harness/blob/main/evolution/prompts/render.py"
click node_guards "https://github.com/mlc-ai/tirx-harness/blob/main/evolution/preparation/guards.py"
click node_remote_client "https://github.com/mlc-ai/tirx-harness/blob/main/evolution/remote/kcoral_remote.py"
click node_remote_tools "https://github.com/mlc-ai/tirx-harness/blob/main/evolution/remote/kcoral_tool.py"
click node_worker "https://github.com/mlc-ai/tirx-harness/blob/main/evolution/remote/kcoral_tool_worker.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_skills,node_contracts toneBlue
class node_frontend,node_analysis,node_registry,node_emitter toneAmber
class node_nums_api,node_transpiler,node_bindings,node_engine,node_checkers,node_checker_runner,node_reports,node_benchmark toneMint
class node_setup,node_prompts,node_guards toneRose
class node_remote_client,node_remote_tools,node_worker,node_agent,node_tirx,node_gpu toneIndigo
```

## Components

### Kernel authoring

- [Skills and references](https://github.com/mlc-ai/tirx-harness/tree/main/skills/tirx-wiki): `skills/tirx-wiki`
- **Workload contracts**

### Compiler frontend

- [TIRx frontend](https://github.com/mlc-ai/tirx-harness/blob/main/tirx_harness/frontend-rs/src/analyze/frontend.rs): `tirx_harness/frontend-rs/src/analyze/frontend.rs`
- [Static analysis](https://github.com/mlc-ai/tirx-harness/blob/main/tirx_harness/frontend-rs/src/analyze/mod.rs): `tirx_harness/frontend-rs/src/analyze/mod.rs`
- [Operation registry](https://github.com/mlc-ai/tirx-harness/blob/main/tirx_harness/frontend-rs/src/registry.rs): `tirx_harness/frontend-rs/src/registry.rs`
- [Kernel emitter](https://github.com/mlc-ai/tirx-harness/blob/main/tirx_harness/frontend-rs/src/emit/mod.rs): `tirx_harness/frontend-rs/src/emit/mod.rs`

### Simulation and analysis

- [NumSim API](https://github.com/mlc-ai/tirx-harness/blob/main/tirx_harness/src/tirx_harness/numsim/api.py): `tirx_harness/src/tirx_harness/numsim/api.py`
- [NumSim transpiler](https://github.com/mlc-ai/tirx-harness/blob/main/tirx_harness/src/tirx_harness/numsim/transpiler/frontend.py): `tirx_harness/src/tirx_harness/numsim/transpiler/frontend.py`
- [Host bindings](https://github.com/mlc-ai/tirx-harness/blob/main/tirx_harness/src/tirx_harness/numsim/bindings.py): `tirx_harness/src/tirx_harness/numsim/bindings.py`
- [Simulation engine](https://github.com/mlc-ai/tirx-harness/blob/main/tirx_harness/src/tirx_harness/numsim/engine-rs/src/kernel_engine.rs): `tirx_harness/src/tirx_harness/numsim/engine-rs/src/kernel_engine.rs`
- [Correctness checkers](https://github.com/mlc-ai/tirx-harness/blob/main/tirx_harness/src/tirx_harness/numsim/checkers.py): `tirx_harness/src/tirx_harness/numsim/checkers.py`
- [Checker runner](https://github.com/mlc-ai/tirx-harness/blob/main/tirx_harness/src/tirx_harness/numsim/checker_runner.py): `tirx_harness/src/tirx_harness/numsim/checker_runner.py`
- [Run reports](https://github.com/mlc-ai/tirx-harness/blob/main/tirx_harness/src/tirx_harness/numsim/report.py): `tirx_harness/src/tirx_harness/numsim/report.py`

### Agent preparation

- [Run preparation](https://github.com/mlc-ai/tirx-harness/blob/main/evolution/setup.py): `evolution/setup.py`
- [Agent prompts](https://github.com/mlc-ai/tirx-harness/blob/main/evolution/prompts/render.py): `evolution/prompts/render.py`
- [Worktree guards](https://github.com/mlc-ai/tirx-harness/blob/main/evolution/preparation/guards.py): `evolution/preparation/guards.py`

### Remote execution

- [Remote client](https://github.com/mlc-ai/tirx-harness/blob/main/evolution/remote/kcoral_remote.py): `evolution/remote/kcoral_remote.py`
- [Remote tool runners](https://github.com/mlc-ai/tirx-harness/blob/main/evolution/remote/kcoral_tool.py): `evolution/remote/kcoral_tool.py`
- [Remote worker](https://github.com/mlc-ai/tirx-harness/blob/main/evolution/remote/kcoral_tool_worker.py): `evolution/remote/kcoral_tool_worker.py`

### Other components

- **Programming agent**
- **TIRx-lite DSL**
- **Benchmark server**
- **GPU execution environment**

## Connections

- Programming agent → TIRx-lite DSL: authors kernels
- Programming agent → Skills and references: consults
- Programming agent → Workload contracts: follows workload
- TIRx-lite DSL → TIRx frontend: submits IR
- TIRx frontend → Static analysis: analyzes
- TIRx frontend → Operation registry: dispatches operations
- TIRx frontend → Kernel emitter: emits kernel
- Programming agent → NumSim API: runs simulation
- NumSim API → NumSim transpiler: translates kernel
- NumSim API → Host bindings: normalizes inputs
- NumSim API → Simulation engine: executes simulation
- NumSim API → Checker runner: runs checks
- Checker runner → Correctness checkers: dispatches checks
- Checker runner → Run reports: produces report
- Programming agent → Run preparation: prepares run
- Run preparation → Agent prompts: renders guidance
- Run preparation → Worktree guards: configures protections
- Run preparation → Remote client: configures remote runs
- Remote client → Benchmark server: submits benchmark
- Remote tool runners → Remote worker: dispatches tools
- Remote worker → GPU execution environment: runs GPU work
- Remote worker → Benchmark server: returns results