> 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

Install algenta-sdk, construct the sync or async AlgentaClient, configure retries and timeouts, handle typed errors, and jump to the Python method reference by domain.

`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.12 or newer. Pull-request CI builds the wheel and verifies a fresh install of it on Python 3.12, 3.13 and 3.14.

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

## Sync vs async

Every method has an async equivalent on `AsyncAlgentaClient`, which is an async context manager exposing the identical surface.

{% 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`     | Endpoint abuse control, upstream provider limit, or operator policy; carries `.retry_after`. Algenta editions have no execution quota. |
| `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="/sdks/python/simulations-and-queries.md">Simulations &amp; queries</a></td></tr><tr><td><strong>Decisions and products</strong></td><td>Decision memory plus product decision, optimize, forecast.</td><td><a href="/sdks/python/decisions-and-products.md">Decisions &amp; products</a></td></tr><tr><td><strong>Connectors and datasets</strong></td><td>Create connectors, onboard and query datasets.</td><td><a href="/sdks/python/connectors-and-data.md">Connectors &amp; datasets</a></td></tr><tr><td><strong>Repository intelligence</strong></td><td>Snapshot, triage, graph-query, simulate, apply.</td><td><a href="/sdks/python/repositories.md">Repository intelligence</a></td></tr><tr><td><strong>LLM and embeddings</strong></td><td>Models, tokenize, chat, responses, embeddings, rerank.</td><td><a href="/sdks/python/llm.md">LLM &amp; embeddings</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="/sdks/python/simulations-and-queries.md">Simulations &amp; queries</a></td></tr><tr><td><strong>Understand the HTTP contract</strong></td><td>See the endpoints every method calls.</td><td><a href="/http-api/overview.md">API overview</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="/sdks/python.md">Python SDK</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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.