### Setup: Create a Tinker Checkpoint

Source: https://tinker-docs.thinkingmachines.ai/tutorials/deployment/export-hf

This Python script sets up a training client, runs a single SFT step, and saves the LoRA adapter weights. This serves as the input for the export process. Ensure you have the necessary Tinker libraries installed.

```python
import tinker
from tinker_cookbook import renderers
from tinker_cookbook.supervised.data import conversation_to_datum
from tinker_cookbook.tokenizer_utils import get_tokenizer

BASE_MODEL = "Qwen/Qwen3.5-4B"

service_client = tinker.ServiceClient()
training_client = await service_client.create_lora_training_client_async(
    base_model=BASE_MODEL, rank=16
)

# Build a minimal training example
_tokenizer = get_tokenizer(BASE_MODEL)
_renderer = renderers.get_renderer("qwen3", _tokenizer)
_messages = [
    {"role": "user", "content": "What is Tinker?"},
    {"role": "assistant", "content": "Tinker is a cloud training API for LLM fine-tuning."},
]
_datum = conversation_to_datum(_messages, _renderer, max_length=512)

# One training step + save
_fwd = await training_client.forward_backward_async([_datum], loss_fn="cross_entropy")
_opt = await training_client.optim_step_async(tinker.AdamParams(learning_rate=1e-4))
await _fwd.result_async()
await _opt.result_async()

_save_result = training_client.save_weights_for_sampler(name="export-tutorial")
sampler_path = _save_result.result().path
print(f"Base model:  {BASE_MODEL}")
print(f"Checkpoint:  {sampler_path}")

```

--------------------------------

### Switch Between Model Renderers

Source: https://tinker-docs.thinkingmachines.ai/tutorials/core-concepts/rendering

Demonstrates how to get and use different renderers for various model families, such as Qwen3. Ensure you use the correct tokenizer for each model family. This example shows building a generation prompt for Qwen3.

```python
# Example: switching between renderers
# Each model family needs its own tokenizer
qwen_tokenizer = tokenizer_utils.get_tokenizer("Qwen/Qwen3-30B-A3B")
qwen_renderer = renderers.get_renderer("qwen3", qwen_tokenizer)

test_messages = [{"role": "user", "content": "Hello!"}]
prompt_tokens = qwen_renderer.build_generation_prompt(test_messages)
print("Qwen3 prompt:")
print(qwen_tokenizer.decode(prompt_tokens.to_ints()))
```

--------------------------------

### Run Multi-Agent Example Interactively

Source: https://tinker-docs.thinkingmachines.ai/tutorials/advanced/multi-agent

Download and run the multi-agent example script using curl and uv.

```bash
curl -O https://raw.githubusercontent.com/thinking-machines-lab/tinker-cookbook/main/tutorials/405_multi_agent.py && uv run marimo edit 405_multi_agent.py
```

--------------------------------

### Install Dependencies and Set Up API Key

Source: https://tinker-docs.thinkingmachines.ai/cookbook/recipes/agent-rl

Installs the necessary package and sets the OpenAI API key for LLM judge grading.

```bash
uv pip install 'tinker-cookbook[modal]'
modal token new
export OPENAI_API_KEY=...
```

--------------------------------

### Setup Tinker Sampling Client and Renderer

Source: https://tinker-docs.thinkingmachines.ai/tutorials/core-concepts/completers

Initializes a ServiceClient, creates a SamplingClient for a specified model, and obtains a tokenizer and renderer. This setup is used throughout the tutorial.

```python
MODEL_NAME = "Qwen/Qwen3-4B-Instruct-2507"

service_client = tinker.ServiceClient()
sampling_client = service_client.create_sampling_client(base_model=MODEL_NAME)
tokenizer = sampling_client.get_tokenizer()
renderer = get_renderer("qwen3_instruct", tokenizer)

print(f"Sampling client ready for {MODEL_NAME}")
```

--------------------------------

### Example Model Configuration Output

Source: https://tinker-docs.thinkingmachines.ai/tutorials/deployment/export-hf

This is an example of the output you might see when verifying a model's configuration.

```text
Architecture:    Qwen3_5ForConditionalGeneration
Hidden size:     2560
Num layers:      32
Vocab size:      248320
```

--------------------------------

### Install tinker-cookbook with Modal support

Source: https://tinker-docs.thinkingmachines.ai/cookbook/recipes/code-rl

Install the library with optional Modal sandboxing support and set up Modal authentication.

```bash
uv pip install 'tinker-cookbook[modal]'
modal token new

```

--------------------------------

### Client Creation

Source: https://tinker-docs.thinkingmachines.ai/tinker/quickstart

Demonstrates how to create ServiceClient, TrainingClient, and SamplingClient instances, and how to get the tokenizer.

```APIDOC
## Create clients
```python
import tinker
from tinker import types

# Entry point — reads TINKER_API_KEY from environment
service_client = tinker.ServiceClient()

# Training client (LoRA fine-tuning)
training_client = service_client.create_lora_training_client(
    base_model="Qwen/Qwen3-8B", rank=32
)

# Sampling client (text generation)
sampling_client = service_client.create_sampling_client(
    base_model="Qwen/Qwen3-8B"
)

# Tokenizer
tokenizer = training_client.get_tokenizer()

```

### Subprocess Sampling
`SamplingClient` is picklable — you can pass it to other processes for parallel sampling. If your training loop has CPU-heavy work (grading, environment logic), set `TINKER_SUBPROCESS_SAMPLING=1` to run `sample()` and `compute_logprobs()` in a dedicated subprocess, preventing GIL contention.
```

--------------------------------

### Install tinker-cookbook

Source: https://tinker-docs.thinkingmachines.ai/cookbook/recipes/chat-sl

Install the tinker-cookbook library using pip. This is a prerequisite for running the training scripts.

```bash
uv pip install tinker-cookbook

```

--------------------------------

### Install Tinker Cookbook and Prime CLI

