# shubhayu-dev/gambit architecture

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

- Interactive diagram: https://gitdiagram.com/shubhayu-dev/gambit
- Repository: https://github.com/shubhayu-dev/gambit

## Overview

GAMBIT evaluates chess agents and uses their move-level telemetry to drive a closed-loop workflow: load benchmark positions, run agent evaluations, analyze performance, investigate candidate causes, test interventions on held-out positions, and report results. The engine provides chess rules, agents, search, and evaluation; supporting branches add Lichess data, anomaly and disagreement analysis, and move commentary. The README documents these capabilities, while sampled source confirms key evaluation, diagnostic, and integration links; some unsampled subsystem wiring is therefore shown only where explicitly documented.

Main entry points: [`run_full_pipeline.py`](https://github.com/shubhayu-dev/gambit/blob/main/run_full_pipeline.py) (Pipeline Runner), [`experiments/runner.py`](https://github.com/shubhayu-dev/gambit/blob/main/experiments/runner.py) (Experiment Runner), [`engine/search.py`](https://github.com/shubhayu-dev/gambit/blob/main/engine/search.py) (Alpha-Beta Search), [`analysis/commentary.py`](https://github.com/shubhayu-dev/gambit/blob/main/analysis/commentary.py) (Move Commentary)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_engine["Chess Engine"]
  node_board["Chess Environment<br/>[environment.py]"]
  node_agents["Agent Implementations<br/>[agents.py]"]
  node_search["Alpha-Beta Search<br/>[search.py]"]
  node_evaluation_fn["Position Evaluation<br/>[evaluation.py]"]
end

subgraph group_evaluation["Evaluation Pipeline"]
  node_pipeline["Pipeline Runner"]
  node_lichess["Lichess Loader<br/>[lichess_data.py]"]
  node_benchmark["Experiment Runner<br/>[runner.py]"]
  node_store[("Trajectory Store<br/>[data_store.py]")]
end

subgraph group_diagnosis["Diagnosis Loop"]
  node_diagnostic["Empirical Investigation"]
  node_hypotheses["Hypothesis Formation<br/>[hypotheses.py]"]
  node_intervention["Held-out Validation<br/>[intervention.py]"]
  node_reasoner["LLM Diagnosis<br/>[llm_reasoner.py]"]
end

subgraph group_insight["Analysis &amp; Reporting"]
  node_metrics["Metrics &amp; Profiling<br/>[metrics.py]"]
  node_anomaly["Anomaly Detection<br/>[anomaly.py]"]
  node_disagreement["Agent Disagreement<br/>[disagreement.py]"]
  node_commentary["Move Commentary<br/>[commentary.py]"]
  node_rule_commentary["Rule Commentary"]
  node_report["HTML Report<br/>[report_html.py]"]
end

node_user(("Evaluator"))
node_gemini["Gemini API"]
node_ollama["Ollama Service"]

node_user -->|"starts run"| node_pipeline
node_pipeline -->|"loads positions"| node_lichess
node_pipeline -->|"runs evaluation"| node_benchmark
node_benchmark -->|"builds positions"| node_board
node_benchmark -->|"requests moves"| node_agents
node_agents -->|"searches moves"| node_search
node_search -->|"scores positions"| node_evaluation_fn
node_search -->|"queries moves"| node_board
node_benchmark -->|"writes trajectories"| node_store
node_pipeline -->|"summarizes records"| node_metrics
node_pipeline -->|"detects anomalies"| node_anomaly
node_pipeline -->|"compares agents"| node_disagreement
node_pipeline -->|"investigates blunders"| node_diagnostic
node_diagnostic -->|"forms hypotheses"| node_hypotheses
node_pipeline -->|"checks candidates"| node_intervention
node_pipeline -->|"submits evidence"| node_reasoner
node_reasoner -.->|"requests diagnosis"| node_gemini
node_pipeline -->|"generates report"| node_report
node_rule_commentary -->|"filters commentary"| node_commentary
node_commentary -.->|"requests annotations"| node_gemini
node_commentary -.->|"requests annotations"| node_ollama

click node_pipeline "https://github.com/shubhayu-dev/gambit/blob/main/run_full_pipeline.py"
click node_lichess "https://github.com/shubhayu-dev/gambit/blob/main/experiments/lichess_data.py"
click node_benchmark "https://github.com/shubhayu-dev/gambit/blob/main/experiments/runner.py"
click node_store "https://github.com/shubhayu-dev/gambit/blob/main/experiments/data_store.py"
click node_board "https://github.com/shubhayu-dev/gambit/blob/main/engine/environment.py"
click node_agents "https://github.com/shubhayu-dev/gambit/blob/main/engine/agents.py"
click node_search "https://github.com/shubhayu-dev/gambit/blob/main/engine/search.py"
click node_evaluation_fn "https://github.com/shubhayu-dev/gambit/blob/main/engine/evaluation.py"
click node_metrics "https://github.com/shubhayu-dev/gambit/blob/main/analysis/metrics.py"
click node_anomaly "https://github.com/shubhayu-dev/gambit/blob/main/analysis/anomaly.py"
click node_disagreement "https://github.com/shubhayu-dev/gambit/blob/main/analysis/disagreement.py"
click node_commentary "https://github.com/shubhayu-dev/gambit/blob/main/analysis/commentary.py"
click node_rule_commentary "https://github.com/shubhayu-dev/gambit/blob/main/analysis/rule_based_commentary.py"
click node_diagnostic "https://github.com/shubhayu-dev/gambit/blob/main/diagnosis/diagnostic_experiment.py"
click node_hypotheses "https://github.com/shubhayu-dev/gambit/blob/main/diagnosis/hypotheses.py"
click node_intervention "https://github.com/shubhayu-dev/gambit/blob/main/diagnosis/intervention.py"
click node_reasoner "https://github.com/shubhayu-dev/gambit/blob/main/diagnosis/llm_reasoner.py"
click node_report "https://github.com/shubhayu-dev/gambit/blob/main/dashboard/report_html.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_board,node_agents,node_search,node_evaluation_fn toneBlue
class node_pipeline,node_lichess,node_benchmark,node_store toneAmber
class node_diagnostic,node_hypotheses,node_intervention,node_reasoner,node_gemini toneMint
class node_metrics,node_anomaly,node_disagreement,node_commentary,node_rule_commentary,node_report toneRose
class node_user,node_ollama toneIndigo
```

## Components

### Chess Engine

- [Chess Environment](https://github.com/shubhayu-dev/gambit/blob/main/engine/environment.py): `engine/environment.py`
- [Agent Implementations](https://github.com/shubhayu-dev/gambit/blob/main/engine/agents.py): `engine/agents.py`
- [Alpha-Beta Search](https://github.com/shubhayu-dev/gambit/blob/main/engine/search.py): `engine/search.py`
- [Position Evaluation](https://github.com/shubhayu-dev/gambit/blob/main/engine/evaluation.py): `engine/evaluation.py`

### Evaluation Pipeline

- [Pipeline Runner](https://github.com/shubhayu-dev/gambit/blob/main/run_full_pipeline.py): `run_full_pipeline.py`
- [Lichess Loader](https://github.com/shubhayu-dev/gambit/blob/main/experiments/lichess_data.py): `experiments/lichess_data.py`
- [Experiment Runner](https://github.com/shubhayu-dev/gambit/blob/main/experiments/runner.py): `experiments/runner.py`
- [Trajectory Store](https://github.com/shubhayu-dev/gambit/blob/main/experiments/data_store.py): `experiments/data_store.py`

### Diagnosis Loop

- [Empirical Investigation](https://github.com/shubhayu-dev/gambit/blob/main/diagnosis/diagnostic_experiment.py): `diagnosis/diagnostic_experiment.py`
- [Hypothesis Formation](https://github.com/shubhayu-dev/gambit/blob/main/diagnosis/hypotheses.py): `diagnosis/hypotheses.py`
- [Held-out Validation](https://github.com/shubhayu-dev/gambit/blob/main/diagnosis/intervention.py): `diagnosis/intervention.py`
- [LLM Diagnosis](https://github.com/shubhayu-dev/gambit/blob/main/diagnosis/llm_reasoner.py): `diagnosis/llm_reasoner.py`

### Analysis & Reporting

- [Metrics & Profiling](https://github.com/shubhayu-dev/gambit/blob/main/analysis/metrics.py): `analysis/metrics.py`
- [Anomaly Detection](https://github.com/shubhayu-dev/gambit/blob/main/analysis/anomaly.py): `analysis/anomaly.py`
- [Agent Disagreement](https://github.com/shubhayu-dev/gambit/blob/main/analysis/disagreement.py): `analysis/disagreement.py`
- [Move Commentary](https://github.com/shubhayu-dev/gambit/blob/main/analysis/commentary.py): `analysis/commentary.py`
- [Rule Commentary](https://github.com/shubhayu-dev/gambit/blob/main/analysis/rule_based_commentary.py): `analysis/rule_based_commentary.py`
- [HTML Report](https://github.com/shubhayu-dev/gambit/blob/main/dashboard/report_html.py): `dashboard/report_html.py`

### Other components

- **Evaluator**
- **Gemini API**
- **Ollama Service**

## Connections

- Evaluator → Pipeline Runner: starts run
- Pipeline Runner → Lichess Loader: loads positions
- Pipeline Runner → Experiment Runner: runs evaluation
- Experiment Runner → Chess Environment: builds positions
- Experiment Runner → Agent Implementations: requests moves
- Agent Implementations → Alpha-Beta Search: searches moves
- Alpha-Beta Search → Position Evaluation: scores positions
- Alpha-Beta Search → Chess Environment: queries moves
- Experiment Runner → Trajectory Store: writes trajectories
- Pipeline Runner → Metrics & Profiling: summarizes records
- Pipeline Runner → Anomaly Detection: detects anomalies
- Pipeline Runner → Agent Disagreement: compares agents
- Pipeline Runner → Empirical Investigation: investigates blunders
- Empirical Investigation → Hypothesis Formation: forms hypotheses
- Pipeline Runner → Held-out Validation: checks candidates
- Pipeline Runner → LLM Diagnosis: submits evidence
- LLM Diagnosis → Gemini API: requests diagnosis
- Pipeline Runner → HTML Report: generates report
- Rule Commentary → Move Commentary: filters commentary
- Move Commentary → Gemini API: requests annotations
- Move Commentary → Ollama Service: requests annotations