Tutorials

A progressive learning path from first API call to advanced training techniques. All tutorials are marimo notebooks — reactive Python notebooks stored as .py files. Read them here or run them interactively.

Prerequisites

• Python 3.11+
• tinker >= 0.22.3 — the tutorials use the 0.22.3 API surface (TensorData wrappers, awaited save/REST calls, Config.recipe_name), and checkpoint download in Weights Management was broken on earlier versions.
• A Tinker API key — get one from the Tinker Console.

Setup

Install the SDK together with the cookbook's [tutorials] extra, then set your API key:

uv pip install tinker "tinker-cookbook[tutorials]"
export TINKER_API_KEY="your-api-key-here"

The [tutorials] extra pulls in marimo (to open the notebooks), matplotlib (for the loss-curve plots in a few tutorials), and the [math-rl] dependencies (sympy, pylatexenc, math-verify) that some RL tutorials import.

Run tutorials interactively

Clone the cookbook and open any notebook in marimo's interactive editor:

git clone https://github.com/thinking-machines-lab/tinker-cookbook.git
cd tinker-cookbook
marimo edit tutorials/101_hello_tinker.py

You can also try the notebooks online in molab without installing anything — the cookbook tutorials README links each notebook to its molab launcher.

Running from a cloned cookbook as a uv project

If you use uv run inside the cloned repo instead of a global install, pass --extra tutorials on every invocation:

uv run --extra tutorials marimo edit tutorials/101_hello_tinker.py

A bare uv run re-syncs the project environment and uninstalls marimo, so the editor won't launch.

Pair tutorials with a matching cookbook

Run the tutorials against a recent cookbook that matches them — an editable clone of main or a nightly build. Stable PyPI tinker-cookbook paired with newer tutorial files can drift.

100: Basics

Start here. Learn the core Tinker SDK operations.

Beginner\
101: Hello Tinker\
\
ServiceClient, SamplingClient, and basic text generation
Beginner\
102: Your First SFT\
\
Renderers, Datum construction, forward-backward, optimizer step
Beginner\
103: Async Patterns\
\
Futures, concurrent requests, throughput optimization
Beginner\
104: First RL\
\
GRPO algorithm, reward functions, GSM8K math training

200: Core Concepts

Deep dives into specific SDK features. Each tutorial is standalone.

Intermediate\
201: Rendering\
\
How tokenization and chat templates work across model families
Intermediate\
202: Loss Functions\
\
Cross-entropy, importance sampling, PPO, custom losses
Intermediate\
203: Completers\
\
TokenCompleter vs MessageCompleter for RL environments
Intermediate\
204: Weights Management\
\
Save, load, download, and publish model weights
Intermediate\
205: Evaluations\
\
Evaluate your fine-tuned models during and after training

300: Cookbook Abstractions

Learn the higher-level training patterns from tinker-cookbook.

Intermediate\
301: Env & EnvGroupBuilder\
\
Core RL types: Env, EnvGroupBuilder, RLDataset, ProblemEnv
Intermediate\
302: Custom Environment\
\
Implementing a custom ProblemEnv subclass with format compliance
Intermediate\
303: SFT with Config\
\
Using train.Config and dataset builders for supervised learning
Intermediate\
304: RL with Config\
\
Full GRPO implementation using cookbook abstractions

400: Advanced

Advanced techniques for experienced users.

Advanced\
401: SL Hyperparameters\
\
Sweep learning rate and LoRA rank with the cookbook's sweep module
Advanced\
402: RL Hyperparameters\
\
KL penalty, advantage estimation, reward shaping
Advanced\
403: DPO & Preferences\
\
Direct preference optimization, RLHF pipeline
Advanced\
404: Sequence Extension\
\
Multi-turn RL with conversation history
Advanced\
405: Multi-Agent RL\
\
Self-play, competitive environments
Advanced\
406: Prompt Distillation\
\
Distilling long system prompts into model weights
Advanced\
407: RLHF Pipeline\
\
Full 3-stage RLHF: SFT → preference model → RL training

500: Deployment

Getting trained models into production.

Deployment\
501: Export to HuggingFace\
\
Merge LoRA adapter into a full HuggingFace model
Deployment\
502: Build LoRA Adapter\
\
Convert to PEFT format for efficient serving
Deployment\
503: Publish to Hub\
\
Upload trained models to HuggingFace Hub
Deployment\
504: OpenCode\
\
Chat with a fine-tuned checkpoint in OpenCode