Sync contents

docs/api/types.md

@@ -0,0 +1,911 @@
+# `tinker.types.optim_step_request`
+
+## `AdamParams` Objects
+
+```python
+class AdamParams(StrictBase)
+```
+
+#### `learning_rate`
+
+Learning rate for the optimizer
+
+#### `beta1`
+
+Coefficient used for computing running averages of gradient
+
+#### `beta2`
+
+Coefficient used for computing running averages of gradient square
+
+#### `eps`
+
+Term added to the denominator to improve numerical stability
+
+# `tinker.types.optim_step_response`
+
+## `OptimStepResponse` Objects
+
+```python
+class OptimStepResponse(BaseModel)
+```
+
+#### `metrics`
+
+Optimization step metrics as key-value pairs
+
+# `tinker.types.model_input`
+
+## `ModelInput` Objects
+
+```python
+class ModelInput(StrictBase)
+```
+
+#### `chunks`
+
+Sequence of input chunks (formerly TokenSequence)
+
+#### `from_ints`
+
+```python
+@classmethod
+def from_ints(cls, tokens: List[int]) -> "ModelInput"
+```
+
+Create a ModelInput from a list of ints (tokens).
+
+#### `to_ints`
+
+```python
+def to_ints() -> List[int]
+```
+
+Convert the ModelInput to a list of ints (tokens)
+Throws exception if there are any non-token chunks
+
+#### `length`
+
+```python
+@property
+def length() -> int
+```
+
+Return the total context length used by this ModelInput.
+
+#### `empty`
+
+```python
+@classmethod
+def empty(cls) -> "ModelInput"
+```
+
+Create an empty ModelInput.
+
+#### `append`
+
+```python
+def append(chunk: ModelInputChunk) -> "ModelInput"
+```
+
+Add a new chunk, return a new ModelInput.
+
+#### `append_int`
+
+```python
+def append_int(token: int) -> "ModelInput"
+```
+
+Add a new token, return a new ModelInput.
+
+# `tinker.types.weights_info_response`
+
+## `WeightsInfoResponse` Objects
+
+```python
+class WeightsInfoResponse(BaseModel)
+```
+
+Minimal information for loading public checkpoints.
+
+# `tinker.types.checkpoint`
+
+## `Checkpoint` Objects
+
+```python
+class Checkpoint(BaseModel)
+```
+
+#### `checkpoint_id`
+
+The checkpoint ID
+
+#### `checkpoint_type`
+
+The type of checkpoint (training or sampler)
+
+#### `time`
+
+The time when the checkpoint was created
+
+#### `tinker_path`
+
+The tinker path to the checkpoint
+
+#### `size_bytes`
+
+The size of the checkpoint in bytes
+
+#### `public`
+
+Whether the checkpoint is publicly accessible
+
+## `ParsedCheckpointTinkerPath` Objects
+
+```python
+class ParsedCheckpointTinkerPath(BaseModel)
+```
+
+#### `tinker_path`
+
+The tinker path to the checkpoint
+
+#### `training_run_id`
+
+The training run ID
+
+#### `checkpoint_type`
+
+The type of checkpoint (training or sampler)
+
+#### `checkpoint_id`
+
+The checkpoint ID
+
+#### `from_tinker_path`
+
+```python
+@classmethod
+def from_tinker_path(cls, tinker_path: str) -> "ParsedCheckpointTinkerPath"
+```
+
+Parse a tinker path to an instance of ParsedCheckpointTinkerPath
+
+# `tinker.types.checkpoint_archive_url_response`
+
+## `CheckpointArchiveUrlResponse` Objects
+
+```python
+class CheckpointArchiveUrlResponse(BaseModel)
+```
+
+#### `url`
+
+Signed URL to download the checkpoint archive
+
+#### `expires`
+
+Unix timestamp when the signed URL expires, if available
+
+# `tinker.types.sampled_sequence`
+
+## `SampledSequence` Objects
+
+```python
+class SampledSequence(BaseModel)
+```
+
+#### `stop_reason`
+
+Reason why sampling stopped
+
+#### `tokens`
+
+List of generated token IDs
+
+#### `logprobs`
+
+Log probabilities for each token (optional)
+
+# `tinker.types.try_again_response`
+
+## `TryAgainResponse` Objects
+
+```python
+class TryAgainResponse(BaseModel)
+```
+
+#### `request_id`
+
+Request ID that is still pending
+
+# `tinker.types.load_weights_request`
+
+## `LoadWeightsRequest` Objects
+
+```python
+class LoadWeightsRequest(StrictBase)
+```
+
+#### `path`
+
+A tinker URI for model weights at a specific step
+
+#### `optimizer`
+
+Whether to load optimizer state along with model weights
+
+# `tinker.types.telemetry_send_request`
+
+## `TelemetrySendRequest` Objects
+
+```python
+class TelemetrySendRequest(StrictBase)
+```
+
+#### `platform`
+
+Host platform name
+
+#### `sdk_version`
+
+SDK version string
+
+# `tinker.types.image_asset_pointer_chunk`
+
+## `ImageAssetPointerChunk` Objects
+
+```python
+class ImageAssetPointerChunk(StrictBase)
+```
+
+#### `format`
+
+Image format
+
+#### `height`
+
+Image height in pixels
+
+#### `location`
+
+Path or URL to the image asset
+
+#### `tokens`
+
+Number of tokens this image represents
+
+#### `width`
+
+Image width in pixels
+
+# `tinker.types.checkpoints_list_response`
+
+## `CheckpointsListResponse` Objects
+
+```python
+class CheckpointsListResponse(BaseModel)
+```
+
+#### `checkpoints`
+
+List of available model checkpoints for the model
+
+#### `cursor`
+
+Pagination cursor information (None for unpaginated responses)
+
+# `tinker.types.generic_event`
+
+## `GenericEvent` Objects
+
+```python
+class GenericEvent(BaseModel)
+```
+
+#### `event`
+
+Telemetry event type
+
+#### `event_name`
+
+Low-cardinality event name
+
+#### `severity`
+
+Log severity level
+
+#### `event_data`
+
+Arbitrary structured JSON payload
+
+# `tinker.types.encoded_text_chunk`
+
+## `EncodedTextChunk` Objects
+
+```python
+class EncodedTextChunk(StrictBase)
+```
+
+#### `tokens`
+
+Array of token IDs
+
+# `tinker.types.forward_backward_input`
+
+## `ForwardBackwardInput` Objects
+
+```python
+class ForwardBackwardInput(StrictBase)
+```
+
+#### `data`
+
+Array of input data for the forward/backward pass
+
+#### `loss_fn`
+
+Fully qualified function path for the loss function
+
+#### `loss_fn_config`
+
+Optional configuration parameters for the loss function (e.g., PPO clip thresholds, DPO beta)
+
+# `tinker.types.session_start_event`
+
+## `SessionStartEvent` Objects
+
+```python
+class SessionStartEvent(BaseModel)
+```
+
+#### `event`
+
+Telemetry event type
+
+#### `severity`
+
+Log severity level
+
+# `tinker.types.training_runs_response`
+
+## `TrainingRunsResponse` Objects
+
+```python
+class TrainingRunsResponse(BaseModel)
+```
+
+#### `training_runs`
+
+List of training runs
+
+#### `cursor`
+
+Pagination cursor information
+
+# `tinker.types.save_weights_response`
+
+## `SaveWeightsResponse` Objects
+
+```python
+class SaveWeightsResponse(BaseModel)
+```
+
+#### `path`
+
+A tinker URI for model weights at a specific step
+
+# `tinker.types.sample_request`
+
+## `SampleRequest` Objects
+
+```python
+class SampleRequest(StrictBase)
+```
+
+#### `num_samples`
+
+Number of samples to generate
+
+#### `base_model`
+
+Optional base model name to sample from.
+
+Is inferred from model_path, if provided. If sampling against a base model, this
+is required.
+
+#### `model_path`
+
+Optional tinker:// path to your model weights or LoRA weights.
+
+If not provided, samples against the base model.
+
+#### `sampling_session_id`
+
+Optional sampling session ID to use instead of model_path/base_model.
+
+If provided along with seq_id, the model configuration will be loaded from the
+sampling session. This is useful for multi-turn conversations.
+
+#### `seq_id`
+
+Sequence ID within the sampling session.
+
+Required when sampling_session_id is provided. Used to generate deterministic
+request IDs for the sampling request.
+
+#### `prompt_logprobs`
+
+If set to `true`, computes and returns logprobs on the prompt tokens.
+
+Defaults to false.
+
+#### `topk_prompt_logprobs`
+
+If set to a positive integer, returns the top-k logprobs for each prompt token.
+
+# `tinker.types.forward_backward_output`
+
+## `ForwardBackwardOutput` Objects
+
+```python
+class ForwardBackwardOutput(BaseModel)
+```
+
+#### `loss_fn_output_type`
+
+The type of the ForwardBackward output. Can be one of [...] TODO
+
+#### `loss_fn_outputs`
+
+Dictionary mapping field names to tensor data
+
+#### `metrics`
+
+Training metrics as key-value pairs
+
+# `tinker.types.sample_response`
+
+## `SampleResponse` Objects
+
+```python
+class SampleResponse(BaseModel)
+```
+
+#### `prompt_logprobs`
+
+If prompt_logprobs was set to true in the request, logprobs are computed for
+every token in the prompt. The `prompt_logprobs` response contains a float32
+value for every token in the prompt.
+
+#### `topk_prompt_logprobs`
+
+If topk_prompt_logprobs was set to a positive integer k in the request,
+the top-k logprobs are computed for every token in the prompt. The
+`topk_prompt_logprobs` response contains, for every token in the prompt,
+a list of up to k (token_id, logprob) tuples.
+
+# `tinker.types.create_sampling_session_response`
+
+## `CreateSamplingSessionResponse` Objects
+
+```python
+class CreateSamplingSessionResponse(BaseModel)
+```
+
+#### `sampling_session_id`
+
+The generated sampling session ID
+
+# `tinker.types.cursor`
+
+## `Cursor` Objects
+
+```python
+class Cursor(BaseModel)
+```
+
+#### `offset`
+
+The offset used for pagination
+
+#### `limit`
+
+The maximum number of items requested
+
+#### `total_count`
+
+The total number of items available
+
+# `tinker.types.create_model_request`
+
+## `CreateModelRequest` Objects
+
+```python
+class CreateModelRequest(StrictBase)
+```
+
+#### `base_model`
+
+Optional metadata about this model/training run, set by the end-user
+
+# `tinker.types.datum`
+
+## `Datum` Objects
+
+```python
+class Datum(StrictBase)
+```
+
+#### `loss_fn_inputs`
+
+Dictionary mapping field names to tensor data
+
+#### `convert_tensors`
+
+```python
+@model_validator(mode="before")
+@classmethod
+def convert_tensors(cls, data: Any) -> Any
+```
+
+Convert torch.Tensor and numpy arrays to TensorData in loss_fn_inputs during construction.
+
+# `tinker.types.training_run`
+
+## `TrainingRun` Objects
+
+```python
+class TrainingRun(BaseModel)
+```
+
+#### `training_run_id`
+
+The unique identifier for the training run
+
+#### `base_model`
+
+The base model name this model is derived from
+
+#### `model_owner`
+
+The owner/creator of this model
+
+#### `is_lora`
+
+Whether this model uses LoRA (Low-Rank Adaptation)
+
+#### `corrupted`
+
+Whether the model is in a corrupted state
+
+#### `lora_rank`
+
+The LoRA rank if this is a LoRA model, null otherwise
+
+#### `last_request_time`
+
+The timestamp of the last request made to this model
+
+#### `last_checkpoint`
+
+The most recent training checkpoint, if available
+
+#### `last_sampler_checkpoint`
+
+The most recent sampler checkpoint, if available
+
+#### `user_metadata`
+
+Optional metadata about this training run, set by the end-user
+
+# `tinker.types.session_end_event`
+
+## `SessionEndEvent` Objects
+
+```python
+class SessionEndEvent(BaseModel)
+```
+
+#### `duration`
+
+ISO 8601 duration string
+
+#### `event`
+
+Telemetry event type
+
+#### `severity`
+
+Log severity level
+
+# `tinker.types.telemetry_batch`
+
+## `TelemetryBatch` Objects
+
+```python
+class TelemetryBatch(BaseModel)
+```
+
+#### `platform`
+
+Host platform name
+
+#### `sdk_version`
+
+SDK version string
+
+# `tinker.types.unhandled_exception_event`
+
+## `UnhandledExceptionEvent` Objects
+
+```python
+class UnhandledExceptionEvent(BaseModel)
+```
+
+#### `event`
+
+Telemetry event type
+
+#### `severity`
+
+Log severity level
+
+#### `traceback`
+
+Optional Python traceback string
+
+# `tinker.types.image_chunk`
+
+## `ImageChunk` Objects
+
+```python
+class ImageChunk(StrictBase)
+```
+
+#### `data`
+
+Image data as bytes
+
+#### `format`
+
+Image format
+
+#### `height`
+
+Image height in pixels
+
+#### `tokens`
+
+Number of tokens this image represents
+
+#### `width`
+
+Image width in pixels
+
+#### `expected_tokens`
+
+Expected number of tokens this image represents.
+This is only advisory: the tinker backend will compute the number of tokens
+from the image, and we can fail requests quickly if the tokens does not
+match expected_tokens.
+
+#### `validate_data`
+
+```python
+@field_validator("data", mode="before")
+@classmethod
+def validate_data(cls, value: Union[bytes, str]) -> bytes
+```
+
+Deserialize base64 string to bytes if needed.
+
+#### `serialize_data`
+
+```python
+@field_serializer("data")
+def serialize_data(value: bytes) -> str
+```
+
+Serialize bytes to base64 string for JSON.
+
+# `tinker.types.save_weights_request`
+
+## `SaveWeightsRequest` Objects
+
+```python
+class SaveWeightsRequest(StrictBase)
+```
+
+#### `path`
+
+A file/directory name for the weights
+
+# `tinker.types.lora_config`
+
+## `LoraConfig` Objects
+
+```python
+class LoraConfig(StrictBase)
+```
+
+#### `rank`
+
+LoRA rank (dimension of low-rank matrices)
+
+#### `seed`
+
+Seed used for initialization of LoRA weights.
+
+Useful if you need deterministic or reproducible initialization of weights.
+
+#### `train_unembed`
+
+Whether to add lora to the unembedding layer
+
+#### `train_mlp`
+
+Whether to add loras to the MLP layers (including MoE layers)
+
+#### `train_attn`
+
+Whether to add loras to the attention layers
+
+# `tinker.types.create_sampling_session_request`
+
+## `CreateSamplingSessionRequest` Objects
+
+```python
+class CreateSamplingSessionRequest(StrictBase)
+```
+
+#### `session_id`
+
+The session ID to create the sampling session within
+
+#### `sampling_session_seq_id`
+
+Sequence ID for the sampling session within the session
+
+#### `base_model`
+
+Optional base model name to sample from.
+
+Is inferred from model_path, if provided. If sampling against a base model, this
+is required.
+
+#### `model_path`
+
+Optional tinker:// path to your model weights or LoRA weights.
+
+If not provided, samples against the base model.
+
+# `tinker.types.future_retrieve_request`
+
+## `FutureRetrieveRequest` Objects
+
+```python
+class FutureRetrieveRequest(StrictBase)
+```
+
+#### `request_id`
+
+The ID of the request to retrieve
+
+# `tinker.types.tensor_data`
+
+## `TensorData` Objects
+
+```python
+class TensorData(StrictBase)
+```
+
+#### `data`
+
+Flattened tensor data as array of numbers.
+
+#### `shape`
+
+Optional.
+
+The shape of the tensor (see PyTorch tensor.shape). The shape of a
+one-dimensional list of length N is `(N,)`. Can usually be inferred if not
+provided, and is generally inferred as a 1D tensor.
+
+#### `to_numpy`
+
+```python
+def to_numpy() -> npt.NDArray[Any]
+```
+
+Convert TensorData to numpy array.
+
+#### `to_torch`
+
+```python
+def to_torch() -> "torch.Tensor"
+```
+
+Convert TensorData to torch tensor.
+
+# `tinker.types.save_weights_for_sampler_request`
+
+## `SaveWeightsForSamplerRequest` Objects
+
+```python
+class SaveWeightsForSamplerRequest(StrictBase)
+```
+
+#### `path`
+
+A file/directory name for the weights
+
+# `tinker.types.sampling_params`
+
+## `SamplingParams` Objects
+
+```python
+class SamplingParams(BaseModel)
+```
+
+#### `max_tokens`
+
+Maximum number of tokens to generate
+
+#### `seed`
+
+Random seed for reproducible generation
+
+#### `stop`
+
+Stop sequences for generation
+
+#### `temperature`
+
+Sampling temperature
+
+#### `top_k`
+
+Top-k sampling parameter (-1 for no limit)
+
+#### `top_p`
+
+Nucleus sampling probability
+
+# `tinker.types.save_weights_for_sampler_response`
+
+## `SaveWeightsForSamplerResponseInternal` Objects
+
+```python
+class SaveWeightsForSamplerResponseInternal(BaseModel)
+```
+
+#### `path`
+
+A tinker URI for model weights for sampling at a specific step
+
+#### `sampling_session_id`
+
+The generated sampling session ID
+
+## `SaveWeightsForSamplerResponse` Objects
+
+```python
+class SaveWeightsForSamplerResponse(BaseModel)
+```
+
+#### `path`
+
+A tinker URI for model weights for sampling at a specific step
+
+# `tinker.types.load_weights_response`
+
+## `LoadWeightsResponse` Objects
+
+```python
+class LoadWeightsResponse(BaseModel)
+```
+
+#### `path`
+
+A tinker URI for model weights at a specific step