Source: https://tinker-docs.thinkingmachines.ai/cookbook/recipes/verifiers-rl

Installs the necessary libraries for using Tinker with RL environments. Ensure you have `uv` and `pip` installed.

```bash
uv pip install tinker-cookbook
uv tool install prime
prime env install primeintellect/reverse-text  # or any other environment
```

--------------------------------

### Install for Local Development

Source: https://tinker-docs.thinkingmachines.ai/cookbook/quickstart

Clones the tinker-cookbook repository and installs it in editable mode for local development.

```bash
git clone https://github.com/thinking-machines-lab/tinker-cookbook.git
cd tinker-cookbook
uv pip install -e .

```

--------------------------------

### Install Tinker Cookbook with Math RL

Source: https://tinker-docs.thinkingmachines.ai/cookbook/recipes/math-rl

Installs the necessary package for the math RL recipe. Ensure you have uv and pip installed.

```bash
uv pip install 'tinker-cookbook[math-rl]'
```

--------------------------------

### Install Tinker SDK

Source: https://tinker-docs.thinkingmachines.ai/tutorials

Installs the Tinker SDK, cookbook, and marimo using uv pip. Ensure you have Python and pip/uv installed.

```bash
uv pip install tinker tinker-cookbook marimo

```

--------------------------------

### Setup: Train for One Step

Source: https://tinker-docs.thinkingmachines.ai/tutorials/core-concepts/weights

Initializes a training client and performs a single training step to generate a checkpoint.

```python
import warnings

warnings.filterwarnings("ignore", message="IProgress not found")

import tinker
import torch
from tinker import TensorData
```

```python
MODEL_NAME = "Qwen/Qwen3-4B-Instruct-2507"

service_client = tinker.ServiceClient()
training_client = await service_client.create_lora_training_client_async(
    base_model=MODEL_NAME, rank=16
)
tokenizer = training_client.get_tokenizer()

# One quick SFT step
text = "The Pythagorean theorem states that a^2 + b^2 = c^2."
ids = tokenizer.encode(text)
model_input = tinker.ModelInput.from_ints(ids[:-1])
target_tokens = ids[1:]
weights = [1.0] * len(target_tokens)

datum = tinker.Datum(
    model_input=model_input,
    loss_fn_inputs={
        "target_tokens": TensorData.from_torch(torch.tensor(target_tokens)),
        "weights": TensorData.from_torch(torch.tensor(weights)),
    },
)

fb_future = await training_client.forward_backward_async([datum], loss_fn="cross_entropy")
await fb_future.result_async()
optim_future = await training_client.optim_step_async(tinker.AdamParams(learning_rate=1e-4))
await optim_future.result_async()
print("Training step complete")
```

--------------------------------

### Multi-teacher Configuration Example

Source: https://tinker-docs.thinkingmachines.ai/cookbook/recipes/distillation

Example configuration for multi-teacher distillation, specifying dataset builders, teacher models, and batch sizes.

```python
{
    "dataset_builder": RLDatasetBuilder,
    "teacher_model": {
        "base_model": str,  # e.g. "Qwen/Qwen3-32B"
        "load_checkpoint_path": str | None  # e.g. "tinker://<unique_id>/sampler_weights/final"
    },
    "groups_per_batch": int
}

```

--------------------------------

### Install Tinker and Cookbook

Source: https://tinker-docs.thinkingmachines.ai/cookbook/quickstart

Installs the Tinker SDK and cookbook. Set the TINKER_API_KEY environment variable before running.

```bash
uv pip install tinker tinker-cookbook
export TINKER_API_KEY="your-api-key-here"

```

--------------------------------

### Install Tinker SDK

Source: https://tinker-docs.thinkingmachines.ai/tinker/quickstart

Install the Tinker Python SDK using pip. This command also installs the Tinker CLI.

```bash
uv pip install tinker

```

--------------------------------

### Install Nightly Builds

Source: https://tinker-docs.thinkingmachines.ai/cookbook/quickstart

Installs the latest nightly build of the tinker-cookbook from GitHub.

```bash
uv pip install 'tinker-cookbook @ git+https://github.com/thinking-machines-lab/tinker-cookbook.git@nightly'

```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://tinker-docs.thinkingmachines.ai/cookbook/contributing

Clone the Tinker Cookbook repository, navigate into the directory, synchronize dependencies with uv, and install pre-commit hooks.

```bash
git clone https://github.com/thinking-machines-lab/tinker-cookbook.git
cd tinker-cookbook
uv sync --extra dev
pre-commit install

```

--------------------------------

### Install Cloud Storage Support

Source: https://tinker-docs.thinkingmachines.ai/cookbook/storage

Install the necessary package to enable support for cloud storage backends like GCS, S3, and Azure.

```bash
uv pip install 'tinker-cookbook[cloud]'
```

--------------------------------

### Run Tinker Completers Tutorial Interactively

Source: https://tinker-docs.thinkingmachines.ai/tutorials/core-concepts/completers

Download the tutorial script and run it interactively using marimo edit. This is the starting point for the tutorial.

```bash
curl -O https://raw.githubusercontent.com/thinking-machines-lab/tinker-cookbook/main/tutorials/203_completers.py && uv run marimo edit 203_completers.py
```

--------------------------------

### Install Tinker Cookbook with Vector Search

Source: https://tinker-docs.thinkingmachines.ai/cookbook/recipes/search-tool

Install the necessary package for Tinker Cookbook with vector search capabilities.

```bash
uv pip install 'tinker-cookbook[vector-search]'
```

--------------------------------

### Setup Tinker Clients and Evaluation Data

Source: https://tinker-docs.thinkingmachines.ai/tutorials/core-concepts/evaluations

Initializes a ServiceClient, a LoRA TrainingClient, and prepares held-out SFT data formatted as Tinker Datums for NLL evaluation. This setup is crucial before implementing custom evaluators.

