Algenta is a set of self-hosted foundational components for building AI applications. This repository provides its Python and TypeScript client libraries as well as the official MCP server. These SDKs are how Python and TypeScript call the Algenta engine, providing typed access to governed data queries, Monte Carlo simulations and recommendations, decision memory with execution credentials, agent runs with human approval, managed connectors, and full audit trails. These capabilities are enforced by the engine, not by client conventions.
Main capabilities: the engine's compute core (simulation, scoring, local query execution) is written in Mojo and proprietary, distributed via the signed algenta-runtime-native wheel, and is not in this repository. More than 6,000 deterministic functions sit atop the custom Mojo kernel, unified behind one API, SDK, and MCP interface. Decision memory pins the policy and schema snapshot that each run is based on with execution credentials, and agent runs support human-in-the-loop approval.
Usage: the MCP server is located in this repository's packages/mcp/ directory (implemented as packages/mcp/algenta_mcp, with stdio transport by default and optional Streamable HTTP). It can be installed via pip install algenta-mcp and run with the algenta-mcp command, and is also registered on the official MCP Registry as io.github.thyn-ai/algenta. Introspection (initialize / tools/list) requires no credentials; execution tools require a free community login—do device registration at algenta.ai (free), run algenta login, or at https://app.algenta.ai/dashboard/api-keys create a key, then set ALGENTA_API_KEY. Both clients read ALGENTA_API_KEY from environment variables and by default point to the hosted API https://api.algenta.ai。自托管引擎可指向自己的部署：Python Use AlgentaClient(base_url="http://localhost:8000")，TypeScript Use new AlgentaClient({ baseUrl: "http://localhost:8000" }), and use the API key provided by the operator. The self_hosted and air_gapped deployment configurations fail closed and never silently fall back to Algenta Cloud. Framework integrations (LangChain, LlamaIndex, Vercel AI SDK, etc.) are in the companion repository thyn-ai/algenta-integrations, adopt a self-hosted-first default policy, resolve endpoints from ALGENTA_BASE_URL or an explicit base_url, and do not default to 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/.
Error handling: both SDKs throw the same exception taxonomy, with each error carrying the HTTP status, an engine-readable error_code, and in Python also an engine-assigned request_id; validation failures additionally expose per-field details via field_errors (Python) / fieldErrors (TypeScript). Transient network errors are retried using the same policy as 5xx responses; the Python SDK additionally never retries the rate-limit code inline_preview_rate_limited.
Naming compatibility: the SDK has been renamed in its history. The PyPI package is algenta-sdk, but the importable module is still decision_engine: from decision_engine import AlgentaClient. CodnaClient (and Python's AsyncCodnaClient) is still exported as an alias of AlgentaClient. The environment variables DE_API_KEY, DE_BASE_URL, and ALGENTA_API_URL are still accepted alongside the canonical names ALGENTA_API_KEY and ALGENTA_BASE_URL. The published API contract guarantees a 90-day deprecation window (DEPRECATION_WIN before any old name is removedOW_DAYS).
Openness: This repository contains Algenta's Python and TypeScript client SDKs and the official MCP server (packages/mcp/), licensed under Apache-2.0. The Algenta engine itself is closed-source and is not in this repository; engine licensing, device rights, worker limits, concurrency limits, and Server Compute Units are independently enforced by the engine and are subject to a separate Algenta Engine license. The SDK is a pure HTTP client; it does not hold license signing keys, has no rights enforcement logic, and shares no secrets with the engine; modifying or replacing the SDK will not change the execution capacity licensed to the Algenta engine. Algenta execution does not require hosted inference or telemetry; paid licenses extend local execution and governance capacity rather than charging per SDK call.
Version and release verification: Each release built by release.yml is bound to a protected sdk-vX.Y.Z source tag, the exact commit that tag points to, and a release authorization record signed by the internal release pipeline after the engine test suite has verified that commit. release.yml refuses to build or release unless all of the above are independently consistent. Since signing was added in September 2026, each GitHub Release carries, in addition to the wheel, sdist, and release-manifest.json, a keyless Sigstore signature bundle for each asset (<asset>.sigstore.json), signed by the release.yml run itself, as well as SLSA build provenance covering all three assets (multiple.intoto.jsonl). Releases published via the workflow_dispatch path of release.yml are signed from the dispatched branch, and their certificate identity ends with @refs/heads/main rather than a tag.
Version management: The two packages share a single version number because they encapsulate the same API contract, and they follow semantic versioning: patch versions are for bug fixes and documentation with no API surface changes; minor versions are backward-compatible additions (new methods, new optional fields); major versions are breaking changes to exported symbols, required fields, or behavior, announced in advance through the aforementioned deprecation window. Release history is in CHANGELOG.md.
Use cases: Suitable for teams that need to build AI applications with governed data queries, decision memory, simulation recommendations, and agent runs with approvals on their own infrastructure.Limitations: The engine is closed-source and proprietary; using the tools requires a free community login and API key; execution capacity is subject to the engine license; specific fees and pricing information for paid licenses are not yet provided; configuration details for self-hosting and air-gapped deployment are not yet provided.
