Neuralese / hackable GRPO baseline

Repository layout

Storage conventions

• storage.cache_dir is the canonical runtime root. Relative runtime paths like artifacts/runs/grpo-llama32-3b resolve under that directory.
• Use cache/datasets for dataset cache, cache/models for model/tokenizer cache, and cache/logs/wandb for W&B logs.
• Training runs live in cache/artifacts/runs, sweep outputs in cache/artifacts/sweeps, eval outputs in cache/artifacts/eval.
• Permanent checkpoints now live under each run at checkpoints/permanent/.

src/hackable/ modules

• config.py — Loads YAML into typed dataclasses (ExperimentConfig, ModelConfig, TrainerConfig, GenerationConfig, ObjectiveConfig, RewardsConfig, …). Normalizes optimizer/scheduler aliases and numeric fields.
• registry.py — @register_data_provider, @register_reward, @register_objective plus build_* factories. Reward kwargs from YAML are partially applied via build_reward so each reward can receive static options (e.g. tokenizer name for length penalty).
• interfaces.py — TrainingSample and protocol shapes for providers/rewards/objectives.
• objectives.py — TokenGRPOObjective (main token-level GRPO recipe) and LatentNeuraleseObjective (stub: format reward only, extra_reward no-op for future latent scoring).
• reward_plugins.py — Registered rewards: strict format, GSM8K/MATH-style correctness, length penalty, optional token-utilisation shaping. See Length penalty rewards below.
• data_plugins.py — GSM8K, Hendrycks MATH by level, interleaved curricula (gsm8k_math_curriculum, etc.). Shared prompt prefix matches the strict completion format expected by rewards.
• backends.py — Loads causal LMs with Liger Llama patches when applicable, FlashAttention2 when importable, else SDPA. Exposes generation_kwargs from config.
• utils.py — import_from_path for objective.class_path style "module:Class" loading.

src/ evaluation utilities

• eval_sweep_models.py — Distributed evaluation of every run_* directory under a sweep root: loads checkpoints, runs GSM8K test generations, scores correctness, records CoT word length stats, writes CSV/JSON summaries (used after lambda or reward-variant sweeps).
• eval_permanent_checkpoints.py — Walks checkpoints/permanent folders, evaluates each checkpoint, can emit simple SVG learning curves.
• eval_math_level1_thinking_zeroshot.py — Zero-shot / thinking-format eval on MATH-style data with JSONL output (for downstream rewards or analysis).

scripts/ (high level)

Length penalty rewards

What gets measured

1. Strict format only — _think_length_tokens in reward_plugins.py parses the completion with the same regex as format_tag_reward: a single block <redacted_thinking>...</redacted_thinking> followed by \boxed{...}. If the completion does not match, thinking length is treated as 0 (so length reward does not reward malformed outputs on length grounds).
2. Token count — If tokenizer_name is passed (via rewards.kwargs.length_penalty_reward in YAML and build_reward), the thinking substring is encoded with that tokenizer (add_special_tokens=False) and the length is the number of token IDs. If no tokenizer is configured, length falls back to whitespace-split words inside the thinking block.
3. Per-group normalization — For each group (G) of completions (see grouping below), let (L_i) be the thinking length of completion (i), and (\bar{L} = \frac{1}{|G|}\sum_j L_j). If (\bar{L} \le 0), every score in the group is 0. Otherwise:

How groups are formed

• If group_size is set (again, typically under rewards.kwargs.length_penalty_reward), the flat batch is chunked in order: [0:group_size), [group_size:2*group_size), …
• Else groups are inferred by contiguous runs of identical prompt text in the parallel lists passed to the reward.

How TokenGRPOObjective combines length with other rewards

• format_tag_reward — 1.0 if strict thinking + non-empty boxed answer, else 0.0.
• gsm8k_correctness_reward — Parses \boxed{...} vs reference (GSM8K #### answers or MATH boxed solutions), numeric normalization and tolerant float compare.
• length_penalty_reward — if enable_length_penalty: true.
• token_utilisation_reward — optional; shapes training vs a frozen zero-shot correctness JSONL (see docstring in reward_plugins.py).

1. additive — Total score is the sum of all enabled reward outputs for that sample. If strict_format_gate: true, any sample with format_tag_reward ≤ 0.5 is replaced by non_strict_penalty (default -1.0) instead of the sum.
2. weighted_length_penalty — Correctness and length interact multiplicatively; format is added (and optionally multiplied into the interaction):
   • Let (r_c, r_f, r_\ell) be correctness, format, and length scores in ([0,1]) (length may be 0 if disabled or malformed).
   • Base interaction: (r_c \times r_\ell).
   • If length_penalty_interaction is correctness_length_format, the interaction is (r_c \times r_\ell \times r_f).
   • Total (before optional token-util term):
   [ \texttt{correctness_weight} \cdot r_c + \texttt{length_penalty_lambda} \cdot \text{interaction} + r_f + r_{\mathrm{util}}. ]
   If strict_format_gate is true and (r_f \le 0.5), the total is non_strict_penalty and the formula above is skipped.

Hackable extension path

• Implement a new objective class with reward_names() and combine_rewards-equivalent behavior (your trainer must call into it the same way as the baseline), or add new @register_reward functions.
• Point config at a custom class: objective.class_path: "my_package.my_module:MyObjective".
• LatentNeuraleseObjective is a stub: keep token rewards while you add latent signals via extra_reward or a future trainer hook.

Quickstart

1. pip install -r requirements.txt (you may need a CUDA-matched Torch and optional FlashAttention build).
2. Set HF_TOKEN / WANDB_API_KEY if needed (names configurable under auth in YAML).
3. Single GPU: bash scripts/run_grpo.sh (requires src/train_grpo.py and configs/grpo_llama32_3b_bf16.yaml present).
4. Many scripts default to offline Hub/datasets/W&B; override WANDB_MODE, HF_HUB_OFFLINE, etc. if you need network access.
5. Runtime outputs default to cache/artifacts/... through storage.cache_dir; agent docs live in AGENTS.md and docs/repository-map.md.

Attention backend