Skip to main content

orxtra

CI Python 3.12+ BUSL-1.1

Structured Orchestration of AI agents as a tree of tasks, against spaghetti vibe-coding -- Task preconditions and postconditions, spend tracking and limits, event logging, etc.

The problem

AI agent orchestration today is unstructured. Agents spawn agents, there are no verification boundaries, no budget enforcement, and no systematic way to know if work was done correctly. Free-form agent delegation is the goto of AI workflows — it produces results, but they are fragile, opaque, and unverifiable.

The solution

orxtra applies structured programming to AI workflows. Every piece of work is a task with explicit entry conditions (pre-checks), exit conditions (post-checks), and a budget ceiling. Tasks nest recursively. Failure propagates up the hierarchy. The system verifies work at every boundary — not after the fact, but as a structural guarantee.

What makes it different

Every tool call requires an active task.

There is no way to do untracked work. Every file read, every edit, every git operation happens inside a task with a budget, a trace, and verification boundaries. If an agent tries to call a tool outside a task, it gets a hard error.

Verification is structural, not bolted on.

Pre-checks gate entry. Post-checks gate exit. A check can be a Python script, a read-only AI agent that produces a structured verdict, or an entire sub-workflow. Failed post-checks let the agent retry. Exhausted retries escalate to the parent. The system does not trust agents to self-report quality.

The Overseer is a persistent LLM brain that acts only through typed action tools.

It can create workflows, add constraints, record decisions, create inbox items for human review — but only through a fixed vocabulary of actions. Every action is recorded in the trace. The Overseer cannot perform side effects outside its action tool set. It reasons and decides; the scheduler executes.

Budgets are denominated in USD.

Every task has a cost ceiling. Token usage is tracked per-task and converted to dollars using an internal pricing table. When a task exceeds its budget, execution stops — no silent overruns.

Agents cannot bypass safety mechanisms.

There is no bash tool. Git mutations go through safegit (concurrency-safe). File deletion goes through saferm (audited, recoverable). Write safety enforces per-path locking and stale-write detection. The system is designed so that agents cannot take shortcuts even if they want to.

Events are first-class.

Subscriptions with typed filter predicates, per-subscription action chains, accumulator buffering with count and time thresholds. External systems write events into the same store and subscribe to patterns. Dual-phase delivery: in-process futures for zero-latency task waking, PG-backed subscriptions for durable cross-process reactions.

Each module works standalone.

Use just the LLM client. Or just the task scheduler. Or just the event system. Or the full stack. 28 modules across five layers, strict dependency direction, no circular imports.

Modules

Use case Module Install
Typed LLM client with streaming and tool calls transport pip install orxtra-transport
Agent definitions from TOML + composable markdown prompts agent pip install orxtra-agent
Tool registry with path enforcement and write safety tool pip install orxtra-tool
Pre/post-check execution (scripts, agents, workflows) verify pip install orxtra-verify
Deterministic task execution with budgets and constraints scheduler pip install orxtra-scheduler
Reactive event subscriptions with actions and accumulators dispatch pip install orxtra-dispatch
Persistent AI brain with action tools and memory overseer pip install orxtra-overseer
PG event store with crash recovery and state machines trace pip install orxtra-trace
Full CLI for agents and humans cli pip install orxtra-cli
MCP server for dashboard integration mcp pip install orxtra-mcp

Six more foundation modules (protocols, secrets, write-safety, notepad, session, services) are installed as dependencies when you need them.

Quick start

One-shot LLM call, no orchestration:

from orxtra.services import ask

result = await ask(
    prompt="Summarize this document.",
    provider_type="anthropic",
    model="claude-sonnet-4-20250514",
    api_key="sk-...",
)

Structured workflow with verification:

from orxtra.services import start_run, RunConfig

run_id = await start_run(
    pool=pg_pool,
    workflow_path="workflows/review.toml",
    config=RunConfig(
        provider_type="anthropic",
        model="claude-sonnet-4-20250514",
        api_key="sk-...",
        autonomy_level="medium",
    ),
)

Examples


CLAUDE.md — full technical reference | CHANGELOG.md — release history

Metadata

Release files for orxtra 0.14.3

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

Source distribution (sdist)

Source distribution for orxtra 0.14.3
File Size Uploaded
orxtra-0.14.3.tar.gz 324.4 kB Details

Built distribution (wheel)

Table of built distributions (wheels) for orxtra 0.14.3
File Interpreter ABI Platform
orxtra-0.14.3-py3-none-any.whl Python 3 none any Details

Total release size: 754.2 kB

Release files / orxtra-0.14.3.tar.gz

Download URL orxtra-0.14.3.tar.gz
Size 324.4 kB
Tags Source
SHA-256 checksum
How to use checksums
7d6581cb6dd018ae0976fb6055051ad97feaa5ca71187bfb411a7881122d0cce
BLAKE2b-256 checksum
How to use checksums
5d8eca7d29f898e77f3a54843179a7d12cd7e0ca7dc29b61db6edcf3c3e8c3e4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 15, 2026.

Transparency log

Release files / orxtra-0.14.3-py3-none-any.whl

Download URL orxtra-0.14.3-py3-none-any.whl
Size 429.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3c2c5909cecd85f54cfd3551228d302008d11d32ba35b9b82975448ba3a9dab8
BLAKE2b-256 checksum
How to use checksums
7073b6e8d2ef26961601f6f922b23b974c01f47f6463a507ede8b0b2c8881c09
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 15, 2026.

Transparency log

Release history Release notifications | RSS feed

This release

0.14.3 This release

2 release files

0.14.2

2 release files

0.14.1

2 release files

0.14.0

2 release files

0.10.1

2 release files

0.10.0

2 release files

0.9.0

2 release files

0.8.0

2 release files

0.1.0

2 release files

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