composeai 0.2.0__tar.gz → 0.3.0__tar.gz

{composeai-0.2.0 → composeai-0.3.0}/.gitignore

@@ -8,5 +8,5 @@ build/
 .pytest_cache/
 .ruff_cache/
 .superpowers/
-docs/
+plans/
 .env

composeai-0.3.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: composeai
+Version: 0.3.0
+Summary: Radically simple, functional framework for multi-agent AI workflows — typed agent functions, pipe composition, always-on local tracing, durable flows.
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.7
+Provides-Extra: all
+Requires-Dist: anthropic>=0.40; extra == 'all'
+Requires-Dist: mcp<2,>=1.27; extra == 'all'
+Requires-Dist: openai>=1.60; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.40; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: anthropic>=0.40; extra == 'dev'
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: mcp<2,>=1.27; extra == 'dev'
+Requires-Dist: openai>=1.60; extra == 'dev'
+Requires-Dist: pyright>=1.1.380; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.27; extra == 'mcp'
+Provides-Extra: openai
+Requires-Dist: openai>=1.60; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# composeai — 𝑓(𝑔(𝑥))
+
+A radically simple, functional framework for multi-agent AI workflows.
+
+- **Agents are typed functions.** The docstring is the system prompt, the body returns the user prompt, the return annotation is the structured output type. Calling one returns that type — or raises.
+- **Composition is checked before it runs.** `pipe(researcher, copywriter)` verifies every stage boundary at build time; a wiring bug raises `CompositionTypeError` before a single API call is made.
+- **Tracing is always on, and local.** Every run persists spans, token usage, and cost to a SQLite store on your disk (`./.compose`). No SaaS, no instrumentation, no opt-in — the trace is just there.
+- **Flows are durable.** A `@flow` journals every step; if it crashes — or pauses on a **named interrupt** (`approve("publish")`) waiting for a human — `resume(run_id)` continues it in the same process or a brand-new one, days later, replaying finished steps without re-paying for them.
+- **Every run can carry a spend cap.** `Budget(usd=..., tokens=...)` is enforced after every LLM call in a run's subtree, and stays cumulative across `resume()` — a run can't dodge its budget by crashing and getting resumed.
+- **Streaming and tracing are the same event bus.** `.stream()` yields `text_delta`/`thinking_delta`/`tool_call_started`/`tool_args_delta` interleaved with the very `span_started`/`span_finished`/`run_finished` events the trace is built from — on agents, pipelines, and flows alike, so a live UI and the trace can never disagree.
+- **MCP servers plug straight into `tools=`.** `compose.mcp_tools(command=..., ...)` connects to a Model Context Protocol server (stdio or streamable HTTP) and turns its tools into ordinary composeai `Tool` objects — indistinguishable from `@compose.tool` ones, including the same `requires_approval=` pause/resume.
+
+Runtime dependencies: **pydantic + the standard library**. Provider SDKs are optional extras. Python ≥ 3.10.
+
+## Install
+
+```bash
+pip install composeai                  # core: pydantic + stdlib only
+pip install "composeai[anthropic]"     # + the Anthropic SDK
+pip install "composeai[openai]"        # + the OpenAI SDK
+pip install "composeai[all]"           # both
+```
+
+## The 90-second tour
+
+Define an agent as a typed function. The docstring is its system prompt, the return annotation is its structured output type:
+
+```python
+import composeai as compose
+from pydantic import BaseModel, Field
+
+
+class FactSheet(BaseModel):
+    topic: str
+    key_facts: list[str] = Field(description="Three crisp, verifiable facts")
+
+
+@compose.tool
+def count_words(text: str) -> int:
+    """Count the words in a piece of text.
+
+    Args:
+        text: The text whose words should be counted.
+    """
+    return len(text.split())
+
+
+@compose.agent(model="anthropic/claude-sonnet-5", tools=[count_words])
+def researcher(topic: str) -> FactSheet:
+    """You are a meticulous researcher. Extract crisp, verifiable facts."""
+    return compose.prompt(f"Build a fact sheet about: {topic}")
+
+
+facts = researcher("quantum computing")   # -> FactSheet (or raises)
+```
+
+Calling `researcher(...)` runs the whole loop and returns the validated `FactSheet`. Every call like this is automatically persisted, so you can inspect it from the command line right afterward:
+
+```console
+$ compose trace --last
+trace 01KXC6RDB8E29NZHEAC2F54M11 — ok — [$0.0150 · 2.9k tok · 3ms]
+└─ ◆ researcher [$0.0150 · 2.9k tok · 3ms]
+   ├─ ▸ anthropic/claude-sonnet-5 [$0.0075 · 1.5k tok · 0ms]
+   ├─ ⚙ count_words [0ms]
+   └─ ▸ anthropic/claude-sonnet-5 [$0.0075 · 1.5k tok · 0ms]
+```
+
+No accounts, no exporters, no instrumentation to wire up — the trace (and its cost) is just there, in `./.compose`, the moment the agent finishes. See [agents](docs/agents.md) for `.run()`/`.stream()`, repairs, and resilience knobs; [composition](docs/composition.md) and [flows](docs/flows.md) for wiring agents into pipelines and durable, resumable workflows; [budgets](docs/budgets.md) for the `Budget(usd=..., tokens=...)` cap shown above.
+
+## Documentation
+
+| Page | What's there |
+| :--- | :--- |
+| [docs/index.md](docs/index.md) | Project overview, the 90-second tour, and where to go next |
+| [docs/agents.md](docs/agents.md) | The `@agent` idiom, structured output and repairs, tools, resilience knobs, naming/replacing agents, `.run()`/`.stream()` |
+| [docs/composition.md](docs/composition.md) | `pipe`, `aggregate`, `map`, build-time type checking, nesting combinators |
+| [docs/flows.md](docs/flows.md) | `@task`/`@flow`, the journal, determinism, `resume()`, human-in-the-loop |
+| [docs/providers.md](docs/providers.md) | Model strings vs `Model` instances, API keys, `openai_compatible`, pricing, reasoning-model gotchas |
+| [docs/observability.md](docs/observability.md) | The local tracing model, every `compose` CLI command, `--import`, `COMPOSE_TRACE_CONTENT` |
+| [docs/budgets.md](docs/budgets.md) | `Budget(usd=, tokens=)`, what counts, cumulative spend across `resume()`, `BudgetExceededError` |
+| [docs/testing.md](docs/testing.md) | `FakeModel`, cassettes, `@agent(cache=True)`, `reset_registries()` |
+| [docs/mcp.md](docs/mcp.md) | Connect MCP servers' tools to your agents |
+
+## Rules of the road
+
+The contracts composeai holds you to — and the ones it holds itself to:
+
+- **Flow bodies must be deterministic.** Replay works by re-running the body and substituting journaled step results in call order. Side effects, randomness, and clock reads belong inside `@task`/`@agent` steps, never in the flow body itself. Nothing detects a violation; it just won't replay correctly.
+- **A step journals only after it returns.** If the process dies between a task's external side effect and its journal write, resume re-runs that task — make external side effects idempotent.
+- **Journals are for pause/approval and crash recovery, not cross-release storage.** If a `@flow`'s source changes between pause and resume, `resume()` fails loud with `ResumeMismatchError` (the journal may no longer match the new call sequence); `allow_code_change=True` overrides it deliberately.
+- **State lives at `COMPOSE_DIR`** (default `./.compose`). `COMPOSE_TRACE_CONTENT=0` stops *spans* from capturing input/output payloads — usage, status, and timing are always recorded regardless. This does **not** extend to anything composeai needs as functional state to actually work, all of which are written in full unconditionally, regardless of `COMPOSE_TRACE_CONTENT`: a paused agent's `agent_state` snapshot (durable pause/resume — `approve()`/`ask_human()`/`@tool(requires_approval=True)` — requires the full in-progress conversation, including tool call arguments and results, so `resume()` can continue exactly where it left off); the `@flow` journal (step results must be real to replay correctly); and the test kit's own on-disk artifacts — `record_cassette`/the `cassette` fixture and `@compose.agent(cache=True)`'s filesystem response cache both need a call's real request/response to be replayable or servable as a cache hit later. If your tools handle secrets/PII in their arguments or results, treat `{COMPOSE_DIR}` (`runs.db`, `cache/`, and any cassette files you commit) as sensitive (filesystem permissions, encryption at rest, etc.) rather than relying on `COMPOSE_TRACE_CONTENT` to keep it out of the store.
+- **`temperature` is passthrough-only.** composeai never sets one for you, and modern Claude models reject sampling parameters with a 400 — leave it unset for Claude.
+- **Cost is never fabricated.** Priced models get exact USD from a dated, in-repo price table; calls with no known price report `cost_usd=None`, and any total that includes them renders as a `≥$X` partial (or `-` when nothing was priceable) instead of a made-up number. USD budgets consequently can't see unpriced spend — set a token budget too if you need a hard cap.
+- **Retries can re-stream.** With `retries > 0`, a provider error striking mid-stream re-runs the call from the start — consumers of `.stream()` may see the same deltas twice on one llm span. Render final outputs (or treat a fresh delta burst as a reset) if double-rendering matters.
+
+## vs. the alternatives
+
+| | LangChain / LangGraph | composeai |
+| :--- | :--- | :--- |
+| **Core architecture** | Configuration & state graphs (`Runnable`, `StateGraph`) | Plain typed functions, composed with `pipe`/`aggregate`/`map` |
+| **Learning curve** | A proprietary class ecosystem | Decorators on regular functions and pydantic types |
+| **Wiring bugs surface** | At runtime, mid-graph | At composition time, before any API call |
+| **Debugging** | Deeply nested framework traces | A breakpoint between two functions; local trace trees with exact costs |
+| **Observability** | External/SaaS platforms, opt-in callbacks | Always-on local SQLite tracing + a CLI, zero setup |
+| **Durability & HITL** | Separate checkpointer/orchestrator machinery | Journaled `@flow` + named interrupts, one `resume()` |
+| **Dependencies** | Heavy transitive footprint | pydantic + stdlib; provider SDKs as optional extras |
+
+## Roadmap
+
+- OpenTelemetry exporter (the span model already tracks `gen_ai.*` attribute conventions)
+- Async API (`await agent(...)`, async tools)
+- TypeScript sibling package
+- Extended-thinking / reasoning request configuration (Anthropic `thinking` budget, OpenAI `reasoning.summary`/`encrypted_content`) -- today `ThinkingPart` only round-trips whatever a provider returns unprompted by default; there's no `ModelRequest` field to actually ask for it
+
+## License
+
+MIT

