Skip to main content

Ailu — Python SDK

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

Install ailu, import ailu. The PyPI distribution and the import package share the same name.

pip install adriane-ai
import ailu

ailu.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 @ailu-ai/graph-sdk pip install adriane-ai
Import import { createGraph } from "@ailu-ai/graph-sdk" import ailu
Rust engine built in — the native addon @ailu-ai/napi is a dependency; no TypeScript fallback built in — the wheel ships the compiled pyo3 extension
Bridge napi-rs (crates/bindings) pyo3 (crates/py-bindings)
Surface full builder + custom handlers + streaming validate, compile, model policy, catalogs, run a component or a prebuilt agent, GraphRunner: run, resume, approve, signal and replay a graph with your functions as steps, tools and conditions, and run_catalog_graph for saved graphs (no graph builder or streaming yet)

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 ailu

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

ailu.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']}]

ailu.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 (ailu.GraphCompileError) when the DSL fails to parse, compile, or validate.

Model policy

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

ailu.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`:
ailu.resolve_model("frontier", available=["anthropic"], provider="mistral", model="mistral-tiny")
# -> {'provider': 'mistral', 'model': 'mistral-tiny', 'recommended': False}

Catalogs

ailu.list_components()   # -> list[str] of the component kinds, e.g. "promptBuilder"
ailu.list_prebuilt()     # -> list[dict] of the 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. A prebuilt agent reads its provider's API key from the environment (ANTHROPIC_API_KEY, OPENAI_API_KEY, …); with no key it raises an error naming the variable to set. To run offline on the engine's deterministic mock gateway (tests, CI), set AILU_LLM_MOCK=1.

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

ailu.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.
ailu.prebuilt.summarizer("please summarise this long text")   # same as run_prebuilt("summarizer", ...)
ailu.prebuilt.classifier("is this spam?", provider="mistral") # override forwarded through

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

Graph runner

GraphRunner drives the same engine runner as the TypeScript SDK, over an engine spec ({"graph": ..., "agents": ..., ...}, camelCase keys). Your functions are the parts the engine cannot run itself:

def send(node: ailu.HostNodeInput) -> dict:
    # node.channels: the run's channels; node.effect_key: the same for a retry of this step
    # from the same checkpoint — perform an external effect at most once per key.
    return {"receipt": post_message(node.channels["message"])}

runner = ailu.GraphRunner(
    {"graph": graph},                       # a GraphDefinition dict
    nodes={"send": send},                   # plain action nodes whose step is yours
    tools={"lookup": lambda query: [...]},  # tools agents may call
    conditions={"approved": lambda channels: channels["ok"]},
    on_event=print,                         # every run lifecycle event
)
outcome = runner.run({"message": "hi"}, run_id="run-1", is_cancelled=lambda: False)
outcome = runner.resume(outcome["state"])                       # past a human gate
outcome = runner.approve_and_resume(state, [{"name": "refund", "requestedBy": "agent", "resolvedBy": "alice"}])
outcome = runner.signal(state, "paid", {"amount": 42})          # to a run waiting on a signal
replayed = runner.replay(entry_state, "audit-1", replay_journal)  # never calls your functions

Each call returns {"state", "status", "pendingApprovals"}, plus replayJournal and entryState when AILU_LLM_RECORD=1. A replay serves steps and tools from the recording and raises ailu.RunError when it diverges from it.

Saved graphs

A graph saved with its agents, components and fan-outs as settings on its nodes (metadata.agent, metadata.component, metadata.mapAgents) runs as it is: the engine reads those settings, as for the TypeScript runCatalogGraph.

outcome = ailu.run_catalog_graph(
    graph,                                  # the saved GraphDefinition dict
    initial_data={"ticket": "The export button does nothing."},
    nodes={"file": file_ticket},            # plain steps that are yours
    tools={"lookup": lookup},               # tools its agents call
    subgraphs=[child],                      # graphs its subgraph nodes name
)
outcome = ailu.resume_catalog_graph(graph, outcome["state"], nodes={"file": file_ticket})
replayed = ailu.replay_catalog_graph(graph, entry_state, "audit-1", replay_journal)

A nodes id that names no plain step raises ailu.HostNodeBindingError.

With approval_engine= (ailu.InMemoryApprovalEngine(), or your own request / get_by_id over a database), a suspended run files a request per gated tool and per human gate, and resume_catalog_graph raises ailu.ApprovalNotGrantedError until a person other than the requester approved what the run waits on — the same decisions as the TypeScript approvalEngine, made by the engine.

A step can suspend the run until a date or an external event: return ailu.sleep_until(wake_at, update) or ailu.wait_for_signal(name, wake_at=..., update=...), read why a run waits with ailu.read_suspend_meta(state), and a delivered payload with ailu.read_signal(state_or_node, name). stream_tokens=True on run_catalog_graph (or GraphRunner.run) sends agents' replies to on_event as token_delta events. ailu.llm_complete(input, provider=... or tier=...) calls a model once through the engine's gateway (the TypeScript model.invoke()).

Graph builder

app = (
    ailu.create_graph("Triage")
    .channel("ticket", "string", default="")
    .agent_node("triage", system="Say how urgent it is.", tools={"lookup": lookup})
    .human_gate("review")
    .node("file", file_ticket)
    .edge("triage", "review")
    .edge("review", "file")
    .compile()
)
paused = app.run({"ticket": "..."})
done = app.resume(paused["state"])

ailu.create_graph writes the definition the TypeScript createGraph writes for the same calls, so a graph built in one SDK runs from the other. Not in the Python builder yet: mapAgents, taskNode, fanOut, and agents' memory, skills, filesystem and web search options.

Embeddings and a vector store

ailu.create_embeddings(provider="mistral" | "openai", api_key=, model=, base_url=, dimensions=, transport=) turns texts into vectors through the engine; ailu.create_vector_store(persist_path=None) keeps {"id", "content", "embedding", "metadata"?} items (in memory or in the JSON file the TypeScript store writes) and answers query(embedding, k) by cosine similarity.

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 ailu
print(ailu.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/ailu-<version>-cp39-abi3-*.whl

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

maturin compiles the pyo3 cdylib and places it as the ailu.ailu submodule — the leaf import name ailu resolves the PyInit_ailu symbol emitted by #[pymodule] fn ailu 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_ailu.py    # plain-assert fallback when pytest is absent

Metadata

Release files for adriane-ai 2.8.1

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 2.8.1
File Actions
adriane_ai-2.8.1-cp39-abi3-win_amd64.whl CPython 3.9 abi3 Windows x86-64 Details for adriane_ai-2.8.1-cp39-abi3-win_amd64.whl
adriane_ai-2.8.1-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-2.8.1-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
adriane_ai-2.8.1-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl CPython 3.9 abi3 Linux glibc 2.17+ ARM64 Details for adriane_ai-2.8.1-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
adriane_ai-2.8.1-cp39-abi3-macosx_11_0_arm64.whl CPython 3.9 abi3 macOS 11.0+ ARM64 Details for adriane_ai-2.8.1-cp39-abi3-macosx_11_0_arm64.whl

Total release size: 23.6 MB

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

Download URL adriane_ai-2.8.1-cp39-abi3-win_amd64.whl
Size 5.5 MB
Tags CPython 3.9 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
2d5b53e766fddd90e60e932c01dae7e0cc60cc4be9d8b993c8ff062ee9c2dc42
BLAKE2b-256 checksum
How to use checksums
6c0cf9ab29ced1ea9729846c2f833d94f2a0c11b41c3dd54eec4b84416a8dd10
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.1

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

Download URL adriane_ai-2.8.1-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 6.3 MB
Tags CPython 3.9 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
f8cf1193acf6b93e1f0d26eb0a935237e1bc8498a33504176ffb34000f55b1e4
BLAKE2b-256 checksum
How to use checksums
85203d1978ab36a3eebd400a115aa74f2775b64ddadf39cb4a16496a9b91ee51
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.1

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

Download URL adriane_ai-2.8.1-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Size 6.2 MB
Tags CPython 3.9 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
d70cbaf23accf99d22f63d66d9986eab26fa2c891dc850041ac2e6de673f2dc9
BLAKE2b-256 checksum
How to use checksums
f921142f3abcfeedc0fdb5df141132ef49e502e8f3351bc44b86b2c499a97c6e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.1

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

Download URL adriane_ai-2.8.1-cp39-abi3-macosx_11_0_arm64.whl
Size 5.6 MB
Tags CPython 3.9 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
0171601c4301c5cfc9d9e7294dc5e5dd8b5a9a912d1a46f949e8b22357fc17c3
BLAKE2b-256 checksum
How to use checksums
71f33b9bdb870959981a76aad1a14f603d7421a080a8755f16e64d5b50d0aa5d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.15.1

Security for adriane-ai 2.8.1

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

2.8.1 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