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, 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.

The distribution is algenta-sdk; the import name is decision_engine. This is the historical, stable module name.

Install

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.

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.

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.

Sync

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)

Async

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

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:

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.

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.

Simulate and query

Monte Carlo, resolve, query, verify, recommend.

Decisions and products

Decision memory plus product decision, optimize, forecast.

Connectors and datasets

Create connectors, onboard and query datasets.

Repository intelligence

Snapshot, triage, graph-query, simulate, apply.

LLM and embeddings

Models, tokenize, chat, responses, embeddings, rerank.

Next steps

Run your first simulation

Call simulate and read the decision envelope.

Understand the HTTP contract

See the endpoints every method calls.

See the full integration guide

Runtime, CLI, and end-to-end examples.