How ysingh-grid/gah-v2 works
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_registry.py Tool registry · internal.py Internal routes · planner.py Planner · tools.py Agent tools
Components 22
Control plane
Agent orchestration and task compilation
- RLM config · Configures the primary and sub-agents for the fast-rlm runtime
rlm/rlm_config.py - Tool pulling · Connects the agent runtime to available tools
rlm/pull_tools.py - Agent tools · Agent-facing tool definitions and wrappers
rlm/tools.py
Knowledge base
Prompt guidance and geometric primitives used by the agent
- Skills index · Markdown index of reasoning guides injected into prompts
skills/SKILLS.md - Skills loader · Loads skill guides on demand for prompting and repair behavior
skills/skills_loader.py - Primitives library · Structured primitive definitions, templates, and verification guidance
primitives/library.json
Tool boundary
Operational tools invoked by the agent
- Tool registry · Central registration point for agent-visible capabilities
tools/tools_registry.py - CadQuery exec · Runs CadQuery in a separate conda environment for geometry generation
tools/execute_cadquery.py - Mesh inspect · Performs mesh-level quality and validity checks
tools/inspect_mesh.py - Render views · Produces image views for human or vision review
tools/render_views.py - Vision verify · 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 · Internal JSON routes exposing safe backend operations
backend/routes/internal.py - Path guard · Restricts filesystem and repository access for backend operations
backend/security/path_guard.py - Pipeline svc · Backend service for pipeline operations and coordination
backend/services/pipeline_service.py - Skill svc · Backend service for reading and serving skill content
backend/services/skill_service.py - Trace svc · Backend service for trace access and persistence support
backend/services/trace_service.py
Runtime flow
Planning, compilation, execution, validation, and trace capture
- Planner · Turns tasks into structured actions and intermediate plans
runtime/planner.py - Runtime schema · Structured task and plan schema used across the runtime boundary
runtime/schema.py - Compiler · Compiles planned actions into executable runtime steps
runtime/compile.py - Write trace · Persists full run traces and execution metadata
tools/write_trace.py - Load trace · Loads prior traces for replay and debugging
tools/load_trace.py - Artifacts · Manages generated geometry, renders, and other run outputs
tools/artifacts.py
Connections 28
- 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