> For the complete documentation index, see [llms.txt](https://docs.algenta.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.algenta.ai/sdks/python/overview.md).

# Python client reference

`algenta-sdk` is the typed Python client for the Algenta HTTP API. You install it as `algenta-sdk` and import it as `decision_engine`; the client is a thin, faithful surface over the same `/v1` contract described in [API overview](/http-api/overview.md), so every method maps to one endpoint. This page covers installation, constructing the client, sync versus async, retries and timeouts, and the exception hierarchy — then routes you to the method reference for each domain.

{% hint style="info" %}
The distribution is `algenta-sdk`; the import name is `decision_engine`. This is the historical, stable module name.
{% endhint %}

## Install

```bash
pip install algenta-sdk
```

The client requires Python 3.10 or newer.

## Construct the client

Pass your API key explicitly, or let the constructor read it from the environment. Point `base_url` at the hosted API (the default) or at your own engine.

```python
import os
from decision_engine import AlgentaClient

client = AlgentaClient(
    api_key=os.environ["ALGENTA_API_KEY"],
    base_url="https://api.algenta.ai",   # default; override for self-hosted
)
```

The API key resolves, in order, from the `api_key=` argument, then `ALGENTA_API_KEY`, then the legacy `DE_API_KEY`. If none is set, the constructor raises `ValueError`.

| Argument      | Type            | Default                  | Notes                                                           |
| ------------- | --------------- | ------------------------ | --------------------------------------------------------------- |
| `api_key`     | `str` or `None` | `None`                   | Falls back to `ALGENTA_API_KEY`, then `DE_API_KEY`.             |
| `base_url`    | `str` or `None` | `https://api.algenta.ai` | Point at your self-hosted engine, e.g. `http://localhost:8000`. |
| `timeout`     | `float`         | `120.0`                  | Per-request timeout in seconds.                                 |
| `max_retries` | `int`           | `3`                      | Automatic retries on `429` and `5xx`.                           |

The client is a context manager that holds a pooled HTTP client; use `with` (or call `close()`) so connections are released.

```python
with AlgentaClient(api_key=os.environ["ALGENTA_API_KEY"]) as client:
    print(client.list_models().data)
```

{% hint style="info" %}
`AlgentaClient` is the preferred name. `DecisionEngineClient` and `CodnaClient` are accepted aliases for the same class, kept for backward compatibility.
{% endhint %}

## Sync vs async

Every method has an async equivalent on `AsyncAlgentaClient`, which is an async context manager exposing the identical surface. Aliases `AsyncDecisionEngineClient` and `AsyncCodnaClient` refer to the same class.

{% tabs %}
{% tab title="Sync" %}

```python
import os
from decision_engine import AlgentaClient

with AlgentaClient(api_key=os.environ["ALGENTA_API_KEY"]) as client:
    datasets = client.list_datasets(search="orders", compact=True)
    print(datasets.datasets)
```

{% endtab %}

{% tab title="Async" %}

```python
import asyncio
import os
from decision_engine import AsyncAlgentaClient

async def main() -> None:
    async with AsyncAlgentaClient(api_key=os.environ["ALGENTA_API_KEY"]) as client:
        datasets = await client.list_datasets(search="orders", compact=True)
        print(datasets.datasets)

asyncio.run(main())
```

{% endtab %}
{% endtabs %}

## Retries and timeouts

The client automatically retries `429` (rate limit) and `5xx` (server) responses up to `max_retries` (default `3`), then raises the corresponding typed exception. Each request is bounded by `timeout` seconds (default `120.0`). Tune both in the constructor:

```python
client = AlgentaClient(
    api_key=os.environ["ALGENTA_API_KEY"],
    timeout=30.0,
    max_retries=5,
)
```

## Errors

Every method raises a subclass of `DecisionEngineError`. All are importable from `decision_engine`.

| Exception             | Raised on | Notes                                                                                                 |
| --------------------- | --------- | ----------------------------------------------------------------------------------------------------- |
| `AuthenticationError` | `401`     | Missing, invalid, expired, or revoked API key.                                                        |
| `ValidationError`     | `422`     | Request failed validation; inspect `.validation_errors` / `.field_errors`.                            |
| `NotFoundError`       | `404`     | Resource not found.                                                                                   |
| `RateLimitError`      | `429`     | Quota or rate limit exceeded; carries `.retry_after`. The client already retried up to `max_retries`. |
| `ServerError`         | `5xx`     | Server-side error.                                                                                    |
| `DecisionEngineError` | any       | Base class; carries `.status_code`, `.error_code`, `.request_id`, and `.details`.                     |

```python
from decision_engine import (
    AuthenticationError,
    NotFoundError,
    RateLimitError,
    ServerError,
    ValidationError,
    DecisionEngineError,
)

try:
    client.get_dataset_summary("does-not-exist")
except NotFoundError as exc:
    print(exc.error_code, exc.request_id)
except RateLimitError as exc:
    print("retry after", exc.retry_after)   # already retried up to max_retries
except ValidationError as exc:
    print(exc.field_errors)
except DecisionEngineError as exc:
    print(exc.status_code, exc)
```

## Reference by domain

Each method maps to one endpoint. Pick the surface you need.

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Simulate and query</strong></td><td>Monte Carlo, resolve, query, verify, recommend.</td><td><a href="/pages/l0mqGrhl5ic9OfaGy52Q">/pages/l0mqGrhl5ic9OfaGy52Q</a></td></tr><tr><td><strong>Decisions and products</strong></td><td>Decision memory plus product decision, optimize, forecast.</td><td><a href="/pages/azHBRVU9OvmCqePoXOAt">/pages/azHBRVU9OvmCqePoXOAt</a></td></tr><tr><td><strong>Connectors and datasets</strong></td><td>Create connectors, onboard and query datasets.</td><td><a href="/pages/Vhju5AdW90FgzsTAtSnu">/pages/Vhju5AdW90FgzsTAtSnu</a></td></tr><tr><td><strong>Repository intelligence</strong></td><td>Snapshot, triage, graph-query, simulate, apply.</td><td><a href="/pages/eNrZVq5FBOE8nqPiEbrI">/pages/eNrZVq5FBOE8nqPiEbrI</a></td></tr><tr><td><strong>LLM and embeddings</strong></td><td>Models, tokenize, chat, responses, embeddings, rerank.</td><td><a href="/pages/S275RME6M3n4F4QkPcEk">/pages/S275RME6M3n4F4QkPcEk</a></td></tr></tbody></table>

## Next steps

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Run your first simulation</strong></td><td>Call <code>simulate</code> and read the decision envelope.</td><td><a href="/pages/l0mqGrhl5ic9OfaGy52Q">/pages/l0mqGrhl5ic9OfaGy52Q</a></td></tr><tr><td><strong>Understand the HTTP contract</strong></td><td>See the endpoints every method calls.</td><td><a href="/pages/7stbYFWr2YSgMNff3QuV">/pages/7stbYFWr2YSgMNff3QuV</a></td></tr><tr><td><strong>See the full integration guide</strong></td><td>Runtime, CLI, and end-to-end examples.</td><td><a href="/pages/9i6iZAg7l3UEawtf7i4b">/pages/9i6iZAg7l3UEawtf7i4b</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.algenta.ai/sdks/python/overview.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.