# ServiceClient

*Generated from tinker 0.30.4 at commit [`1e5777e`](https://github.com/thinking-machines-lab/tinker/tree/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d). Source links point at that snapshot.*

## *class* [**tinker.ServiceClient**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L37)(*user_metadata=None*, *project_id=None*, \*\**kwargs*)

The ServiceClient is the main entry point for the Tinker API. It provides methods to:

- Query server capabilities and health status
- Generate TrainingClient instances for model training workflows
- Generate SamplingClient instances for text generation and inference
- Generate RestClient instances for REST API operations like listing weights
- Close the client by finishing the current session when the training script is done

**Parameters:**

- [**user_metadata**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L70) (*dict[str, str] | None*, default: `None`) – Optional metadata attached to the created session.
- [**project_id**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L71) (*str | None*, default: `None`) – Optional project ID to attach to the created session. If not provided, falls back to the `TINKER_PROJECT_ID` environment variable.
- [**\*\*kwargs**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L72) (*Any*) – advanced options passed to the underlying HTTP client, including API keys, headers, and connection settings.

**Example:**

```python
# Near instant
client = ServiceClient()

# Takes a moment as we initialize the model and assign resources
training_client = client.create_lora_training_client(base_model="Qwen/Qwen3-8B")

# Near-instant
sampling_client = client.create_sampling_client(base_model="Qwen/Qwen3-8B")

# Near-instant
rest_client = client.create_rest_client()
```

### *property* [**holder**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L154)

The sessionful holder. Deprecated: kept for backwards compatibility with callers that reach into ServiceClient internals.

**Returns:** *[InternalClientHolder](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/internal_client_holder.py#L189)*

### [**get_console_url**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L159)()

Return the Tinker Console URL for this session.

**Returns:** *str*

### [**get_server_capabilities**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L184)()

Query the server's supported features and capabilities.

**Returns:**

- [`GetServerCapabilitiesResponse`](https://tinker-docs.thinkingmachines.ai/tinker/api-reference/types/getservercapabilitiesresponse/index.md) with available models, features, and limits

**Example:**

```python
capabilities = service_client.get_server_capabilities()
print(f"Supported models: {capabilities.supported_models}")
print(f"Max batch size: {capabilities.max_batch_size}")
```

*Async variant:* `get_server_capabilities_async()`

### [**create_lora_training_client**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L276)(*base_model*, *rank=32*, *seed=None*, *train_mlp=True*, *train_attn=True*, *train_unembed=True*, *user_metadata=None*, *optimizer=None*)

Create a TrainingClient for LoRA fine-tuning.

**Parameters:**

- [**base_model**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L278) (*str*) – Name of the base model to fine-tune (e.g., "Qwen/Qwen3-8B")
- [**rank**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L279) (*int*, default: `32`) – LoRA rank controlling the size of adaptation matrices (default 32)
- [**seed**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L280) (*int | None*, default: `None`) – Random seed for initialization. None means random seed.
- [**train_mlp**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L281) (*bool*, default: `True`) – Whether to train MLP layers (default True)
- [**train_attn**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L282) (*bool*, default: `True`) – Whether to train attention layers (default True)
- [**train_unembed**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L283) (*bool*, default: `True`) – Whether to train unembedding layers (default True)
- [**user_metadata**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L284) (*dict[str, str] | None*, default: `None`) – Optional metadata to attach to the training run
- [**optimizer**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L285) (*types.[OptimizerConfig](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/types/optimizer.py#L26) | None*, default: `None`) – Fixed optimizer configuration. Defaults to AdamW.

**Returns:**

- [`TrainingClient`](https://tinker-docs.thinkingmachines.ai/tinker/api-reference/trainingclient/index.md) configured for LoRA training

**Example:**

```python
training_client = service_client.create_lora_training_client(
    base_model="Qwen/Qwen3-8B",
    rank=16,
    train_mlp=True,
    train_attn=True
)
# Now use training_client.forward_backward() to train
```

*Async variant:* `create_lora_training_client_async()`

### [**copy_weights**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L446)(*path*, *ttl_seconds=None*, *weights_access_token=None*)

Copy weights into this client's project.

Storage is shared with the source, so no bytes are duplicated. Either kind of weights can be copied, and the copy keeps that kind. A new training run is created to hold it, which cannot be trained on.

**Parameters:**

- [**path**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L448) (*str*) – Tinker path of the weights to copy
- [**ttl_seconds**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L450) (*int | None*, default: `None`) – Seconds until the copy expires, between 1 hour (3600) and 10 years, or None for no expiry
- [**weights_access_token**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L451) (*str | None*, default: `None`) – Optional access token for copying weights readable under a different account

**Returns:**

- A future for the tinker path of the copy. Await it, or call `.result()`.

**Example:**

```python
# The copy lands in this client's project.
archive = tinker.ServiceClient(project_id="proj-archive")
archived_path = archive.copy_weights("tinker://run-id/weights/step-400").result()
```

### [**create_training_client_from_state**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L479)(*path*, *base_model=None*, *user_metadata=None*, *weights_access_token=None*, *optimizer=None*)

Create a TrainingClient from saved model weights.

This loads only the model weights, not optimizer state. To also restore optimizer state (e.g., Adam momentum), use create_training_client_from_state_with_optimizer.

**Parameters:**

- [**path**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L481) (*str*) – Tinker path to saved weights (e.g., "tinker://run-id/weights/checkpoint-001")
- [**base_model**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L482) (*str | None*, default: `None`) – Optional override of the checkpoint's base model; must be compatible with it (e.g. a different context length)
- [**user_metadata**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L483) (*dict[str, str] | None*, default: `None`) – Optional metadata to attach to the new training run
- [**weights_access_token**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L484) (*str | None*, default: `None`) – Optional access token for loading checkpoints under a different account.
- [**optimizer**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L485) (*types.[OptimizerConfig](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/types/optimizer.py#L26) | None*, default: `None`) – Optimizer for the new training run; defaults to Adam.

**Returns:**

- [`TrainingClient`](https://tinker-docs.thinkingmachines.ai/tinker/api-reference/trainingclient/index.md) loaded with the specified weights

**Example:**

```python
# Resume training from a checkpoint (weights only, optimizer resets)
training_client = service_client.create_training_client_from_state(
    "tinker://run-id/weights/checkpoint-001"
)
# Continue training from the loaded state
```

*Async variant:* `create_training_client_from_state_async()`

### [**create_training_client_from_state_with_optimizer**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L594)(*path*, *base_model=None*, *user_metadata=None*, *weights_access_token=None*)

Create a TrainingClient from saved model weights and optimizer state.

This is similar to create_training_client_from_state but also restores optimizer state (e.g., Adam momentum), which is useful for resuming training exactly where it left off.

**Parameters:**

- [**path**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L596) (*str*) – Tinker path to saved weights (e.g., "tinker://run-id/weights/checkpoint-001")
- [**base_model**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L597) (*str | None*, default: `None`) – Optional override of the checkpoint's base model; must be compatible with it (e.g. a different context length)
- [**user_metadata**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L598) (*dict[str, str] | None*, default: `None`) – Optional metadata to attach to the new training run
- [**weights_access_token**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L599) (*str | None*, default: `None`) – Optional access token for loading checkpoints under a different account.

**Returns:**

- [`TrainingClient`](https://tinker-docs.thinkingmachines.ai/tinker/api-reference/trainingclient/index.md) loaded with the specified weights and optimizer state

**Example:**

```python
# Resume training from a checkpoint with optimizer state
training_client = service_client.create_training_client_from_state_with_optimizer(
    "tinker://run-id/weights/checkpoint-001"
)
# Continue training with restored optimizer momentum
```

*Async variant:* `create_training_client_from_state_with_optimizer_async()`

### [**create_sampling_client**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L700)(*model_path=None*, *base_model=None*, *retry_config=None*, *record_stability_info=False*)

Create a SamplingClient for text generation.

**Parameters:**

- [**model_path**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L702) (*str | None*, default: `None`) – Path to saved model weights (e.g., "tinker://run-id/weights/checkpoint-001")
- [**base_model**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L703) (*str | None*, default: `None`) – Name of base model to use (e.g., "Qwen/Qwen3-8B")
- [**retry_config**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L704) (*[RetryConfig](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/retry_handler.py#L40) | None*, default: `None`) – Optional configuration for retrying failed requests
- [**record_stability_info**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L705) (*bool*, default: `False`)

**Returns:**

- [`SamplingClient`](https://tinker-docs.thinkingmachines.ai/tinker/api-reference/samplingclient/index.md) configured for text generation

**Raises:**

ValueError: If neither model_path nor base_model is provided

**Example:**

```python
# Use a base model
sampling_client = service_client.create_sampling_client(
    base_model="Qwen/Qwen3-8B"
)

# Or use saved weights
sampling_client = service_client.create_sampling_client(
    model_path="tinker://run-id/weights/checkpoint-001"
)
```

*Async variant:* `create_sampling_client_async()`

### [**create_rest_client**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L765)()

Create a RestClient for REST API operations.

The RestClient provides access to various REST endpoints for querying model information, checkpoints, sessions, and managing checkpoint visibility.

**Returns:**

- [`RestClient`](https://tinker-docs.thinkingmachines.ai/tinker/api-reference/restclient/index.md) for accessing REST API endpoints

**Example:**

```python
rest_client = service_client.create_rest_client()

# List checkpoints for a training run
checkpoints = rest_client.list_checkpoints("run-id").result()

# Get training run info
training_run = rest_client.get_training_run("run-id").result()

# Publish a checkpoint
rest_client.publish_checkpoint_from_tinker_path(
    "tinker://run-id/weights/checkpoint-001"
).result()
```

### [**close**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L839)(*status*, *detail=None*)

Finish the session and release local client resources.

Marks the session terminal. Further operations against it will be rejected. A finish reason is first-wins and cannot replace an existing one.

Also stops session heartbeats and releases HTTP/telemetry resources.

**Parameters:**

- [**status**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L841) (*Literal['success', 'errored', 'interrupted']*) – `"success"`, `"errored"`, or `"interrupted"`
- [**detail**](https://github.com/thinking-machines-lab/tinker/blob/1e5777ef1e0bb2bae6d9b8d63a6144eec405377d/src/tinker/lib/public_interfaces/service_client.py#L842) (*str | None*, default: `None`) – Optional human-readable explanation

**Returns:**

- A future that completes when the session is finished. Await it, or call `.result()`.

**Example:**

```python
service_client.close("success", detail="training complete").result()
```