Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.baseten.co/llms.txt

Use this file to discover all available pages before exploring further.

Most Tinker code runs on Loops with one install change. The forward pass, backward pass, optimizer step, sampling, and all shared types carry over without modification. Three things behave differently: checkpoints come back as paginated presigned URLs rather than a single archive, authentication uses a BASETEN_API_KEY instead of a Thinking Machines key, and cluster routing resolves to your Baseten org rather than a Tinker tenant. This page covers the install first, then a side-by-side compatibility table, then each of the three deltas.

​
Compatibility at a glance

The tinker-loops package provides the tinker namespace so existing imports work unchanged. The table below shows where the two systems align and where they diverge.
AspectTinkerLoops
Importimport tinkerimport tinker (provided by tinker-loops)
ServiceClient constructiontinker.ServiceClient(...)tinker.ServiceClient(training_project_id=...)
Forward / backward / optimizeridenticalidentical
Checkpoint downloadsingle archivepaginated presigned URLs
AuthenticationThinking Machines keyBASETEN_API_KEY
Cluster scopeper Tinker tenantper Baseten org

​
Install tinker-loops

Add baseten-loops (the underlying SDK) and tinker-loops (which provides the tinker namespace) to your project: 
uv add baseten-loops tinker-loops
Once installed, existing code that starts with import tinker works without modification: 
import tinker  # provided by tinker-loops

​
Using with tinker-cookbook

tinker-cookbook depends on the original Thinking Machines tinker package. Without an override, installing tinker-cookbook first pulls in that package, and its files conflict with tinker-loops when tinker-loops is added later. The fix is to declare a uv override in pyproject.toml before installing any dependencies. There is no CLI command for this step. Add the override first: 
[tool.uv]
override-dependencies = [
    "tinker ; python_version < '0'",
]
Then add the dependencies: 
uv init
uv add tinker-cookbook
uv add baseten-loops tinker-loops
The tinker namespace will be provided by tinker-loops instead of the original package.

​
What’s the same

The training loop API is identical between the two systems. forward, backward, optim_step, save_weights, and the sampling interface share the same method names and argument shapes. The shared types (Datum, ModelInput, TensorData, SamplingParams, and AdamParams) are all available under tinker.types with the same field names and semantics. The cookbook recipes in the compatibility examples directory are the proof: they run on Loops without changes to any training logic.

​
What’s different

​
Checkpoints come back as folders

Tinker returns a single archive URL for a checkpoint. Loops returns a folder of files behind paginated presigned URLs, because weight sync writes an unzipped folder rather than a compressed archive. Consumer code paginates using ?page_token= and ?page_size= query parameters instead of downloading a single file. See the Loops API overview for the checkpoint files route.

​
Authentication is a Baseten API key

Set BASETEN_API_KEY in your environment and pass it when constructing ServiceClient. Most routes use the org-level scope (manage_org_training_projects); the session search route uses the per-user scope (manage_own_user_or_service_account). The Thinking Machines key used by Tinker is not accepted. See API keys for how to generate one.

​
Cluster routing is per-org

Loops sessions resolve to the caller’s Baseten org and the cluster configured for that org. Tinker uses per-tenant scoping, where the tenant determines the cluster. In practice this means you don’t choose a cluster when creating a session. Your org’s configuration determines it automatically. Loops must be enabled for your organization before sessions will start. Contact support to request access.

​
Running tinker-cookbook recipes on Loops

The cookbook recipes contain self-contained examples covering supervised fine-tuning, reinforcement learning from human feedback, distillation, and sampling. They run on Loops without modification to training logic. Running a recipe end to end is the fastest way to confirm that your environment is configured correctly and that tinker-loops is resolving the right namespace.