# lightvector/katago architecture

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

- Interactive diagram: https://gitdiagram.com/lightvector/katago
- Repository: https://github.com/lightvector/katago

## Overview

#### Purpose and entry points
KataGo is a C++ Go engine using neural-network-guided Monte Carlo graph search, plus Python tooling for training and self-play. The executable starts at `cpp/main.cpp`, dispatching subcommands through `cpp/command/commandline.cpp`. Primary operational interfaces are GTP (`cpp/command/gtp.cpp`), JSON line-based analysis (`cpp/command/analysis.cpp`), benchmarking, matches, and self-play.

#### Game-state foundation
Rules, board mutation, legality, scoring state, and repetition/history semantics form the deterministic game layer consumed by search and protocols. `Board` models positions; `BoardHistory` carries game progression and rules-dependent outcome context. Graph-position identity supports transposition-aware search.
Paths: `cpp/game/board.cpp`, `cpp/game/boardhistory.cpp`, `cpp/game/rules.cpp`, `cpp/game/graphhash.cpp`.

#### Search and decision pipeline
The search subsystem owns the Monte Carlo graph: nodes, transposition tables, PUCT selection, expansion, backup, time controls, and multithreaded execution. It requests neural evaluations for leaf positions, caches them, then exposes move/analysis results to callers. This is the core boundary between Go semantics and model inference.
Paths: `cpp/search/search.cpp`, `cpp/search/searchnode.cpp`, `cpp/search/searchpuct.cpp`, `cpp/search/evalcache.cpp`, `cpp/search/asyncbot.cpp`.

#### Neural inference abstraction and backends
A backend-neutral evaluator batches encoded board positions, executes the loaded model, and returns policy/value/ownership-style outputs to search. Model loading/version interpretation is separated from accelerator implementation. Supported material runtimes are Eigen CPU, OpenCL, CUDA/cuDNN, TensorRT, and macOS Metal; CUDA and OpenCL include native kernels/helpers.
Paths: `cpp/neuralnet/nneval.cpp`, `cpp/neuralnet/nninputs.cpp`, `cpp/neuralnet/cudabackend.cpp`, `cpp/neuralnet/openclbackend.cpp`, `cpp/neuralnet/trtbackend.cpp`, `cpp/neuralnet/metalbackend.swift`.

#### Protocol and command surfaces
Command handlers assemble configuration, model evaluators, search bots, and output adapters. GTP is the interactive text-protocol boundary for Go GUIs. The analysis command is a batched JSON service boundary intended for external backend applications. Match, self-play, contribution, and gatekeeper commands reuse the engine for training operations.
Paths: `cpp/command/gtp.cpp`, `cpp/command/analysis.cpp`, `cpp/command/selfplay.cpp`, `cpp/command/match.cpp`, `cpp/command/gatekeeper.cpp`.

#### Training-data and distributed self-play flow
Self-play runs games through the same search/inference stack and serializes positions/training targets; SGF and model/data file handling are separate I/O boundaries. The optional distributed client obtains and executes remote contribution tasks over HTTP. Training configurations encode self-play and gatekeeper job parameters.
Paths: `cpp/program/selfplaymanager.cpp`, `cpp/dataio/trainingwrite.cpp`, `cpp/dataio/loadmodel.cpp`, `cpp/distributed/client.cpp`, `cpp/configs/training/selfplay8mainb18.cfg`.

#### Python training and model lifecycle
Python consumes generated training data, defines PyTorch model architectures, runs optimization/metrics, and exports models for C++ inference. Shell loops coordinate shuffle, train, export, and distributed self-play stages; the public training ecosystem is associated with katagotraining.org.
Paths: `python/train.py`, `python/katago/train/data_processing_pytorch.py`, `python/katago/train/model_pytorch.py`, `python/export_model_pytorch.py`, `python/selfplay/synchronous_loop.sh`.

#### Build and embedded dependencies
CMake builds the native engine and selects platform/backend capabilities. The repository vendors inference-adjacent and portability dependencies, notably CLBlast OpenCL kernels, cuDNN frontend headers, ONNX definitions, HTTP client support, and CoreML conversion code.
Paths: `cpp/CMakeLists.txt`, `cpp/external/clblast`, `cpp/external/cudnn-frontend`, `cpp/external/onnx`, `cpp/external/katagocoreml`.

