> ## Documentation Index
> Fetch the complete documentation index at: https://www.adaline.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Adaline

# Adaline

The main client class for interacting with the Adaline platform. Provides methods to fetch deployments, manage cached deployment controllers with background refresh, and initialize monitoring.

## Constructor

```python theme={null}
from adaline.main import Adaline

adaline = Adaline(
    api_key="your-api-key",        # optional, defaults to ADALINE_API_KEY env var
    host="https://api.adaline.ai/v2",  # optional, defaults to ADALINE_BASE_URL env var
    debug=False                     # optional, enables DEBUG logging
)
```

All constructor parameters are keyword-only.

### Parameters

<ParamField body="api_key" type="str | None" optional>
  Your Adaline API key. Defaults to the `ADALINE_API_KEY` environment variable.
</ParamField>

<ParamField body="host" type="str | None" optional>
  The base URL for the Adaline API. Falls back to the `ADALINE_BASE_URL` environment variable, then `https://api.adaline.ai/v2`.
</ParamField>

<ParamField body="debug" type="bool" optional default="False">
  If `True`, enables `DEBUG`-level logging on the `adaline` logger with a `StreamHandler` that outputs `[Adaline] LEVEL: message`.
</ParamField>

## Methods

### get\_deployment

Fetches a specific prompt deployment by prompt ID and deployment ID. This is an async method.

```python theme={null}
deployment = await adaline.get_deployment(
    prompt_id="your-prompt-id",
    deployment_id="your-deployment-id"
)
```

#### Parameters

<ParamField body="prompt_id" type="str" required>
  The unique ID of the prompt.
</ParamField>

<ParamField body="deployment_id" type="str" required>
  The specific deployment ID.
</ParamField>

**Returns:** A [`Deployment`](/docs/reference/sdk/v2/python/types/deployment) object.

**Raises:** `ApiException` if the API call fails (4xx errors fail immediately, 5xx errors are retried).

***

### get\_latest\_deployment

Fetches the latest deployment for a prompt in a specific environment. This is an async method.

```python theme={null}
deployment = await adaline.get_latest_deployment(
    prompt_id="your-prompt-id",
    deployment_environment_id="your-environment-id"
)
```

#### Parameters

<ParamField body="prompt_id" type="str" required>
  The unique ID of the prompt.
</ParamField>

<ParamField body="deployment_environment_id" type="str" required>
  The deployment environment ID.
</ParamField>

**Returns:** The latest [`Deployment`](/docs/reference/sdk/v2/python/types/deployment) object for the given environment.

**Raises:** `ApiException` if the API call fails.

***

### init\_latest\_deployment

Initializes a cached latest deployment with automatic background refresh. Fetches the latest deployment immediately, then starts a background loop that refreshes the cache at the given interval. This is an async method.

```python theme={null}
controller = await adaline.init_latest_deployment(
    prompt_id="your-prompt-id",
    deployment_environment_id="your-environment-id",
    refresh_interval=60,
    max_continuous_failures=3
)

# Retrieve cached deployment (no API call unless forced)
deployment = await controller.get()

# Force a refresh from the API
deployment = await controller.get(force_refresh=True)

# Check background refresh status
status = controller.get_background_status()
# {"stopped": False, "consecutive_failures": 0, "last_error": None, "last_refreshed": datetime}

# Stop the background refresh
await controller.stop()
```

#### Parameters

<ParamField body="prompt_id" type="str" required>
  The unique ID of the prompt.
</ParamField>

<ParamField body="deployment_environment_id" type="str" required>
  The deployment environment ID.
</ParamField>

<ParamField body="refresh_interval" type="int" optional default="60">
  Seconds between background refreshes. Clamped to `[1, 600]`.
</ParamField>

<ParamField body="max_continuous_failures" type="int" optional default="3">
  Number of consecutive failures before the background loop stops itself.
</ParamField>

**Returns:** A `Controller` instance for retrieving and managing the cached deployment.

**Raises:** `ApiException` if the initial fetch fails.

#### Controller

The `Controller` class returned by `init_latest_deployment` provides:

| Method                  | Signature                                                        | Description                                                                                |
| ----------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `get`                   | `async get(force_refresh: bool = False) -> Optional[Deployment]` | Returns the cached deployment. If `force_refresh=True`, bypasses the cache.                |
| `stop`                  | `async stop()`                                                   | Cancels the background refresh task and clears the cache entry.                            |
| `get_background_status` | `get_background_status() -> dict`                                | Returns a snapshot: `{"stopped", "consecutive_failures", "last_error", "last_refreshed"}`. |

***

### init\_evaluation\_results

