# 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/index.md) was broken on earlier versions. - A Tinker API key — get one from the [Tinker Console](https://tinker.thinkingmachines.ai/keys). ## Setup Install the SDK together with the cookbook's `[tutorials]` extra, then set your API key: ```bash 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: ```bash 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: > > ```bash > 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)