> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adaptive-ml.com/llms.txt
> Use this file to discover all available pages before exploring further.
# SDK Reference
> Python SDK API reference
# Client
## Adaptive (Sync)
```python theme={null}
Adaptive(base_url: str, api_key: str | None = None, default_headers: Optional = None, timeout_secs: float | None = 90.0)
```
Instantiates a new synchronous Adaptive client bounded to a use case.
* **base\_url**: The base URL for the Adaptive API.
* **api\_key**: API key for authentication. Defaults to None, in which case environment variable `ADAPTIVE_API_KEY` needs to be set.
* **timeout\_secs**: Timeout in seconds for HTTP requests. Defaults to 90.0 seconds. Set to None for no timeout.
## AsyncAdaptive (Async)
```python theme={null}
AsyncAdaptive(base_url: str, api_key: str | None = None, default_headers: Optional = None, timeout_secs: float | None = 90.0)
```
Instantiates a new asynchronous Adaptive client bounded to a use case.
* **base\_url**: The base URL for the Adaptive API.
* **api\_key**: API key for authentication. Defaults to None, in which case environment variable `ADAPTIVE_API_KEY` needs to be set.
* **timeout\_secs**: Timeout in seconds for HTTP requests. Defaults to 90.0 seconds. Set to None for no timeout.
***
# Resources
## A/B Tests
*Resource to interact with AB Tests*
Access via `adaptive.ab_tests`
### `cancel`
```python theme={null}
cancel(key: str)
```
Cancel an ongoing AB test.
* **key**: The AB test key.
### `create`
```python theme={null}
create(ab_test_key: str, feedback_key: str, models: List[str], traffic_split: float = 1.0, feedback_type: Literal['metric', 'preference'] = 'metric', auto_deploy: bool = False, use_case: str | None = None)
```
Creates a new A/B test in the client's use case.
* **ab\_test\_key**: A unique key to identify the AB test.
* **feedback\_key**: The feedback key against which the AB test will run.
* **models**: The models to include in the AB test; they must be attached to the use case.
* **traffic\_split**: Percentage of production traffic to route to AB test. `traffic_split*100` % of inference requests for the use case will be sent randomly to one of the models included in the AB test.
* **feedback\_type**: What type of feedback to run the AB test on, metric or preference.
* **auto\_deploy**: If set to `True`, when the AB test is completed, the winning model automatically gets promoted to the use case default model.
### `get`
```python theme={null}
get(key: str)
```
Get the details of an AB test.
* **key**: The AB test key.
### `list`
```python theme={null}
list(active: bool | None = None, status: Literal['warmup', 'in_progress', 'done', 'cancelled'] | None = None, use_case: str | None = None)
```
List the use case AB tests.
* **active**: Filter on active or inactive AB tests.
* **status**: Filter on one of the possible AB test status.
## Chat
Access via `adaptive.chat`
### `create`
```python theme={null}
create(messages: List[input_types.ChatMessage], stream: bool | None = None, model: str | None = None, stop: List[str] | None = None, max_tokens: int | None = None, temperature: float | None = None, top_p: float | None = None, stream_include_usage: bool | None = None, session_id: str | UUID | None = None, use_case: str | None = None, user: str | UUID | None = None, ab_campaign: str | None = None, n: int | None = None, labels: Dict[str, str] | None = None)
```
Create a chat completion.
* **messages**: Input messages, each dict with keys `role` and `content`.
* **stream**: If `True`, partial message deltas will be returned. If stream is over, chunk.choices will be None.
* **model**: Target model key for inference. If `None`, the requests will be routed to the use case's default model.
* **stop**: Sequences or where the API will stop generating further tokens.
* **max\_tokens**: Maximum # of tokens allowed to generate.
* **temperature**: Sampling temperature.
* **top\_p**: Threshold for top-p sampling.
* **stream\_include\_usage**: If set, an additional chunk will be streamed with the token usage statistics for the entire request.
* **user**: ID of user making request. If not `None`, will be logged as metadata for the request.
* **ab\_campaign**: AB test key. If set, request will be guaranteed to count towards AB test results, no matter the configured `traffic_split`.
* **n**: Number of chat completions to generate for each input messages.
* **labels**: Key-value pairs of interaction labels.
## Compute Pools
*Resource to interact with compute pools*
Access via `adaptive.compute_pools`
### `resize_inference_partition`
```python theme={null}
resize_inference_partition(compute_pool_key: str, size: int)
```
Resize the inference partitions of all harmony groups in a compute pool.
## Recipes
*Resource to interact with custom scripts*
Access via `adaptive.recipes`
### `upload`
```python theme={null}
upload(path: str, recipe_key: str, name: str | None = None, description: str | None = None, labels: dict[str, str] | None = None, use_case: str | None = None)
```
Upload a recipe from either a single Python file or a directory (path). If a directory is provided, it must contain a 'main.py' and will be zipped in-memory before upload.
## Datasets
*Resource to interact with file datasets*
Access via `adaptive.datasets`
### `delete`
```python theme={null}
delete(key: str, use_case: str | None = None)
```
Delete dataset.
### `get`
```python theme={null}
get(key: str, use_case: str | None = None)
```
Get details for dataset.
* **key**: Dataset key.
### `list`
```python theme={null}
list(use_case: str | None = None)
```
List previously uploaded datasets.
### `upload`
```python theme={null}
upload(file_path: str, dataset_key: str, name: str | None = None, use_case: str | None = None)
```
Upload a dataset from a file. File must be jsonl, where each line should match supported structure.
* **file\_path**: Path to jsonl file.
* **dataset\_key**: New dataset key.
* **name**: Optional name to render in UI; if `None`, defaults to same as `dataset_key`.
## Embeddings
*Resource to interact with embeddings*
Access via `adaptive.embeddings`
### `create`
```python theme={null}
create(input: str, model: str | None = None, encoding_format: Literal['Float', 'Base64'] = 'Float', use_case: str | None = None, user: str | UUID | None = None)
```
Creates embeddings inference request.
* **input**: Input text to embed.
* **model**: Target model key for inference. If `None`, the requests will be routed to the use case's default model. Request will error if default model is not an embedding model.
* **encoding\_format**: Encoding format of response.
* **user**: ID of user making the requests. If not `None`, will be logged as metadata for the request.
## Graders
*Resource to interact with grader definitions used to evaluate model completions*
Access via `adaptive.graders`
### `delete`
```python theme={null}
delete(grader_key: str, use_case: str | None = None)
```
Delete a grader. Returns True on success.
### `get`
```python theme={null}
get(grader_key: str, use_case: str | None = None)
```
Retrieve a specific grader by ID or key.
### `list`
```python theme={null}
list(use_case: str | None = None)
```
List all graders for the given use case.
### `lock`
```python theme={null}
lock(grader_key: str, locked: bool, use_case: str | None = None)
```
Lock or unlock a grader.
* **grader\_key**: ID or key of the grader.
* **locked**: Whether to lock (True) or unlock (False) the grader.
* **use\_case**: Explicit use-case key. Falls back to client.default\_use\_case.
### `test_external_endpoint`
```python theme={null}
test_external_endpoint(url: str)
```
Test external endpoint to check if it is reachable from Adaptive and returns a valid response.
## Jobs
*Resource to interact with jobs*
Access via `adaptive.jobs`
## Feedback
*Resource to interact with and log feedback*
Access via `adaptive.feedback`
### `get_key`
```python theme={null}
get_key(feedback_key: str)
```
Get the details of a feedback key.
* **feedback\_key**: The feedback key. return self.\_gql\_client.describe\_metric(input=feedback\_key).metric
### `link`
```python theme={null}
link(feedback_key: str, use_case: str | None = None)
```
Link a feedback key to the client's use case. Once a feedback key is linked to a use case, its statistics and associations with interactions will render in the UI.
* **feedback\_key**: The feedback key to be linked.
### `list_keys`
```python theme={null}
list_keys()
```
List all feedback keys.
### `log_metric`
```python theme={null}
log_metric(value: bool | float | int, completion_id: str | UUID, feedback_key: str, user: str | UUID | None = None, details: str | None = None)
```
Log metric feedback for a single completion, which can be a float, int or bool depending on the kind of `feedback_key` it is logged against.
* **value**: The feedback values.
* **completion\_id**: The completion\_id to attach the feedback to.
* **feedback\_key**: The feedback key to log against.
* **user**: ID of user submitting feedback. If not `None`, will be logged as metadata for the request.
* **details**: Textual details for the feedback. Can be used to provide further context on the feedback `value`.
### `log_preference`
```python theme={null}
log_preference(feedback_key: str, preferred_completion: str | UUID | input_types.ComparisonCompletion, other_completion: str | UUID | input_types.ComparisonCompletion, user: str | UUID | None = None, messages: List[Dict[str, str]] | None = None, tied: Literal['good', 'bad'] | None = None, use_case: str | None = None)
```
Log preference feedback between 2 completions.
* **feedback\_key**: The feedback key to log against.
* **preferred\_completion**: Can be a completion\_id or a dict with keys `model` and `text`, corresponding the a valid model key and its attributed completion.
* **other\_completion**: Can be a completion\_id or a dict with keys `model` and `text`, corresponding the a valid model key and its attributed completion.
* **user**: ID of user submitting feedback.
* **messages**: Input chat messages, each dict with keys `role` and `content`. Ignored if `preferred_` and `other_completion` are completion\_ids.
* **tied**: Indicator if both completions tied as equally bad or equally good.
### `register_key`
```python theme={null}
register_key(key: str, kind: Literal['scalar', 'bool'] = 'scalar', scoring_type: Literal['higher_is_better', 'lower_is_better'] = 'higher_is_better', name: str | None = None, description: str | None = None)
```
Register a new feedback key. Feedback can be logged against this key once it is created.
* **key**: Feedback key.
* **kind**: Feedback kind. If `"bool"`, you can log values `0`, `1`, `True` or `False` only. If `"scalar"`, you can log any integer or float value.
* **scoring\_type**: Indication of what good means for this feedback key; a higher numeric value (or `True`) , or a lower numeric value (or `False`). name Human-readable feedback name that will render in the UI. If `None`, will be the same as `key`.
* **description**: Description of intended purpose or nuances of feedback. Will render in the UI.
### `unlink`
```python theme={null}
unlink(feedback_key: str, use_case: str | None = None)
```
Unlink a feedback key from the client's use case.
* **feedback\_key**: The feedback key to be unlinked.
## Interactions
*Resource to interact with interactions*
Access via `adaptive.interactions`
### `create`
```python theme={null}
create(messages: List[input_types.ChatMessage], completion: str, model: str | None = None, feedbacks: List[input_types.InteractionFeedbackDict] | None = None, user: str | UUID | None = None, session_id: str | UUID | None = None, use_case: str | None = None, ab_campaign: str | None = None, labels: Dict[str, str] | None = None, created_at: str | None = None)
```
Create/log an interaction.
* **model**: Model key.
* **messages**: Input chat messages, each dict should have keys `role` and `content`.
* **completion**: Model completion.
* **feedbacks**: List of feedbacks, each dict should with keys `feedback_key`, `value` and optional(`details`).
* **user**: ID of user making the request. If not `None`, will be logged as metadata for the interaction.
* **ab\_campaign**: AB test key. If set, provided `feedbacks` will count towards AB test results.
* **labels**: Key-value pairs of interaction labels.
* **created\_at**: Timestamp of interaction creation or ingestion.
### `get`
```python theme={null}
get(completion_id: str, use_case: str | None = None)
```
Get the details for one specific interaction.
* **completion\_id**: The ID of the completion.
### `list`
```python theme={null}
list(order: List[input_types.Order] | None = None, filters: input_types.ListCompletionsFilterInput | None = None, page: input_types.CursorPageInput | None = None, group_by: Literal['model', 'prompt'] | None = None, use_case: str | None = None)
```
List interactions in client's use case.
* **order**: Ordering of results.
* **filters**: List filters.
* **page**: Paging config.
* **group\_by**: Retrieve interactions grouped by selected dimension.
## Models
*Resource to interact with models*
Access via `adaptive.models`
### `add_external`
```python theme={null}
add_external(name: str, external_model_id: str, api_key: str, provider: Literal['open_ai', 'google', 'azure'], endpoint: str | None = None)
```
Add proprietary external model to Adaptive model registry.
* **name**: Adaptive name for the new model.
* **external\_model\_id**: Should match the model id publicly shared by the model provider.
* **api\_key**: API Key for authentication against external model provider.
* **provider**: External proprietary model provider.
### `add_hf_model`
```python theme={null}
add_hf_model(hf_model_id: SupportedHFModels, output_model_name: str, output_model_key: str, hf_token: str, compute_pool: str | None = None)
```
Add model from the HuggingFace Model hub to Adaptive model registry. It will take several minutes for the model to be downloaded and converted to Adaptive format.
* **hf\_model\_id**: The ID of the selected model repo on HuggingFace Model Hub.
* **output\_model\_key**: The key that will identify the new model in Adaptive.
* **hf\_token**: Your HuggingFace Token, needed to validate access to gated/restricted model.
### `attach`
```python theme={null}
attach(model: str, wait: bool = False, make_default: bool = False, use_case: str | None = None, placement: input_types.ModelPlacementInput | None = None)
```
Attach a model to the client's use case.
* **model**: Model key.
* **wait**: If the model is not deployed already, attaching it to the use case will automatically deploy it. If `True`, this call blocks until model is `Online`.
* **make\_default**: Make the model the use case's default on attachment.
### `deploy`
```python theme={null}
deploy(model: str, wait: bool = False)
```
Deploy a model, loading it to memory and making it ready for inference.
* **model**: Model key.
* **wait**: If `True`, call block until model is in `Online` state.
### `detach`
```python theme={null}
detach(model: str, use_case: str | None = None)
```
Detach model from client's use case.
* **model**: Model key.
### `get`
```python theme={null}
get(model)
```
Get the details for a model.
* **model**: Model key.
### `list`
```python theme={null}
list(filter: input_types.ModelFilter | None = None)
```
List all models in Adaptive model registry.
### `terminate`
```python theme={null}
terminate(model: str, force: bool = False)
```
Terminate model, removing it from memory and making it unavailable to all use cases.
* **model**: Model key.
* **force**: If model is attached to several use cases, `force` must equal `True` in order for the model to be terminated.
### `update`
```python theme={null}
update(model: str, is_default: bool | None = None, attached: bool | None = None, desired_online: bool | None = None, use_case: str | None = None, placement: input_types.ModelPlacementInput | None = None)
```
Update config of model attached to client's use case.
* **model**: Model key.
* **is\_default**: Change the selection of the model as default for the use case. `True` to promote to default, `False` to demote from default. If `None`, no changes are applied.
* **attached**: Whether model should be attached or detached to/from use case. If `None`, no changes are applied.
* **desired\_online**: Turn model inference on or off for the client use case. This does not influence the global status of the model, it is use case-bounded. If `None`, no changes are applied.
### `update_compute_config`
```python theme={null}
update_compute_config(model: str, compute_config: input_types.ModelComputeConfigInput)
```
Update compute config of model.
## Permissions
*Resource to list permissions*
Access via `adaptive.permissions`
## Roles
*Resource to manage roles*
Access via `adaptive.roles`
### `create`
```python theme={null}
create(key: str, permissions: List[str], name: str | None = None)
```
Creates new role.
* **key**: Role key.
* **permissions**: List of permission identifiers such as `use_case:read`. You can list all possible permissions with client.permissions.list().
* **name**: Role name; if not provided, defaults to `key`.
## Teams
*Resource to manage teams*
Access via `adaptive.teams`
## Use Cases
*Resource to interact with use cases*
Access via `adaptive.use_cases`
### `create`
```python theme={null}
create(key: str, name: str | None = None, description: str | None = None, team: str | None = None)
```
Create new use case.
* **key**: Use case key.
* **name**: Human-readable use case name which will be rendered in the UI. If not set, will be the same as `key`.
* **description**: Description of model which will be rendered in the UI.
### `get`
```python theme={null}
get(use_case: str | None = None)
```
Get details for the client's use case.
### `list`
```python theme={null}
list()
```
List all use cases.
### `share`
```python theme={null}
share(use_case: str, team: str, role: str, is_owner: bool = False)
```
Share use case with another team. Requires use\_case:share permissions on the target use case.
* **use\_case**: Use case key.
* **team**: Team key.
* **role**: Role key.
### `unshare`
```python theme={null}
unshare(use_case: str, team: str)
```
Remove use case access for a team. Requires use\_case:share permissions on the target use case.
* **use\_case**: Use case key.
* **team**: Team key.
## Users
*Resource to manage users and permissions*
Access via `adaptive.users`
### `add_to_team`
```python theme={null}
add_to_team(email: str, team: str, role: str)
```
Update team and role for user.
* **email**: User email.
* **team**: Key of team to which user will be added to.
* **role**: Assigned role
### `create`
```python theme={null}
create(email: str, name: str, teams_with_role: Sequence[tuple[str, str]])
```
Create a user and with preset teams and role
### `list`
```python theme={null}
list()
```
List all users registered to Adaptive deployment.
### `me`
```python theme={null}
me()
```
Get details of current user.
### `remove_from_team`
```python theme={null}
remove_from_team(email: str, team: str)
```
Remove user from team.
* **email**: User email.
* **team**: Key of team to remove user from.