Initializes a cached, polling fetcher for evaluation results. Mirrors `init_latest_deployment` but targets [`EvaluationsClient.get_results`](/docs/reference/sdk/v2/python/classes/evaluation-results#list). Useful when an evaluation is still running server-side and you want to surface partial results without writing your own polling loop — the same query (pagination + filters) is replayed on every refresh. This is an async method.

```python theme={null}
results = await adaline.init_evaluation_results(
    prompt_id="your-prompt-id",
    evaluation_id="your-evaluation-id",
    grade="fail",
    expand="row",
    sort="score:desc",
    limit=50,
    refresh_interval=30,
    max_continuous_failures=3,
)

# Retrieve cached page (no API call unless forced)
page = await results.get()

# Force a refresh
page = await results.get(force_refresh=True)

# Check background refresh status
status = results.get_background_status()

# Stop the background refresh when you're done
await results.stop()
```

#### Parameters

<ParamField body="prompt_id" type="str" required>
  The unique ID of the prompt.
</ParamField>

<ParamField body="evaluation_id" type="str" required>
  The unique ID of the evaluation.
</ParamField>

<ParamField body="grade" type="str | None" optional>
  Filter by grade: `"pass"`, `"fail"`, or `"unknown"`.
</ParamField>

<ParamField body="expand" type="str | None" optional>
  Pass `"row"` to include the underlying dataset row in each result.
</ParamField>

<ParamField body="sort" type="str | None" optional>
  Sort order: `"createdAt:asc"`, `"createdAt:desc"`, `"score:asc"`, or `"score:desc"`.
</ParamField>

<ParamField body="limit" type="int | None" optional>
  Page size.
</ParamField>

<ParamField body="cursor" type="str | None" optional>
  Pagination cursor from a previous response.
</ParamField>

<ParamField body="refresh_interval" type="int" optional default="60">
  Seconds between background refreshes. Clamped to `[1, 600]`.
</ParamField>

<ParamField body="max_continuous_failures" type="int" optional default="3">
  Consecutive failures before the background loop stops itself.
</ParamField>

**Returns:** An `EvaluationResultsController` exposing `get(force_refresh=False)`, `get_background_status()`, and `stop()` — identical in shape to the deployment controller.

**Raises:** `ApiException` if the initial fetch fails.

***

### init\_monitor

Initializes and returns a new [`Monitor`](/docs/reference/sdk/v2/python/classes/monitor) instance for logging traces and spans. This is a synchronous method.

```python theme={null}
monitor = adaline.init_monitor(
    project_id="your-project-id",
    flush_interval_seconds=1,
    max_buffer_size=1000,
    default_content=None
)
```

#### Parameters

<ParamField body="project_id" type="str" required>
  Unique project identifier for grouping traces and spans.
</ParamField>

<ParamField body="flush_interval_seconds" type="int" optional default="1">
  Interval (in seconds) at which the buffer is automatically flushed.
</ParamField>

<ParamField body="max_buffer_size" type="int" optional default="1000">
  Maximum number of buffered entries before oldest items are dropped.
</ParamField>

<ParamField body="default_content" type="LogSpanContent | None" optional>
  Default content attached to spans when none is provided. See [`LogSpanContent`](/docs/reference/sdk/v2/python/types/LogSpanContent) for available types. Defaults to an [`LogSpanOtherContent`](/docs/reference/sdk/v2/python/types/LogSpanOtherContent) with empty input/output.
</ParamField>

## Namespace clients

Seven namespace clients are attached to every `Adaline` instance. Each wraps the corresponding autogen API with retry-on-5xx, abort-on-4xx, and keyword-only arguments:

| Attribute           | Client                                                        | Covers                                                                          |
| ------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `adaline.datasets`  | [DatasetsClient](/docs/reference/sdk/v2/python/classes/datasets)   | Datasets (+ `.rows`, `.columns` sub-clients)                                    |
| `adaline.prompts`   | [PromptsClient](/docs/reference/sdk/v2/python/classes/prompts)     | Prompts (+ `.draft`, `.playgrounds`, `.evaluators`, `.evaluations` sub-clients) |
| `adaline.providers` | [ProvidersClient](/docs/reference/sdk/v2/python/classes/providers) | configured LLM providers                                                        |
| `adaline.models`    | [ModelsClient](/docs/reference/sdk/v2/python/classes/models)       | models available across providers                                               |
| `adaline.projects`  | [ProjectsClient](/docs/reference/sdk/v2/python/classes/projects)   | list / get / update workspace projects                                          |
| `adaline.logs`      | [LogsClient](/docs/reference/sdk/v2/python/classes/logs)           | read-side log access (+ `.traces`, `.spans` sub-clients)                        |

Raw escape hatches are also exposed:

* `adaline.deployments_api` — raw `DeploymentsApi` from `adaline_api`
* `adaline.logs_api` — raw `LogsApi` (used internally by [`Monitor`](/docs/reference/sdk/v2/python/classes/monitor))

If you need identical retry behavior on an arbitrary call, use the exported `with_retry` helper:

```python theme={null}
from adaline.main import Adaline
from adaline.clients import with_retry

adaline = Adaline()

response = await with_retry(lambda: adaline.projects.list())
```

**Returns:** A [Monitor](/docs/reference/sdk/v2/python/classes/monitor) instance.