API reference

Autogenerated from the installed package via mkdocstrings.

Facade

aire.ai.AI

Unified entry point to the aire library.

Namespaces operate on the process-wide default runtime; use :meth:AI.configure to replace it (e.g. with a specific config file).

Top-level package

aire

aire — the agent-first AI creation library.

One consistent interface from idea to deployed AI system:

from aire import AI, tool

assistant = AI.project("docs-bot").documents("./docs").model("mock:echo")
assistant.index()
answer = assistant.ask("How do I authenticate?")
print(answer.text, answer.citations)

Heavy dependencies are never imported until the subsystem needing them is actually used. Everything is discoverable via .describe() manifests.

Agent

A composable agent. Create via AI.agents.create(...) or directly.

run(input, *, use_planning=None) async

Run the agent to a terminal state and persist memory (+ optional session).

use_planning overrides config.planning. When planning is on, delegates to :class:~aire.agents.plan.PlanActVerify with use_planning=False on nested calls to avoid recursion.

pause() async

Save current messages to the session and mark it paused.

ask(input) async

Convenience: run and return just the final text.

run_stream(input) async

Stream each agent step as an :class:~aire.agents.streaming.AgentEvent.

reset()

Start a fresh conversation (keeps tools and config, clears memory).

attach_session(path)

Attach or create a durable session for checkpoint/resume.

from_session(path, model, **kwargs) classmethod

Rebuild an agent bound to an existing session file; hydrate state.

as_tool(*, name=None, description=None, side_effect=None)

Wrap this agent as a :class:Tool — the agent-as-tool building block.

The returned tool takes task: str and returns the agent's final text, so any other agent (or :class:~aire.agents.team.Team) can delegate to it through the standard tool contract.

AgentConfig

Bases: BaseModel

Execution limits and behavior for an agent run.

AgentResult

Bases: BaseModel

Final outcome of an agent run.

Team

A supervisor-routed group of agents.

run(task) async

Run the team: supervisor routes, members execute, answer is synthesized.

describe()

Machine-readable team manifest — for agents.

TeamResult

Bases: BaseModel

Outcome of a team run.

AI

Unified entry point to the aire library.

Namespaces operate on the process-wide default runtime; use :meth:AI.configure to replace it (e.g. with a specific config file).

configure(settings=None, *, lock=None, **overrides) classmethod

Rebuild the default runtime from explicit settings or overrides.

Pass lock= (path or :class:~aire.project.lock.ProjectLock) to pin model/embedder refs from aire.lock into settings before build.

project(name, *, config=None) classmethod

Start a fluent project builder (documents → index → ask → deploy).

from_config(path) classmethod

Load a project from a configuration file.

recipe(name, **options) classmethod

One-call scaffold: rag | agent | finetune | gateway.

topologies() classmethod

Multi-agent topology helpers (swarm, debate, auction, blackboard).

tool(fn=None, *, register=True, name=None, description=None, permissions=None, timeout_seconds=30.0, retry=None, side_effect=SideEffect.READ_ONLY, **kwargs) classmethod

@AI.tool decorator: create (and optionally register) a tool.

tools() classmethod

The runtime tool registry as a ToolRegistry view.

openapi_tools(source, **options) classmethod

Import an OpenAPI 3.x spec as aire Tools.

evaluate(target, dataset, *, metrics=None, judge=None, gates=None, **kwargs) classmethod

Evaluate any target (agent, knowledge, model, callable) synchronously.

eval_gates(report, gates) classmethod

Check an evaluation report against metric thresholds.

ui(**options) classmethod

Minimal local FastAPI UI for traces/costs (requires aire-ai[serve]).

describe() classmethod

Machine-readable description of the whole library surface — for agents.

Settings

Bases: BaseModel

Root settings object for a project or process.

load(path=None, *, overrides=None, env=True) classmethod

Load settings by merging file, environment and explicit overrides.

safe_dict()

Configuration for inspection, with known secret-bearing keys masked.

Custom secret fields must be listed in observability.mask_fields. Key-based masking cannot identify arbitrary secrets embedded in text.

AudioContent

Bases: _BytesContent

Audio block.

DocumentContent

Bases: _BytesContent

Document block (PDF, office formats, ...).

ImageContent

