Getting Started

Getting Started

Install a client, point it at an engine, make your first governed call. Five minutes.

Install

pip install algenta-sdk       # Python 3.10+; the importable module is decision_engine
npm install algenta-sdk       # TypeScript / JavaScript; Node.js 18+

The PyPI package is algenta-sdk but the import name is decision_engine — a legacy name kept for backward compatibility (see FAQ).

Get an API key

• Hosted (Cloud Managed): create a key in the Algenta console and export it as ALGENTA_API_KEY. Live keys carry the de_live_ prefix, test keys de_test_.
• Self-hosted: use the API key provisioned by your engine operator.

Both clients read ALGENTA_API_KEY from the environment and default to https://api.algenta.ai. Legacy DE_API_KEY is still accepted.

First call — Python

from decision_engine import AlgentaClient

client = AlgentaClient()  # reads ALGENTA_API_KEY; defaults to https://api.algenta.ai

# Discover what the connected engine publishes (cached contract document).
contract = client.get_contract()

# Find a dataset and run a governed metric query against it.
datasets = client.list_datasets(search="orders", compact=True)
summary = client.get_dataset_summary(datasets.datasets[0].dataset_id)
result = client.query_with_metadata(
    {
        "dataset_id": summary.dataset_id,
        "metric": {"hint": "gross_revenue"},
        "aggregation": "sum",
    }
)
print(result.data.result)

Async is first-class too: from decision_engine import AsyncAlgentaClient exposes the same surface with await.

First call — TypeScript

import { AlgentaClient } from "algenta-sdk";

const client = new AlgentaClient(); // reads ALGENTA_API_KEY; defaults to https://api.algenta.ai

const contract = await client.getContract();

const datasets = await client.listDatasets({ search: "orders", compact: true });
const summary = await client.getDatasetSummary(datasets.datasets[0].dataset_id);
const result = await client.queryWithMetadata({
  dataset_id: summary.dataset_id,
  metric: { hint: "gross_revenue" },
  aggregation: "sum",
});
console.log(result.data.result);

Hosted vs self-hosted

	Hosted (default)	Self-hosted
Endpoint	https://api.algenta.ai (built-in default)	Your deployment, e.g. http://localhost:8000
API key	Console-issued (de_live_…)	Operator-provisioned
Configure	nothing, or ALGENTA_API_KEY	base_url / baseUrl + operator key

client = AlgentaClient(base_url="http://localhost:8000")           # Python

const client = new AlgentaClient({ baseUrl: "http://localhost:8000" }); // TypeScript

The canonical endpoint env var is ALGENTA_BASE_URL (legacy: DE_BASE_URL, ALGENTA_API_URL). Fail-closed privacy profiles: when ALGENTA_DEPLOYMENT_MODE=self_hosted or air_gapped (or ALGENTA_DISABLE_CLOUD is truthy), the clients refuse to resolve any Algenta-owned cloud host instead of silently falling back to it. Framework integrations in thyn-ai/algenta-integrations take the opposite default on purpose: self-hosted-first, never hosted.

Useful knobs

Setting	Python	TypeScript	Default
Request timeout	timeout (seconds)	timeout (milliseconds)	120
Retries per request	max_retries	maxRetries	3

client = AlgentaClient(timeout=30.0, max_retries=5)

const client = new AlgentaClient({ timeout: 30_000, maxRetries: 5 });

Retryable errors (5xx, rate limits, transient network failures) are retried automatically with backoff — details in Error Handling.

No API key at all?

The TypeScript Runtime facade and the pure-local Python runtime (pip install algenta, a separate package from algenta-sdk) execute locally without a key:

import { Runtime, libraries } from "algenta-sdk";

const rt = new Runtime({ mode: "local" });            // embedded local execution, no API key
const catalog = await libraries({ mode: "local" });   // local runtime library catalog

console.log(catalog.modules.length);

See Architecture → Execution paths and the local-runtime example.

Where next

• Full method surface: packages/python-sdk/README.md and packages/ts-sdk/README.md
• Governed queries with typed filters: QueryFilterCondition / QueryFilterSpec (Python) in the Python SDK README
• Simulations, jobs, triggers, agent runs, decisions, connectors: same READMEs, or jump into Examples
• Governance model (profiles, receipts, approvals): Governance Profiles & Receipts