# ServiceClient

## *class* [**tinker.ServiceClient**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/service_client.py#L34)(*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

```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()
```

**Parameters:**

- [**user_metadata**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/service_client.py#L66) (*dict[str, str] | None*, default: `None`) – Optional metadata attached to the created session.
- [**project_id**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/service_client.py#L67) (*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/main/src/tinker/lib/public_interfaces/service_client.py#L68) (*Any*) – advanced options passed to the underlying HTTP client, including API keys, headers, and connection settings.

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

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/main/src/tinker/lib/internal_client_holder.py#L175)*

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

Return the Tinker Console URL for this session.

**Returns:** *str*

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

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

```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/main/src/tinker/lib/public_interfaces/service_client.py#L232)(*base_model*, *rank=32*, *seed=None*, *train_mlp=True*, *train_attn=True*, *train_unembed=True*, *user_metadata=None*)

Create a TrainingClient for LoRA fine-tuning.

**Parameters:**

- [**base_model**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/service_client.py#L234) (*str*) – Name of the base model to fine-tune (e.g., "Qwen/Qwen3-8B")
- [**rank**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/service_client.py#L235) (*int*, default: `32`) – LoRA rank controlling the size of adaptation matrices (default 32)
- [**seed**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/service_client.py#L236) (*int | None*, default: `None`) – Random seed for initialization. None means random seed.
- [**train_mlp**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/service_client.py#L237) (*bool*, default: `True`) – Whether to train MLP layers (default True)
- [**train_attn**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/service_client.py#L238) (*bool*, default: `True`) – Whether to train attention layers (default True)
- [**train_unembed**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/service_client.py#L239) (*bool*, default: `True`) – Whether to train unembedding layers (default True)
- [**user_metadata**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/service_client.py#L240) (*dict[str, str] | None*, default: `None`) – Optional metadata to attach to the training run

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

```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/main/src/tinker/lib/public_interfaces/service_client.py#L395)(*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/main/src/tinker/lib/public_interfaces/service_client.py#L397) (*str*) – Tinker path of the weights to copy
- [**ttl_seconds**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/service_client.py#L399) (*int | None*, default: `None`) – Seconds until the copy expires, or None for no expiry
- [**weights_access_token**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/service_client.py#L400) (*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()`.

```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/main/src/tinker/lib/public_interfaces/service_client.py#L427)(*path*, *base_model=None*, *user_metadata=None*, *weights_access_token=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/main/src/tinker/lib/public_interfaces/service_client.py#L429) (*str*) – Tinker path to saved weights (e.g., "tinker://run-id/weights/checkpoint-001")
- [**base_model**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/service_client.py#L430) (*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/main/src/tinker/lib/public_interfaces/service_client.py#L431) (*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/main/src/tinker/lib/public_interfaces/service_client.py#L432) (*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

```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/main/src/tinker/lib/public_interfaces/service_client.py#L535)(*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/main/src/tinker/lib/public_interfaces/service_client.py#L537) (*str*) – Tinker path to saved weights (e.g., "tinker://run-id/weights/checkpoint-001")
- [**base_model**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/service_client.py#L538) (*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/main/src/tinker/lib/public_interfaces/service_client.py#L539) (*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/main/src/tinker/lib/public_interfaces/service_client.py#L540) (*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

```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/main/src/tinker/lib/public_interfaces/service_client.py#L637)(*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/main/src/tinker/lib/public_interfaces/service_client.py#L639) (*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/main/src/tinker/lib/public_interfaces/service_client.py#L640) (*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/main/src/tinker/lib/public_interfaces/service_client.py#L641) (*[RetryConfig](https://github.com/thinking-machines-lab/tinker/blob/main/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/main/src/tinker/lib/public_interfaces/service_client.py#L642) (*bool*, default: `False`)

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

```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/main/src/tinker/lib/public_interfaces/service_client.py#L702)()

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

```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()
```