Bases: _BytesContent

Image block (inline bytes, local file, or remote URI).

Message

Bases: BaseModel

A single conversational turn.

text_content property

Concatenated text of all text blocks (empty string if none).

StructuredContent

Bases: ContentBase

JSON-like structured data block (records, tool payloads, rows).

TextContent

Bases: ContentBase

Plain text block.

VideoContent

Bases: _BytesContent

Video block.

AireError

Bases: Exception

Base class for all aire errors.

Attributes:

Name	Type	Description
code	str	Stable, machine readable error code (e.g. "model.not_found").
message		Human readable description.
context	dict[str, Any]	Structured details safe to log or serialize.
retryable	bool	Whether retrying the same operation may succeed.

to_dict()

Serialize the error to a JSON-safe dictionary.

ConfigurationError

Bases: AireError

Invalid, missing or conflicting configuration.

PermissionDeniedError

Bases: AireError

An action lacked the required permission or approval.

ProviderError

Bases: AireError

An external provider failed or returned an unusable response.

Runtime

Composition root for aire subsystems.

describe()

Machine-readable inventory of everything registered — for agents.

Capability

Bases: StrEnum

Normalized model/component capabilities.

HealthStatus

Bases: BaseModel

Health probe result for any component.

Manifest

Bases: BaseModel

Machine-readable self-description emitted by every component.

Agents use manifests to discover what exists, what it accepts, and what it can do without reading source code.

Ref

Bases: BaseModel

A provider:name identifier (models, stores, embedders, tools...).

Usage

Bases: BaseModel

Token and cost accounting for one operation.

Dataset

An ordered, immutable set of :class:Record objects.

version property

Content-addressed version of record text and metadata (not IDs).

map(fn)

Transform each record.

filter(predicate)

Keep records where predicate(record) is true.

validate(*, min_length=1, max_length=None, required_metadata=None)

Drop invalid records and raise if everything is dropped.

deduplicate(*, key=None)

Remove exact duplicates by text fingerprint (or custom key).

sample(n=None, *, frac=None, seed=42)

Deterministically sample a count or fraction; default to all records.

split(*, train=0.8, validation=0.1, test=0.1, seed=42)

Reproducibly split into train/validation/test datasets.

quality_report(*, pii=True)

Compute a quality summary (counts, lengths, duplicates, PII suspects).

Record

Bases: BaseModel

One normalized data row flowing through pipelines.

EvalCase

Bases: BaseModel

One evaluation example.

Loaded from JSONL where each line has at least input and optionally expected, context (for grounding metrics) and arbitrary metadata.

EvalReport

Bases: BaseModel

Aggregate outcome of an evaluation run.

metric_summary()

Mean/min/max per metric across cases.

Evaluator

Runs evaluation suites and produces reports.

run(target, dataset, *, metrics=None, concurrency=4) async

Evaluate target on every case with the requested metrics.

KnowledgeGraph

A self-contained GraphRAG pipeline (ingest → query → cited answer).

ingest(source, *, metadata=None) async

Load, chunk, extract triples and index. Returns a GraphIndexReport.

subgraph(question, *, depth=1, limit=8) async

Link question terms to entities and expand their neighborhood.

query(question, *, k=5, depth=1) async

Graph-grounded answering: facts + communities + vector context → cited answer.

describe()

Machine-readable pipeline manifest — for agents.

Assistant

A configured knowledge assistant project (RAG vertical slice).

documents(source, *more)

Add document sources (paths, directories, URLs, lists).

model(spec)

Set the answering model (provider:name).

embedder(spec)

Set the embedding model (provider:name).

vector_store(spec, **options)

Set the vector store (provider:name); local needs no services.

rewriter(name)

Set query rewriter (None / identity disables rewrite).

compressor(name='truncate')

Set context compressor used before generation.

knowledge()

Materialize the underlying Knowledge pipeline.

index_async() async

Ingest all configured sources (chunk → embed → store).

ask_async(question, *, k=5, rewrite=None, compress=None, **kwargs) async

Ask a grounded question; returns an Answer with citations.

Optional rewrite / compress override pipeline defaults for this call.

evaluate_async(dataset, *, metrics=None) async

Evaluate the assistant against a QA dataset.

deploy(**options)

