Skip to main content

Adriane — Python SDK

A thin, Pythonic SDK over the Adriane Rust engine, exposed through a pyo3 native extension module.

Install adriane-ai, import adriane_ai. The distribution name on PyPI is adriane-ai (hyphen, matching the @adriane-ai npm scope); the import package is adriane_ai (underscore, per PEP 8 — Python module names can't contain a hyphen). This is the standard pip↔import convention.

pip install adriane-ai
import adriane_ai

adriane_ai.engine_version()   # -> the bound Rust engine version, e.g. "0.1.0"

One engine, two SDKs — what to install where

The graph model, validator, and DSL compiler live once in Rust (under crates/). Each language SDK is a thin shim over that single engine, not a re-implementation — so a graph that validates one way in TypeScript validates exactly the same way in Python. There is no second source of truth to drift.

TypeScript Python (this package)
Install npm i @adriane-ai/graph-sdk pip install adriane-ai
Import import { createGraph } from "@adriane-ai/graph-sdk" import adriane_ai
Rust engine optional — @adriane-ai/napi activates it; falls back to the in-bundle TS engine when absent built in — the wheel ships the compiled pyo3 extension
Bridge napi-rs (crates/bindings) pyo3 (crates/py-bindings)
Surface full builder + custom handlers + streaming JSON-in / JSON-out: validate, compile, model policy, catalogs, run paths

Both bindings expose the identical JSON-in / JSON-out core (graph validation, DSL compilation, the model policy, the component/prebuilt catalogs, and the fully-Rust run paths). The TypeScript SDK adds a builder and custom node handlers on top; the Python SDK is the thin JSON surface.

API

Graph model & DSL

import adriane_ai

adriane_ai.engine_version()            # -> the bound Rust engine version string

adriane_ai.validate_graph({            # -> list[dict] of validation errors ([] if sound)
    "id": "g", "version": "0.0.0", "name": "g", "channels": {},
    "nodes": [{"id": "a", "type": "action", "label": "a"}],
    "edges": [{"id": "e1", "from": "a", "to": "ghost", "type": "default"}],
    "entryNodeId": "a",
})
# [{'code': 'INVALID_EDGE_REFERENCE', 'message': "Edge 'e1' references unknown node 'ghost'.", 'path': ['e1']}]

adriane_ai.compile_graph_yaml("""    # -> dict (a compiled GraphDefinition)
id: g
version: 0.0.0
name: g
entryNodeId: a
nodes:
  - id: a
    type: action
    label: A
edges: []
channels: {}
""")

validate_graph returns the full list of structural errors (it does not raise on an invalid-but-parseable graph). compile_graph_yaml raises ValueError (adriane_ai.GraphCompileError) when the DSL fails to parse, compile, or validate.

Model policy

adriane_ai.available_providers()       # -> list[str], from process env credentials
# e.g. ["mistral"] when MISTRAL_API_KEY is set; [] when none are.

adriane_ai.resolve_model("fast", available=["mistral"])
# -> {'provider': 'mistral', 'model': 'mistral-small-latest', 'recommended': True}

# Tiers: "frontier" | "balanced" | "fast" | "creative".
# Omit `available` to derive it from the env. A provider/model override wins
# over the policy choice and flags `recommended = False`:
adriane_ai.resolve_model("frontier", available=["anthropic"], provider="mistral", model="mistral-tiny")
# -> {'provider': 'mistral', 'model': 'mistral-tiny', 'recommended': False}

Catalogs

adriane_ai.list_components()   # -> list[str] of the component kinds, e.g. "promptBuilder"
adriane_ai.list_prebuilt()     # -> list[dict] of the 16 prebuilt micro-agents
# each: {'name', 'description', 'tier', 'systemPrompt', 'toolNames',
#        'suspendForApproval', 'outputChannel'}  (camelCase, from the Rust engine)

Run paths (fully on Rust)

Both runs execute end-to-end in Rust — no Python callbacks. When no provider credentials are present in the env, run_prebuilt falls back to a deterministic mock gateway, so a run still completes offline.

adriane_ai.run_component(              # -> dict, the component's channel-update map
    "promptBuilder",
    {"template": "Hello {{name}}!", "into": "prompt"},
    {"name": "Ada"},
)
# {'prompt': 'Hello Ada!'}

adriane_ai.run_prebuilt("summarizer", "please summarise this long text")
# -> {'status': 'completed',
#     'channels': {'input': ..., 'summary': {...}},
#     'resolvedModel': {'provider': 'mock', 'model': 'mock-model'}}

# Ergonomic accessor: each attribute is bound to that agent name.
adriane_ai.prebuilt.summarizer("please summarise this long text")   # same as run_prebuilt("summarizer", ...)
adriane_ai.prebuilt.classifier("is this spam?", provider="mistral") # override forwarded through

run_component and run_prebuilt raise ValueError (adriane_ai.RunError) on an unknown kind/agent, invalid input, or an engine/runtime failure.

Install

A single cp39-abi3 wheel covers CPython 3.9+ (the extension targets the stable ABI), so nothing compiles on the user's machine:

pip install adriane-ai
import adriane_ai
print(adriane_ai.engine_version())

From source (dev)

The package is built with maturin over the Rust workspace crate crates/py-bindings, driven by python/pyproject.toml:

. "$HOME/.cargo/env"
python3 -m venv .venv && source .venv/bin/activate
pip install maturin

cd python
maturin develop            # build the extension + install into the active venv
# …or build a distributable wheel:
maturin build --release    # -> target/wheels/adriane_ai-<version>-cp39-abi3-*.whl

python -c "import adriane_ai; print(adriane_ai.engine_version())"

maturin compiles the pyo3 cdylib and places it as the adriane_ai.adriane submodule — the leaf import name adriane resolves the PyInit_adriane symbol emitted by #[pymodule] fn adriane in crates/py-bindings/src/lib.rs.

Tests

cd python
maturin develop                 # build + install the extension into the venv
python -m pytest tests -q       # if pytest is installed
python tests/test_adriane.py    # plain-assert fallback when pytest is absent

Metadata

Release files for adriane-ai 1.27.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for adriane-ai 1.27.0
File Actions
adriane_ai-1.27.0-cp39-abi3-win_amd64.whl CPython 3.9 abi3 Windows x86-64 Details for adriane_ai-1.27.0-cp39-abi3-win_amd64.whl
adriane_ai-1.27.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl CPython 3.9 abi3 Linux glibc 2.17+ x86-64 Details for adriane_ai-1.27.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
adriane_ai-1.27.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl CPython 3.9 abi3 Linux glibc 2.17+ ARM64 Details for adriane_ai-1.27.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
adriane_ai-1.27.0-cp39-abi3-macosx_11_0_arm64.whl CPython 3.9 abi3 macOS 11.0+ ARM64 Details for adriane_ai-1.27.0-cp39-abi3-macosx_11_0_arm64.whl

Total release size: 11.1 MB

Release files / adriane_ai-1.27.0-cp39-abi3-win_amd64.whl

Download URL adriane_ai-1.27.0-cp39-abi3-win_amd64.whl
Size 2.5 MB
Tags CPython 3.9 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
d856c8c3b6747ad7a4f6e3eeb7efd1000f8165750373b2193adf70feae7de19e
BLAKE2b-256 checksum
How to use checksums
addff459310c016210055c11494868096bd2edda4c40b66a4c2356143e1c6058
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Release files / adriane_ai-1.27.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL adriane_ai-1.27.0-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 3.1 MB
Tags CPython 3.9 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
8c987adb38da8a477ec51c0f4328f7064723cc9a4ef2dee89c3af3875acd348c
BLAKE2b-256 checksum
How to use checksums
7eea0a41392f987074f7fc0c9024c1a7a7735f12fec6188ecc2cee5a8a05865d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Release files / adriane_ai-1.27.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL adriane_ai-1.27.0-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Size 2.9 MB
Tags CPython 3.9 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
1ed2aae505cd244c175208dae89ef8429035cfaaecd346ed84e3d2a130879a18
BLAKE2b-256 checksum
How to use checksums
3453443f85e1c814d23c45d95e1b97b56dbbd9dd4a1e2a2051d193692cc298c8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Release files / adriane_ai-1.27.0-cp39-abi3-macosx_11_0_arm64.whl

Download URL adriane_ai-1.27.0-cp39-abi3-macosx_11_0_arm64.whl
Size 2.6 MB
Tags CPython 3.9 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
796146b678934f1e7ea5d1ca0654a744dd0456aea51f848ec4fd01a12d8bddff
BLAKE2b-256 checksum
How to use checksums
170e1a05a07ab342edba795bb7573af3070c866e51f28bf0cd0c3ed0c18b5d9b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Security for adriane-ai 1.27.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.27.0 This release

4 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page