Metadata-Version: 2.5
Name: orxtra
Version: 0.14.3
Summary: 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.
Project-URL: Homepage, https://smmh.dev/orxtra/
Project-URL: Documentation, https://smmh.dev/orxtra/
Project-URL: Repository, https://github.com/smm-h/orxtra
Project-URL: Issues, https://github.com/smm-h/orxtra/issues
Project-URL: Changelog, https://github.com/smm-h/orxtra/blob/main/CHANGELOG.md
License-Expression: BUSL-1.1
License-File: LICENSE
Keywords: agent-orchestration,ai-agents,cli,llm,mcp,postgresql,rlsbl,workflow-engine
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.12
Requires-Dist: a2a-sdk[http-server]
Requires-Dist: ag-ui-protocol
Requires-Dist: asyncpg
Requires-Dist: fastware>=0.5.0
Requires-Dist: httpx
Requires-Dist: jsonpatch
Requires-Dist: jsonschema
Requires-Dist: mcp<2,>=1.27
Requires-Dist: pathspec
Requires-Dist: pydantic-monty
Requires-Dist: pydantic>=2
Requires-Dist: strictcli>=0.41.1
Requires-Dist: strictspec
Requires-Dist: uuid6
Requires-Dist: websockets
Description-Content-Type: text/markdown

<!-- Auto-generated by selfdoc from .stricttools/docs/_README.md — do not edit -->

# orxtra

![CI](https://github.com/smm-h/orxtra/actions/workflows/ci-router.yml/badge.svg)
![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)
![BUSL-1.1](https://img.shields.io/badge/license-BUSL--1.1-blue.svg)

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

<details>
<summary><b>Every tool call requires an active task.</b></summary>

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.
</details>

<details>
<summary><b>Verification is structural, not bolted on.</b></summary>

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.
</details>

<details>
<summary><b>The Overseer is a persistent LLM brain that acts only through typed action tools.</b></summary>

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.
</details>

<details>
<summary><b>Budgets are denominated in USD.</b></summary>

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.
</details>

<details>
<summary><b>Agents cannot bypass safety mechanisms.</b></summary>

There is no bash tool. Git mutations go through [safegit](https://github.com/smm-h/safegit) (concurrency-safe). File deletion goes through [saferm](https://github.com/smm-h/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.
</details>

<details>
<summary><b>Events are first-class.</b></summary>

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.
</details>

<details>
<summary><b>Each module works standalone.</b></summary>

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.
</details>

## Modules

> [!TIP]
> Each module installs independently. Start with what you need; add more as your requirements grow.

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

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

## Quick start

One-shot LLM call, no orchestration:

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

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

- [`basic_agent.toml`](examples/basic_agent.toml) — minimal agent definition
- [`simple_workflow.toml`](examples/simple_workflow.toml) — workflow with dependencies and post-checks
- [`categories.toml`](examples/categories.toml) — multi-provider model routing
- [`coder_agent.toml`](examples/coder_agent.toml) — agent with exec capabilities

---

[CLAUDE.md](CLAUDE.md) — full technical reference | [CHANGELOG.md](CHANGELOG.md) — release history