```python
MODEL_NAME = "Qwen/Qwen3-4B-Instruct-2507"

service_client = tinker.ServiceClient()
training_client = await service_client.create_lora_training_client_async(
    base_model=MODEL_NAME, rank=16
)
tokenizer = training_client.get_tokenizer()
renderer = get_renderer("qwen3_instruct", tokenizer)

# Prepare held-out SFT data for the NLL evaluator
eval_examples = [
    "The speed of light is approximately 3 * 10^8 meters per second.",
    "Water freezes at 0 degrees Celsius under standard pressure.",
    "The Earth orbits the Sun once every 365.25 days.",
]

eval_datums = []
for text in eval_examples:
    ids = tokenizer.encode(text)
    model_input = tinker.ModelInput.from_ints(ids[:-1])
    target_tokens = ids[1:]
    w = [1.0] * len(target_tokens)
    eval_datums.append(
        tinker.Datum(
            model_input=model_input,
            loss_fn_inputs={
                "target_tokens": TensorData.from_torch(torch.tensor(target_tokens)),
                "weights": TensorData.from_torch(torch.tensor(w)),
            },
        )
    )

print(f"Prepared {len(eval_datums)} evaluation datums")
```

--------------------------------

### Run Marimo Notebook Interactively

Source: https://tinker-docs.thinkingmachines.ai/tutorials/deployment/lora-adapter

Execute the Marimo notebook for this tutorial interactively. Ensure you have Marimo installed.

```bash
curl -O https://raw.githubusercontent.com/thinking-machines-lab/tinker-cookbook/main/tutorials/502_lora_adapter.py && uv run marimo edit 502_lora_adapter.py
```

--------------------------------

### Setup Tinker Client and Model

Source: https://tinker-docs.thinkingmachines.ai/tutorials/basics/async-patterns

Initializes the Tinker ServiceClient, SamplingClient, tokenizer, and renderer. Sets up sampling parameters and a list of diverse prompts for testing.

```python
import time
import warnings

warnings.filterwarnings("ignore", message="IProgress not found")

import tinker

from tinker_cookbook.renderers import get_renderer, get_text_content


BASE_MODEL = "Qwen/Qwen3.5-4B"

service_client = tinker.ServiceClient()
sampling_client = await service_client.create_sampling_client_async(base_model=BASE_MODEL)
tokenizer = sampling_client.get_tokenizer()
renderer = get_renderer("qwen3_5", tokenizer)

stop_sequences = renderer.get_stop_sequences()
params = tinker.SamplingParams(max_tokens=150, temperature=0.7, stop=stop_sequences)

# A diverse set of prompts to sample from
prompts = [
    "What causes thunder?",
    "Write a haiku about the ocean.",
    "What is the capital of New Zealand?",
    "Explain what a hash table is in two sentences.",
    "Name three inventions from the 19th century.",
    "Why do leaves change color in autumn?",
    "Translate to Spanish: The library closes at nine.",
    "What is the smallest prime number greater than 50?",
]

print(f"Model: {BASE_MODEL}")
print(f"Prompts: {len(prompts)}")

```

--------------------------------

### Run Training with Config - Tinker Cookbook

Source: https://tinker-docs.thinkingmachines.ai/cookbook

Use this snippet to initiate the main training process with a configuration object. Ensure the `tinker-cookbook` is installed.

```python
asyncio.run(train.main(config))
```

--------------------------------

### Setup Renderer and Tokenizer

Source: https://tinker-docs.thinkingmachines.ai/tutorials/core-concepts/rendering

Initialize the tokenizer and renderer for a specific model. Ensure the correct model name is used for the tokenizer.

```python
from tinker_cookbook import renderers, tokenizer_utils

tokenizer = tokenizer_utils.get_tokenizer("Qwen/Qwen3-30B-A3B")
renderer = renderers.get_renderer("qwen3", tokenizer)
```

--------------------------------

### Launch Chroma DB Service

Source: https://tinker-docs.thinkingmachines.ai/cookbook/recipes/search-tool

Start the Chroma DB service to host the Wikipedia index. Ensure sufficient RAM is available.

```bash
chroma run --host localhost --path <decompressed_path>/chroma_db --port 8000
```

--------------------------------

### Configure Benchmark Execution

Source: https://tinker-docs.thinkingmachines.ai/cookbook/eval/benchmarks-guide

Set parameters like example limits, concurrency, timeouts, and save directories for benchmark runs.

```python
from tinker_cookbook.eval.benchmarks import run_benchmark, BenchmarkConfig

config = BenchmarkConfig(
    max_examples=200,         # Cap number of examples (None = all)
    concurrency=64,           # Parallel rollouts (single-turn)
    agent_concurrency=8,      # Parallel rollouts (multi-turn)
    timeout_seconds=300,      # Per-example timeout
    max_tokens=32768,         # Max generation tokens
    temperature=0.6,
    save_dir="evals/run_01",  # Save trajectories and results
)

result = await run_benchmark("gsm8k", sampling_client, renderer, config)
```

--------------------------------

### Run Interactive Tutorial

Source: https://tinker-docs.thinkingmachines.ai/tutorials/cookbook-abstractions/custom-environment

Download and run the tutorial script interactively using `uv` and `marimo`.

```bash
curl -O https://raw.githubusercontent.com/thinking-machines-lab/tinker-cookbook/main/tutorials/302_custom_environment.py && uv run marimo edit 302_custom_environment.py
```

--------------------------------

### Initialize Vision Renderer with Image Processor

Source: https://tinker-docs.thinkingmachines.ai/tutorials/core-concepts/rendering

To use vision renderers, you need to obtain an image processor specific to the model. This example shows how to get the tokenizer and image processor and then initialize a vision-enabled renderer.

```python
from tinker_cookbook.image_processing_utils import get_image_processor

model_name = "Qwen/Qwen3-VL-235B-A22B-Instruct"
tokenizer = tokenizer_utils.get_tokenizer(model_name)
image_processor = get_image_processor(model_name)

renderer = renderers.get_renderer("qwen3_vl_instruct", tokenizer, image_processor=image_processor)
```

