# sogliuzzol/chessbehaviors architecture

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

- Interactive diagram: https://gitdiagram.com/sogliuzzol/chessbehaviors
- Repository: https://github.com/sogliuzzol/chessbehaviors

## Overview

ChessBehaviors is a research workflow for modeling and evaluating human chess move choices with Maia-2 and adaptation/search variants. Researchers build position datasets from PGNs, generate predictions (including empirical ground truth), evaluate accuracy and distribution/style divergence, then export tables and heatmaps. The graph preserves the documented capability branches and the core model, search, pruning, and style-representation layers. Edges use README workflow statements or indexed source references; unsampled implementation details are not inferred.

Main entry points: [`evaluate_style.py`](https://github.com/sogliuzzol/chessbehaviors/blob/main/evaluate_style.py) (Style evaluation), [`models/base.py`](https://github.com/sogliuzzol/chessbehaviors/blob/main/models/base.py) (Policy wrappers), [`maia2_descent.py`](https://github.com/sogliuzzol/chessbehaviors/blob/main/maia2_descent.py) (Search variants), [`evaluate_style_common_fens.py`](https://github.com/sogliuzzol/chessbehaviors/blob/main/evaluate_style_common_fens.py) (Common-FEN style)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Dataset preparation"]
  node_dataset_builder["Dataset builder<br/>[build_dataset.py]"]
  node_data_utils["Data utilities<br/>[data.py]"]
  node_dataset_files[("Position datasets")]
end

subgraph group_prediction["Prediction models"]
  node_ground_truth["Ground truth<br/>[ground_truth.py]"]
  node_maia_baseline["Maia baseline<br/>[maia2_baseline.py]"]
  node_maia_ft["Fine-tuned Maia<br/>[maia2_ft.py]"]
  node_maia_nucleus["Nucleus variants<br/>[maia2_nucleus.py]"]
  node_search_variants["Search variants<br/>[maia2_descent.py]"]
  node_mcts_variants["MCTS variants<br/>[maia2_mcts.py]"]
  node_moe_variants["MoE-LoRA variants<br/>[maia2_moe_lora.py]"]
  node_predictions[("Prediction files")]
end

subgraph group_analysis["Evaluation and analysis"]
  node_move_accuracy["Move accuracy"]
  node_cp_error["CP error"]
  node_jsd_eval["JSD evaluation<br/>[evaluate_jsd.py]"]
  node_common_fens_jsd["Common-FEN JSD"]
  node_style_eval["Style evaluation<br/>[evaluate_style.py]"]
  node_common_fens_style["Common-FEN style"]
  node_jsd_heatmaps["JSD heatmaps"]
  node_style_heatmaps["Style heatmaps"]
  node_common_style_heatmaps["Common-FEN heatmaps"]
  node_tables["LaTeX tables<br/>[tabs.py]"]
end

subgraph group_core["Model internals"]
  node_base_model["Policy wrappers<br/>[base.py]"]
  node_finetuning["Player fine-tuning<br/>[maia_ft.py]"]
  node_moe_adapter["MoE-LoRA adapter<br/>[moe_lora.py]"]
  node_train_dataset["Training dataset<br/>[dataset.py]"]
  node_embeddings["Player embeddings<br/>[embeddings.py]"]
  node_pruning["Policy pruning<br/>[pruning.py]"]
  node_descent["Descent search<br/>[descent.py]"]
  node_mcts["MCTS search<br/>[mcts.py]"]
  node_transitions["Board transitions<br/>[transitions.py]"]
  node_style_model["Style manifold<br/>[style.py]"]
end

node_researcher(("Researcher"))
node_pgn["Raw PGN files"]

node_researcher -->|"builds data"| node_dataset_builder
node_pgn -->|"provides games"| node_dataset_builder
node_dataset_builder -->|"uses utilities"| node_data_utils
node_dataset_builder -->|"writes datasets"| node_dataset_files
node_dataset_files -->|"inputs positions"| node_ground_truth
node_dataset_files -->|"inputs positions"| node_maia_baseline
node_dataset_files -->|"inputs positions"| node_maia_ft
node_dataset_files -->|"inputs positions"| node_maia_nucleus
node_dataset_files -->|"inputs positions"| node_search_variants
node_dataset_files -->|"inputs positions"| node_mcts_variants
node_dataset_files -->|"inputs positions"| node_moe_variants
node_ground_truth -->|"writes predictions"| node_predictions
node_maia_baseline -->|"writes predictions"| node_predictions
node_maia_ft -->|"writes predictions"| node_predictions
node_maia_nucleus -->|"writes predictions"| node_predictions
node_search_variants -->|"writes predictions"| node_predictions
node_mcts_variants -->|"writes predictions"| node_predictions
node_moe_variants -->|"writes predictions"| node_predictions
node_predictions -->|"evaluates moves"| node_move_accuracy
node_predictions -->|"evaluates error"| node_cp_error
node_predictions -->|"evaluates distributions"| node_jsd_eval
node_predictions -->|"compares common FENs"| node_common_fens_jsd
node_predictions -->|"evaluates style"| node_style_eval
node_predictions -->|"compares common FENs"| node_common_fens_style
node_jsd_eval -->|"visualizes metrics"| node_jsd_heatmaps
node_style_eval -->|"visualizes metrics"| node_style_heatmaps
node_common_fens_style -->|"visualizes metrics"| node_common_style_heatmaps
node_move_accuracy -->|"tabulates results"| node_tables
node_cp_error -->|"tabulates results"| node_tables
node_jsd_eval -->|"tabulates results"| node_tables
node_style_eval -->|"tabulates results"| node_tables
node_maia_ft -->|"uses model API"| node_finetuning
node_search_variants -->|"uses wrappers"| node_base_model
node_mcts_variants -->|"uses wrappers"| node_base_model
node_search_variants -->|"uses pruning"| node_pruning
node_moe_variants -->|"uses adapter"| node_moe_adapter
node_finetuning -->|"trains on"| node_train_dataset
node_finetuning -->|"uses embeddings"| node_embeddings
node_moe_adapter -->|"wraps backbone"| node_base_model
node_base_model -->|"delegates search"| node_descent
node_base_model -->|"delegates search"| node_mcts
node_style_eval -->|"extracts transitions"| node_transitions
node_style_eval -->|"uses style analysis"| node_style_model
node_common_fens_style -->|"extracts transitions"| node_transitions
node_common_fens_style -->|"uses style analysis"| node_style_model
node_style_heatmaps -->|"uses style analysis"| node_style_model
node_common_style_heatmaps -->|"uses style analysis"| node_style_model

click node_dataset_builder "https://github.com/sogliuzzol/chessbehaviors/blob/main/build_dataset.py"
click node_data_utils "https://github.com/sogliuzzol/chessbehaviors/blob/main/utils/data.py"
click node_ground_truth "https://github.com/sogliuzzol/chessbehaviors/blob/main/ground_truth.py"
click node_maia_baseline "https://github.com/sogliuzzol/chessbehaviors/blob/main/maia2_baseline.py"
click node_maia_ft "https://github.com/sogliuzzol/chessbehaviors/blob/main/maia2_ft.py"
click node_maia_nucleus "https://github.com/sogliuzzol/chessbehaviors/blob/main/maia2_nucleus.py"
click node_search_variants "https://github.com/sogliuzzol/chessbehaviors/blob/main/maia2_descent.py"
click node_mcts_variants "https://github.com/sogliuzzol/chessbehaviors/blob/main/maia2_mcts.py"
click node_moe_variants "https://github.com/sogliuzzol/chessbehaviors/blob/main/maia2_moe_lora.py"
click node_move_accuracy "https://github.com/sogliuzzol/chessbehaviors/blob/main/evaluate_move_accuracy.py"
click node_cp_error "https://github.com/sogliuzzol/chessbehaviors/blob/main/evaluate_cp_error.py"
click node_jsd_eval "https://github.com/sogliuzzol/chessbehaviors/blob/main/evaluate_jsd.py"
click node_common_fens_jsd "https://github.com/sogliuzzol/chessbehaviors/blob/main/evaluate_common_fens_jsd.py"
click node_style_eval "https://github.com/sogliuzzol/chessbehaviors/blob/main/evaluate_style.py"
click node_common_fens_style "https://github.com/sogliuzzol/chessbehaviors/blob/main/evaluate_style_common_fens.py"
click node_jsd_heatmaps "https://github.com/sogliuzzol/chessbehaviors/blob/main/generate_jsd_heatmaps.py"
click node_style_heatmaps "https://github.com/sogliuzzol/chessbehaviors/blob/main/generate_style_heatmaps.py"
click node_common_style_heatmaps "https://github.com/sogliuzzol/chessbehaviors/blob/main/generate_style_heatmaps_common_fens.py"
click node_tables "https://github.com/sogliuzzol/chessbehaviors/blob/main/tabs.py"
click node_base_model "https://github.com/sogliuzzol/chessbehaviors/blob/main/models/base.py"
click node_finetuning "https://github.com/sogliuzzol/chessbehaviors/blob/main/models/maia_ft.py"
click node_moe_adapter "https://github.com/sogliuzzol/chessbehaviors/blob/main/models/adapters/moe_lora.py"
click node_train_dataset "https://github.com/sogliuzzol/chessbehaviors/blob/main/models/dataset.py"
click node_embeddings "https://github.com/sogliuzzol/chessbehaviors/blob/main/models/embeddings.py"
click node_pruning "https://github.com/sogliuzzol/chessbehaviors/blob/main/utils/pruning.py"
click node_descent "https://github.com/sogliuzzol/chessbehaviors/blob/main/search/descent.py"
click node_mcts "https://github.com/sogliuzzol/chessbehaviors/blob/main/search/mcts.py"
click node_transitions "https://github.com/sogliuzzol/chessbehaviors/blob/main/utils/transitions.py"
click node_style_model "https://github.com/sogliuzzol/chessbehaviors/blob/main/models/style.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_dataset_builder,node_data_utils,node_dataset_files toneBlue
class node_ground_truth,node_maia_baseline,node_maia_ft,node_maia_nucleus,node_search_variants,node_mcts_variants,node_moe_variants,node_predictions toneAmber
class node_move_accuracy,node_cp_error,node_jsd_eval,node_common_fens_jsd,node_style_eval,node_common_fens_style,node_jsd_heatmaps,node_style_heatmaps,node_common_style_heatmaps,node_tables toneMint
class node_base_model,node_finetuning,node_moe_adapter,node_train_dataset,node_embeddings,node_pruning,node_descent,node_mcts,node_transitions,node_style_model toneRose
class node_researcher,node_pgn toneIndigo
```

## Components

### Dataset preparation

- [Dataset builder](https://github.com/sogliuzzol/chessbehaviors/blob/main/build_dataset.py): `build_dataset.py`
- [Data utilities](https://github.com/sogliuzzol/chessbehaviors/blob/main/utils/data.py): `utils/data.py`
- **Position datasets**

### Prediction models

- [Ground truth](https://github.com/sogliuzzol/chessbehaviors/blob/main/ground_truth.py): `ground_truth.py`
- [Maia baseline](https://github.com/sogliuzzol/chessbehaviors/blob/main/maia2_baseline.py): `maia2_baseline.py`
- [Fine-tuned Maia](https://github.com/sogliuzzol/chessbehaviors/blob/main/maia2_ft.py): `maia2_ft.py`
- [Nucleus variants](https://github.com/sogliuzzol/chessbehaviors/blob/main/maia2_nucleus.py): `maia2_nucleus.py`
- [Search variants](https://github.com/sogliuzzol/chessbehaviors/blob/main/maia2_descent.py): `maia2_descent.py`
- [MCTS variants](https://github.com/sogliuzzol/chessbehaviors/blob/main/maia2_mcts.py): `maia2_mcts.py`
- [MoE-LoRA variants](https://github.com/sogliuzzol/chessbehaviors/blob/main/maia2_moe_lora.py): `maia2_moe_lora.py`
- **Prediction files**

### Evaluation and analysis

- [Move accuracy](https://github.com/sogliuzzol/chessbehaviors/blob/main/evaluate_move_accuracy.py): `evaluate_move_accuracy.py`
- [CP error](https://github.com/sogliuzzol/chessbehaviors/blob/main/evaluate_cp_error.py): `evaluate_cp_error.py`
- [JSD evaluation](https://github.com/sogliuzzol/chessbehaviors/blob/main/evaluate_jsd.py): `evaluate_jsd.py`
- [Common-FEN JSD](https://github.com/sogliuzzol/chessbehaviors/blob/main/evaluate_common_fens_jsd.py): `evaluate_common_fens_jsd.py`
- [Style evaluation](https://github.com/sogliuzzol/chessbehaviors/blob/main/evaluate_style.py): `evaluate_style.py`
- [Common-FEN style](https://github.com/sogliuzzol/chessbehaviors/blob/main/evaluate_style_common_fens.py): `evaluate_style_common_fens.py`
- [JSD heatmaps](https://github.com/sogliuzzol/chessbehaviors/blob/main/generate_jsd_heatmaps.py): `generate_jsd_heatmaps.py`
- [Style heatmaps](https://github.com/sogliuzzol/chessbehaviors/blob/main/generate_style_heatmaps.py): `generate_style_heatmaps.py`
- [Common-FEN heatmaps](https://github.com/sogliuzzol/chessbehaviors/blob/main/generate_style_heatmaps_common_fens.py): `generate_style_heatmaps_common_fens.py`
- [LaTeX tables](https://github.com/sogliuzzol/chessbehaviors/blob/main/tabs.py): `tabs.py`

### Model internals

- [Policy wrappers](https://github.com/sogliuzzol/chessbehaviors/blob/main/models/base.py): `models/base.py`
- [Player fine-tuning](https://github.com/sogliuzzol/chessbehaviors/blob/main/models/maia_ft.py): `models/maia_ft.py`
- [MoE-LoRA adapter](https://github.com/sogliuzzol/chessbehaviors/blob/main/models/adapters/moe_lora.py): `models/adapters/moe_lora.py`
- [Training dataset](https://github.com/sogliuzzol/chessbehaviors/blob/main/models/dataset.py): `models/dataset.py`
- [Player embeddings](https://github.com/sogliuzzol/chessbehaviors/blob/main/models/embeddings.py): `models/embeddings.py`
- [Policy pruning](https://github.com/sogliuzzol/chessbehaviors/blob/main/utils/pruning.py): `utils/pruning.py`
- [Descent search](https://github.com/sogliuzzol/chessbehaviors/blob/main/search/descent.py): `search/descent.py`
- [MCTS search](https://github.com/sogliuzzol/chessbehaviors/blob/main/search/mcts.py): `search/mcts.py`
- [Board transitions](https://github.com/sogliuzzol/chessbehaviors/blob/main/utils/transitions.py): `utils/transitions.py`
- [Style manifold](https://github.com/sogliuzzol/chessbehaviors/blob/main/models/style.py): `models/style.py`

### Other components

- **Researcher**
- **Raw PGN files**

## Connections

- Researcher → Dataset builder: builds data (evidence: `README.md`)
- Raw PGN files → Dataset builder: provides games (evidence: `README.md`)
- Dataset builder → Data utilities: uses utilities (evidence: `build_dataset.py`)
- Dataset builder → Position datasets: writes datasets (evidence: `README.md`)
- Position datasets → Ground truth: inputs positions (evidence: `README.md`)
- Position datasets → Maia baseline: inputs positions (evidence: `README.md`)
- Position datasets → Fine-tuned Maia: inputs positions (evidence: `README.md`)
- Position datasets → Nucleus variants: inputs positions (evidence: `README.md`)
- Position datasets → Search variants: inputs positions (evidence: `README.md`)
- Position datasets → MCTS variants: inputs positions (evidence: `README.md`)
- Position datasets → MoE-LoRA variants: inputs positions (evidence: `README.md`)
- Ground truth → Prediction files: writes predictions (evidence: `README.md`)
- Maia baseline → Prediction files: writes predictions (evidence: `README.md`)
- Fine-tuned Maia → Prediction files: writes predictions (evidence: `README.md`)
- Nucleus variants → Prediction files: writes predictions (evidence: `README.md`)
- Search variants → Prediction files: writes predictions (evidence: `README.md`)
- MCTS variants → Prediction files: writes predictions (evidence: `README.md`)
- MoE-LoRA variants → Prediction files: writes predictions (evidence: `README.md`)
- Prediction files → Move accuracy: evaluates moves (evidence: `README.md`)
- Prediction files → CP error: evaluates error (evidence: `README.md`)
- Prediction files → JSD evaluation: evaluates distributions (evidence: `README.md`)
- Prediction files → Common-FEN JSD: compares common FENs (evidence: `README.md`)
- Prediction files → Style evaluation: evaluates style (evidence: `README.md`)
- Prediction files → Common-FEN style: compares common FENs (evidence: `README.md`)
- JSD evaluation → JSD heatmaps: visualizes metrics (evidence: `README.md`)
- Style evaluation → Style heatmaps: visualizes metrics (evidence: `README.md`)
- Common-FEN style → Common-FEN heatmaps: visualizes metrics (evidence: `README.md`)
- Move accuracy → LaTeX tables: tabulates results (evidence: `README.md`)
- CP error → LaTeX tables: tabulates results (evidence: `README.md`)
- JSD evaluation → LaTeX tables: tabulates results (evidence: `README.md`)
- Style evaluation → LaTeX tables: tabulates results (evidence: `README.md`)
- Fine-tuned Maia → Player fine-tuning: uses model API (evidence: `maia2_ft.py`)
- Search variants → Policy wrappers: uses wrappers (evidence: `maia2_descent.py`)
- MCTS variants → Policy wrappers: uses wrappers (evidence: `maia2_mcts.py`)
- Search variants → Policy pruning: uses pruning
- MoE-LoRA variants → MoE-LoRA adapter: uses adapter
- Player fine-tuning → Training dataset: trains on (evidence: `models/maia_ft.py`)
- Player fine-tuning → Player embeddings: uses embeddings (evidence: `models/maia_ft.py`)
- MoE-LoRA adapter → Policy wrappers: wraps backbone (evidence: `models/adapters/moe_lora.py`)
- Policy wrappers → Descent search: delegates search (evidence: `models/base.py`)
- Policy wrappers → MCTS search: delegates search (evidence: `models/base.py`)
- Style evaluation → Board transitions: extracts transitions (evidence: `evaluate_style.py`)
- Style evaluation → Style manifold: uses style analysis (evidence: `evaluate_style.py`)
- Common-FEN style → Board transitions: extracts transitions (evidence: `evaluate_style_common_fens.py`)
- Common-FEN style → Style manifold: uses style analysis (evidence: `evaluate_style_common_fens.py`)
- Style heatmaps → Style manifold: uses style analysis (evidence: `generate_style_heatmaps.py`)
- Common-FEN heatmaps → Style manifold: uses style analysis (evidence: `generate_style_heatmaps_common_fens.py`)
