thyn-ai/algenta-sdk

**Python and TypeScript client libraries and the official MCP server for Algenta — self-hosted building blocks for AI applications.**
📖 **Full documentation: GitHub Wiki**
Docs · Python SDK · TypeScript SDK · MCP server · Integrations · Examples · Contributing
Custom Mojo kernels give Algenta its speed. Your team never writes a line of
Mojo — the blocks speak Python and TypeScript. On your infrastructure, not
ours. These SDKs are how Python and TypeScript call the engine: typed access
to governed data queries, Monte Carlo simulations and recommendations,
decision memory with execution receipts that pin the policy and schema
snapshots each execution ran under, agent runs with human-in-the-loop
approvals, managed connectors, and a full audit trail — enforced by the
engine, never by client-side convention.
MCP server
**MCP server (algenta-mcp)** — the official MCP server for Algenta lives in
THIS repository at packages/mcp/ (implementation:
packages/mcp/algenta_mcp; stdio transport by default, Streamable HTTP
optional). Install it with pip install algenta-mcp and run it as the
algenta-mcp command; it is also on the official MCP Registry as
io.github.thyn-ai/algenta. The framework integrations (LangChain, LlamaIndex,
Vercel AI SDK, …) are what live in the companion repository
thyn-ai/algenta-integrations
— not the MCP server.
Introspection (initialize/tools/list) needs no credentials. Executing tools
requires a free community login — device registration at algenta.ai (free): run
algenta login, or create a key at
https://app.algenta.ai/dashboard/api-keys, then set ALGENTA_API_KEY.
Installation
Quickstart
Both clients read ALGENTA_API_KEY from the environment and default to
Algenta's hosted API at https://api.algenta.ai.
**Python** — note the import name is decision_engine (see
Legacy names):
**TypeScript:**
**Self-hosted engine?** Point the client at your own deployment —
AlgentaClient(base_url="http://localhost:8000") in Python,
new AlgentaClient({ baseUrl: "http://localhost:8000" }) in TypeScript — and
use the API key provisioned by your operator. The self_hosted and
air_gapped deployment profiles fail closed: they never silently fall back to
Algenta's cloud. Framework integrations in
thyn-ai/algenta-integrations
take the opposite default on purpose: they are self-hosted-first, resolve their
endpoint from ALGENTA_BASE_URL or an explicit base_url, and never default or
fall back to the hosted API.
The full API surface — governed queries, connectors, simulations, jobs,
triggers, agent runs, decisions, repository intelligence, and the TypeScript
local Runtime facade — is documented in
packages/python-sdk/README.md and
packages/ts-sdk/README.md, with runnable
projects in examples/. The MCP server lives in this repository
(see MCP server above); framework integrations (LangChain,
LlamaIndex, Vercel AI SDK, and more) live in the companion repository
thyn-ai/algenta-integrations.
Errors, retries, and timeouts
Both SDKs raise the same exception taxonomy. Every error carries the HTTP
status, the engine's machine-readable error_code, and — in Python — the
engine-assigned request_id; validation failures additionally expose
per-field details via field_errors (Python) / fieldErrors (TypeScript).
| Exception | HTTP status | Raised when | Retried by default |
| --- | --- | --- | --- |
| AuthenticationError | 401 | Missing or invalid API key | No |
| NotFoundError | 404 | Resource does not exist | No |
| ValidationError | 422 | Request failed schema validation | No |
| RateLimitError | 429 | Quota or rate limit exceeded | Yes — honors the engine's Retry-After (retry_after / retryAfter, default 60s) |
| ServerError | 5xx | Engine-side failure | Yes — exponential backoff |
| DecisionEngineError | any | Base class for all of the above | — |