# krafton-ai/whale architecture

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

- Interactive diagram: https://gitdiagram.com/krafton-ai/whale
- Repository: https://github.com/krafton-ai/whale

## Overview

WHALE reproduces alternating model-weight and harness optimization experiments across three domains, including Lichess chess puzzles. In each cycle, online rejection-sampling fine-tuning updates the model under the current harness, then Meta-Harness searches for a better harness under the updated model. The chess tree separates puzzle data, environment and reward code, domain harness/runner code, and benchmark/search code. The README documents the optimization loop, but the sampled excerpts do not show the chess modules’ internal calls or their full runtime wiring; those relationships are therefore not inferred.

Main entry points: [`domains/chess_puzzles/run`](https://github.com/krafton-ai/whale/tree/main/domains/chess_puzzles/run) (WHALE Alternation), [`domains/chess_puzzles/meta_harness/meta_harness_chess_puzzle.py`](https://github.com/krafton-ai/whale/blob/main/domains/chess_puzzles/meta_harness/meta_harness_chess_puzzle.py) (Meta-Harness), [`domains/chess_puzzles/verl/trainer/ppo/ray_trainer.py`](https://github.com/krafton-ai/whale/blob/main/domains/chess_puzzles/verl/trainer/ppo/ray_trainer.py) (RSFT Training Framework), [`domains/chess_puzzles/meta_harness/chess_puzzle_benchmark.py`](https://github.com/krafton-ai/whale/blob/main/domains/chess_puzzles/meta_harness/chess_puzzle_benchmark.py) (Puzzle Benchmark)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experiment["WHALE Cycle"]
  node_whale["WHALE Alternation"]
  node_model_weights["Model Weights"]
  node_harness_candidate["Updated Harness"]
end

subgraph group_chess_runtime["Chess Runtime"]
  node_puzzle_data["Puzzle Data<br/>[grpo_dataset.py]"]
  node_puzzle_env["Puzzle Environment<br/>[env.py]"]
  node_base_harness["Base Harness<br/>[base_harness.py]"]
  node_chess_reward["Puzzle Reward<br/>[grpo_reward.py]"]
  node_domain_harness["Chess Harness<br/>[harness.py]"]
  node_chess_runner["Chess Runner<br/>[runner.py]"]
end

subgraph group_harness_search["Harness Search"]
  node_benchmark["Puzzle Benchmark"]
  node_meta_harness["Meta-Harness"]
  node_claude_wrapper["Claude Wrapper<br/>[claude_wrapper.py]"]
end

subgraph group_training["Weight Training"]
  node_grpo_dataset["GRPO Dataset<br/>[grpo_dataset.py]"]
  node_ppo_training["RSFT Training Framework<br/>[ray_trainer.py]"]
end

node_researcher(("Experiment Runner"))

node_researcher -->|"runs condition"| node_whale
node_whale -->|"trains weights"| node_ppo_training
node_ppo_training -->|"updates weights"| node_model_weights
node_whale -->|"searches harness"| node_meta_harness
node_meta_harness -->|"improves harness"| node_harness_candidate
node_whale -->|"alternates updates"| node_model_weights
node_whale -->|"alternates searches"| node_harness_candidate
node_benchmark -.->|"evaluates candidates"| node_harness_candidate

click node_whale "https://github.com/krafton-ai/whale/tree/main/domains/chess_puzzles/run"
click node_puzzle_data "https://github.com/krafton-ai/whale/blob/main/domains/chess_puzzles/autoharness_chess_puzzle/grpo_dataset.py"
click node_puzzle_env "https://github.com/krafton-ai/whale/blob/main/domains/chess_puzzles/environments/chess_puzzle/env.py"
click node_base_harness "https://github.com/krafton-ai/whale/blob/main/domains/chess_puzzles/environments/chess_puzzle/base_harness.py"
click node_chess_reward "https://github.com/krafton-ai/whale/blob/main/domains/chess_puzzles/environments/chess_puzzle/grpo_reward.py"
click node_domain_harness "https://github.com/krafton-ai/whale/blob/main/domains/chess_puzzles/autoharness_chess_puzzle/harness.py"
click node_chess_runner "https://github.com/krafton-ai/whale/blob/main/domains/chess_puzzles/autoharness_chess_puzzle/runner.py"
click node_benchmark "https://github.com/krafton-ai/whale/blob/main/domains/chess_puzzles/meta_harness/chess_puzzle_benchmark.py"
click node_meta_harness "https://github.com/krafton-ai/whale/blob/main/domains/chess_puzzles/meta_harness/meta_harness_chess_puzzle.py"
click node_claude_wrapper "https://github.com/krafton-ai/whale/blob/main/domains/chess_puzzles/meta_harness/claude_wrapper.py"
click node_grpo_dataset "https://github.com/krafton-ai/whale/blob/main/domains/chess_puzzles/autoharness_chess_puzzle/grpo_dataset.py"
click node_ppo_training "https://github.com/krafton-ai/whale/blob/main/domains/chess_puzzles/verl/trainer/ppo/ray_trainer.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_whale,node_model_weights,node_harness_candidate toneBlue
class node_puzzle_data,node_puzzle_env,node_base_harness,node_chess_reward,node_domain_harness,node_chess_runner toneAmber
class node_benchmark,node_meta_harness,node_claude_wrapper toneMint
class node_grpo_dataset,node_ppo_training toneRose
class node_researcher toneIndigo
```

## Components

### WHALE Cycle

- [WHALE Alternation](https://github.com/krafton-ai/whale/tree/main/domains/chess_puzzles/run): `domains/chess_puzzles/run`
- **Model Weights**
- **Updated Harness**

### Chess Runtime

- [Puzzle Data](https://github.com/krafton-ai/whale/blob/main/domains/chess_puzzles/autoharness_chess_puzzle/grpo_dataset.py): `domains/chess_puzzles/autoharness_chess_puzzle/grpo_dataset.py`
- [Puzzle Environment](https://github.com/krafton-ai/whale/blob/main/domains/chess_puzzles/environments/chess_puzzle/env.py): `domains/chess_puzzles/environments/chess_puzzle/env.py`
- [Base Harness](https://github.com/krafton-ai/whale/blob/main/domains/chess_puzzles/environments/chess_puzzle/base_harness.py): `domains/chess_puzzles/environments/chess_puzzle/base_harness.py`
- [Puzzle Reward](https://github.com/krafton-ai/whale/blob/main/domains/chess_puzzles/environments/chess_puzzle/grpo_reward.py): `domains/chess_puzzles/environments/chess_puzzle/grpo_reward.py`
- [Chess Harness](https://github.com/krafton-ai/whale/blob/main/domains/chess_puzzles/autoharness_chess_puzzle/harness.py): `domains/chess_puzzles/autoharness_chess_puzzle/harness.py`
- [Chess Runner](https://github.com/krafton-ai/whale/blob/main/domains/chess_puzzles/autoharness_chess_puzzle/runner.py): `domains/chess_puzzles/autoharness_chess_puzzle/runner.py`

### Harness Search

- [Puzzle Benchmark](https://github.com/krafton-ai/whale/blob/main/domains/chess_puzzles/meta_harness/chess_puzzle_benchmark.py): `domains/chess_puzzles/meta_harness/chess_puzzle_benchmark.py`
- [Meta-Harness](https://github.com/krafton-ai/whale/blob/main/domains/chess_puzzles/meta_harness/meta_harness_chess_puzzle.py): `domains/chess_puzzles/meta_harness/meta_harness_chess_puzzle.py`
- [Claude Wrapper](https://github.com/krafton-ai/whale/blob/main/domains/chess_puzzles/meta_harness/claude_wrapper.py): `domains/chess_puzzles/meta_harness/claude_wrapper.py`

### Weight Training

- [GRPO Dataset](https://github.com/krafton-ai/whale/blob/main/domains/chess_puzzles/autoharness_chess_puzzle/grpo_dataset.py): `domains/chess_puzzles/autoharness_chess_puzzle/grpo_dataset.py`
- [RSFT Training Framework](https://github.com/krafton-ai/whale/blob/main/domains/chess_puzzles/verl/trainer/ppo/ray_trainer.py): `domains/chess_puzzles/verl/trainer/ppo/ray_trainer.py`

### Other components

- **Experiment Runner**

## Connections

- Experiment Runner → WHALE Alternation: runs condition (evidence: `README.md`)
- WHALE Alternation → RSFT Training Framework: trains weights (evidence: `README.md`)
- RSFT Training Framework → Model Weights: updates weights (evidence: `README.md`)
- WHALE Alternation → Meta-Harness: searches harness (evidence: `README.md`)
- Meta-Harness → Updated Harness: improves harness (evidence: `README.md`)
- WHALE Alternation → Model Weights: alternates updates (evidence: `README.md`)
- WHALE Alternation → Updated Harness: alternates searches (evidence: `README.md`)
- Puzzle Benchmark → Updated Harness: evaluates candidates