# ServiceClient

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

```
# 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#L64) ( _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#L65) ( _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#L66) ( _Any_) – advanced options passed to the underlying HTTP client, including API keys, headers, and connection settings.

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

Query the server's supported features and capabilities.

**Returns:** [`GetServerCapabilitiesResponse`](https://tinker-docs.thinking-machines.ai/tinker/api-reference/types/getservercapabilitiesresponse/) with available models, features, and limits

```
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#L168)( _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#L170) ( _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#L171) ( _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#L172) ( _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#L173) ( _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#L174) ( _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#L175) ( _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#L176) ( _dict[str, str] \| None_, default: `None`) – Optional metadata to attach to the training run

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

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

### [**create_training_client_from_state**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/service_client.py#L255)( _path_, _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#L257) ( _str_) – Tinker path to saved weights (e.g., "tinker://run-id/weights/checkpoint-001")
- [**user_metadata**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/service_client.py#L258) ( _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#L259) ( _str \| None_, default: `None`) – Optional access token for loading checkpoints under a different account.

**Returns:** [`TrainingClient`](https://tinker-docs.thinking-machines.ai/tinker/api-reference/trainingclient/) loaded with the specified weights

```
# 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#L341)( _path_, _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#L343) ( _str_) – Tinker path to saved weights (e.g., "tinker://run-id/weights/checkpoint-001")
- [**user_metadata**](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/public_interfaces/service_client.py#L344) ( _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#L345) ( _str \| None_, default: `None`) – Optional access token for loading checkpoints under a different account.

**Returns:** [`TrainingClient`](https://tinker-docs.thinking-machines.ai/tinker/api-reference/trainingclient/) loaded with the specified weights and optimizer state

```
# 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#L421)( _model_path=None_, _base_model=None_, _retry_config=None_)

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#L423) ( _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#L424) ( _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#L425) ( _[RetryConfig](https://github.com/thinking-machines-lab/tinker/blob/main/src/tinker/lib/retry_handler.py#L39) \| None_, default: `None`) – Optional configuration for retrying failed requests

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

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

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.thinking-machines.ai/tinker/api-reference/restclient/) for accessing REST API endpoints

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