# argo-navis-lab/scalelab architecture

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

- Interactive diagram: https://gitdiagram.com/argo-navis-lab/scalelab
- Repository: https://github.com/argo-navis-lab/scalelab

## Overview

ScaleLab is a measurement lab for small-model reinforcement learning. The principal workflow configures and prices an experiment, constructs a transformer and arithmetic task, runs warm-start or budget-limited RL training, records checkpoints and telemetry, grades runs, then analyzes and exports results. The graph preserves the documented sweep/worker, cost-model, and analysis capabilities. Edges reflect README statements or shown source/index references; several subsystem internals were not sampled, so their links are documented rather than inferred from names.

Main entry points: [`src/scalelab/rl/experiment.py`](https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/rl/experiment.py) (Run orchestration), [`src/scalelab/cli.py`](https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/cli.py) (Command interface), [`src/scalelab/rl/loop.py`](https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/rl/loop.py) (RL training loop), [`src/scalelab/rl/costing.py`](https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/rl/costing.py) (Run cost estimate)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_run["Experiment runs"]
  node_config["Experiment config<br/>[config.py]"]
  node_experiment["Run orchestration<br/>[experiment.py]"]
  node_rl["RL training loop<br/>[loop.py]"]
  node_warm["Warm-start loop<br/>[warmstart_loop.py]"]
  node_rollout["Answer rollouts<br/>[rollout.py]"]
  node_trainer["Policy optimization<br/>[trainer.py]"]
end

subgraph group_domain["Model and tasks"]
  node_model["Transformer model<br/>[transformer.py]"]
  node_task["Arithmetic tasks<br/>[arithmetic.py]"]
  node_tokenizer["Digit tokenizer<br/>[tokenizer.py]"]
  node_eval["Evaluation sets<br/>[evalsets.py]"]
end

subgraph group_observe["Run records"]
  node_registry[("Run registry<br/>[registry.py]")]
  node_checkpoint["Checkpoint state<br/>[checkpoint.py]"]
  node_storage["Run storage<br/>[storage.py]"]
  node_telemetry["Metric sink<br/>[sink.py]"]
  node_detectors["Anomaly detection<br/>[detectors.py]"]
end

subgraph group_cost["Cost modeling"]
  node_costing["Run cost estimate<br/>[costing.py]"]
  node_stepmodel["RL step model<br/>[rlstep.py]"]
  node_opmodel["Operation model<br/>[ops.py]"]
  node_hardware["Hardware specs<br/>[specs.py]"]
end

subgraph group_insight["Analysis and planning"]
  node_costreport["Cost reports<br/>[costreport.py]"]
  node_scaling["Scaling analysis<br/>[scaling.py]"]
  node_stats["Statistical analysis<br/>[stats.py]"]
  node_export["Dataset export<br/>[export.py]"]
  node_sweep["Sweep planning<br/>[sweep.py]"]
end

node_user(("Researcher"))
node_cli["Command interface<br/>[cli.py]"]

node_user -->|"invokes"| node_cli
node_cli -->|"loads config"| node_config
node_cli -->|"starts run"| node_experiment
node_experiment -->|"constructs"| node_model
node_experiment -->|"constructs"| node_task
node_experiment -->|"loads sets"| node_eval
node_task -->|"encodes prompts"| node_tokenizer
node_experiment -->|"dispatches RL"| node_rl
node_experiment -->|"dispatches warm start"| node_warm
node_rl -->|"samples answers"| node_rollout
node_rl -->|"optimizes policy"| node_trainer
node_rl -->|"saves state"| node_checkpoint
node_checkpoint -->|"writes artifacts"| node_storage
node_experiment -->|"records run"| node_registry
node_experiment -->|"records metrics"| node_telemetry
node_telemetry -->|"writes metrics"| node_storage
node_experiment -->|"monitors anomalies"| node_detectors
node_cli -->|"prices run"| node_costing
node_costing -->|"predicts step"| node_stepmodel
node_stepmodel -->|"uses op timings"| node_opmodel
node_costing -->|"uses device spec"| node_hardware
node_cli -->|"reports costs"| node_costreport
node_costreport -->|"reads predictions"| node_stepmodel
node_cli -->|"fits scaling"| node_scaling
node_scaling -->|"uses statistics"| node_stats
node_cli -->|"exports runs"| node_export
node_cli -.->|"plans sweeps"| node_sweep