Wrap the assistant in a production FastAPI app (requires aire-ai[serve]).

deploy_artifacts(directory)

Generate Dockerfile, entrypoint and env template for deployment.

LongTermMemory

Bases: Memory

Episodic + semantic memory with model-driven consolidation.

remember(text, *, kind=MemoryKind.SEMANTIC, salience=1.0, metadata=None) async

Store a durable memory, embedded for semantic recall.

recall_semantic(query, *, k=5, kind=None) async

Recall memories by meaning, weighted by salience and recency.

consolidate(model, *, max_facts=8, keep=20) async

Fold recent episodes into durable semantic facts with a model.

Returns the new semantic entries. Episodes beyond keep are dropped after consolidation (they live on in the distilled facts).

add_procedural(text, *, salience=1.0, metadata=None) async

Store a procedural memory (how to do something / successful plan).

recall_procedural(query, *, k=5) async

Recall procedural memories by meaning.

MemoryEntry

Bases: BaseModel

One durable memory with salience-weighted recall.

EmbeddingModel

Bases: ABC

Unified embedding model interface.

embed(request) abstractmethod async

Embed a batch of texts.

GenerationRequest

Bases: BaseModel

Everything needed to produce one model completion.

GenerationResult

Bases: BaseModel

A completed generation.

parsed(schema_model)

Validate text as JSON against a pydantic model.

Model

Bases: ABC

Unified generative model interface.

info abstractmethod property

Normalized metadata describing this model.

generate(request) abstractmethod async

Produce one completion.

stream(request) async

Stream a completion. Default: single-chunk wrapper around generate().

health() async

Liveness probe. Default: attempt a minimal generation.

ask(prompt, **kwargs) async

One-shot text-in, text-out convenience.

ask_structured(prompt, schema_model, *, retries=1, **kwargs) async

Generate and validate JSON output against a pydantic model.

ModelInfo

Bases: BaseModel

Normalized metadata every model must expose.

Answer

Bases: BaseModel

A grounded answer with citations and usage accounting.

Citation

Bases: BaseModel

Verifiable pointer from an answer back to its source.

Knowledge

A self-contained retrieval-augmented generation pipeline.

ingest(source, *, chunker=None, metadata=None, replace=False) async

Load, chunk, embed and index a source. Returns an IndexReport.

ingest_documents(documents, *, chunker=None) async

Chunk, embed and upsert pre-built documents. Returns chunk count.

reindex_document(document, *, chunker=None) async

Prepare new chunks first, then replace the document in the store.

retrieve(query, *, k=5, filter=None, rewrite=True) async

Retrieve and rerank relevant chunks for a query (optional rewrite).

ask(question, *, model=None, k=5, citations=True, filter=None, template=None, compress=True, rewrite=True, **generate_kwargs) async

Retrieve context and generate a grounded answer with citations.

SideEffect

Bases: StrEnum

Risk classification for a tool's effects on the world.

Ordered by severity; policies gate execution on this level.

Tool

A function wrapped with its full executable contract.

definition()

The model-facing view of this tool.

check_permissions(context=None)

Raise PermissionDeniedError if the context lacks required permissions.

execute(arguments=None, *, context=None) async

Validate arguments, enforce timeout/retries, invoke, normalize result.

ToolResult

Bases: BaseModel

Normalized outcome of one tool execution.

ToolSpec

Bases: BaseModel

Full machine-readable declaration of a tool.

This is what agents read to decide whether and how to call a tool — the universal contract across functions, REST APIs, MCP servers and CLIs.

Workflow

A directed graph of executable nodes with deterministic scheduling.

add(name, fn, *, retries=0, timeout_seconds=None, requires_approval=False)

Add a node. The first node added becomes the default entry point.

connect(source, target, *, when=None)

Connect two nodes, optionally gated on a condition over the output.

run(input=None, *, state=None) async

Execute the workflow to completion (optionally resuming from state).

load_checkpoint(path) staticmethod

Load a persisted :class:WorkflowState from a checkpoint file.

resume(checkpoint_path=None) async

Resume from a checkpoint file (defaults to checkpoint_path).

Completed nodes are not re-executed; pending nodes continue with the persisted inputs/outputs.

WorkflowResult

Bases: BaseModel

Final outcome of a workflow run.