composeai-0.3.0/README.md

@@ -0,0 +1,117 @@
+# composeai — 𝑓(𝑔(𝑥))
+
+A radically simple, functional framework for multi-agent AI workflows.
+
+- **Agents are typed functions.** The docstring is the system prompt, the body returns the user prompt, the return annotation is the structured output type. Calling one returns that type — or raises.
+- **Composition is checked before it runs.** `pipe(researcher, copywriter)` verifies every stage boundary at build time; a wiring bug raises `CompositionTypeError` before a single API call is made.
+- **Tracing is always on, and local.** Every run persists spans, token usage, and cost to a SQLite store on your disk (`./.compose`). No SaaS, no instrumentation, no opt-in — the trace is just there.
+- **Flows are durable.** A `@flow` journals every step; if it crashes — or pauses on a **named interrupt** (`approve("publish")`) waiting for a human — `resume(run_id)` continues it in the same process or a brand-new one, days later, replaying finished steps without re-paying for them.
+- **Every run can carry a spend cap.** `Budget(usd=..., tokens=...)` is enforced after every LLM call in a run's subtree, and stays cumulative across `resume()` — a run can't dodge its budget by crashing and getting resumed.
+- **Streaming and tracing are the same event bus.** `.stream()` yields `text_delta`/`thinking_delta`/`tool_call_started`/`tool_args_delta` interleaved with the very `span_started`/`span_finished`/`run_finished` events the trace is built from — on agents, pipelines, and flows alike, so a live UI and the trace can never disagree.
+- **MCP servers plug straight into `tools=`.** `compose.mcp_tools(command=..., ...)` connects to a Model Context Protocol server (stdio or streamable HTTP) and turns its tools into ordinary composeai `Tool` objects — indistinguishable from `@compose.tool` ones, including the same `requires_approval=` pause/resume.
+
+Runtime dependencies: **pydantic + the standard library**. Provider SDKs are optional extras. Python ≥ 3.10.
+
+## Install
+
+```bash
+pip install composeai                  # core: pydantic + stdlib only
+pip install "composeai[anthropic]"     # + the Anthropic SDK
+pip install "composeai[openai]"        # + the OpenAI SDK
+pip install "composeai[all]"           # both
+```
+
+## The 90-second tour
+
+Define an agent as a typed function. The docstring is its system prompt, the return annotation is its structured output type:
+
+```python
+import composeai as compose
+from pydantic import BaseModel, Field
+
+
+class FactSheet(BaseModel):
+    topic: str
+    key_facts: list[str] = Field(description="Three crisp, verifiable facts")
+
+
+@compose.tool
+def count_words(text: str) -> int:
+    """Count the words in a piece of text.
+
+    Args:
+        text: The text whose words should be counted.
+    """
+    return len(text.split())
+
+
+@compose.agent(model="anthropic/claude-sonnet-5", tools=[count_words])
+def researcher(topic: str) -> FactSheet:
+    """You are a meticulous researcher. Extract crisp, verifiable facts."""
+    return compose.prompt(f"Build a fact sheet about: {topic}")
+
+
+facts = researcher("quantum computing")   # -> FactSheet (or raises)
+```
+
+Calling `researcher(...)` runs the whole loop and returns the validated `FactSheet`. Every call like this is automatically persisted, so you can inspect it from the command line right afterward:
+
+```console
+$ compose trace --last
+trace 01KXC6RDB8E29NZHEAC2F54M11 — ok — [$0.0150 · 2.9k tok · 3ms]
+└─ ◆ researcher [$0.0150 · 2.9k tok · 3ms]
+   ├─ ▸ anthropic/claude-sonnet-5 [$0.0075 · 1.5k tok · 0ms]
+   ├─ ⚙ count_words [0ms]
+   └─ ▸ anthropic/claude-sonnet-5 [$0.0075 · 1.5k tok · 0ms]
+```
+
+No accounts, no exporters, no instrumentation to wire up — the trace (and its cost) is just there, in `./.compose`, the moment the agent finishes. See [agents](docs/agents.md) for `.run()`/`.stream()`, repairs, and resilience knobs; [composition](docs/composition.md) and [flows](docs/flows.md) for wiring agents into pipelines and durable, resumable workflows; [budgets](docs/budgets.md) for the `Budget(usd=..., tokens=...)` cap shown above.
+
+## Documentation
+
+| Page | What's there |
+| :--- | :--- |
+| [docs/index.md](docs/index.md) | Project overview, the 90-second tour, and where to go next |
+| [docs/agents.md](docs/agents.md) | The `@agent` idiom, structured output and repairs, tools, resilience knobs, naming/replacing agents, `.run()`/`.stream()` |
+| [docs/composition.md](docs/composition.md) | `pipe`, `aggregate`, `map`, build-time type checking, nesting combinators |
+| [docs/flows.md](docs/flows.md) | `@task`/`@flow`, the journal, determinism, `resume()`, human-in-the-loop |
+| [docs/providers.md](docs/providers.md) | Model strings vs `Model` instances, API keys, `openai_compatible`, pricing, reasoning-model gotchas |
+| [docs/observability.md](docs/observability.md) | The local tracing model, every `compose` CLI command, `--import`, `COMPOSE_TRACE_CONTENT` |
+| [docs/budgets.md](docs/budgets.md) | `Budget(usd=, tokens=)`, what counts, cumulative spend across `resume()`, `BudgetExceededError` |
+| [docs/testing.md](docs/testing.md) | `FakeModel`, cassettes, `@agent(cache=True)`, `reset_registries()` |
+| [docs/mcp.md](docs/mcp.md) | Connect MCP servers' tools to your agents |
+
+## Rules of the road
+
+The contracts composeai holds you to — and the ones it holds itself to:
+
+- **Flow bodies must be deterministic.** Replay works by re-running the body and substituting journaled step results in call order. Side effects, randomness, and clock reads belong inside `@task`/`@agent` steps, never in the flow body itself. Nothing detects a violation; it just won't replay correctly.
+- **A step journals only after it returns.** If the process dies between a task's external side effect and its journal write, resume re-runs that task — make external side effects idempotent.
+- **Journals are for pause/approval and crash recovery, not cross-release storage.** If a `@flow`'s source changes between pause and resume, `resume()` fails loud with `ResumeMismatchError` (the journal may no longer match the new call sequence); `allow_code_change=True` overrides it deliberately.
+- **State lives at `COMPOSE_DIR`** (default `./.compose`). `COMPOSE_TRACE_CONTENT=0` stops *spans* from capturing input/output payloads — usage, status, and timing are always recorded regardless. This does **not** extend to anything composeai needs as functional state to actually work, all of which are written in full unconditionally, regardless of `COMPOSE_TRACE_CONTENT`: a paused agent's `agent_state` snapshot (durable pause/resume — `approve()`/`ask_human()`/`@tool(requires_approval=True)` — requires the full in-progress conversation, including tool call arguments and results, so `resume()` can continue exactly where it left off); the `@flow` journal (step results must be real to replay correctly); and the test kit's own on-disk artifacts — `record_cassette`/the `cassette` fixture and `@compose.agent(cache=True)`'s filesystem response cache both need a call's real request/response to be replayable or servable as a cache hit later. If your tools handle secrets/PII in their arguments or results, treat `{COMPOSE_DIR}` (`runs.db`, `cache/`, and any cassette files you commit) as sensitive (filesystem permissions, encryption at rest, etc.) rather than relying on `COMPOSE_TRACE_CONTENT` to keep it out of the store.
+- **`temperature` is passthrough-only.** composeai never sets one for you, and modern Claude models reject sampling parameters with a 400 — leave it unset for Claude.
+- **Cost is never fabricated.** Priced models get exact USD from a dated, in-repo price table; calls with no known price report `cost_usd=None`, and any total that includes them renders as a `≥$X` partial (or `-` when nothing was priceable) instead of a made-up number. USD budgets consequently can't see unpriced spend — set a token budget too if you need a hard cap.
+- **Retries can re-stream.** With `retries > 0`, a provider error striking mid-stream re-runs the call from the start — consumers of `.stream()` may see the same deltas twice on one llm span. Render final outputs (or treat a fresh delta burst as a reset) if double-rendering matters.
+
+## vs. the alternatives
+
+| | LangChain / LangGraph | composeai |
+| :--- | :--- | :--- |
+| **Core architecture** | Configuration & state graphs (`Runnable`, `StateGraph`) | Plain typed functions, composed with `pipe`/`aggregate`/`map` |
+| **Learning curve** | A proprietary class ecosystem | Decorators on regular functions and pydantic types |
+| **Wiring bugs surface** | At runtime, mid-graph | At composition time, before any API call |
+| **Debugging** | Deeply nested framework traces | A breakpoint between two functions; local trace trees with exact costs |
+| **Observability** | External/SaaS platforms, opt-in callbacks | Always-on local SQLite tracing + a CLI, zero setup |
+| **Durability & HITL** | Separate checkpointer/orchestrator machinery | Journaled `@flow` + named interrupts, one `resume()` |
+| **Dependencies** | Heavy transitive footprint | pydantic + stdlib; provider SDKs as optional extras |
+
+## Roadmap
+
+- OpenTelemetry exporter (the span model already tracks `gen_ai.*` attribute conventions)
+- Async API (`await agent(...)`, async tools)
+- TypeScript sibling package
+- Extended-thinking / reasoning request configuration (Anthropic `thinking` budget, OpenAI `reasoning.summary`/`encrypted_content`) -- today `ThinkingPart` only round-trips whatever a provider returns unprompted by default; there's no `ModelRequest` field to actually ask for it
+
+## License
+
+MIT