click node_cli "https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/cli.py"
click node_config "https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/core/config.py"
click node_experiment "https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/rl/experiment.py"
click node_rl "https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/rl/loop.py"
click node_warm "https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/rl/warmstart_loop.py"
click node_rollout "https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/rl/rollout.py"
click node_trainer "https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/rl/trainer.py"
click node_model "https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/models/transformer.py"
click node_task "https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/tasks/arithmetic.py"
click node_tokenizer "https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/tasks/tokenizer.py"
click node_eval "https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/tasks/evalsets.py"
click node_registry "https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/core/registry.py"
click node_checkpoint "https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/core/checkpoint.py"
click node_storage "https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/core/storage.py"
click node_telemetry "https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/telemetry/sink.py"
click node_detectors "https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/telemetry/detectors.py"
click node_costing "https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/rl/costing.py"
click node_stepmodel "https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/costmodel/rlstep.py"
click node_opmodel "https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/costmodel/ops.py"
click node_hardware "https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/costmodel/specs.py"
click node_costreport "https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/analysis/costreport.py"
click node_scaling "https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/analysis/scaling.py"
click node_stats "https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/analysis/stats.py"
click node_export "https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/analysis/export.py"
click node_sweep "https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/core/sweep.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_config,node_experiment,node_rl,node_warm,node_rollout,node_trainer toneBlue
class node_model,node_task,node_tokenizer,node_eval toneAmber
class node_registry,node_checkpoint,node_storage,node_telemetry,node_detectors toneMint
class node_costing,node_stepmodel,node_opmodel,node_hardware toneRose
class node_costreport,node_scaling,node_stats,node_export,node_sweep,node_user toneIndigo
class node_cli toneTeal
```

## Components

### Experiment runs

- [Experiment config](https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/core/config.py): `src/scalelab/core/config.py`
- [Run orchestration](https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/rl/experiment.py): `src/scalelab/rl/experiment.py`
- [RL training loop](https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/rl/loop.py): `src/scalelab/rl/loop.py`
- [Warm-start loop](https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/rl/warmstart_loop.py): `src/scalelab/rl/warmstart_loop.py`
- [Answer rollouts](https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/rl/rollout.py): `src/scalelab/rl/rollout.py`
- [Policy optimization](https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/rl/trainer.py): `src/scalelab/rl/trainer.py`

### Model and tasks

- [Transformer model](https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/models/transformer.py): `src/scalelab/models/transformer.py`
- [Arithmetic tasks](https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/tasks/arithmetic.py): `src/scalelab/tasks/arithmetic.py`
- [Digit tokenizer](https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/tasks/tokenizer.py): `src/scalelab/tasks/tokenizer.py`
- [Evaluation sets](https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/tasks/evalsets.py): `src/scalelab/tasks/evalsets.py`

### Run records

- [Run registry](https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/core/registry.py): `src/scalelab/core/registry.py`
- [Checkpoint state](https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/core/checkpoint.py): `src/scalelab/core/checkpoint.py`
- [Run storage](https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/core/storage.py): `src/scalelab/core/storage.py`
- [Metric sink](https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/telemetry/sink.py): `src/scalelab/telemetry/sink.py`
- [Anomaly detection](https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/telemetry/detectors.py): `src/scalelab/telemetry/detectors.py`

### Cost modeling

- [Run cost estimate](https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/rl/costing.py): `src/scalelab/rl/costing.py`
- [RL step model](https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/costmodel/rlstep.py): `src/scalelab/costmodel/rlstep.py`
- [Operation model](https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/costmodel/ops.py): `src/scalelab/costmodel/ops.py`
- [Hardware specs](https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/costmodel/specs.py): `src/scalelab/costmodel/specs.py`

### Analysis and planning

- [Cost reports](https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/analysis/costreport.py): `src/scalelab/analysis/costreport.py`
- [Scaling analysis](https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/analysis/scaling.py): `src/scalelab/analysis/scaling.py`
- [Statistical analysis](https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/analysis/stats.py): `src/scalelab/analysis/stats.py`
- [Dataset export](https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/analysis/export.py): `src/scalelab/analysis/export.py`
- [Sweep planning](https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/core/sweep.py): `src/scalelab/core/sweep.py`

### Other components

- **Researcher**
- [Command interface](https://github.com/argo-navis-lab/scalelab/blob/main/src/scalelab/cli.py): `src/scalelab/cli.py`

## Connections

- Researcher → Command interface: invokes (evidence: `README.md`)
- Command interface → Experiment config: loads config (evidence: `src/scalelab/cli.py`)
- Command interface → Run orchestration: starts run (evidence: `src/scalelab/cli.py`)
- Run orchestration → Transformer model: constructs (evidence: `src/scalelab/rl/experiment.py`)
- Run orchestration → Arithmetic tasks: constructs (evidence: `src/scalelab/rl/experiment.py`)
- Run orchestration → Evaluation sets: loads sets (evidence: `src/scalelab/rl/experiment.py`)
- Arithmetic tasks → Digit tokenizer: encodes prompts (evidence: `src/scalelab/tasks/arithmetic.py`)
- Run orchestration → RL training loop: dispatches RL (evidence: `src/scalelab/rl/experiment.py`)
- Run orchestration → Warm-start loop: dispatches warm start (evidence: `src/scalelab/rl/experiment.py`)
- RL training loop → Answer rollouts: samples answers (evidence: `src/scalelab/rl/loop.py`)
- RL training loop → Policy optimization: optimizes policy (evidence: `src/scalelab/rl/loop.py`)
- RL training loop → Checkpoint state: saves state (evidence: `src/scalelab/rl/loop.py`)
- Checkpoint state → Run storage: writes artifacts (evidence: `src/scalelab/core/checkpoint.py`)
- Run orchestration → Run registry: records run (evidence: `README.md`)
- Run orchestration → Metric sink: records metrics (evidence: `src/scalelab/rl/experiment.py`)
- Metric sink → Run storage: writes metrics (evidence: `src/scalelab/telemetry/sink.py`)
- Run orchestration → Anomaly detection: monitors anomalies (evidence: `src/scalelab/rl/experiment.py`)
- Command interface → Run cost estimate: prices run (evidence: `README.md`)
- Run cost estimate → RL step model: predicts step (evidence: `src/scalelab/rl/costing.py`)
- RL step model → Operation model: uses op timings (evidence: `src/scalelab/costmodel/rlstep.py`)
- Run cost estimate → Hardware specs: uses device spec (evidence: `src/scalelab/rl/costing.py`)
- Command interface → Cost reports: reports costs (evidence: `src/scalelab/cli.py`)
- Cost reports → RL step model: reads predictions (evidence: `src/scalelab/analysis/costreport.py`)
- Command interface → Scaling analysis: fits scaling (evidence: `src/scalelab/cli.py`)
- Scaling analysis → Statistical analysis: uses statistics (evidence: `src/scalelab/analysis/scaling.py`)
- Command interface → Dataset export: exports runs (evidence: `src/scalelab/cli.py`)
- Command interface → Sweep planning: plans sweeps (evidence: `README.md`)
