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'
    

Tinker

Refer to the docs to start from basics. Here we introduce a few Tinker primitives - the basic components to fine-tune LLMs:

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

sampling_client = training_client.save_weights_and_get_sampling_client()
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.

To download the weights of any model:

rest_client = service_client.create_rest_client()
future = rest_client.get_checkpoint_archive_url_from_tinker_path(sampling_client.model_path)
with open(f"model-checkpoint.tar.gz", "wb") as f:
    f.write(future.result())

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 a wide range of more sophisticated examples in the tinker_cookbook/recipes/ folder:

  1. Chat supervised learning: supervised fine-tuning on conversational datasets like Tulu3.
  2. Math reasoning: improve LLM reasoning capability by rewarding it for answering math questions correctly.
  3. Preference learning: showcase a three-stage RLHF pipeline: 1) supervised fine-tuning, 2) learning a reward model, 3) RL against the reward model.
  4. Tool use: train LLMs to better use retrieval tools to answer questions more accurately.
  5. Prompt distillation: internalize long and complex instructions into LLMs.
  6. Multi-Agent: optimize LLMs to play against another LLM or themselves.

These examples are located in each subfolder, and their README.md files will walk you through the key implementation details, the commands to run them, and the expected performance.

Documentation

The docs/ directory contains a mirror of the Tinker documentation. These files are synced from our internal documentation site.

Note: The documentation files use MDX format (Markdown with JSX), which includes some syntax that isn't standard Markdown. You may see things like import statements, <Callout> components, or curly-brace expressions. These are artifacts of our documentation framework - the actual content should still be readable as Markdown.

If you find errors or want to improve the documentation, feel free to submit a PR editing files in docs/. We'll sync the changes back to our documentation site.

For the rendered documentation, visit tinker-docs.thinkingmachines.ai.

Import our utilities

Tinker cookbook includes several utilities. Here's a quick overview:

  • renderers converts tokens from/to structured chat message objects
  • hyperparam_utils helps calculate hyperparameters suitable for LoRAs
  • evaluation provides abstractions for evaluating Tinker models and inspect_evaluation shows how to integrate with InspectAI to make evaluating on standard benchmarks easy.

Claude Code Skills

Tinker Cookbook ships with Claude Code skills that teach Claude how to use the Tinker API — SFT, RL, DPO, renderers, environments, and more. Install them globally so Claude can help you in any project:

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

Once installed, use /tinker-sft, /tinker-grpo, /tinker-setup, etc. in Claude Code. Skills update automatically from the repo.

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, 2025. Tinker. https://thinkingmachines.ai/tinker/.

Or use this BibTeX citation:

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

Metadata

Release files for tinker-cookbook 0.2.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.2.1
File Size Uploaded Provenance Actions
tinker_cookbook-0.2.1.tar.gz 1.7 MB Without provenance Details for tinker_cookbook-0.2.1.tar.gz

Built distribution (wheel)

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

Total release size: 2.4 MB

Release files / tinker_cookbook-0.2.1.tar.gz

Download URL tinker_cookbook-0.2.1.tar.gz
Size 1.7 MB
Tags Source
SHA-256 checksum
How to use checksums
4d96e668b57e4f341a5e8ae1e49aafdd093e18de3c9f03b9fec80a60bae2fc0d
BLAKE2b-256 checksum
How to use checksums
ff5f1a819b7bf0cab89a59d854b70138b66457c0342f9e96ea4f693e4dfb0d5f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.2 {"installer":{"name":"uv","version":"0.11.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

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

Download URL tinker_cookbook-0.2.1-py3-none-any.whl
Size 653.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1b86988865743a757617b4a478d0e4b470a89d89b9f3c0c5e3c0411c533a35fe
BLAKE2b-256 checksum
How to use checksums
9e3e173c324a8ac082af6d7221447846527705754735b502acaa9af3826d8b17
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.2 {"installer":{"name":"uv","version":"0.11.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for tinker-cookbook 0.2.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.

No provenance found

None of the files in this release were uploaded with provenance metadata.

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