algenta

algenta is the public Python facade and CLI for Algenta's local native runtime and API client. The native runtime is installed automatically as a dependency. Users do not install Mojo, compile binaries, launch a daemon, or configure a side process.

For the typed HTTP-only client on its own, use algenta-sdk; algenta already depends on it.

Install

python3 -m venv .venv
source .venv/bin/activate
pip install algenta

One install brings the CLI, the API client and the local native runtime, on Python 3.12 or newer. The runtime carries its own Python, so it runs the same under any of them.

There is no fallback build: on any other platform (Windows, Intel Macs, macOS before 13, musl-based Linux such as Alpine, glibc older than 2.34) pip install algenta fails at install time. pip cannot check the CPU floor: algenta runtime doctor runs a real kernel and names the installed runtime wheel with its floors. If the runtime cannot run, MojoRuntime returns error_code="compute_runtime_unavailable" and doctor says why, with no Python compute fallback.

Verify

algenta version
algenta runtime doctor
algenta simulate
algenta benchmark

benchmark reports cold startup separately from warm native executions. It does not use a Python compute fallback or print a synthetic speedup.

Runtime libraries

The installed contract contains 635 modules and 5,983 callable functions. Discover and execute them without starting another service:

algenta runtime modules
algenta runtime functions vector_kernels.dot
algenta runtime execute vector_kernels.dot dot64_f32 \
  --args-json '{"a":[1,2,6],"b":[3,2,1]}'

The same surface is available from Python:

from algenta import MojoRuntime

runtime = MojoRuntime(mode="local")

print(runtime.health())
print(runtime.list_functions("vector_kernels.dot"))

result = runtime.execute(
    "vector_kernels.dot",
    "dot64_f32",
    {"a": [1, 2, 6], "b": [3, 2, 1]},
)

if not result["success"]:
    raise RuntimeError(result["error"])

print(result["result"])       # 13.0
print(result["latency_ms"])
print(result["engine_used"])  # mojo

The runtime validates module names, function names, argument counts, scalar and list types, and public struct fields before execution.

Local data helpers

algenta import orders.csv --name orders
algenta map orders.csv
algenta query "revenue by region" orders.csv
algenta demo

These commands are local helpers. The governed data/query surface of your Algenta server is available through API mode.

API mode

API mode needs no extra install: algenta-sdk ships as a dependency of algenta, so the same facade can call your Algenta server directly.

import os

from algenta import Runtime

runtime = Runtime(
    mode="self_hosted",
    api_key=os.environ["ALGENTA_API_KEY"],
    base_url="http://localhost:8000",
)

datasets = runtime.list_datasets(search="orders", compact=True)
print(datasets)

Private deployment modes require an explicit base URL and fail closed instead of silently falling back to the built-in default base_url.

Contract discovery

The facade exports the generated public query contract, so applications can discover endpoint and filter capabilities without hard-coded paths:

from algenta import PRIMARY_DATA_QUERY_CONTRACT

print(PRIMARY_DATA_QUERY_CONTRACT["api"]["contract_endpoint"])

The API publishes its OpenAPI document at /openapi.json and identifies the active query contract with x-primary-data-query-contract. The main HTTP facade methods are get_contract(), list_connectors(), connect_data(), get_dataset(), get_dataset_summary(), refresh_dataset(), delete_dataset(), query_batch(), and query_sql_report(). Runtime evidence is discoverable through get_runtime_manifest(), get_runtime_modules(), get_runtime_benchmarks(), and get_runtime_release_validation().

Runtime(mode="api") calls the server named by base_url, or by ALGENTA_BASE_URL when base_url is not passed; set either to your Algenta server. Runtime(mode="self_hosted") requires base_url to point at your own server and intentionally fails closed when that configuration is missing.

Unified Capability Plane

The same facade routes datasets, skills, MCP tools, and runtime libraries:

route = runtime.route_capabilities(
    {
        "objective": "Investigate the latest checkout incident",
        "kinds": ["dataset", "skill", "mcp_tool", "runtime_library"],
    }
)

capability = runtime.get_capability(
    route.selected_capability_id,
    include_instruction=True,
)
execution = runtime.execute_capability(
    {
        "capability_id": route.selected_capability_id,
        "binding_id": route.selected_binding_id,
        "input": {"objective": "Investigate the latest checkout incident"},
    }
)
providers = runtime.list_capability_providers()
skills = runtime.list_skills()
mcp_providers = runtime.list_mcp_providers()

Local runtime execution fails closed for algenta_managed capabilities. Use Runtime(mode="api") or Runtime(mode="self_hosted") for those routes. Local adapters registered with runtime.register_capability_adapter(adapter) execute only client_managed capabilities. Full route and execution examples are in examples/capability-plane/ and examples/langgraph/capability_router.py.

Authentication

algenta login registers this device under your free community license (required, free) and stores API and license credentials only in the operating-system credential store. If no secure keyring backend is available, storage fails explicitly; set ALGENTA_API_KEY in the process environment instead.

algenta login
algenta whoami

The runtime wheel is verified against its signed manifest and platform tag before public release execution. Release mode denies unverified overrides and does not open a TCP listener.

MCP

The MCP client is a separate, thin package because it connects editors and agents to your Algenta server:

pipx install algenta-mcp
algenta-mcp

Or install the optional dependency with this package:

pip install "algenta[mcp]"
algenta mcp

Its runtime tools are list_runtime_libraries and execute_runtime_library.

Links

• Documentation
• Python and CLI install guide
• Python SDK reference
• Runtime libraries
• Source
• Issues