--------------------------------

### Save Audit Log Script Usage Examples

Source: https://tinker-docs.thinkingmachines.ai/cookbook/api-reference/scripts/save_audit_log

Demonstrates how to run the script for one-shot fetching or for backfilling and continuous polling.

```bash
python -m tinker_cookbook.scripts.save_audit_log --once
```

```bash
python -m tinker_cookbook.scripts.save_audit_log \
    --output-dir ./audit_logs \
    --backfill-days 7 \
    --interval-seconds 3600
```

--------------------------------

### Run DPO Tutorial Interactively

Source: https://tinker-docs.thinkingmachines.ai/tutorials/advanced/dpo-preferences

Download and run the DPO preferences tutorial script interactively using uv and marimo.

```bash
curl -O https://raw.githubusercontent.com/thinking-machines-lab/tinker-cookbook/main/tutorials/403_dpo_preferences.py && uv run marimo edit 403_dpo_preferences.py
```

--------------------------------

### Run Interactive Tutorial

Source: https://tinker-docs.thinkingmachines.ai/tutorials/advanced/sequence-extension

Download and run the interactive Marimo notebook for this tutorial.

```bash
curl -O https://raw.githubusercontent.com/thinking-machines-lab/tinker-cookbook/main/tutorials/404_sequence_extension.py && uv run marimo edit 404_sequence_extension.py
```

--------------------------------

### SFT Cross-Entropy Loss Example

Source: https://tinker-docs.thinkingmachines.ai/tinker/losses

Demonstrates creating a `Datum` for supervised fine-tuning (SFT) with cross-entropy loss. Ensure `input_tokens`, `target_tokens`, and `weights` are defined.

```python
import tinker
from tinker import types

# A single training example: predict target_tokens from input_tokens
datum = types.Datum(
    model_input=types.ModelInput.from_ints(input_tokens),  # shape: (N,)
    loss_fn_inputs={
        "target_tokens": target_tokens,  # shape: (N,) — what to predict at each position
        "weights": weights,              # shape: (N,) — 0 for prompt, 1 for completion
    }
)

# forward_backward computes the loss and gradients in one call
future = await training_client.forward_backward_async([datum], loss_fn="cross_entropy")
result = await future.result_async()
print(f"Loss: {result.loss}")

```

--------------------------------

### Download and Run Single Tutorial

Source: https://tinker-docs.thinkingmachines.ai/tutorials

Downloads a single tutorial Python file using curl and then runs it with marimo. Useful for testing individual tutorials without cloning the entire repository.

```bash
curl -O https://raw.githubusercontent.com/thinking-machines-lab/tinker-cookbook/main/tutorials/101_hello_tinker.py
uv run marimo edit 101_hello_tinker.py

```

--------------------------------

### Initialize ServiceClient and Create Clients

Source: https://tinker-docs.thinkingmachines.ai/tinker/api-reference/serviceclient

Demonstrates how to initialize the ServiceClient and create instances of TrainingClient, SamplingClient, and RestClient. Initialization of ServiceClient is near instant, while creating a TrainingClient may take longer.

```python
# Near instant
client = ServiceClient()

# Takes a moment as we initialize the model and assign resources
training_client = client.create_lora_training_client(base_model="Qwen/Qwen3-8B")

# Near-instant
sampling_client = client.create_sampling_client(base_model="Qwen/Qwen3-8B")

# Near-instant
rest_client = client.create_rest_client()

```

--------------------------------

### Prepare Data for Supervised Fine-Tuning

Source: https://tinker-docs.thinkingmachines.ai/tutorials/core-concepts/rendering

Use `build_supervised_example` to prepare data for training. It returns model input tokens and per-token loss weights, distinguishing prompt (weight 0) from completion (weight 1) tokens.

```python
model_input, weights = renderer.build_supervised_example(messages)

# Show which tokens are prompt vs completion
token_ids = model_input.to_ints()
for i, (tok_id, w) in enumerate(zip(token_ids, weights.tolist())):
    label = "COMPLETION" if w > 0 else "prompt"
    print(f"  [{i:3d}] {label:10s}  {repr(tokenizer.decode([tok_id]))}")

```

--------------------------------

### Generate Example Data

Source: https://tinker-docs.thinkingmachines.ai/cookbook/recipes/rubric

Executes a script to generate example data for the rubric-based grading recipe.

```bash
python -m tinker_cookbook.recipes.rubric.generate_data

```

--------------------------------

### Instantiate and Interact with MathEnv

Source: https://tinker-docs.thinkingmachines.ai/tutorials/cookbook-abstractions/env-and-envgroupbuilder

Demonstrates creating a MathEnv instance and simulating its lifecycle by calling initial_observation() and step(). Shows how to get the initial observation and process a simulated action.

```python
from tinker_cookbook.recipes.math_rl.math_env import MathEnv

MODEL_NAME = "Qwen/Qwen3.5-4B"
RENDERER_NAME = "qwen3_5"

tokenizer = get_tokenizer(MODEL_NAME)
renderer = renderers.get_renderer(RENDERER_NAME, tokenizer=tokenizer)

# Create a single MathEnv instance
env = MathEnv(
    problem="What is 2 + 3?",
    answer="5",
    renderer=renderer,
)

# initial_observation() returns the prompt tokens and stop condition
ob, stop_cond = await env.initial_observation()
print(f"Observation length: {ob.length} tokens")
print(f"Stop condition: {stop_cond}")
print(f"Question: {env.get_question()}")
```

--------------------------------

### Run RL Hyperparameters Tutorial Interactively

Source: https://tinker-docs.thinkingmachines.ai/tutorials/advanced/rl-hyperparams

Download and run the RL hyperparameters tutorial script interactively using Marimo.

