Contributing

Guide for developing and contributing to tinker-cookbook.

Reference

Read CONTRIBUTING.md for the full guide.

Development setup

git clone https://github.com/thinking-machines-lab/tinker-cookbook.git
cd tinker-cookbook
uv sync --extra dev
pre-commit install

This installs dev dependencies and registers pre-commit hooks (ruff formatting/linting).

Code style

• Formatter/Linter: ruff (line length: 100)
• Type checker: pyright
• Pre-commit hooks run automatically on every commit

uv run ruff check tinker_cookbook/
uv run ruff format tinker_cookbook/
uv run pyright tinker_cookbook/

Typing rules

• Use explicit types everywhere
• Avoid Any and type: ignore — prefer casting
• Prefer single types over union types
• Don't add convoluted generics just to satisfy the type checker

Design conventions

Builder pattern

Config objects build runtime objects:

• SupervisedDatasetBuilder → SupervisedDataset
• RLDatasetBuilder → RLDataset
• EnvGroupBuilder → group of Env objects

Config objects use @chz.chz decorator. They have a __call__ method that builds the runtime object.

Config/runtime separation

• Config: @chz.chz dataclasses, serializable, lightweight
• Runtime: Regular classes or dataclasses, heavyweight (datasets, clients)

Training script organization

• tinker_cookbook/<module>/train.py — Main training loop with detailed Config (not CLI-constructable)
• tinker_cookbook/recipes/<name>/train.py — Launch script with CLIConfig from command line

Async

• All methods that take nontrivial time should be async (especially in RL)
• Some beginner-oriented code (e.g., sl_loop.py) uses sync for simplicity

Env lifecycle

• Env objects are single-use (no reset)
• Shared resources managed by EnvGroupBuilder, not individual Envs

Dimension notation

Subscript suffixes on variable names:

• _P = problems, _G = groups, _T = tokens, _D = datums
• Example: tokens_P_G_T[p][g][t] = token t of group g of problem p
• Flattened: tokens_PG_T = problems and groups merged into one dimension

PR process

1. Create a feature branch from main
2. Make changes with tests
3. Run pre-commit run --all-files
4. Open PR with clear description

CI runs pre-commit, pyright, and pytest on every PR.

Testing

See the /ci skill for full testing details.

# Unit tests (no API key needed)
uv run pytest tinker_cookbook/

# Integration tests (requires TINKER_API_KEY)
uv run pytest tests/