Metadata-Version: 2.4
Name: algenta
Version: 1.0.38
Summary: Algenta repository intelligence and computational runtime CLI and API client with an automatically installed native runtime.
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.1.0
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. 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`](https://pypi.org/project/algenta-sdk/); `algenta` already
depends on it.

## Install

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

| Platform | Requirements | Acceleration |
| --- | --- | --- |
| macOS on Apple silicon | macOS 13 or newer | Metal on macOS 26 or newer |
| Linux x86-64 | glibc 2.34+ (e.g. Ubuntu 22.04+, Debian 12+, RHEL 9, Amazon Linux 2023), x86-64-v3 CPU (AVX2) | NVIDIA CUDA: T4, A100, L4, H100/H200 |
| Linux arm64 | glibc 2.34+, Armv8.2 CPU (Neoverse N1 or newer) | CPU only |

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

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

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

```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")` 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:

```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 your Algenta server:

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