```bash
curl -O https://raw.githubusercontent.com/thinking-machines-lab/tinker-cookbook/main/tutorials/402_rl_hyperparams.py && uv run marimo edit 402_rl_hyperparams.py
```

--------------------------------

### Run Tinker Loss Functions Tutorial Interactively

Source: https://tinker-docs.thinkingmachines.ai/tutorials/core-concepts/loss-functions

Download the tutorial script and run it interactively using Marimo.

```bash
curl -O https://raw.githubusercontent.com/thinking-machines-lab/tinker-cookbook/main/tutorials/202_loss_functions.py && uv run marimo edit 202_loss_functions.py
```

--------------------------------

### Run Tinker Tutorial Interactively

Source: https://tinker-docs.thinkingmachines.ai/tutorials/basics/hello-tinker

Download the tutorial script and run it using `uv run marimo edit`. This command opens the script in an interactive Marimo environment.

```bash
curl -O https://raw.githubusercontent.com/thinking-machines-lab/tinker-cookbook/main/tutorials/101_hello_tinker.py && uv run marimo edit 101_hello_tinker.py
```

--------------------------------

### Print Training Example Count

Source: https://tinker-docs.thinkingmachines.ai/tutorials/basics/first-sft

This snippet prints the total number of training examples generated after the conversion process.

```python
print(f"Built {len(training_data)} training examples")
```

--------------------------------

### Run Interactive RL Tutorial

Source: https://tinker-docs.thinkingmachines.ai/tutorials/basics/first-rl

Download the Python script for the RL tutorial and run it interactively using marimo.

```bash
curl -O https://raw.githubusercontent.com/thinking-machines-lab/tinker-cookbook/main/tutorials/104_first_rl.py && uv run marimo edit 104_first_rl.py
```

--------------------------------

### Create Training Client from Saved State (with Optimizer)

Source: https://tinker-docs.thinkingmachines.ai/tinker/api-reference/serviceclient

Create a TrainingClient by loading both model weights and optimizer state from a specified path. This allows for resuming training exactly where it left off, including optimizer momentum.

```python
# Resume training from a checkpoint with optimizer state
training_client = service_client.create_training_client_from_state_with_optimizer(
"tinker://run-id/weights/checkpoint-001"
)
# Continue training with restored optimizer momentum

```

--------------------------------

### Setup Tinker Training Client and Tokenizer

Source: https://tinker-docs.thinkingmachines.ai/tutorials/core-concepts/loss-functions

Initialize a ServiceClient and create a LoRA training client with a specified base model and rank. Retrieve the tokenizer for subsequent use.

```python
MODEL_NAME = "Qwen/Qwen3-4B-Instruct-2507"

service_client = tinker.ServiceClient()
training_client = await service_client.create_lora_training_client_async(
    base_model=MODEL_NAME, rank=16
)
tokenizer = training_client.get_tokenizer()

print(f"Training client ready for {MODEL_NAME}")
```

--------------------------------

### Tinker Checkpoint Path Example

Source: https://tinker-docs.thinkingmachines.ai/tutorials/deployment/opencode

This is an example of a sampler checkpoint path obtained after saving a Tinker model. Use this path as the model ID in your `opencode.json` configuration.

```text
tinker://040ac13a-4dea-5e21-bee5-2d1e581ae9d4:train:0/sampler_weights/000043
```

--------------------------------

### build_supervised_example(messages, train_on_what)

Source: https://tinker-docs.thinkingmachines.ai/cookbook/api-reference/renderers/renderer

Builds tokens and per-token weights for supervised fine-tuning, with detailed control over training targets.

```APIDOC
### Method build_supervised_example(messages, train_on_what)

Build tokens and per-token weights for supervised fine-tuning.

**Parameters:**
* **messages** (list[Message]) – A list of messages to render.
* **train_on_what** (TrainOnWhat) – Controls which tokens receive non-zero training weight: - LAST_ASSISTANT_MESSAGE: Only the last assistant message - LAST_ASSISTANT_TURN: The last assistant message after the last user message - ALL_ASSISTANT_MESSAGES: All assistant messages - ALL_MESSAGES: All messages (but not headers) - ALL_TOKENS: Everything including headers - ALL_USER_AND_SYSTEM_MESSAGES: User and system messages only - CUSTOMIZED: Use the 'trainable' field on each message

**Returns:** tuple[tinker.ModelInput, torch.Tensor]: A `(model_input, weights)` tuple where weights is a 1-D float tensor with the same length as the total number of tokens.
```

--------------------------------

### Example Math RL Output with Boxed Answer

Source: https://tinker-docs.thinkingmachines.ai/cookbook/recipes/math-rl

An example of a model's output after training on the MATH dataset, showing chain-of-thought reasoning and a final answer enclosed in \boxed{}.

```text
<|im_start|>user
The numbers 2, 3, 5, 7, 11, 13 are arranged in a multiplication table, with three along the top and the other three down the left.  The multiplication table is completed and the sum of the nine entries is tabulated.  What is the largest possible sum of the nine entries?

\[
\begin{array}{c||c|c|c|}
\times & a & b & c \\ \hline \hline
d & & & \\ \hline
e & & & \\ \hline
f & & & \\ \hline
\end{array}
\] Write your answer in \boxed{} format.<|im_end|>
<|im_start|>assistant
<think>
Okay, so we have to arrange the primes 2,3,5,7,11,13 into a 3x3 multiplication table. The sum of all entries is (a+b+c)*(d+e+f) - because the sum of the products is the product of the sums. To maximize the total sum, we need to maximize the product of the sums of the two groups. So, split the numbers into two groups of three, one group for the top row (a,b,c) and one for the left column (d,e,f). The product (sum1)*(sum2) is maximized when the sums are as close as possible? Or maybe when one is as large as possible and the other as small? Wait, for a fixed sum, the product is maximized when they're equal. But since the total sum of all numbers is 2+3+5+7+11+13= 41. So sum1 + sum2 =41. To maximize sum1*sum2, we need sum1 and sum2 as close as possible to 41/2=20.5. So find two subsets of three numbers that add up to around 20.5.

Let me try combinations. Let's see:

Possible sums for three numbers:

- 2+3+13=18

- 2+5+13=20
- 2+7+11=20

- 3+5+13=21

- 3+7+11=21

- 5+7+11=23

So the best possible is sum1=20 and sum2=21, product 420. So the maximum sum is 420. \boxed{420}</think>

\boxed{420}<|im_end|>
```

