Skip to main content

Tinker Cookbook

pytest pyright smoke-test-recipes PyPI

We provide two libraries for the broader community to customize their language models: tinker and tinker-cookbook.

  • tinker is a training SDK for researchers and developers to fine-tune language models. You send API requests to us and we handle the complexities of distributed training.
  • tinker-cookbook includes realistic examples of fine-tuning language models. It builds on the Tinker API and provides common abstractions to fine-tune language models.

Installation

  1. Sign up for Tinker here.
  2. Once you have access, create an API key from the console and export it as environment variable TINKER_API_KEY.
  3. Install tinker-cookbook (includes the tinker SDK as a dependency):
    # Latest stable release from PyPI
    uv pip install tinker-cookbook
    
    # Or install the nightly build
    uv pip install 'tinker-cookbook @ git+https://github.com/thinking-machines-lab/tinker-cookbook.git@nightly'
    

Using Inkling models

Inkling is Thinking Machines Lab's model family tailored for Tinker: general-purpose models that can code, reason, and call tools. Inkling is also natively multimodal. Every Inkling model shares the same rendering path and reasoning-effort interface. Tinker Cookbook supports sampling and post-training every Inkling model through the standalone tml-renderers library, included in the default installation together with the required torch>=2.10.

Pass model_name="thinkingmachines/Inkling-2-Small", model_name="thinkingmachines/Inkling", or model_name="thinkingmachines/Inkling-Small" anywhere the cookbook accepts a model name. The appropriate renderer and tokenizer are selected automatically for each of these models, including the :peft: long-context variants. The tokenizer depends on the model, so always get it from the model name.

All Inkling models support controllable reasoning effort and multimodal image inputs. Inkling and Inkling-Small also accept audio inputs. See the Inkling documentation for setup and usage details, and Models & Pricing for per-model context lengths and pricing.

Tinker

Here we introduce a few Tinker primitives — the basic components to fine-tune LLMs (see the quickstart guide for more details):

import tinker
service_client = tinker.ServiceClient()
training_client = service_client.create_lora_training_client(
  base_model="meta-llama/Llama-3.2-1B", rank=32,
).result()
training_client.forward_backward(...)
training_client.optim_step(...)
training_client.save_state(...)
resumed_client = service_client.create_training_client_from_state(...).result()

sampling_client = training_client.save_weights_and_get_sampling_client().result()
sampling_client.sample(...)

See tinker_cookbook/recipes/sl_loop.py and tinker_cookbook/recipes/rl_loop.py for minimal examples of using these primitives to fine-tune LLMs.

Tutorials

New to Tinker? The tutorials/ directory contains 20+ progressive marimo notebooks that walk through core concepts — rendering, loss functions, completers, weight management — and advanced topics such as custom RL environments, DPO, RLHF, and weight export. Run any tutorial with marimo edit tutorials/101_hello_tinker.py. See the tutorials README for the full list, or browse rendered versions on the Tinker docs site.

To export and download trained weights:

from tinker_cookbook import weights

export = training_client.save_weights_external(name="export").result()
weights.download(tinker_path=export.path, output_dir="model-checkpoint")

Tinker Cookbook

Besides these primitives, we also offer Tinker Cookbook (a.k.a. this repo), a library of a wide range of abstractions to help you customize training environments. tinker_cookbook/recipes/sl_basic.py and tinker_cookbook/recipes/rl_basic.py contain minimal examples to configure supervised learning and reinforcement learning.

We also include more complete examples in the tinker_cookbook/recipes/ folder:

  • Chat SFT: supervised fine-tuning on conversational datasets (e.g., Tulu3).
  • Math RL: reinforcement learning for mathematical reasoning with verifiable rewards.
  • Code RL: RL on competitive programming with sandboxed code execution (DeepCoder replication).
  • Preference learning: DPO and a three-stage RLHF pipeline (SFT, reward model, RL).
  • Distillation: on-policy and off-policy knowledge distillation with single- and multi-teacher configurations.
  • Tool use: RL for retrieval-augmented generation (Search-R1 replication).
  • Multi-agent: multi-agent RL with self-play and cross-play.
  • Audio: SFT and RL for Inkling audio inputs, including speech recognition and speaking-style classification.
  • VLM image classification: supervised training and evaluation for vision-language models.

The recipes README covers all available recipes, including Harbor RL, rubric-based grading, VLM classification, and SDFT. Each recipe includes a README.md with implementation details, launch commands, and expected results.

Evaluation (experimental)

Tinker Cookbook includes a benchmark framework for evaluating trained models:

from tinker_cookbook import cli_utils
from tinker_cookbook.eval.benchmarks import run_benchmarks, BenchmarkConfig

