Install & Compatibility
Where this runs
tested against v0.22.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✕ build_error
py 3.9
✕ build_error
✕ build_error
313MB installed
● package 313MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ServiceClient
✓ from tinker import ServiceClient
✗ import tinker
client = tinker.ServiceClient()
This quickstart demonstrates how to initialize the Tinker SDK, set up a service client, and create a LoRA training client. It also includes a basic asynchronous example for initiating an optimizer step, highlighting the typical pattern for interacting with the Tinker API. A Tinker API key must be set as an environment variable (TINKER_API_KEY).
import os
import tinker
from tinker import types
os.environ['TINKER_API_KEY'] = os.environ.get('TINKER_API_KEY', 'your_tinker_api_key_here')
# Initialize the Tinker ServiceClient
service_client = tinker.ServiceClient()
# Create a LoRA training client (example for fine-tuning)
training_client = service_client.create_lora_training_client(
base_model="meta-llama/Llama-3.2-1B",
rank=32,
)
# Example of an asynchronous operation (replace with actual data and loss_fn)
async def run_optim_step():
# In a real scenario, you would have actual data and define a loss function
# For this quickstart, we'll simulate a minimal Datum and OptimStepRequest
dummy_model_input = types.ModelInput(
text="This is a dummy prompt.",
tokens=[1, 2, 3]
)
dummy_loss_fn_inputs = {"labels": types.TensorData(data_float=[1.0, 2.0])}
datum = types.Datum(model_input=dummy_model_input, loss_fn_inputs=dummy_loss_fn_inputs)
optim_request = types.OptimStepRequest(
datums=[datum],
# Other required fields like loss_fn, optim_params, etc. would go here
# This is a simplified example; refer to full docs for actual usage
loss_fn=types.LossFunction.CROSS_ENTROPY,
optim_params=types.AdamParams(learning_rate=1e-5)
)
optim_future = await training_client.optim_step_async(optim_request)
# await optim_future.get_result_async()
print("Optim step initiated.")
import asyncio
asyncio.run(run_optim_step())
Debug
Known issues
breakingThe `RenderedMessage` fields `prefix`, `content`, and `suffix` were renamed to `header`, `output`, and `stop_overlap` respectively. The `Renderer` interface also changed from `Protocol` to `ABC`.fixUpdate your code to use the new field names (`header`, `output`, `stop_overlap`) when working with `RenderedMessage` objects. Adapt `Renderer` implementations to inherit from `ABC`.
affects: 0.x.x (exact version for breaking change not specified, but occurred in tinker-cookbook changelog prior to current)
gotchaMaking sequential API calls instead of utilizing asynchronous patterns is a major performance bottleneck, especially for operations like `sample` or `optim_step`.fixAlways use the `_async` variants of API calls and use `asyncio.gather` for concurrent requests. For example, use `sampling_client.sample_async()` instead of `sampling_client.sample()` in loops.
affects: All versions
gotchaA sampling client created before saving new weights will silently sample from old, stale weights, leading to unexpected model behavior.fixAlways create a new sampling client after saving model weights (`training_client.save_weights_and_get_sampling_client()`) to ensure it reflects the latest model state.
affects: All versions
gotchaLoRA fine-tuning typically requires a significantly higher learning rate compared to full fine-tuning, often around 10x higher.fixWhen using LoRA, consult `hyperparam_utils.get_lr(model_name)` or experiment with learning rates approximately 10 times higher than you would for full fine-tuning.
affects: All versions
Upgrade
Version history
0.22.3latest on PyPI · released May 31, 2026
Audit
Dependencies
torchoptionalRequired for training functionalities, but is an optional dependency.