# Tutorials A progressive learning path from first API call to advanced training techniques. All tutorials are [marimo](https://marimo.io/) 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](https://tinker-docs.thinkingmachines.ai/tutorials/core-concepts/weights/) was broken on earlier versions. - A Tinker API key — get one from the [Tinker Console](https://tinker-console.thinkingmachines.ai/). ## 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](https://molab.marimo.io/notebooks) without installing anything — the [cookbook tutorials README](https://github.com/thinking-machines-lab/tinker-cookbook/tree/main/tutorials) 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](https://tinker-docs.thinkingmachines.ai/tutorials/basics/hello-tinker) [Beginner\ 102: Your First SFT\ \ Renderers, Datum construction, forward-backward, optimizer step](https://tinker-docs.thinkingmachines.ai/tutorials/basics/first-sft) [Beginner\ 103: Async Patterns\ \ Futures, concurrent requests, throughput optimization](https://tinker-docs.thinkingmachines.ai/tutorials/basics/async-patterns) [Beginner\ 104: First RL\ \ GRPO algorithm, reward functions, GSM8K math training](https://tinker-docs.thinkingmachines.ai/tutorials/basics/first-rl) ## 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](https://tinker-docs.thinkingmachines.ai/tutorials/core-concepts/rendering) [Intermediate\ 202: Loss Functions\ \ Cross-entropy, importance sampling, PPO, custom losses](https://tinker-docs.thinkingmachines.ai/tutorials/core-concepts/loss-functions) [Intermediate\ 203: Completers\ \ TokenCompleter vs MessageCompleter for RL environments](https://tinker-docs.thinkingmachines.ai/tutorials/core-concepts/completers) [Intermediate\ 204: Weights Management\ \ Save, load, download, and publish model weights](https://tinker-docs.thinkingmachines.ai/tutorials/core-concepts/weights) [Intermediate\ 205: Evaluations\ \ Evaluate your fine-tuned models during and after training](https://tinker-docs.thinkingmachines.ai/tutorials/core-concepts/evaluations) ## 300: Cookbook Abstractions Learn the higher-level training patterns from `tinker-cookbook`. [Intermediate\ 301: Env & EnvGroupBuilder\ \ Core RL types: Env, EnvGroupBuilder, RLDataset, ProblemEnv](https://tinker-docs.thinkingmachines.ai/tutorials/cookbook-abstractions/env-and-envgroupbuilder) [Intermediate\ 302: Custom Environment\ \ Implementing a custom ProblemEnv subclass with format compliance](https://tinker-docs.thinkingmachines.ai/tutorials/cookbook-abstractions/custom-environment) [Intermediate\ 303: SFT with Config\ \ Using train.Config and dataset builders for supervised learning](https://tinker-docs.thinkingmachines.ai/tutorials/cookbook-abstractions/sft-with-config) [Intermediate\ 304: RL with Config\ \ Full GRPO implementation using cookbook abstractions](https://tinker-docs.thinkingmachines.ai/tutorials/cookbook-abstractions/rl-with-config) ## 400: Advanced Advanced techniques for experienced users. [Advanced\ 401: SL Hyperparameters\ \ Sweep learning rate and LoRA rank with the cookbook's sweep module](https://tinker-docs.thinkingmachines.ai/tutorials/advanced/sl-hyperparams) [Advanced\ 402: RL Hyperparameters\ \ KL penalty, advantage estimation, reward shaping](https://tinker-docs.thinkingmachines.ai/tutorials/advanced/rl-hyperparams) [Advanced\ 403: DPO & Preferences\ \ Direct preference optimization, RLHF pipeline](https://tinker-docs.thinkingmachines.ai/tutorials/advanced/dpo-preferences) [Advanced\ 404: Sequence Extension\ \ Multi-turn RL with conversation history](https://tinker-docs.thinkingmachines.ai/tutorials/advanced/sequence-extension) [Advanced\ 405: Multi-Agent RL\ \ Self-play, competitive environments](https://tinker-docs.thinkingmachines.ai/tutorials/advanced/multi-agent) [Advanced\ 406: Prompt Distillation\ \ Distilling long system prompts into model weights](https://tinker-docs.thinkingmachines.ai/tutorials/advanced/prompt-distillation) [Advanced\ 407: RLHF Pipeline\ \ Full 3-stage RLHF: SFT → preference model → RL training](https://tinker-docs.thinkingmachines.ai/tutorials/advanced/rlhf-pipeline) ## 500: Deployment Getting trained models into production. [Deployment\ 501: Export to HuggingFace\ \ Merge LoRA adapter into a full HuggingFace model](https://tinker-docs.thinkingmachines.ai/tutorials/deployment/export-hf) [Deployment\ 502: Build LoRA Adapter\ \ Convert to PEFT format for efficient serving](https://tinker-docs.thinkingmachines.ai/tutorials/deployment/lora-adapter) [Deployment\ 503: Publish to Hub\ \ Upload trained models to HuggingFace Hub](https://tinker-docs.thinkingmachines.ai/tutorials/deployment/publish-hub) [Deployment\ 504: OpenCode\ \ Chat with a fine-tuned checkpoint in OpenCode](https://tinker-docs.thinkingmachines.ai/tutorials/deployment/opencode)