--------------------------------

### Run tinker cookbook interactively

Source: https://tinker-docs.thinkingmachines.ai/tutorials/deployment/publish-hub

This command downloads the tutorial script and opens it in the Marimo editor for interactive execution.

```bash
curl -O https://raw.githubusercontent.com/thinking-machines-lab/tinker-cookbook/main/tutorials/503_publish_hub.py && uv run marimo edit 503_publish_hub.py
```

--------------------------------

### result

Source: https://tinker-docs.thinkingmachines.ai/tinker/api-reference/apifuture

Get the result synchronously with optional timeout.

```APIDOC
## result(_timeout=None_)

### Description
Get the result synchronously with optional timeout.

### Parameters
#### Path Parameters
- **_timeout_** (int) - Optional - Timeout in seconds.

### Returns
- The result value of type T
```

--------------------------------

### get_lora_param_count

Source: https://tinker-docs.thinkingmachines.ai/cookbook/api-reference/hyperparam_utils

Get the number of parameters in the LoRA adapter.

```APIDOC
## get_lora_param_count()

### Description
Get the number of parameters in the LoRA adapter.

### Function Signature
`get_lora_param_count()`
```

--------------------------------

### initial_observation

Source: https://tinker-docs.thinkingmachines.ai/cookbook/api-reference/rl/problemenv

Builds the initial prompt for the environment.

```APIDOC
## initial_observation()

### Description
Build the initial prompt from the conversation prefix and question.

### Method
GET (conceptual)

### Endpoint
N/A (method call)

### Returns
- **Any**: The initial observation/prompt.
```

--------------------------------

### get_lora_lr_multiplier

Source: https://tinker-docs.thinkingmachines.ai/cookbook/api-reference/hyperparam_utils

Get a model-specific multiplier for the LR, when training with LoRA.

```APIDOC
## get_lora_lr_multiplier()

### Description
Get a model-specific multiplier for the LR, when training with LoRA.

### Function Signature
`get_lora_lr_multiplier()`
```

--------------------------------

### Run Tinker Evaluation Tutorial Interactively

Source: https://tinker-docs.thinkingmachines.ai/tutorials/core-concepts/evaluations

Download the evaluation tutorial script and open it in the Marimo editor for interactive execution.

```bash
curl -O https://raw.githubusercontent.com/thinking-machines-lab/tinker-cookbook/main/tutorials/205_evaluations.py && uv run marimo edit 205_evaluations.py
```

--------------------------------

### get_lr

Source: https://tinker-docs.thinkingmachines.ai/cookbook/api-reference/hyperparam_utils

Get a recommended learning rate for the given model.

```APIDOC
## get_lr()

### Description
Get a recommended learning rate for the given model.

### Function Signature
`get_lr()`
```

--------------------------------

### Configure and Run RL Training

Source: https://tinker-docs.thinkingmachines.ai/tutorials/advanced/rlhf-pipeline

Set up the Reinforcement Learning training process by loading checkpoints from previous stages, building the RL dataset with preference model rewards, and configuring the training parameters. Use a lower learning rate for RL updates.

```python
from tinker_cookbook.preference.comparison_policy_evaluator import (
    ComparisonEvaluator,
)
from tinker_cookbook.preference.types import PreferenceModelBuilderFromChatRenderer
from tinker_cookbook.rl import preference_envs, train as rl_train

# Load checkpoints from Stages 1 and 2
sft_ckpt = checkpoint_utils.get_last_checkpoint(sft_log_path)
rm_ckpt = checkpoint_utils.get_last_checkpoint(rm_log_path)
assert sft_ckpt is not None, f"No SFT checkpoint in {sft_log_path}"
assert rm_ckpt is not None, f"No RM checkpoint in {rm_log_path}"

print(f"SFT checkpoint: {sft_ckpt.state_path}")
print(f"RM checkpoint:  {rm_ckpt.sampler_path}")

# Build the preference model from the RM checkpoint
pm_builder = PreferenceModelBuilderFromChatRenderer(
    renderer_name=renderer_name,
    model_name=BASE_MODEL,
    rm_weights_path=rm_ckpt.sampler_path,
)

# Build the RL dataset: prompts from HHH, rewards from the preference model
rl_comparison_builder = HHHComparisonBuilder()
rl_dataset_builder = preference_envs.PairwisePreferenceRLDatasetBuilder(
    comparison_builder=rl_comparison_builder,
    policy_renderer_name=renderer_name,
    policy_model_name=BASE_MODEL,
    preference_model_builder=pm_builder,
    batch_size=BATCH_SIZE,
    group_size=4,
    tournament_pattern=preference_envs.TournamentPattern.ALL_PAIRS_BOTH_WAYS,
)

# Build an evaluator that measures win rate on held-out comparisons
def make_evaluator() -> ComparisonEvaluator:
    eval_builder = HHHComparisonBuilder(test_size=256)
    _, test_set = eval_builder.get_train_and_test_datasets()
    assert test_set is not None
    comparisons = [
        eval_builder.example_to_labeled_comparison(ex).comparison
        for ex in test_set
        if eval_builder.example_to_labeled_comparison(ex) is not None
    ]
    return ComparisonEvaluator(
        preference_model_builder=pm_builder,
        comparisons=comparisons,
        renderer_name=renderer_name,
        model_name_for_tokenizer=BASE_MODEL,
    )

# Configure and run RL
rl_log_path = f"{LOG_ROOT}/rl"
rl_config = rl_train.Config(
    model_name=BASE_MODEL,
    renderer_name=renderer_name,
    dataset_builder=rl_dataset_builder,
    load_checkpoint_path=sft_ckpt.state_path,
    learning_rate=1e-5,
    max_tokens=1024,
    log_path=rl_log_path,
    evaluator_builders=[make_evaluator],
    wandb_project=None,
    wandb_name="rlhf-tutorial-rl",
    lora_rank=LORA_RANK,
    save_every=100,
    eval_every=20,
    num_groups_to_log=4,
    max_steps=None,
)

asyncio.run(rl_train.main(rl_config))
print("Stage 3 (RL) complete.")
```

