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