Main entry points: [`cpp/search/search.cpp`](https://github.com/lightvector/katago/blob/master/cpp/search/search.cpp) (Monte Carlo graph search), [`cpp/neuralnet/nneval.cpp`](https://github.com/lightvector/katago/blob/master/cpp/neuralnet/nneval.cpp) (Neural evaluator), [`cpp/program/selfplaymanager.cpp`](https://github.com/lightvector/katago/blob/master/cpp/program/selfplaymanager.cpp) (Self-play manager), [`cpp/command/commandline.cpp`](https://github.com/lightvector/katago/blob/master/cpp/command/commandline.cpp) (Command dispatcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_engine["C++ Engine"]
  node_main["Executable entry<br/>C++ entrypoint<br/>[main.cpp]"]
  node_commandline["Command dispatcher<br/>C++ commands<br/>[commandline.cpp]"]
  node_protocols["GTP and analysis<br/>protocol handlers<br/>[gtp.cpp]"]
  node_training_commands["Training commands<br/>command handlers<br/>[selfplay.cpp]"]
  node_board["Board state<br/>Go position<br/>[board.cpp]"]
  node_history["Game history and rules<br/>game semantics<br/>[boardhistory.cpp]"]
  node_graphhash["Position identity<br/>graph hashing<br/>[graphhash.cpp]"]
  node_asyncbot["Async search bot<br/>search API<br/>[asyncbot.cpp]"]
  node_search["Monte Carlo graph search<br/>search engine<br/>[search.cpp]"]
  node_searchnode["Search nodes<br/>search graph<br/>[searchnode.cpp]"]
  node_evalcache[("Evaluation cache<br/>inference cache<br/>[evalcache.cpp]")]
end

subgraph group_neural["Neural Inference"]
  node_nneval["Neural evaluator<br/>backend-neutral inference<br/>[nneval.cpp]"]
  node_nninputs["NN input encoding<br/>feature encoder<br/>[nninputs.cpp]"]
  node_backends{{"Accelerator backends<br/>CPU/GPU runtimes<br/>[cudabackend.cpp]"}}
  node_modelio["Model loading<br/>model I/O<br/>[loadmodel.cpp]"]
end

subgraph group_training["Self-Play &amp; Training"]
  node_selfplay_manager["Self-play manager<br/>game generation"]
  node_training_writer["Training data writer<br/>data serialization<br/>[trainingwrite.cpp]"]
  node_distributed_client["Distributed client<br/>HTTP worker<br/>[client.cpp]"]
  node_pytorch_training["PyTorch training<br/>model optimization<br/>[train.py]"]
  node_model_export["Model export<br/>model conversion"]
  node_training_loop["Training loop<br/>shell orchestration"]
end

subgraph group_build["Build &amp; Dependencies"]
  node_cmake["CMake build<br/>native build<br/>[CMakeLists.txt]"]
  node_dependencies["Embedded dependencies<br/>vendored libraries"]
end

node_main -->|"dispatches"| node_commandline
node_commandline -->|"runs"| node_protocols
node_commandline -->|"runs"| node_training_commands
node_protocols -->|"requests moves and analysis"| node_asyncbot
node_training_commands -->|"starts"| node_selfplay_manager
node_asyncbot -->|"drives"| node_search
node_search -->|"traverses"| node_searchnode
node_search -->|"evaluates legal positions"| node_board
node_search -->|"applies game context"| node_history
node_searchnode -->|"uses identity"| node_graphhash
node_search -->|"looks up evaluations"| node_evalcache
node_evalcache -.->|"misses request inference"| node_nneval
node_nneval -->|"encodes positions"| node_nninputs
node_nneval -->|"executes batches"| node_backends
node_modelio -->|"loads model into"| node_nneval
node_selfplay_manager -->|"plays games with"| node_asyncbot
node_selfplay_manager -->|"emits targets"| node_training_writer
node_distributed_client -->|"runs assigned tasks"| node_selfplay_manager
node_training_writer -->|"provides training data"| node_pytorch_training
node_pytorch_training -->|"produces trained model"| node_model_export
node_model_export -->|"exports for inference"| node_modelio
node_training_loop -->|"orchestrates"| node_pytorch_training
node_training_loop -->|"coordinates"| node_distributed_client
node_cmake -->|"builds"| node_main
node_cmake -->|"selects capabilities"| node_backends
node_dependencies -->|"supports"| node_backends

click node_main "https://github.com/lightvector/katago/blob/master/cpp/main.cpp"
click node_commandline "https://github.com/lightvector/katago/blob/master/cpp/command/commandline.cpp"
click node_protocols "https://github.com/lightvector/katago/blob/master/cpp/command/gtp.cpp"
click node_training_commands "https://github.com/lightvector/katago/blob/master/cpp/command/selfplay.cpp"
click node_board "https://github.com/lightvector/katago/blob/master/cpp/game/board.cpp"
click node_history "https://github.com/lightvector/katago/blob/master/cpp/game/boardhistory.cpp"
click node_graphhash "https://github.com/lightvector/katago/blob/master/cpp/game/graphhash.cpp"
click node_asyncbot "https://github.com/lightvector/katago/blob/master/cpp/search/asyncbot.cpp"
click node_search "https://github.com/lightvector/katago/blob/master/cpp/search/search.cpp"
click node_searchnode "https://github.com/lightvector/katago/blob/master/cpp/search/searchnode.cpp"
click node_evalcache "https://github.com/lightvector/katago/blob/master/cpp/search/evalcache.cpp"
click node_nneval "https://github.com/lightvector/katago/blob/master/cpp/neuralnet/nneval.cpp"
click node_nninputs "https://github.com/lightvector/katago/blob/master/cpp/neuralnet/nninputs.cpp"
click node_backends "https://github.com/lightvector/katago/blob/master/cpp/neuralnet/cudabackend.cpp"
click node_modelio "https://github.com/lightvector/katago/blob/master/cpp/dataio/loadmodel.cpp"
click node_selfplay_manager "https://github.com/lightvector/katago/blob/master/cpp/program/selfplaymanager.cpp"
click node_training_writer "https://github.com/lightvector/katago/blob/master/cpp/dataio/trainingwrite.cpp"
click node_distributed_client "https://github.com/lightvector/katago/blob/master/cpp/distributed/client.cpp"
click node_pytorch_training "https://github.com/lightvector/katago/blob/master/python/train.py"
click node_model_export "https://github.com/lightvector/katago/blob/master/python/export_model_pytorch.py"
click node_training_loop "https://github.com/lightvector/katago/blob/master/python/selfplay/synchronous_loop.sh"
click node_cmake "https://github.com/lightvector/katago/blob/master/cpp/CMakeLists.txt"
click node_dependencies "https://github.com/lightvector/katago/tree/master/cpp/external/clblast"

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_main,node_commandline,node_protocols,node_training_commands,node_board,node_history,node_graphhash,node_asyncbot,node_search,node_searchnode,node_evalcache toneBlue
class node_nneval,node_nninputs,node_backends,node_modelio toneAmber
class node_selfplay_manager,node_training_writer,node_distributed_client,node_pytorch_training,node_model_export,node_training_loop toneMint
class node_cmake,node_dependencies toneRose
```

## Components

### C++ Engine

- [Executable entry](https://github.com/lightvector/katago/blob/master/cpp/main.cpp): C++ entrypoint · `cpp/main.cpp`
- [Command dispatcher](https://github.com/lightvector/katago/blob/master/cpp/command/commandline.cpp): C++ commands · `cpp/command/commandline.cpp`
- [GTP and analysis](https://github.com/lightvector/katago/blob/master/cpp/command/gtp.cpp): protocol handlers · Interactive GTP and JSON-lines analysis interfaces. · `cpp/command/gtp.cpp`
- [Training commands](https://github.com/lightvector/katago/blob/master/cpp/command/selfplay.cpp): command handlers · Self-play, match, and gatekeeper operational modes. · `cpp/command/selfplay.cpp`
- [Board state](https://github.com/lightvector/katago/blob/master/cpp/game/board.cpp): Go position · Board mutation, legality, and scoring state. · `cpp/game/board.cpp`
- [Game history and rules](https://github.com/lightvector/katago/blob/master/cpp/game/boardhistory.cpp): game semantics · Rules-dependent progression, outcomes, and repetition semantics. · `cpp/game/boardhistory.cpp`
- [Position identity](https://github.com/lightvector/katago/blob/master/cpp/game/graphhash.cpp): graph hashing · Transposition-aware position identity. · `cpp/game/graphhash.cpp`
- [Async search bot](https://github.com/lightvector/katago/blob/master/cpp/search/asyncbot.cpp): search API · Search-facing interface used by commands. · `cpp/search/asyncbot.cpp`
- [Monte Carlo graph search](https://github.com/lightvector/katago/blob/master/cpp/search/search.cpp): search engine · Multithreaded PUCT selection, expansion, backup, and time control. · `cpp/search/search.cpp`
- [Search nodes](https://github.com/lightvector/katago/blob/master/cpp/search/searchnode.cpp): search graph · Nodes and transposition-aware graph state. · `cpp/search/searchnode.cpp`
- [Evaluation cache](https://github.com/lightvector/katago/blob/master/cpp/search/evalcache.cpp): inference cache · `cpp/search/evalcache.cpp`

### Neural Inference

- [Neural evaluator](https://github.com/lightvector/katago/blob/master/cpp/neuralnet/nneval.cpp): backend-neutral inference · Batches encoded positions and returns policy, value, and ownership outputs. · `cpp/neuralnet/nneval.cpp`
- [NN input encoding](https://github.com/lightvector/katago/blob/master/cpp/neuralnet/nninputs.cpp): feature encoder · `cpp/neuralnet/nninputs.cpp`
- [Accelerator backends](https://github.com/lightvector/katago/blob/master/cpp/neuralnet/cudabackend.cpp): CPU/GPU runtimes · Eigen, CUDA, OpenCL, TensorRT, and Metal execution backends. · `cpp/neuralnet/cudabackend.cpp`
- [Model loading](https://github.com/lightvector/katago/blob/master/cpp/dataio/loadmodel.cpp): model I/O · Loads and interprets exported neural models. · `cpp/dataio/loadmodel.cpp`

### Self-Play & Training

- [Self-play manager](https://github.com/lightvector/katago/blob/master/cpp/program/selfplaymanager.cpp): game generation · Runs self-play games through the engine stack. · `cpp/program/selfplaymanager.cpp`
- [Training data writer](https://github.com/lightvector/katago/blob/master/cpp/dataio/trainingwrite.cpp): data serialization · Writes positions and training targets. · `cpp/dataio/trainingwrite.cpp`
- [Distributed client](https://github.com/lightvector/katago/blob/master/cpp/distributed/client.cpp): HTTP worker · Fetches and executes remote contribution tasks. · `cpp/distributed/client.cpp`
- [PyTorch training](https://github.com/lightvector/katago/blob/master/python/train.py): model optimization · Consumes self-play data and trains neural architectures. · `python/train.py`
- [Model export](https://github.com/lightvector/katago/blob/master/python/export_model_pytorch.py): model conversion · Exports trained PyTorch models for C++ inference. · `python/export_model_pytorch.py`
- [Training loop](https://github.com/lightvector/katago/blob/master/python/selfplay/synchronous_loop.sh): shell orchestration · Coordinates shuffle, train, export, and distributed self-play stages. · `python/selfplay/synchronous_loop.sh`

### Build & Dependencies

- [CMake build](https://github.com/lightvector/katago/blob/master/cpp/CMakeLists.txt): native build · Builds the engine and selects platform inference capabilities. · `cpp/CMakeLists.txt`
- [Embedded dependencies](https://github.com/lightvector/katago/tree/master/cpp/external/clblast): vendored libraries · Inference and portability dependencies including CLBlast, cuDNN frontend, ONNX, and CoreML support. · `cpp/external/clblast`

## Connections

- Executable entry → Command dispatcher: dispatches
- Command dispatcher → GTP and analysis: runs
- Command dispatcher → Training commands: runs
- GTP and analysis → Async search bot: requests moves and analysis
- Training commands → Self-play manager: starts
- Async search bot → Monte Carlo graph search: drives
- Monte Carlo graph search → Search nodes: traverses
- Monte Carlo graph search → Board state: evaluates legal positions
- Monte Carlo graph search → Game history and rules: applies game context
- Search nodes → Position identity: uses identity
- Monte Carlo graph search → Evaluation cache: looks up evaluations
- Evaluation cache → Neural evaluator: misses request inference
- Neural evaluator → NN input encoding: encodes positions
- Neural evaluator → Accelerator backends: executes batches
- Model loading → Neural evaluator: loads model into
- Self-play manager → Async search bot: plays games with
- Self-play manager → Training data writer: emits targets
- Distributed client → Self-play manager: runs assigned tasks
- Training data writer → PyTorch training: provides training data
- PyTorch training → Model export: produces trained model
- Model export → Model loading: exports for inference
- Training loop → PyTorch training: orchestrates
- Training loop → Distributed client: coordinates
- CMake build → Executable entry: builds
- CMake build → Accelerator backends: selects capabilities
- Embedded dependencies → Accelerator backends: supports