--------------------------------

### tinker.types.ModelInput.length

Source: https://tinker-docs.thinkingmachines.ai/tinker/api-reference/types/modelinput

Gets the total context length used by the ModelInput object.

```APIDOC
## length

### Description
Return the total context length used by this ModelInput.

### Returns
- **int** - The total context length.
```

--------------------------------

### SidecarStartupError

Source: https://tinker-docs.thinkingmachines.ai/tinker/api-reference/exceptions

Raised when the sidecar subprocess fails to start or times out during startup.

```APIDOC
## SidecarStartupError

### Description
Raised when the sidecar subprocess fails to start or times out.

### Inheritance
- `SidecarError`
```

--------------------------------

### Configure and Run SFT Training

Source: https://tinker-docs.thinkingmachines.ai/cookbook/quickstart

Sets up a supervised fine-tuning (SFT) configuration including logging path, model name, dataset builder, learning rate, LoRA rank, and saving/evaluation frequencies. Then, it runs the training pipeline.

```python
from tinker_cookbook.supervised import train
from tinker_cookbook.supervised.types import ChatDatasetBuilder

config = train.Config(
    log_path="~/logs/my-sft-run",
    model_name="Qwen/Qwen3-8B",
    dataset_builder=my_dataset_builder,
    learning_rate=1e-4,
    lora_rank=32,
    save_every=20,
    eval_every=10,
)
asyncio.run(train.main(config))

```

--------------------------------

### tinker_cookbook.rl.Env.initial_observation

Source: https://tinker-docs.thinkingmachines.ai/cookbook/api-reference/rl/env

Returns the starting observation and stop condition for a new episode.

```APIDOC
## initial_observation()

### Description
Return the starting observation and stop condition for this episode.

### Returns
tuple[Observation, StopCondition]: The initial observation (model input) and the stop condition for the first generation step.
```

--------------------------------

### build_supervised_examples(messages, train_on_what)

Source: https://tinker-docs.thinkingmachines.ai/cookbook/api-reference/renderers/renderer

Builds tokens and per-token weights for supervised fine-tuning.

```APIDOC
### Method build_supervised_examples(messages, train_on_what)

Build tokens and per-token weights for supervised fine-tuning.

**Parameters:**
* **messages** (list[Message]) – The conversation to render.
* **train_on_what** (TrainOnWhat) – Which parts of the sequence to compute loss on.

**Returns:** list[tuple[tinker.ModelInput, torch.Tensor]]: A list of `(ModelInput, weight_tensor)` tuples for training.
```

--------------------------------

### get_full_finetune_param_count

Source: https://tinker-docs.thinkingmachines.ai/cookbook/api-reference/hyperparam_utils

Get the total parameter count for a model by reading safetensors headers.

```APIDOC
## get_full_finetune_param_count()

### Description
Get the total parameter count for a model by reading safetensors headers.

### Function Signature
`get_full_finetune_param_count()`
```

--------------------------------

### Get Recommended Renderer Name

Source: https://tinker-docs.thinkingmachines.ai/cookbook/api-reference/model_info

Returns the most recommended renderer for the specified model.

```APIDOC
## get_recommended_renderer_name()

### Description
Return the most recommended renderer for the model.

### Function Signature
`get_recommended_renderer_name()`

### Parameters
None
```

--------------------------------

### Setup Tinker Training Client and Renderer

Source: https://tinker-docs.thinkingmachines.ai/tutorials/basics/first-rl

Initializes a Tinker ServiceClient, creates a LoRA training client for a base model (Llama-3.1-8B), and sets up a renderer and sampling parameters.

```python
base_model = "meta-llama/Llama-3.1-8B"

service_client = tinker.ServiceClient()
training_client = await service_client.create_lora_training_client_async(base_model=base_model, rank=32)
tokenizer = training_client.get_tokenizer()
renderer = get_renderer("llama3", tokenizer)

sampling_params = tinker.SamplingParams(
    max_tokens=256,
    stop=renderer.get_stop_sequences(),
)
adam_params = tinker.AdamParams(learning_rate=4e-5, beta1=0.9, beta2=0.95)
```

--------------------------------

### set_epoch

Source: https://tinker-docs.thinkingmachines.ai/cookbook/api-reference/supervised/superviseddataset

Notifies the dataset that a new epoch is starting, allowing for deterministic shuffling.

```APIDOC
## set_epoch(seed)

### Description
Notify the dataset that a new epoch is starting.

### Parameters
#### Path Parameters
- **seed** (int) - Optional - Epoch seed that can be used for deterministic shuffling. Default `0`.
```

--------------------------------

### Run Tinker Cookbook Script Interactively

Source: https://tinker-docs.thinkingmachines.ai/tutorials/basics/first-sft

Download and run the first SFT tutorial script using `curl` and `uv run marimo edit`. This command fetches the script and opens it in the Marimo editor for interactive execution.

```bash
curl -O https://raw.githubusercontent.com/thinking-machines-lab/tinker-cookbook/main/tutorials/102_first_sft.py && uv run marimo edit 102_first_sft.py
```

--------------------------------

### Get Sampler Information

Source: https://tinker-docs.thinkingmachines.ai/tinker/api-reference/restclient

