# ysingh-grid/gah-v2 architecture

> Architecture diagram of the GitHub repository ysingh-grid/gah-v2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ysingh-grid/gah-v2
- Repository: https://github.com/ysingh-grid/gah-v2

## Overview

1. **What this repo is**
   - GAH-v2 is a CAD-generation orchestration system: it turns a natural-language task into CadQuery code, runs that code, inspects the resulting geometry, optionally repairs it, and records a full trace.
   - The architecture is centered on an LLM-driven agent pipeline rather than a traditional application server.

2. **Top-level orchestration layer**
   - The main control plane lives in `rlm/` and `runtime/`.
   - `rlm/rlm_config.py` configures the primary and sub-agents for the `fast-rlm` framework, while `rlm/pull_tools.py` and `rlm/tools.py` connect the agent runtime to the toolset.
   - `runtime/planner.py`, `runtime/schema.py`, and `runtime/compile.py` suggest a planning/compilation boundary where tasks are turned into structured actions and then executed.

3. **Agent pipeline stages**
   - The system follows a multi-phase flow: intent extraction → primitive planning → code generation → execution → mesh inspection → vision verification → trace writing.
   - This is the main data path an architecture diagram should show, with feedback loops from validation/verification back into repair or refinement subagents.

4. **Tooling boundary**
   - The `tools/` package is the operational boundary between the agent and the real world.
   - Notable tools include CadQuery execution, mesh inspection, geometry verification, view rendering, trace persistence, trace loading, skill reading, primitive lookup, artifact handling, and a backend bridge.
   - `tools/tools_registry.py` is the central registration point, so the agent sees these capabilities as a controlled tool API rather than direct filesystem or process access.

5. **CAD execution path**
   - `tools/execute_cadquery.py` runs CadQuery in a separate conda environment, which is a hard runtime boundary because CadQuery depends on compiled OpenCASCADE binaries.
   - Generated geometry is likely exported as STEP/STL and then passed downstream for inspection and rendering.
   - This subprocess boundary is important: the agent does not execute geometry code in-process.

6. **Geometry validation and visual QA**
   - `tools/inspect_mesh.py` provides mesh-level quality checks, while `tools/render_views.py` produces image views for human/vision review.
   - `tools/verify_geometry.py` uses Gemini as a vision-based judge, creating a second verification layer beyond symbolic or mesh checks.
   - Together these form the validation subsystem that decides whether the generated part is acceptable or needs repair.

7. **Domain knowledge layer: skills**
   - The `skills/` directory contains reasoning guides in Markdown, with `skills/SKILLS.md` acting as the index injected into task prompts.
   - `skills/skills_loader.py` loads these guides on demand, and `tools/read_skill.py` exposes skill content to the agent.
   - This is a prompt-knowledge subsystem, not executable logic; it shapes planning quality and repair behavior.

8. **Domain knowledge layer: primitives**
   - `primitives/library.json` stores 36 solid primitive definitions, including parameters, verification guidance, and CadQuery templates.
   - `tools/primitive_lookup.py` queries this library so the agent can ground its design in reusable geometric building blocks.
   - In the architecture, this is a structured knowledge base used during primitive planning and code generation.

9. **Backend bridge and sandbox boundary**
   - The `backend/` package is a FastAPI-style internal service layer that exposes safe, allowlisted JSON endpoints under `/internal/*`.
   - It includes route modules, service modules, schemas, and a `security/path_guard.py` boundary for restricted file/repo access.
   - The backend appears to support sandboxed RLM tool access, repository inspection, primitive/skill reads, trace access, and pipeline operations without giving the agent unrestricted filesystem control.

10. **Persistence and observability**
   - Trace and artifact handling are first-class concerns: `tools/write_trace.py`, `tools/load_trace.py`, `tools/artifacts.py`, and the backend trace service indicate that runs are recorded and replayable.
   - The repo also includes scripts for smoke tests, full demos, backend start/stop, and state-trace display, which suggests the system is designed for repeatable agent runs and debugging.
   - `outputs/` is implied as the artifact sink for generated geometry, renders, and traces.

