Tinker SDK Types

Quick reference for the core types used throughout the Tinker SDK and cookbook.

Reference

Read docs/api-reference/types.md for the complete type reference.

Core data types

Type hierarchy

Datum
├── model_input: ModelInput (list of chunks)
│   ├── EncodedTextChunk (token IDs)
│   └── ImageChunk (vision inputs)
└── loss_fn_inputs: dict[str, TensorData]
    └── TensorData (numpy/torch wrapper)

ModelInput

from tinker import ModelInput

mi = ModelInput.from_ints([1, 2, 3, 4, 5])  # From token list
tokens = mi.to_ints()                        # Back to list
length = mi.length                           # Token count (property)
mi2 = mi.append(chunk)                       # Append a chunk
mi3 = mi.append_int(42)                      # Append a single token
mi_empty = ModelInput.empty()                # Empty input

TensorData

from tinker import TensorData

td = TensorData.from_numpy(np.array([1.0, 0.0, 1.0]))  # From numpy
td = TensorData.from_torch(torch.tensor([1.0, 0.0]))    # From torch
arr = td.to_numpy()                                       # Back to numpy
tensor = td.to_torch()                                    # Back to torch
lst = td.tolist()                                         # Back to list
# Fields: data (flat list), dtype ("int64"|"float32"), shape (optional)

Datum

from tinker import Datum, ModelInput, TensorData

datum = Datum(
    model_input=ModelInput.from_ints(tokens),
    loss_fn_inputs={"weights": TensorData.from_numpy(weights_array)},
)

Configuration types

SamplingParams

from tinker import SamplingParams

params = SamplingParams(
    max_tokens=256,        # Max generation length
    temperature=1.0,       # Sampling temperature
    top_k=50,              # Top-K sampling (-1 = no limit)
    top_p=0.95,            # Nucleus sampling
    stop=["<|eot_id|>"],   # Stop sequences (strings or token IDs)
    seed=42,               # Reproducible seed
)

AdamParams

from tinker import AdamParams

adam = AdamParams(
    learning_rate=2e-4,
    beta1=0.9,             # Gradient moving average
    beta2=0.95,            # Gradient squared moving average
    eps=1e-12,             # Numerical stability
    weight_decay=0.0,      # Decoupled weight decay
    grad_clip_norm=1.0,    # Global gradient norm clipping (0.0 = disabled)
)

LoraConfig

from tinker import LoraConfig

config = LoraConfig(
    rank=32,               # LoRA rank
    seed=None,             # Initialization seed
    train_mlp=True,        # Train MLP layers
    train_attn=True,       # Train attention layers
    train_unembed=True,    # Train unembedding layer
)

Response types

ForwardBackwardOutput

Returned by forward_backward() and forward():

result = tc.forward_backward(data=batch, loss_fn="cross_entropy")
result.metrics              # dict[str, float] — training metrics (includes loss)
result.loss_fn_outputs      # list[LossFnOutput] — per-sample outputs
result.loss_fn_output_type  # str — loss output class name

SampleResponse / SampledSequence

Returned by sample():

response = sc.sample(prompt=mi, num_samples=4, sampling_params=params)
response.sequences                # list[SampledSequence]
response.prompt_logprobs          # Optional[list[Optional[float]]] — per-prompt-token logprobs
response.topk_prompt_logprobs     # Optional[list[Optional[list[tuple[int, float]]]]] — top-K

for seq in response.sequences:
    seq.tokens       # list[int] — generated token IDs
    seq.logprobs     # Optional[list[float]] — per-token logprobs
    seq.stop_reason  # StopReason: "length" | "stop"

Other response types

• OptimStepResponse — confirms parameter update
• SaveWeightsResponse — path: str (tinker:// path to saved weights)
• LoadWeightsResponse — confirms loaded weights
• GetInfoResponse — model_data: ModelData (model_name, lora_rank, tokenizer_id)
• GetServerCapabilitiesResponse — supported_models: list[SupportedModel]
• WeightsInfoResponse — base_model, lora_rank, is_lora, train_mlp, train_attn, train_unembed

Checkpoint and run types

from tinker import TrainingRun, Checkpoint, CheckpointType, ParsedCheckpointTinkerPath

# TrainingRun — metadata about a training run
run.training_run_id    # str
run.base_model         # str
run.is_lora            # bool
run.lora_rank          # Optional[int]
run.last_checkpoint    # Optional[Checkpoint]
run.user_metadata      # Optional[dict[str, str]]

# Checkpoint — metadata about a saved checkpoint
ckpt.checkpoint_id     # str
ckpt.checkpoint_type   # CheckpointType: "training" | "sampler"
ckpt.tinker_path       # str (tinker:// path)
ckpt.size_bytes        # Optional[int]
ckpt.public            # bool
ckpt.expires_at        # Optional[datetime]

# Parse a tinker:// path
parsed = ParsedCheckpointTinkerPath.from_tinker_path("tinker://run-id/weights/ckpt-id")
parsed.training_run_id  # str
parsed.checkpoint_type  # CheckpointType
parsed.checkpoint_id    # str

Error types

All exceptions inherit from tinker.TinkerError:

• APIError → APIStatusError: BadRequestError (400), AuthenticationError (401), PermissionDeniedError (403), NotFoundError (404), ConflictError (409), UnprocessableEntityError (422), RateLimitError (429), InternalServerError (500+)
• APIConnectionError, APITimeoutError, APIResponseValidationError
• RequestFailedError — async request failure with error category

Cookbook helper functions

Use these instead of manual Datum construction:

• tinker_cookbook.supervised.data.conversation_to_datum(messages, renderer, max_length, train_on_what) — full SL pipeline
• tinker_cookbook.supervised.common.datum_from_model_input_weights(model_input, weights, max_length) — from ModelInput + weights
• renderer.build_supervised_example(messages) — returns (ModelInput, weights)

Common pitfalls

• Use helper functions instead of manual dict construction for Datum
• TensorData wraps arrays — don't pass raw numpy/torch directly to loss_fn_inputs
• ModelInput.from_ints() expects a flat list of integers, not nested lists
• ModelInput.length is a property, not a method
• Handle tinker.RateLimitError in production code with exponential backoff