Retrieves detailed information about a specific sampler using its ID.

```python
# Sync usage
future = rest_client.get_sampler("session-id:sample:0")
response = future.result()
print(f"Base model: {response.base_model}")
print(f"Model path: {response.model_path}")
```

--------------------------------

### Create and use a TrainingClient

Source: https://tinker-docs.thinkingmachines.ai/tinker/api-reference/trainingclient

Demonstrates creating a LoRA training client, performing forward/backward passes, optimizing, and saving the model for sampling.

```python
training_client = service_client.create_lora_training_client(base_model="Qwen/Qwen3-8B")
fwdbwd_future = training_client.forward_backward(training_data, "cross_entropy")
optim_future = training_client.optim_step(types.AdamParams(learning_rate=1e-4))
fwdbwd_result = fwdbwd_future.result()  # Wait for gradients
optim_result = optim_future.result()    # Wait for parameter update
sampling_client = training_client.save_weights_and_get_sampling_client("my-model")

```

--------------------------------

### get_full_finetune_lr_multiplier

Source: https://tinker-docs.thinkingmachines.ai/cookbook/api-reference/hyperparam_utils

Get a model-specific LR multiplier for full fine-tuning, proportional to 1/sqrt(N).

```APIDOC
## get_full_finetune_lr_multiplier()

### Description
Get a model-specific LR multiplier for full fine-tuning, proportional to 1/sqrt(N).

### Function Signature
`get_full_finetune_lr_multiplier()`
```

--------------------------------

### Get Recommended Renderer Names

Source: https://tinker-docs.thinkingmachines.ai/cookbook/api-reference/model_info

Returns a list of renderers that are designed for the specified model.

```APIDOC
## get_recommended_renderer_names()

### Description
Return a list of renderers that are designed for the model.

### Function Signature
`get_recommended_renderer_names()`

### Parameters
None
```

--------------------------------

### get_weights_info_by_tinker_path

Source: https://tinker-docs.thinkingmachines.ai/tinker/api-reference/restclient

Get checkpoint information from a tinker path. Returns an APIFuture containing the checkpoint information.

```APIDOC
## GET WEIGHTS INFO BY TINKER PATH

### Description
Get checkpoint information from a tinker path.

### Method
GET

### Endpoint
/checkpoints/tinker/{tinker_path}

### Parameters
#### Path Parameters
- **tinker_path** (string) - Required - The tinker path to the checkpoint.

### Response
#### Success Response (200)
- **base_model** (string) - The base model of the checkpoint.
- **lora_rank** (integer) - The LoRA rank of the checkpoint.

### Request Example
```python
future = rest_client.get_weights_info_by_tinker_path("tinker://run-id/weights/checkpoint-001")
response = future.result()  # or await future
print(f"Base Model: {response.base_model}, LoRA Rank: {response.lora_rank}")
```
```

--------------------------------

### create_training_client_from_state_with_optimizer

Source: https://tinker-docs.thinkingmachines.ai/tinker/api-reference/serviceclient

Create a TrainingClient by loading both model weights and optimizer state from a specified path, allowing for exact resumption of training.

```APIDOC
## create_training_client_from_state_with_optimizer(_path_, _user_metadata=None_, _weights_access_token=None_)

### Description
Create a TrainingClient by loading both model weights and optimizer state from a specified path, allowing for exact resumption of training.

### Parameters
- **path** (str) - The path to the saved model weights and optimizer state.
- **user_metadata** (dict[str, str] | None, optional) - User-defined metadata.
- **weights_access_token** (str | None, optional) - Access token for private weights.

### Returns
- `TrainingClient`: A client loaded with the specified weights and optimizer state.

### Example
```python
# Resume training from a checkpoint with optimizer state
training_client = service_client.create_training_client_from_state_with_optimizer(
    "tinker://run-id/weights/checkpoint-001"
)
# Continue training with restored optimizer momentum
```

_Async variant:_ `create_training_client_from_state_with_optimizer_async()`
```

--------------------------------

### get_training_run

Source: https://tinker-docs.thinkingmachines.ai/tinker/api-reference/restclient

Get training run info. Returns a Future containing the training run information.

```APIDOC
## GET TRAINING RUN

### Description
Get training run info.

### Method
GET

### Endpoint
/training_runs/{training_run_id}

### Parameters
#### Path Parameters
- **training_run_id** (string) - Required - The ID of the training run.
- **access_scope** (string) - Optional - The access scope for the request (e.g., 'owned'). Defaults to 'owned'.

### Response
#### Success Response (200)
- **training_run_id** (string) - The ID of the training run.
- **base_model** (string) - The base model used for the training run.

### Request Example
```python
future = rest_client.get_training_run("run-id")
response = future.result()
print(f"Training Run ID: {response.training_run_id}, Base: {response.base_model}")
```
```

--------------------------------

### Get Renderer Factory

Source: https://tinker-docs.thinkingmachines.ai/cookbook/api-reference/renderers

A factory function used to create renderer instances by their registered name.

```APIDOC
## get_renderer()

### Description
Factory function to create renderers by name.

### Function Signature
`get_renderer(name: str, **kwargs) -> Renderer`

### Parameters
* **name** (str) - The name of the renderer to create.
* **kwargs** - Additional keyword arguments to pass to the renderer factory.

### Returns
* Renderer - An instance of the specified renderer.
```

--------------------------------

### Get Recommended Renderer Name

Source: https://tinker-docs.thinkingmachines.ai/cookbook/api-reference/model_info/get_recommended_renderer_name

This function returns the most recommended renderer for a specified HuggingFace model.

```APIDOC
## get_recommended_renderer_name

### Description
Return the most recommended renderer for the model.

### Parameters
#### Path Parameters
- **model_name** (str) - Required - HuggingFace model identifier (e.g. "Qwen/Qwen3-8B").

### Returns
str: The top recommended renderer name for this model.
```