> ## Documentation Index
> Fetch the complete documentation index at: https://docs.together.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate from Tinker

> Run a Tinker training script on Together AI post-training by changing its import line.

The Together Python SDK includes a [Tinker](https://tinker-docs.thinkingmachines.ai/)-compatible client, so a training loop written against the `tinker` SDK runs on post-training after you change its import line and, if needed, its base model. The client replaces only the service calls, so your rendering, tokenization, and grading code runs unchanged, including the `tinker_cookbook` helpers it imports.

## Requirements

* Python 3.11 or later.
* The Together Python SDK 3.3.0 or later, with the `tinker` extra. The extra installs `tinker` 0.39.0, the version the client builds on, so it replaces any other `tinker` version you already have installed.
* The `tinker-cookbook` package, if your script imports `tinker_cookbook`.
* `TOGETHER_API_KEY` exported in your shell.
* Enough credit to run your model resource for four hours, the [minimum for creating one](https://docs.together.ai/docs/post-training/pricing.md#minimum-credit-balance).

Install the packages and export your API key:

```bash theme={null}
uv add "together[tinker]>=3.3.0" tinker-cookbook
export TOGETHER_API_KEY=<your_key>
```

## Swap the import

Replace the `tinker` import with the Together client:

```diff theme={null}
-import tinker
+import together.post_training.tinker as tinker
```

`tinker.types` resolves to the real Tinker types, so the prompts and `Datum` objects your code builds pass through unchanged.

Besides the import, the only value you might need to change is the base model. Tinker and Together host different catalogs, so if your script's model isn't one of the [supported models](https://docs.together.ai/docs/post-training/supported-models.md), switch to one that is.

When the script calls `create_lora_training_client`, the client provisions a model resource for the base model, waits until it's ready, and opens a low-rank adapter (LoRA) session on it. [Billing](https://docs.together.ai/docs/post-training/pricing.md) starts when the resource is ready.

The wait takes a few minutes for a small model, and longer when GPU capacity is scarce. The client keeps waiting until the resource is allocated the required GPUs, and if you interrupt it, it stops the queued resource. To set a time limit, create the resource yourself with `ModelResourcesClient.create(..., ready_timeout=3600)`, then [train on it as an existing resource](#train-on-an-existing-resource). `ready_timeout` is in seconds, so if the resource isn't ready within an hour, this call raises `TimeoutError` and stops the resource.

## Run the example scripts

The [post-training cookbook](https://github.com/togethercomputer/post-training-cookbook) has three example scripts in `demos/tinker-migration/`. Each one is adapted from a `tinker_cookbook` recipe, with the import already swapped to the Together client:

* `grpo_gsm8k.py`: A minimal group relative policy optimization (GRPO) loop on GSM8K.
* `grpo_gsm8k_async.py`: The same loop, sampling each batch while the previous one trains.
* `sft_no_robots.py`: A supervised fine-tuning (SFT) loop on No Robots.

From the root of a cookbook checkout, install the Tinker dependencies and run a short smoke test:

```bash theme={null}
uv sync --locked --group tinker
uv run python demos/tinker-migration/grpo_gsm8k.py --batch-size 8 --group-size 4 --max-steps 3
```

Each script also runs on Tinker when you switch the import back, so you can compare training curves across both backends.

> [!NOTE]
>
> The example scripts build their training data in Tinker's format, with `tinker_cookbook` helpers or by hand. When you write a loop on the SDK directly, [build samples](https://docs.together.ai/docs/post-training/samples.md) with every per-token array shifted to the target positions.

## How Tinker calls map to post-training

| Tinker call | On Together |
| - | - |
| `ServiceClient()` | Creates the client without provisioning anything. |
| `create_lora_training_client(base_model, rank)` | Provisions a model resource, waits until it's ready, and opens a LoRA session on it. |
| `create_training_client_from_state(path)` | Provisions a model resource and opens a session from a training checkpoint, loading the weights only. |
| `create_training_client_from_state_with_optimizer(path)` | Provisions a model resource and opens a session from a training checkpoint, restoring the optimizer state too. |
| `forward_backward(data, loss_fn)` | Runs `forward_backward` with the matching [built-in loss function](https://docs.together.ai/docs/post-training/loss-functions.md#built-in-loss-functions). |
| `forward(data, loss_fn)` | Runs a forward-only pass and returns per-datum log-probabilities in `loss_fn_outputs`. |
| `forward_backward_custom(data, loss_fn)` | Reads log-probabilities with `forward`, runs [your loss function](https://docs.together.ai/docs/post-training/custom-loss-functions.md) client-side, and submits the gradients with `custom_forward_backward`. |
| `optim_step(optim_params)` | Runs `optim_step` with Adam. Tinker's legacy `adam_params` argument also works. |
| `save_weights_and_get_sampling_client()` | Publishes the weights with `weights_sync`, then returns a sampling client for them. |
| `sample(...)`, `compute_logprobs(...)` | Run on the session's generator replica. |
| `save_state(name)` | Saves a [training checkpoint](https://docs.together.ai/docs/post-training/checkpoints.md#training-checkpoints) and returns its ID, which `create_training_client_from_state` accepts. |
| `save_weights_for_sampler(name)` | Saves an [inference checkpoint](https://docs.together.ai/docs/post-training/checkpoints.md#inference-checkpoints) and returns its ID, which `download_checkpoint` accepts. |

The client follows Tinker 0.39's two call styles:

* **In synchronous code:** A call returns either a client or an `APIFuture` that you call `.result()` on.
* **Inside a running event loop:** The same calls return an awaitable immediately, so you can `await service_client.create_lora_training_client(...)` or `await sampling_client.sample(...)`. In a notebook, the calls block instead.

A training client sends its requests to the server in the order you call them, so if you call `optim_step` before you await the preceding `forward_backward`, the `optim_step` still runs second.

The deprecated `_async` variants still work.

## Behavior differences

The client differs from Tinker in ways that can affect your results, and some differences need a change to your script.

### Training

* **Some loss functions aren't supported:** The client supports the built-in loss functions `cross_entropy`, `importance_sampling`, `ppo`, `cispo`, and `dro`. Other Tinker loss functions, such as `gspo` and `stable_reinforce`, raise `NotImplementedError`. For a custom loss, pass a callable to `forward_backward_custom`. `create_custom_loss` raises `TinkerError`, and `LossHandle` losses raise `NotImplementedError`.
* **Fractional weights apply to cross-entropy only:** The policy-gradient loss functions accept only `0` and `1` in `weights`. The client warns when it sees fractional values, and the server then fails the operation. To include or exclude tokens, use `mask`.
* **`dro` needs a `beta`:** Pass `loss_fn_config={"beta": ...}`. `beta` has no default.
* **Loss inputs must be one-dimensional:** A two-dimensional `loss_fn_inputs` tensor raises `ValueError`, so loss functions that need several target tokens per position, such as top-K distillation, aren't supported.
* **Text input only:** `model_input` must contain only encoded text chunks. Image chunks raise `ValueError`.
* **Per-datum outputs can be skipped:** As in Tinker, `forward` and `forward_backward` return per-datum log-probabilities in `loss_fn_outputs`. To shrink the response and speed up the step on large batches, pass `return_loss_fn_outputs=False`, an argument Tinker doesn't accept. Either way, the total loss is in `metrics["loss:sum"]`.
* **`forward` returns zeros at unweighted positions:** Positions whose `weights` are `0` come back as `0.0` in `loss_fn_outputs`, not as their log-probabilities. To read every position, pass `weights` of `1` everywhere.
* **Custom loss functions train only weighted positions:** `forward_backward_custom` applies your gradients only at positions whose `weights` are nonzero. A datum with no `weights` gets all zeros, so it trains nothing. Pass `weights` of `1` on every position your loss reads.
* **A failed custom loss stops the training client:** As in Tinker, if `forward_backward_custom` fails, the training client rejects every later training request. Unlike Tinker, the client also does this when the server fails the request. To continue, create a new training client.
* **Adam only:** Passing an `optimizer` other than Adam, or `optim_step` parameters other than `AdamParams`, raises `NotImplementedError`.
* **Module selection is fixed:** `train_mlp` and `train_attn` can't be turned off, so the client warns on non-default values and ignores them. `seed` and `train_unembed` pass through to the session's LoRA config.
* **LoRA rank is limited and alpha is fixed:** The maximum rank is 64 on Qwen models and 32 on every other model. The client never sends `lora_alpha`, so every session uses Together's default of `64`, whatever rank you pass.

### Sampling

* **Sampling clients aren't snapshots:** Together samples from the most recently published weights. Once you call `save_weights_and_get_sampling_client` again, an earlier sampling client raises `RuntimeError` instead of serving the old policy. Create a new sampling client after each publish. To keep a client that samples whatever weights are live, pass `allow_stale=True` or `kind="inflight"` to `save_weights_and_get_sampling_client`.
* **Stop sequences must be strings:** Together's sampler takes stop strings, so the client drops stop sequences given as token IDs and warns. Generation still stops at the model's end-of-sequence token.
* **Some sampling arguments are limited or unsupported:** `topk_prompt_logprobs` above `20` raises `ValueError`. `topk_sample_logprobs`, `target_prompt_logprobs`, `prompt_alt_tokens_k`, and `prompt_logprobs_last_n` raise `NotImplementedError`.

### Checkpoints

* **Checkpoint names are server-assigned:** Training and inference checkpoints get a generated ID, whatever `name` you pass. The client warns on the `ttl_seconds`, `overwrite`, `retry_config`, and `record_stability_info` arguments and ignores them.
* **Checkpoints aren't served by path:** There's no `tinker://` path to pass to an OpenAI-compatible endpoint. To call a trained model, [deploy its inference checkpoint](https://docs.together.ai/docs/post-training/deployment.md) first.

### Client options

* **The project comes from your API key:** `ServiceClient` accepts `project_id` and ignores it, so every call runs in the project that your `TOGETHER_API_KEY` belongs to. The client also ignores `user_metadata`, which `ServiceClient` and the methods that create training clients accept.
* **Transport options are ignored:** `ServiceClient` accepts Tinker's HTTP options and ignores them. It warns on `http_client`, `max_retries`, and `timeout`. Any other unknown argument raises `TypeError`.

### Unsupported calls

Calling a Tinker method the client doesn't define raises an `AttributeError` that names the method as unsupported. These methods include:

* **On `ServiceClient`:** `create_sampling_client`, `get_server_capabilities`, and `get_telemetry`.
* **On training clients:** `get_tokenizer`, `get_info`, `load_state`, `load_state_with_optimizer`, and `save_weights_external`.
* **On sampling clients:** `get_tokenizer` and `get_base_model`.

To get a tokenizer, call `tinker_cookbook.tokenizer_utils.get_tokenizer(base_model)`, as the example scripts do. To sample from a saved checkpoint instead of `create_sampling_client`, see [Sample a saved checkpoint](https://docs.together.ai/docs/post-training/checkpoints.md#sample-a-saved-checkpoint).

`create_rest_client` raises `TinkerError`, and passing `weights_access_token` raises `NotImplementedError`. To catch `TinkerError`, import it with `from tinker import TinkerError`, because `together.post_training.tinker` doesn't re-export it.

## Replace `RestClient` calls

`create_rest_client` isn't available, so call the Together SDK for the run and checkpoint lookups that Tinker's `RestClient` handles:

| Tinker call | On Together |
| - | - |
| `list_training_runs`, `get_training_run` | `client.post_training.sessions.list()`, `client.post_training.sessions.retrieve(session_id)` |
| `list_checkpoints`, `list_user_checkpoints` | `client.post_training.checkpoints.list()`, filtered by `session_id` or `base_model` |
| `get_checkpoint_archive_url` | `download_checkpoint(client, checkpoint_id)` from `together.post_training`, which downloads the files. See [Download the weights](https://docs.together.ai/docs/post-training/checkpoints.md#download-the-weights). |
| `whoami` | `client.whoami()` |
| `get_server_capabilities` | `client.post_training.supported_models.get()` |
| `delete_checkpoint`, `set_checkpoint_ttl_from_tinker_path`, `publish_checkpoint_from_tinker_path` | No equivalent. |

`client` is a `together.Together` client.

## Clean up GPUs

Tinker's training client has no teardown call, so the Together client registers its own cleanup, which stops the session and the model resource the client provisioned. The cleanup runs when the script exits normally, raises an uncaught exception, is interrupted with `Ctrl+C`, or receives `SIGTERM`. Only `SIGKILL` and `os._exit` skip it. If either one ends the script, the resource keeps billing until it [stops on its own](https://docs.together.ai/docs/post-training/limits-and-errors.md#timers) after an hour idle.

In a long-lived process such as a notebook, the cleanup doesn't run until the process exits. To release the GPUs as soon as training ends, call `training_client.close()` or use the training client as a context manager:

```python theme={null}
import together.post_training.tinker as tinker

service_client = tinker.ServiceClient()
with service_client.create_lora_training_client(
    base_model="Qwen/Qwen3.8-27B", rank=32
) as training_client:
    ...  # your training loop
```

To close every training client that a service client created, use the service client as a context manager, or call `service_client.close("success")`. The client accepts the status argument for Tinker compatibility and ignores it.

## Train on an existing resource

To [attach to a model resource](https://docs.together.ai/docs/post-training/model-resources.md#attach-to-an-existing-resource) that's already running, pass its ID to `ServiceClient`:

```python theme={null}
service_client = tinker.ServiceClient(
    model_resources_id="your_model_resources_id"
)
```

The resource must be LoRA-enabled and serve the same base model you pass to `create_lora_training_client`. The client opens its session on that resource. On exit, it stops the session but leaves the resource running.

`model_resources_id` is a Together-only argument, so a script that passes it no longer runs unchanged on Tinker.

## Troubleshooting

* **Creating the training client fails because the base model isn't supported:** The model ID isn't in the post-training catalog. Pick one from [Supported models](https://docs.together.ai/docs/post-training/supported-models.md).
* **Sampling raises `RuntimeError` about a stale sampling client:** The script reused a sampling client after publishing newer weights. Create a new one after each `save_weights_and_get_sampling_client` call, or pass `allow_stale=True`.
* **Reward stays at zero:** If the script's renderer has thinking turned on, completions can use up `max_tokens` on reasoning and never reach the answer. Raise `max_tokens`, or use a renderer with thinking turned off.
* **`ServiceClient` raises `TypeError`:** The script passes an argument the Together client doesn't accept. Remove it.

## Next steps

> [card] [Write a training loop](https://docs.together.ai/docs/post-training/training-loop.md)
>
> Call the session operations behind the Tinker client directly from your own loop.

> [card] [Supported models](https://docs.together.ai/docs/post-training/supported-models.md)
>
> Pick a base model by training mode, context length, and GPU type.

> [card] [Manage checkpoints](https://docs.together.ai/docs/post-training/checkpoints.md)
>
> Download the weights or resume a run from a checkpoint.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.