# gca-spatial-reasoning/gca architecture

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

- Interactive diagram: https://gitdiagram.com/gca-spatial-reasoning/gca
- Repository: https://github.com/gca-spatial-reasoning/gca

## Overview

GCA turns a benchmark sample and its images into a structured spatial answer. The principal flow formalizes the task, plans tool calls, executes geometric and code-based computations, and returns a numeric result with a natural-language summary. The README also identifies five supported evaluation benchmarks; their individual adapters are grouped because their dispatch wiring was not sampled. The graph reflects documented and excerpted relationships only; unsampled components and links are represented at directory level where necessary.

Main entry points: [`workflow/workflow.py`](https://github.com/gca-spatial-reasoning/gca/blob/main/workflow/workflow.py) (Workflow runtime), [`workflow/nodes/solver/executor.py`](https://github.com/gca-spatial-reasoning/gca/blob/main/workflow/nodes/solver/executor.py) (Tool execution), [`tools/apis/reconstructor.py`](https://github.com/gca-spatial-reasoning/gca/blob/main/tools/apis/reconstructor.py) (Geometric reconstruction), [`workflow/nodes/solver/planner.py`](https://github.com/gca-spatial-reasoning/gca/blob/main/workflow/nodes/solver/planner.py) (Tool planning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_evaluation["Evaluation"]
  node_benchmarks["Benchmark adapters"]
  node_benchmark_base["Evaluation base<br/>[base.py]"]
  node_agent_entry["Agent entrypoint<br/>[agent.py]"]
  node_answer["Spatial answer"]
end

subgraph group_workflow["Agent workflow"]
  node_workflow_runtime["Workflow runtime<br/>[workflow.py]"]
  node_analyst["Task formalization<br/>[analyst.py]"]
  node_meta_planner["Task routing<br/>[meta_planner.py]"]
  node_planner["Tool planning<br/>[planner.py]"]
  node_executor["Tool execution<br/>[executor.py]"]
end

subgraph group_geometry["Spatial tools"]
  node_reconstructor["Geometric reconstruction<br/>[reconstructor.py]"]
  node_vggt["3D reconstruction<br/>[vggt_model.py]"]
  node_aligner["Scene alignment<br/>[scene_aligner.py]"]
  node_vision_tools["Vision tools"]
  node_final_answer["Answer generation<br/>[final_answer.py]"]
end

subgraph group_models["Models and execution"]
  node_reasoner["Reasoning model<br/>[cot_reasoner.py]"]
  node_python_tool["Code computation<br/>[python_tool.py]"]
  node_llm_clients["LLM clients"]
  node_retry["LLM retry helper<br/>[llm_invoke.py]"]
end

subgraph group_infrastructure["State and reporting"]
  node_config["Runtime configuration<br/>[config.py]"]
  node_state["Agent state<br/>[state.py]"]
  node_tool_contract["Tool and context types<br/>[base.py]"]
  node_tool_dispatch["Tool dispatch<br/>[tool_call.py]"]
  node_image_io["Image loading<br/>[io.py]"]
  node_reporting["Session logging<br/>[logging.py]"]
end

node_user(("Benchmark sample"))

node_user -->|"submits sample"| node_agent_entry
node_agent_entry -.->|"selects benchmark"| node_benchmarks
node_benchmarks -->|"implements"| node_benchmark_base
node_agent_entry -.->|"starts agent"| node_workflow_runtime
node_workflow_runtime -->|"reads settings"| node_config
node_workflow_runtime -->|"routes workflow"| node_analyst
node_workflow_runtime -->|"optionally routes"| node_meta_planner
node_workflow_runtime -->|"routes workflow"| node_planner
node_workflow_runtime -->|"routes workflow"| node_executor
node_workflow_runtime -->|"manages state"| node_state
node_analyst -->|"updates context"| node_state
node_analyst -.->|"analyzes task"| node_reasoner
node_planner -->|"reads workspace"| node_state
node_planner -->|"invokes with retry"| node_retry
node_retry -.->|"calls invoker"| node_llm_clients
node_planner -->|"produces tool plan"| node_executor
node_executor -->|"records results"| node_state
node_executor -->|"dispatches calls"| node_tool_dispatch
node_tool_dispatch -->|"uses tool interface"| node_tool_contract
node_executor -->|"executes code calls"| node_python_tool
node_executor -.->|"executes geometry calls"| node_reconstructor
node_reconstructor -->|"asks for strategy"| node_reasoner
node_reconstructor -->|"reconstructs scenes"| node_vggt
node_reconstructor -->|"aligns scenes"| node_aligner
node_reconstructor -->|"requests detections"| node_vision_tools
node_vggt -.->|"loads images"| node_image_io
node_python_tool -->|"generates code"| node_retry
node_python_tool -.->|"uses code model"| node_reasoner
node_workflow_runtime -.->|"extracts final result"| node_final_answer
node_workflow_runtime -->|"logs session"| node_reporting
node_final_answer -.->|"returns result"| node_answer
node_workflow_runtime -->|"returns summary"| node_answer

click node_benchmarks "https://github.com/gca-spatial-reasoning/gca/tree/main/evals"
click node_benchmark_base "https://github.com/gca-spatial-reasoning/gca/blob/main/evals/base.py"
click node_agent_entry "https://github.com/gca-spatial-reasoning/gca/blob/main/entrypoints/agent.py"
click node_workflow_runtime "https://github.com/gca-spatial-reasoning/gca/blob/main/workflow/workflow.py"
click node_config "https://github.com/gca-spatial-reasoning/gca/blob/main/workflow/config.py"
click node_state "https://github.com/gca-spatial-reasoning/gca/blob/main/workflow/state.py"
click node_analyst "https://github.com/gca-spatial-reasoning/gca/blob/main/workflow/nodes/analyst.py"
click node_meta_planner "https://github.com/gca-spatial-reasoning/gca/blob/main/workflow/nodes/meta_planner.py"
click node_planner "https://github.com/gca-spatial-reasoning/gca/blob/main/workflow/nodes/solver/planner.py"
click node_executor "https://github.com/gca-spatial-reasoning/gca/blob/main/workflow/nodes/solver/executor.py"
click node_reasoner "https://github.com/gca-spatial-reasoning/gca/blob/main/tools/apis/cot_reasoner.py"
click node_reconstructor "https://github.com/gca-spatial-reasoning/gca/blob/main/tools/apis/reconstructor.py"
click node_vggt "https://github.com/gca-spatial-reasoning/gca/blob/main/tools/apis/vggt_model.py"
click node_aligner "https://github.com/gca-spatial-reasoning/gca/blob/main/tools/apis/scene_aligner.py"
click node_vision_tools "https://github.com/gca-spatial-reasoning/gca/tree/main/tools/apis"
click node_python_tool "https://github.com/gca-spatial-reasoning/gca/blob/main/tools/apis/python_tool.py"
click node_tool_contract "https://github.com/gca-spatial-reasoning/gca/blob/main/tools/apis/base.py"
click node_tool_dispatch "https://github.com/gca-spatial-reasoning/gca/blob/main/tools/tool_call.py"
click node_image_io "https://github.com/gca-spatial-reasoning/gca/blob/main/tools/apis/io.py"
click node_llm_clients "https://github.com/gca-spatial-reasoning/gca/tree/main/tools/llm_client"
click node_retry "https://github.com/gca-spatial-reasoning/gca/blob/main/tools/utils/llm_invoke.py"
click node_reporting "https://github.com/gca-spatial-reasoning/gca/blob/main/workflow/logging.py"
click node_final_answer "https://github.com/gca-spatial-reasoning/gca/blob/main/tools/apis/final_answer.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_benchmarks,node_benchmark_base,node_agent_entry,node_answer toneBlue
class node_workflow_runtime,node_analyst,node_meta_planner,node_planner,node_executor toneAmber
class node_reconstructor,node_vggt,node_aligner,node_vision_tools,node_final_answer toneMint
class node_reasoner,node_python_tool,node_llm_clients,node_retry toneRose
class node_config,node_state,node_tool_contract,node_tool_dispatch,node_image_io,node_reporting,node_user toneIndigo
```

## Components

### Evaluation

- [Benchmark adapters](https://github.com/gca-spatial-reasoning/gca/tree/main/evals): `evals`
- [Evaluation base](https://github.com/gca-spatial-reasoning/gca/blob/main/evals/base.py): `evals/base.py`
- [Agent entrypoint](https://github.com/gca-spatial-reasoning/gca/blob/main/entrypoints/agent.py): `entrypoints/agent.py`
- **Spatial answer**

### Agent workflow

- [Workflow runtime](https://github.com/gca-spatial-reasoning/gca/blob/main/workflow/workflow.py): `workflow/workflow.py`
- [Task formalization](https://github.com/gca-spatial-reasoning/gca/blob/main/workflow/nodes/analyst.py): `workflow/nodes/analyst.py`
- [Task routing](https://github.com/gca-spatial-reasoning/gca/blob/main/workflow/nodes/meta_planner.py): `workflow/nodes/meta_planner.py`
- [Tool planning](https://github.com/gca-spatial-reasoning/gca/blob/main/workflow/nodes/solver/planner.py): `workflow/nodes/solver/planner.py`
- [Tool execution](https://github.com/gca-spatial-reasoning/gca/blob/main/workflow/nodes/solver/executor.py): `workflow/nodes/solver/executor.py`

### Spatial tools

- [Geometric reconstruction](https://github.com/gca-spatial-reasoning/gca/blob/main/tools/apis/reconstructor.py): `tools/apis/reconstructor.py`
- [3D reconstruction](https://github.com/gca-spatial-reasoning/gca/blob/main/tools/apis/vggt_model.py): `tools/apis/vggt_model.py`
- [Scene alignment](https://github.com/gca-spatial-reasoning/gca/blob/main/tools/apis/scene_aligner.py): `tools/apis/scene_aligner.py`
- [Vision tools](https://github.com/gca-spatial-reasoning/gca/tree/main/tools/apis): `tools/apis`
- [Answer generation](https://github.com/gca-spatial-reasoning/gca/blob/main/tools/apis/final_answer.py): `tools/apis/final_answer.py`

### Models and execution

- [Reasoning model](https://github.com/gca-spatial-reasoning/gca/blob/main/tools/apis/cot_reasoner.py): `tools/apis/cot_reasoner.py`
- [Code computation](https://github.com/gca-spatial-reasoning/gca/blob/main/tools/apis/python_tool.py): `tools/apis/python_tool.py`
- [LLM clients](https://github.com/gca-spatial-reasoning/gca/tree/main/tools/llm_client): `tools/llm_client`
- [LLM retry helper](https://github.com/gca-spatial-reasoning/gca/blob/main/tools/utils/llm_invoke.py): `tools/utils/llm_invoke.py`

### State and reporting

- [Runtime configuration](https://github.com/gca-spatial-reasoning/gca/blob/main/workflow/config.py): `workflow/config.py`
- [Agent state](https://github.com/gca-spatial-reasoning/gca/blob/main/workflow/state.py): `workflow/state.py`
- [Tool and context types](https://github.com/gca-spatial-reasoning/gca/blob/main/tools/apis/base.py): `tools/apis/base.py`
- [Tool dispatch](https://github.com/gca-spatial-reasoning/gca/blob/main/tools/tool_call.py): `tools/tool_call.py`
- [Image loading](https://github.com/gca-spatial-reasoning/gca/blob/main/tools/apis/io.py): `tools/apis/io.py`
- [Session logging](https://github.com/gca-spatial-reasoning/gca/blob/main/workflow/logging.py): `workflow/logging.py`

### Other components

- **Benchmark sample**

## Connections

- Benchmark sample → Agent entrypoint: submits sample (evidence: `README.md`)
- Agent entrypoint → Benchmark adapters: selects benchmark
- Benchmark adapters → Evaluation base: implements (evidence: `evals/__init__.py`)
- Agent entrypoint → Workflow runtime: starts agent
- Workflow runtime → Runtime configuration: reads settings (evidence: `workflow/workflow.py`)
- Workflow runtime → Task formalization: routes workflow (evidence: `workflow/workflow.py`)
- Workflow runtime → Task routing: optionally routes (evidence: `workflow/workflow.py`)
- Workflow runtime → Tool planning: routes workflow (evidence: `workflow/workflow.py`)
- Workflow runtime → Tool execution: routes workflow (evidence: `workflow/workflow.py`)
- Workflow runtime → Agent state: manages state (evidence: `workflow/workflow.py`)
- Task formalization → Agent state: updates context (evidence: `workflow/nodes/analyst.py`)
- Task formalization → Reasoning model: analyzes task
- Tool planning → Agent state: reads workspace (evidence: `workflow/nodes/solver/planner.py`)
- Tool planning → LLM retry helper: invokes with retry (evidence: `workflow/nodes/solver/planner.py`)
- LLM retry helper → LLM clients: calls invoker
- Tool planning → Tool execution: produces tool plan (evidence: `workflow/nodes/solver/planner.py`)
- Tool execution → Agent state: records results (evidence: `workflow/state.py`)
- Tool execution → Tool dispatch: dispatches calls (evidence: `workflow/nodes/solver/executor.py`)
- Tool dispatch → Tool and context types: uses tool interface (evidence: `tools/tool_call.py`)
- Tool execution → Code computation: executes code calls (evidence: `workflow/nodes/solver/executor.py`)
- Tool execution → Geometric reconstruction: executes geometry calls
- Geometric reconstruction → Reasoning model: asks for strategy (evidence: `tools/apis/reconstructor.py`)
- Geometric reconstruction → 3D reconstruction: reconstructs scenes (evidence: `tools/apis/reconstructor.py`)
- Geometric reconstruction → Scene alignment: aligns scenes (evidence: `tools/apis/reconstructor.py`)
- Geometric reconstruction → Vision tools: requests detections (evidence: `tools/apis/reconstructor.py`)
- 3D reconstruction → Image loading: loads images (evidence: `tools/apis/vggt_model.py`)
- Code computation → LLM retry helper: generates code (evidence: `tools/apis/python_tool.py`)
- Code computation → Reasoning model: uses code model
- Workflow runtime → Answer generation: extracts final result
- Workflow runtime → Session logging: logs session (evidence: `workflow/workflow.py`)
- Answer generation → Spatial answer: returns result
- Workflow runtime → Spatial answer: returns summary (evidence: `workflow/workflow.py`)
