Metadata-Version: 2.4
Name: algenta
Version: 1.0.34
Summary: Algenta repository intelligence and computational runtime CLI and API client; the native runtime installs automatically where its wheel is published.
Author: Thyn
Maintainer: Thyn
License-Expression: Apache-2.0
Project-URL: Homepage, https://algenta.ai
Project-URL: Documentation, https://docs.algenta.ai
Project-URL: Repository, https://github.com/thyn-ai/algenta
Project-URL: Company, https://thyn.ai
Keywords: algenta,repository-intelligence,computational-runtime,cli,mcp,runtime,deterministic,structured-data,query,resolve,agent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: algenta-sdk<2,>=1.0.33
Requires-Dist: pydantic>=2.7.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: algenta-runtime-native==1.0.7; python_version == "3.14" and implementation_name == "cpython" and sys_platform == "linux" and platform_machine == "x86_64"
Requires-Dist: cryptography>=42
Requires-Dist: keyring<26,>=25
Provides-Extra: mcp
Requires-Dist: algenta-mcp>=1.0.0; extra == "mcp"
Provides-Extra: benchmark
Requires-Dist: numpy; extra == "benchmark"
Provides-Extra: all
Requires-Dist: numpy; extra == "all"
Dynamic: license-file

# algenta

`algenta` is the public Python facade and CLI for Algenta's local native runtime
and API client. Where a native runtime wheel exists it 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`](https://pypi.org/project/algenta-sdk/); `algenta` already
depends on it.

## Install

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

Support matrix:

| Surface | Python | Platforms |
| --- | --- | --- |
| `AlgentaClient`, `Runtime` API modes, CLI | CPython 3.12, 3.13, 3.14 | macOS Apple Silicon, Linux |
| Local native runtime (`MojoRuntime`, `algenta simulate`, `algenta benchmark`) | CPython 3.14 | Linux x86-64 (glibc 2.35+) |

On CPython 3.14 on Linux x86-64, `pip install algenta` also installs the
native runtime (an environment marker selects it), whose only wheel is
`manylinux_2_35_x86_64`: the install there needs glibc 2.35 or newer (for
example Ubuntu 22.04+ or Debian 12+) and fails on older glibc or on musl. On
such a host use CPython 3.12 or 3.13: the client installs, and the local
runtime is unavailable. Wherever the runtime is not installed it fails closed:
`MojoRuntime` returns `error_code="compute_runtime_unavailable"` and
`algenta runtime doctor` says why, with no Python compute fallback.

The free-threaded build (`python3.14t`) is not supported by the local runtime;
`algenta runtime doctor` reports NOT READY there and names the build. `algenta`
runs only with the `algenta-runtime-native` release it pins: installing another
release by hand (for example an older one that published a macOS wheel) does
not enable the local runtime, which then fails closed naming both versions.

## Verify

```bash
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:

```bash
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:

```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

```bash
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 hosted or self-hosted data/query
surface 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 an Algenta deployment directly.

```python
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 using Algenta cloud.

### Contract discovery

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

```python
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")` targets Algenta cloud. `Runtime(mode="self_hosted")`
requires `base_url` to point at your own service and intentionally fails closed
when that configuration is missing.

## Unified Capability Plane

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

```python
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/`](../../examples/capability-plane/) and
[`examples/langgraph/capability_router.py`](../../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.

```bash
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 hosted or self-hosted Algenta:

```bash
pipx install algenta-mcp
algenta-mcp
```

Or install the optional dependency with this package:

```bash
pip install "algenta[mcp]"
algenta mcp
```

Its runtime tools are `list_runtime_libraries` and `execute_runtime_library`.

## Links

- [Documentation](https://docs.algenta.ai)
- [Python and CLI install guide](https://docs.algenta.ai/install)
- [Python SDK reference](https://docs.algenta.ai/sdk/python)
- [Runtime libraries](https://docs.algenta.ai/engine/runtime-libraries)
- [Source](https://github.com/thyn-ai/algenta)
- [Issues](https://github.com/thyn-ai/algenta/issues)