composeai-0.3.0/docs/agents.md

@@ -0,0 +1,144 @@
+# Agents
+
+An agent is a plain Python function decorated with `@compose.agent`: its docstring becomes the system prompt, its body returns the user prompt, and its return-type annotation becomes the structured output type that the model's reply is validated into.
+
+## The `@agent` idiom
+
+```python
+import composeai as compose
+from pydantic import BaseModel, Field
+
+
+class FactSheet(BaseModel):
+    topic: str
+    key_facts: list[str] = Field(description="Three crisp, verifiable facts")
+
+
+@compose.tool
+def count_words(text: str) -> int:
+    """Count the words in a piece of text.
+
+    Args:
+        text: The text whose words should be counted.
+    """
+    return len(text.split())
+
+
+@compose.agent(model="anthropic/claude-sonnet-5", tools=[count_words])
+def researcher(topic: str) -> FactSheet:
+    """You are a meticulous researcher. Extract crisp, verifiable facts."""
+    return compose.prompt(f"Build a fact sheet about: {topic}")
+
+
+facts = researcher("quantum computing")   # -> FactSheet (or raises)
+```
+
+The decorated function *is* the agent: docstring → system prompt, body → user prompt (or a full `list[Message]` conversation), return annotation → structured output schema, validated back into that type. `compose.prompt(...)` marks the body's returned value as the prompt — a typed no-op (declared `-> Any`) that keeps static type checkers happy about a body returning a `str` where the annotation promises `FactSheet`. Returning a bare `str` (or `list[Message]`) works identically at runtime; `prompt()` only exists for type-checker ergonomics. Tools run in a loop until the model produces a final answer.
+
+`model=` is the only required argument, and it's keyword-only: either a `"provider/model-id"` string (resolved lazily) or an existing `Model` instance — including `FakeModel` from `composeai.testing`, for tests that need no network or provider SDK.
+
+## Structured output and `max_repairs=`
+
+Failed structured output doesn't have to be fatal. With `@agent(max_repairs=2)`, if the model's final reply fails JSON parsing or schema validation, composeai appends the validation error as a corrective user message and re-asks — up to `max_repairs` times — instead of raising immediately:
+
+```python
+@compose.agent(model="anthropic/claude-sonnet-5", max_repairs=2)
+def researcher(topic: str) -> FactSheet:
+    """You are a meticulous researcher. Extract crisp, verifiable facts."""
+    return compose.prompt(f"Build a fact sheet about: {topic}")
+```
+
+Each repair is a full-price LLM turn — the whole conversation is re-sent — and counts against `max_turns`, so it isn't free, but it's far cheaper (and more effective against small or local models) than a cold re-run. The default is `max_repairs=0` (fail fast). Every validation failure that reaches you, repaired or not, comes back as a `ComposeError` — a raw pydantic `ValidationError` never leaks out of `@agent`.
+
+## Tools
+
+`@compose.tool` turns a plain, typed function into a model-callable tool. It builds a strict JSON Schema from the function's signature and parses a Google-style docstring for the tool's own description and its per-argument descriptions:
+
+```python
+@compose.tool
+def search_docs(query: str, limit: int = 5) -> str:
+    """Search internal documentation for matching pages.
+
+    Args:
+        query: The search query.
+        limit: Maximum number of results to return.
+    """
+    return f"{limit} results for {query!r}"
+```
+
+Everything before a line reading exactly `Args:` becomes the tool description; each `name: description` line under `Args:` becomes that parameter's schema description. A tool with no docstring (and no explicit `description=`) raises `ConfigError` at decoration time — the model relies on the description to know when to call it.
+
+`@tool(requires_approval=True)` gates the tool behind a human: the agent pauses mid-loop until `resume(run_id, answers={"tool_name": True})` (or `False` to deny — the model sees `"denied by user"` and carries on). See [flows](flows.md) for the full human-in-the-loop story.
+
+`@tool(timeout=...)` (seconds) bounds one execution of the tool body. A timed-out call surfaces to the model as an `is_error` tool result — the agent keeps running and the model can react — it never aborts the run:
+
+```python
+@compose.tool(timeout=5.0)
+def fetch_url(url: str) -> str:
+    """Fetch a URL's contents.
+
+    Args:
+        url: The URL to fetch.
+    """
+    ...
+```
+
+When the model requests several tool calls in one turn, they run in parallel with no blanket bound on the batch as a whole — `@tool(timeout=...)` is the only per-call guard, so an individual tool with no timeout set can run indefinitely alongside its siblings.
+
+Tools can also come from MCP servers — see [mcp](mcp.md).
+
+## Resilience knobs
+
+All of these are keyword-only arguments to `@compose.agent(...)`:
+
+| Argument | Default | What it does |
+| :--- | :--- | :--- |
+| `retries` | `0` | Retry a failed provider call this many times before giving up (or falling back). |
+| `fallback` | `None` | A second `"provider/model-id"` string or `Model`, resolved lazily and used only if every `retries` attempt against the primary model fails. |
+| `timeout` | `None` | Seconds. Checked at turn boundaries only; an in-flight model call is never interrupted. Raises `AgentTimeoutError`. |
+| `max_turns` | `10` | Maximum LLM turns (including repair turns) before raising `MaxTurnsExceededError`. |
+| `max_tokens` | `16000` | Passed to the model on every call; hitting it before the response finishes raises `ComposeError`. |
+| `temperature` | `None` | Passthrough-only — composeai never sets one for you. Modern Claude models reject sampling parameters outright, so leave it unset for Claude. |
+
+Note that `@agent(timeout=...)` is unrelated to a model constructor's own `timeout=`: the agent's `timeout` is a turn-boundary watchdog, while the model's `timeout` bounds each individual HTTP request at the SDK-client level. See [providers](providers.md).
+
+## `name=` and `replace=`
+
+`@agent(name=...)` overrides the registered/routing name (default: the function's `__name__`) — useful when two agents would otherwise share a function name. Agent names must be unique per process, since `resume()` uses the name to route a paused or crashed standalone agent run back to its definition; a duplicate name raises `ConfigError` at decoration time.
+
+`@agent(replace=True)` re-binds an existing name instead of raising — handy for runtime-bound factories and test fixtures. **Warning:** standalone-agent resume has no fingerprint/staleness check (unlike `@flow`), so a paused run resumed after a `replace=True` rebind continues silently against the *new* definition.
+
+## `.run()` vs calling vs `.stream()`
+
+Calling the agent directly (`researcher("quantum computing")`) is sugar for `researcher.run("quantum computing").output`. Need more than the output? `.run()` returns the whole `Run`:
+
+```python
+run = researcher.run("quantum computing")
+run.output          # the FactSheet
+run.usage           # tokens + USD cost, rolled up across every LLM call
+run.trace.print()   # the trace tree
+```
+
+Both the call form and `.run()` accept an optional keyword-only `budget`, enforced across every LLM call in the run — see [budgets](budgets.md):
+
+```python
+researcher.run("quantum computing", budget=compose.Budget(usd=0.50, tokens=200_000))
+```
+
+`.stream(...)` runs the same loop on a background thread and returns a `RunStream` for live consumption — token deltas interleaved with the same span events tracing already produces:
+
+```python
+stream = researcher.stream("quantum computing")
+
+for event in stream:
+    if event.kind == "text_delta" and event.text:
+        print(event.text, end="", flush=True)
+
+stream.run.trace.print()   # blocks until settled; the full trace, same events
+```
+
+The full vocabulary an event's `kind` can take (`composeai.events.Event.kind`) is `span_started`, `text_delta`, `thinking_delta`, `tool_call_started`, `tool_args_delta`, `tool_call_finished`, `span_finished`, `paused`, and `run_finished` — the same events tracing is built from, on agents, pipelines, and flows alike, so a live UI and `compose trace` can never disagree about what happened.
+
+## See also
+
+[composition](composition.md) wires agents together into pipelines with build-time type checking; [flows](flows.md) makes a sequence of agent calls durable and resumable; [testing](testing.md) covers `FakeModel` for testing agents with no network.

composeai-0.3.0/docs/budgets.md

@@ -0,0 +1,148 @@
+# Budgets
+
+`Budget(usd=..., tokens=...)` caps spend across every LLM call in a run's subtree — pass it to `.run()`/`.stream()` (or the bare call form) on an `@agent`, a `pipe`/`aggregate`, or a `@flow`, and composeai raises `BudgetExceededError` the instant a call pushes the running total past the cap.
+
+## `Budget(usd=, tokens=)`
+
+```python
+import composeai as compose
+from composeai import Budget
+
+
+@compose.agent(model="anthropic/claude-sonnet-5")
+def researcher(topic: str) -> str:
+    """You are a researcher."""
+    return compose.prompt(f"Summarize: {topic}")
+
+
+researcher.run("quantum computing", budget=Budget(usd=0.50, tokens=200_000))
+```
+
+At least one of `usd`/`tokens` must be set — an empty `Budget()` couldn't enforce anything, so the constructor raises `ConfigError` immediately. Pass either alone, or both:
+
+```python
+Budget(usd=1.0)                     # dollars only
+Budget(tokens=100_000)              # tokens only
+Budget(usd=1.0, tokens=100_000)     # both -- either crossing the line trips it
+```
+
+Enforcement happens after every LLM call across the whole run's subtree, not just at the top level: an `@agent` nested inside a `pipe`, an `aggregate` branch, or a step inside a `@flow` all count against a budget passed to an enclosing `.run()` call. `check_budgets()` walks every active budget on the stack each time — a nested, tighter budget and an enclosing, looser one are both live at once (see "Nesting" below).
+
+## What counts
+
+`tokens` is input+output tokens combined, summed across every LLM call in the subtree. This is exact regardless of pricing — a token budget sees every call's usage no matter what model it hit.
+
+`usd` only counts calls with a known price. An adapter that can't price a call reports `Usage(cost_usd=None)`, and that call's cost is treated as `0` for budgeting purposes — a `usd` budget simply can't see spend it has no price for. This is the same unpriced-model caveat `compose costs` has: cost is never fabricated, so a call with no registered price is invisible to `Budget(usd=...)`, not silently counted as free spend against you.
+
+If you're on an OpenAI-compatible server with a real bill (ollama.com, a hosted vLLM instance) and want `usd` to actually see that spend, register a price — either `input_price=`/`output_price=` on `compose.openai_compatible(...)`, or `composeai.register_price(provider, model, composeai.ModelPrice(input=..., output=...))` directly. See [providers](providers.md) for both forms. **Pass `tokens` too if you need a hard cap regardless of pricing** — it's the one budget dimension that never depends on a price table.
+
+## Cumulative spend across `resume()`
+
+A `budget=` passed to a run's original `.run()` call stays enforced across every later `resume()` of that run: spend already persisted by earlier attempts counts against the cap, and replayed steps themselves cost nothing (they don't re-issue LLM calls, so they add zero to the running total). A run can't dodge its budget by pausing or crashing and getting resumed with the clock reset.
+
+Worked example — a two-step flow under a 15-token budget, each step scripted to cost exactly 10 tokens (5 in + 5 out) via `FakeModel`:
+
+```python
+import composeai as compose
+from composeai import Budget, resume
+from composeai.messages import Usage
+from composeai.testing import FakeModel
+
+model = FakeModel(["first", "second"], usage=Usage(input_tokens=5, output_tokens=5))
+
+
+@compose.agent(model=model)
+def spender(prompt: str) -> str:
+    """Spend some tokens."""
+    return prompt
+
+
+@compose.flow
+def two_step() -> str:
+    spender("one")                       # 10 tokens -- lifetime total 10, under the 15 cap
+    if not compose.approve("continue"):
+        return "stopped"
+    spender("two")                       # 10 more -- lifetime total 20, over the cap
+    return "done"
+
+
+run = two_step.run(budget=Budget(tokens=15))
+run.status   # "paused" -- the first spend landed at 10, still under the cap
+
+# resume() re-attempts the flow: the first step replays (0 new tokens,
+# journaled), then the second step actually runs, adding 10 more on top of
+# the persisted 10 from the paused attempt -- lifetime total 20 exceeds the
+# 15-token cap, so this raises instead of quietly completing:
+resume(run.id, answers={"continue": True})   # raises BudgetExceededError
+```
+
+Without this accumulation, a resumed attempt would start counting from zero and could complete happily inside a cap the run's *total* spend has already blown past. The same rule applies one level down: a nested `@agent`'s *own* `budget=` (passed on its own `.run()` call, not the flow's) is cumulative across a pause/resume of that same step specifically — only that step's earlier attempts count against its own cap, never a sibling step's spend.
+
+## Per-call agent budgets vs. flow budgets (nesting)
+
+A budget passed to an `@agent`'s own `.run()`/`.stream()` call and a budget passed to an enclosing `pipe`/`aggregate`/`@flow`'s `.run()` are both enforced simultaneously — nesting doesn't replace the outer cap, it adds a second one:
+
+```python
+import composeai as compose
+from composeai import Budget
+from composeai.messages import Usage
+from composeai.testing import FakeModel
+
+inner_model = FakeModel(["inner out"], usage=Usage(input_tokens=10, output_tokens=10))
+outer_model = FakeModel(["outer out"], usage=Usage(input_tokens=10, output_tokens=10))
+
+
+@compose.agent(model=inner_model)
+def inner_agent(x: str) -> str:
+    """Inner."""
+    return x
+
+
+@compose.agent(model=outer_model)
+def outer_agent(x: str) -> str:
+    """Outer."""
+    return x
+
+
+def middle_stage(x: str) -> str:
+    # A tighter budget than the enclosing pipe's -- both are checked.
+    run = inner_agent.run(x, budget=Budget(tokens=5))
+    return run.output
+
+
+pipeline = compose.pipe(outer_agent, middle_stage)
+pipeline.run("go", budget=Budget(tokens=1000))   # generous outer cap...
+# ...but inner_agent's own 5-token budget trips first, since it's tighter.
+```
+
+Whichever budget's cap is crossed first raises — an inner, tighter budget commonly trips before an outer, looser one ever would, but there's no ordering rule beyond "whoever crosses their own line first."
+
+## `resume(budget=)` override
+
+`resume(run_id, budget=...)` replaces the run's stored budget for this attempt **and every later one** — a plain last-write-wins update to the row, not journaled (the journal is first-write-wins, which would otherwise freeze the very first override forever):
+
+```python
+resume(run.id, answers={"continue": True}, budget=Budget(usd=5.0))
+```
+
+Prior attempts' real spend still counts against the new cap — raising the limit doesn't erase what was already spent, it only moves the ceiling. Omitting `budget=` (the default, `None`) keeps whatever budget was already stored; there's no way to *clear* a budget via `resume()` once one is set.
+
+## `BudgetExceededError` handling
+
+`BudgetExceededError` is a `ComposeError`, raised by the budget check immediately after the LLM call that crossed the line — the call itself already happened (and was already billed/journaled); the error just stops the run from making another one. Its message names the span that tripped it, plus the configured cap and the usage that exceeded it:
+
+```python
+from composeai.errors import BudgetExceededError
+
+try:
+    researcher.run("quantum computing", budget=Budget(usd=0.50))
+except BudgetExceededError as exc:
+    print(exc)
+    # budget exceeded on agent 'researcher': usd budget=0.5, used=$0.6231
+```
+
+Inside a `@flow`, an uncaught `BudgetExceededError` fails that run the same way any other uncaught exception would — the run's row is marked `"failed"` and the exception propagates out of `.run()`/`resume()`. A common pattern is to catch it at the call site, inspect what already ran (`compose trace <run_id>`), and either raise the cap and `resume()`, or accept the partial result and stop.
+
+## See also
+
+[agents](agents.md) covers `.run()`/`.stream()`'s other keyword-only arguments; [composition](composition.md) covers `budget=` on a top-level `pipe`/`aggregate` call; [flows](flows.md) covers `resume()` in full, including `answers=`/`allow_code_change=`; [providers](providers.md) covers `input_price=`/`register_price` for making `usd` spend visible on an unpriced or compatible-server model.