11. **Testing and fixtures**
   - The repository includes task-level tests like `Task_test.py`, `Task_test_complex.py`, and integration tests under `tests/`.
   - `tests/fixtures/` contains at least one example enclosure case, which helps validate the end-to-end pipeline on a realistic geometry task.
   - This test layer exercises both the agent/tool stack and the backend bridge.

12. **External dependencies that shape the architecture**
   - `fast-rlm` is the agent runtime backbone.
   - CadQuery is the CAD kernel/interface for solid modeling.
   - Gemini is used both as the main LLM backend and as a vision verifier.
   - MeshLib appears in the mesh-inspection path, and FastAPI-like routing under `backend/` provides the internal service boundary.

13. **How to draw the system**
   - A useful diagram would show: user task → RLM agent → tool registry → CAD execution / inspection / rendering / verification → trace output, with optional repair subagents looping back into code generation.
   - Separately, show the backend bridge as a constrained internal service layer that exposes safe reads, pipeline controls, and trace access.
   - The skills and primitives directories should be drawn as supporting knowledge stores feeding the agent, not as runtime executors.

Main entry points: [`tools/tools_registry.py`](https://github.com/ysingh-grid/gah-v2/blob/main/tools/tools_registry.py) (Tool registry), [`backend/routes/internal.py`](https://github.com/ysingh-grid/gah-v2/blob/main/backend/routes/internal.py) (Internal routes), [`runtime/planner.py`](https://github.com/ysingh-grid/gah-v2/blob/main/runtime/planner.py) (Planner), [`rlm/tools.py`](https://github.com/ysingh-grid/gah-v2/blob/main/rlm/tools.py) (Agent tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_control["Control plane"]
  node_n_rlm_config["RLM config<br/>agent config<br/>[rlm_config.py]"]
  node_n_pull_tools["Tool pulling<br/>tool wiring<br/>[pull_tools.py]"]
  node_n_rlm_tools["Agent tools<br/>agent API<br/>[tools.py]"]
end

subgraph group_g_knowledge["Knowledge base"]
  node_n_skills_index["Skills index<br/>prompt knowledge<br/>[SKILLS.md]"]
  node_n_skills_loader["Skills loader<br/>knowledge loader<br/>[skills_loader.py]"]
  node_n_primitives_lib[("Primitives library<br/>geometry KB<br/>[library.json]")]
end

subgraph group_g_tools["Tool boundary"]
  node_n_tools_registry["Tool registry<br/>[tools_registry.py]"]
  node_n_exec_cq["CadQuery exec<br/>subprocess runtime"]
  node_n_inspect_mesh["Mesh inspect<br/>geometry QA<br/>[inspect_mesh.py]"]
  node_n_render_views["Render views<br/>visual QA<br/>[render_views.py]"]
  node_n_verify_geom["Vision verify<br/>vision judge<br/>[verify_geometry.py]"]
end

subgraph group_g_backend["Backend bridge"]
  node_n_backend_internal["Internal routes<br/>allowlisted API<br/>[internal.py]"]
  node_n_path_guard["Path guard<br/>security boundary<br/>[path_guard.py]"]
  node_n_pipeline_svc["Pipeline svc<br/>orchestration service"]
  node_n_skill_svc["Skill svc<br/>content service<br/>[skill_service.py]"]
  node_n_trace_svc["Trace svc<br/>trace service<br/>[trace_service.py]"]
end

subgraph group_g_runtime["Runtime flow"]
  node_n_planner["Planner<br/>[planner.py]"]
  node_n_schema["Runtime schema<br/>action schema<br/>[schema.py]"]
  node_n_compile["Compiler<br/>[compile.py]"]
  node_n_trace_write["Write trace<br/>trace persistence<br/>[write_trace.py]"]
  node_n_trace_load["Load trace<br/>trace replay<br/>[load_trace.py]"]
  node_n_artifacts["Artifacts<br/>artifact handling<br/>[artifacts.py]"]
end

node_n_rlm_config -->|"wires"| node_n_pull_tools
node_n_pull_tools -->|"exposes"| node_n_rlm_tools
node_n_rlm_config -->|"drives"| node_n_planner
node_n_planner -->|"uses"| node_n_schema
node_n_planner -->|"compiles to"| node_n_compile
node_n_skills_index -->|"indexed by"| node_n_skills_loader
node_n_skills_loader -->|"feeds"| node_n_rlm_tools
node_n_primitives_lib -->|"grounds"| node_n_rlm_tools
node_n_rlm_tools -->|"invokes"| node_n_tools_registry
node_n_tools_registry -->|"dispatches"| node_n_exec_cq
node_n_tools_registry -->|"dispatches"| node_n_inspect_mesh
node_n_tools_registry -->|"dispatches"| node_n_render_views
node_n_tools_registry -->|"dispatches"| node_n_verify_geom
node_n_tools_registry -->|"dispatches"| node_n_trace_write
node_n_tools_registry -->|"dispatches"| node_n_trace_load
node_n_tools_registry -->|"dispatches"| node_n_artifacts
node_n_exec_cq -->|"exports to"| node_n_inspect_mesh
node_n_inspect_mesh -->|"prompts"| node_n_render_views
node_n_render_views -->|"reviews"| node_n_verify_geom
node_n_verify_geom -.->|"repairs via"| node_n_planner
node_n_trace_write -->|"replays"| node_n_trace_load
node_n_backend_internal -->|"constrained by"| node_n_path_guard
node_n_backend_internal -->|"uses"| node_n_pipeline_svc
node_n_backend_internal -->|"uses"| node_n_skill_svc
node_n_backend_internal -->|"uses"| node_n_trace_svc
node_n_skill_svc -->|"reads"| node_n_skills_loader
node_n_trace_svc -->|"persists"| node_n_trace_write
node_n_pipeline_svc -->|"orchestrates"| node_n_tools_registry

click node_n_rlm_config "https://github.com/ysingh-grid/gah-v2/blob/main/rlm/rlm_config.py"
click node_n_pull_tools "https://github.com/ysingh-grid/gah-v2/blob/main/rlm/pull_tools.py"
click node_n_rlm_tools "https://github.com/ysingh-grid/gah-v2/blob/main/rlm/tools.py"
click node_n_planner "https://github.com/ysingh-grid/gah-v2/blob/main/runtime/planner.py"
click node_n_schema "https://github.com/ysingh-grid/gah-v2/blob/main/runtime/schema.py"
click node_n_compile "https://github.com/ysingh-grid/gah-v2/blob/main/runtime/compile.py"
click node_n_skills_index "https://github.com/ysingh-grid/gah-v2/blob/main/skills/SKILLS.md"
click node_n_skills_loader "https://github.com/ysingh-grid/gah-v2/blob/main/skills/skills_loader.py"
click node_n_primitives_lib "https://github.com/ysingh-grid/gah-v2/blob/main/primitives/library.json"
click node_n_tools_registry "https://github.com/ysingh-grid/gah-v2/blob/main/tools/tools_registry.py"
click node_n_exec_cq "https://github.com/ysingh-grid/gah-v2/blob/main/tools/execute_cadquery.py"
click node_n_inspect_mesh "https://github.com/ysingh-grid/gah-v2/blob/main/tools/inspect_mesh.py"
click node_n_render_views "https://github.com/ysingh-grid/gah-v2/blob/main/tools/render_views.py"
click node_n_verify_geom "https://github.com/ysingh-grid/gah-v2/blob/main/tools/verify_geometry.py"
click node_n_trace_write "https://github.com/ysingh-grid/gah-v2/blob/main/tools/write_trace.py"
click node_n_trace_load "https://github.com/ysingh-grid/gah-v2/blob/main/tools/load_trace.py"
click node_n_artifacts "https://github.com/ysingh-grid/gah-v2/blob/main/tools/artifacts.py"
click node_n_backend_internal "https://github.com/ysingh-grid/gah-v2/blob/main/backend/routes/internal.py"
click node_n_path_guard "https://github.com/ysingh-grid/gah-v2/blob/main/backend/security/path_guard.py"
click node_n_pipeline_svc "https://github.com/ysingh-grid/gah-v2/blob/main/backend/services/pipeline_service.py"
click node_n_skill_svc "https://github.com/ysingh-grid/gah-v2/blob/main/backend/services/skill_service.py"
click node_n_trace_svc "https://github.com/ysingh-grid/gah-v2/blob/main/backend/services/trace_service.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_n_rlm_config,node_n_pull_tools,node_n_rlm_tools toneBlue
class node_n_skills_index,node_n_skills_loader,node_n_primitives_lib toneAmber
class node_n_tools_registry,node_n_exec_cq,node_n_inspect_mesh,node_n_render_views,node_n_verify_geom toneMint
class node_n_backend_internal,node_n_path_guard,node_n_pipeline_svc,node_n_skill_svc,node_n_trace_svc toneRose
class node_n_planner,node_n_schema,node_n_compile,node_n_trace_write,node_n_trace_load,node_n_artifacts toneIndigo
```

## Components

### Control plane

Agent orchestration and task compilation

- [RLM config](https://github.com/ysingh-grid/gah-v2/blob/main/rlm/rlm_config.py): agent config · Configures the primary and sub-agents for the fast-rlm runtime · `rlm/rlm_config.py`
- [Tool pulling](https://github.com/ysingh-grid/gah-v2/blob/main/rlm/pull_tools.py): tool wiring · Connects the agent runtime to available tools · `rlm/pull_tools.py`
- [Agent tools](https://github.com/ysingh-grid/gah-v2/blob/main/rlm/tools.py): agent API · Agent-facing tool definitions and wrappers · `rlm/tools.py`

### Knowledge base

Prompt guidance and geometric primitives used by the agent

- [Skills index](https://github.com/ysingh-grid/gah-v2/blob/main/skills/SKILLS.md): prompt knowledge · Markdown index of reasoning guides injected into prompts · `skills/SKILLS.md`
- [Skills loader](https://github.com/ysingh-grid/gah-v2/blob/main/skills/skills_loader.py): knowledge loader · Loads skill guides on demand for prompting and repair behavior · `skills/skills_loader.py`
- [Primitives library](https://github.com/ysingh-grid/gah-v2/blob/main/primitives/library.json): geometry KB · Structured primitive definitions, templates, and verification guidance · `primitives/library.json`

### Tool boundary

Operational tools invoked by the agent

- [Tool registry](https://github.com/ysingh-grid/gah-v2/blob/main/tools/tools_registry.py): tool registry · Central registration point for agent-visible capabilities · `tools/tools_registry.py`
- [CadQuery exec](https://github.com/ysingh-grid/gah-v2/blob/main/tools/execute_cadquery.py): subprocess runtime · Runs CadQuery in a separate conda environment for geometry generation · `tools/execute_cadquery.py`
- [Mesh inspect](https://github.com/ysingh-grid/gah-v2/blob/main/tools/inspect_mesh.py): geometry QA · Performs mesh-level quality and validity checks · `tools/inspect_mesh.py`
- [Render views](https://github.com/ysingh-grid/gah-v2/blob/main/tools/render_views.py): visual QA · Produces image views for human or vision review · `tools/render_views.py`
- [Vision verify](https://github.com/ysingh-grid/gah-v2/blob/main/tools/verify_geometry.py): vision judge · Uses Gemini-based visual verification to judge geometry quality · `tools/verify_geometry.py`

### Backend bridge

Allowlisted internal service layer for safe reads and pipeline operations

- [Internal routes](https://github.com/ysingh-grid/gah-v2/blob/main/backend/routes/internal.py): allowlisted API · Internal JSON routes exposing safe backend operations · `backend/routes/internal.py`
- [Path guard](https://github.com/ysingh-grid/gah-v2/blob/main/backend/security/path_guard.py): security boundary · Restricts filesystem and repository access for backend operations · `backend/security/path_guard.py`
- [Pipeline svc](https://github.com/ysingh-grid/gah-v2/blob/main/backend/services/pipeline_service.py): orchestration service · Backend service for pipeline operations and coordination · `backend/services/pipeline_service.py`
- [Skill svc](https://github.com/ysingh-grid/gah-v2/blob/main/backend/services/skill_service.py): content service · Backend service for reading and serving skill content · `backend/services/skill_service.py`
- [Trace svc](https://github.com/ysingh-grid/gah-v2/blob/main/backend/services/trace_service.py): trace service · Backend service for trace access and persistence support · `backend/services/trace_service.py`

### Runtime flow

Planning, compilation, execution, validation, and trace capture

- [Planner](https://github.com/ysingh-grid/gah-v2/blob/main/runtime/planner.py): task planner · Turns tasks into structured actions and intermediate plans · `runtime/planner.py`
- [Runtime schema](https://github.com/ysingh-grid/gah-v2/blob/main/runtime/schema.py): action schema · Structured task and plan schema used across the runtime boundary · `runtime/schema.py`
- [Compiler](https://github.com/ysingh-grid/gah-v2/blob/main/runtime/compile.py): plan compiler · Compiles planned actions into executable runtime steps · `runtime/compile.py`
- [Write trace](https://github.com/ysingh-grid/gah-v2/blob/main/tools/write_trace.py): trace persistence · Persists full run traces and execution metadata · `tools/write_trace.py`
- [Load trace](https://github.com/ysingh-grid/gah-v2/blob/main/tools/load_trace.py): trace replay · Loads prior traces for replay and debugging · `tools/load_trace.py`
- [Artifacts](https://github.com/ysingh-grid/gah-v2/blob/main/tools/artifacts.py): artifact handling · Manages generated geometry, renders, and other run outputs · `tools/artifacts.py`

## Connections

- RLM config → Tool pulling: wires · Configures tool loading for the agent runtime
- Tool pulling → Agent tools: exposes · Surfaces the agent-facing tool API
- RLM config → Planner: drives · Sets up the planning loop used by the agent
- Planner → Runtime schema: uses · Represents tasks and intermediate actions in a shared schema
- Planner → Compiler: compiles to · Transforms plans into executable runtime steps
- Skills index → Skills loader: indexed by · Provides the prompt knowledge index consumed by the loader
- Skills loader → Agent tools: feeds · Injects skill content into agent prompting and repair
- Primitives library → Agent tools: grounds · Provides reusable geometry primitives to the agent
- Agent tools → Tool registry: invokes · Routes agent requests through the centralized tool registry
- Tool registry → CadQuery exec: dispatches · Sends CAD generation work to the subprocess executor
- Tool registry → Mesh inspect: dispatches · Sends mesh validation work to inspection tools
- Tool registry → Render views: dispatches · Sends render requests to view-generation tools
- Tool registry → Vision verify: dispatches · Sends visual verification requests to the judge
- Tool registry → Write trace: dispatches · Sends trace persistence requests to the recorder
- Tool registry → Load trace: dispatches · Sends trace replay requests to the loader
- Tool registry → Artifacts: dispatches · Manages generated outputs through the artifact layer
- CadQuery exec → Mesh inspect: exports to · Passes generated geometry into inspection after execution
- Mesh inspect → Render views: prompts · Uses inspection results to drive view rendering and QA
- Render views → Vision verify: reviews · Feeds rendered views into vision-based verification
- Vision verify → Planner: repairs via · Creates feedback for repair and refinement loops
- Write trace → Load trace: replays · Stored traces can be loaded back for analysis and debugging
- Internal routes → Path guard: constrained by · Backend routes are limited by repository and path access checks
- Internal routes → Pipeline svc: uses · Internal routes call into pipeline orchestration services
- Internal routes → Skill svc: uses · Internal routes expose safe skill reads
- Internal routes → Trace svc: uses · Internal routes expose trace access
- Skill svc → Skills loader: reads · Backend skill service loads markdown skill content
- Trace svc → Write trace: persists · Backend trace service supports trace storage and retrieval
- Pipeline svc → Tool registry: orchestrates · Backend pipeline operations coordinate tool execution