results = await run_benchmarks(
    ["gsm8k", "mmlu_pro", "ifeval"],
    sampling_client, renderer,
    BenchmarkConfig(save_dir=cli_utils.runs_path("evals", "step500")),
)

The framework currently supports 12 benchmarks (GSM8K, MATH-500, MMLU-Pro, MMLU-Redux, GPQA, IFEval, MBPP, C-Eval, SuperGPQA, IFBench, AIME 2025, AIME 2026) with verified scores against published results, plus experimental benchmarks such as LiveCodeBench, Terminal Bench, and SWE-bench. Benchmarks can also serve as inline training evaluators via BenchmarkEvaluator.

Note: Benchmark scores are sensitive to evaluation configuration — system prompts, max_tokens, temperature, and timeout settings can shift results significantly. We document our exact settings alongside all reported scores. This framework is under active development; feedback and contributions are welcome. See the eval README for verified scores, configuration details, and instructions for adding new benchmarks.

Documentation

For the full Tinker documentation, visit tinker-docs.thinkingmachines.ai.

Utilities

Tinker Cookbook also provides reusable building blocks:

  • renderers — bidirectional conversion between token sequences and structured chat messages
  • hyperparam_utils — learning rate and hyperparameter scaling for LoRA training
  • eval — benchmark framework and inline training evaluators (see Evaluation above)

Claude Code Skills

Tinker Cookbook ships with Claude Code skills that teach Claude how to use the Tinker API. Install them so Claude can help you write training code in any project:

/plugin marketplace add thinking-machines-lab/tinker-cookbook

Then install the tinker plugin from the Discover tab (/plugin → Discover). Once installed, four skills are available:

Command What it does
/tinker:research Plan and run post-training experiments — SFT, RL, DPO, distillation, evaluation, hyperparameters, model selection, and more
/tinker:debug Diagnose slow training, hangs, output mismatches, renderer issues, and errors
/tinker:rollout-ui Build rollout viewers with messages, tool calls, provenance, aligned comparisons, and accessible diffs; link to W&B for metrics
/tinker:inkling Work with Inkling models, including Inkling 2 Small — thinking effort, rendering, post-training, evaluation, and multimodal input

Skills also trigger automatically based on context — ask Claude to "set up SFT training" and it will load the right skill without a slash command. Skills update automatically when the repo is updated.

Development Setup

uv sync --extra dev
pre-commit install

This installs dev dependencies and registers pre-commit hooks that run ruff formatting and linting on every commit. CI enforces these checks on all pull requests.

Contributing

This project is built in the spirit of open science and collaborative development. We believe that the best tools emerge through community involvement and shared learning.

We welcome PR contributions after our private beta is over. If you have any feedback, please email us at tinker@thinkingmachines.ai.

Citation

If you use Tinker for your research, please cite it as:

Thinking Machines Lab, 2026. Tinker. https://thinkingmachines.ai/tinker/.

Or use this BibTeX citation:

@misc{tml2026tinker,
  author = {Thinking Machines Lab},
  title = {Tinker},
  year = {2026},
  url = {https://thinkingmachines.ai/tinker/},
}

Metadata

Release files for tinker-cookbook 0.6.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tinker-cookbook 0.6.1
File Size Uploaded Provenance Actions
tinker_cookbook-0.6.1.tar.gz 5.1 MB With provenance Details for tinker_cookbook-0.6.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tinker-cookbook 0.6.1
File Interpreter ABI Platform Actions
tinker_cookbook-0.6.1-py3-none-any.whl Python 3 none any Details for tinker_cookbook-0.6.1-py3-none-any.whl

Total release size: 6.4 MB

Release files / tinker_cookbook-0.6.1.tar.gz

Download URL tinker_cookbook-0.6.1.tar.gz
Size 5.1 MB
Tags Source
SHA-256 checksum
How to use checksums
edf66f0a4b2c3b375b9328a4d748a3dae104170bb2bcde0d156f0b22de7a1aa3
BLAKE2b-256 checksum
How to use checksums
6b804c9207338b06f59540deaa84f854508b9bdaa40dc54bcac192161173b339
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

Release files / tinker_cookbook-0.6.1-py3-none-any.whl

Download URL tinker_cookbook-0.6.1-py3-none-any.whl
Size 1.3 MB
Tags Python 3
SHA-256 checksum
How to use checksums
48a17bbfcde996c21e00fb90fd8f7f434d1456581b79b34550fca9c0cbd8c0fc
BLAKE2b-256 checksum
How to use checksums
1ff259f25c88122018bb970d428b2782681adfe998a16c76e74fd24743247a5c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

Security for tinker-cookbook 0.6.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for tinker_cookbook-0.6.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 6, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page