Metadata-Version: 2.4
Name: petrarca-agent-flow
Version: 0.20.0
Summary: Deterministic orchestration of coding-agent pipelines (supervised subprocesses, DAG, bounded re-runs).
Author-email: Wolfgang Miller <wolfgang.miller@petrarca-labs.com>
License-Expression: Apache-2.0
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Requires-Python: <4.0,>=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: anyio>=4.0
Requires-Dist: loguru>=0.7
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pydantic>=2.12.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: jsonschema>=4.0
Requires-Dist: universal-pathlib>=0.3.0
Provides-Extra: cli
Requires-Dist: typer>=0.13.0; extra == "cli"
Requires-Dist: rich>=13.0; extra == "cli"
Provides-Extra: all
Requires-Dist: typer>=0.13.0; extra == "all"
Requires-Dist: rich>=13.0; extra == "all"
Provides-Extra: dev
Requires-Dist: petrarca-agent-flow[all]; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: setuptools-scm; extra == "dev"
Requires-Dist: import-linter; extra == "dev"
Requires-Dist: agent-client-protocol>=0.12.1; extra == "dev"
Dynamic: license-file

# agent-flow — deterministic orchestration of coding agents

**agent-flow is a Python library for deterministic orchestration of coding-agent
pipelines.** It runs coding agents — **OpenCode**, **Claude Code**, **oh-my-pi** —
as **supervised processes** in a graph: parallel steps, checks between steps,
bounded re-runs, typed output, and a written verdict from each agent as the only
measure of success.

It orchestrates coding agents that run as their own process with their own agent
loop, tools and model access. Agents you build in your own program (PydanticAI,
LangGraph, plain Python) run in the same graph as in-process steps.

agent-flow replaces the fragile "LLM orchestrator agent" pattern — where a model
is asked to sequence the stages and hangs, loops, or loses the thread — with a
**deterministic engine** that runs the agents as a graph and supervises each one.

> Unrelated to other projects named "agent flow" / "AgentFlow". The PyPI
> distribution is **`petrarca-agent-flow`**; the import package is `agent_flow`.

## Why agent-flow exists

1. **Deterministic orchestration.** The control flow is a dependency graph the
   engine executes, with parallel fan-out and bounded jump-backs. No model
   decides what runs next, so the same inputs run the same stages in the same
   order.

2. **Supervised agents.** A coding agent can hang, crash, or misreport.
   agent-flow supervises by **liveness** — an agent is stopped when it goes
   silent, not after a fixed time — and takes the verdict from a small JSON file
   the agent writes, never from its prose.

3. **A controlled input plane.** Each prompt is composed from ordered channels:
   the completion protocol, run-wide context, the node's context and
   instructions, its work order. The engine injects file content, so an agent
   has the rules in front of it instead of being told to go read them.

4. **Runtime-agnostic.** The coding agent behind a node is a choice of runtime:
   OpenCode as a one-shot CLI, or any [Agent Client Protocol](https://agentclientprotocol.com)
   agent (OpenCode, oh-my-pi, Claude Code) over one shared transport. The flow
   does not change.

5. **A programming model for external agents.** Workflow engines run graphs but
   know nothing about agents; agent frameworks know agents but run them inside
   your program. agent-flow brings typed input and output, a context plane,
   checks and bounded re-runs to agents running as external processes — and to
   in-process agents in the same graph.

## What it looks like

A flow is data: nodes, their inputs and how they depend on each other. An
analyst writes a report; a verifier checks it and may send the analyst back to
redo it.

```python
from agent_flow import FlowDef, NodeDef, run_flow

flow = FlowDef(
    name="tech",
    nodes=[
        NodeDef(name="tech-stack", agent="tech-stack-analyst",
                inputs={"PRODUCT_KEY": "{product_key}", "REPORT": "{run_dir}/tech-stack.md"}),
        NodeDef(name="tech-stack-verify", agent="tech-stack-verifier", depends_on=["tech-stack"],
                inputs={"REPORT": "{run_dir}/tech-stack.md"}, rerun_targets=["tech-stack"]),
    ],
)

run_flow(flow, product_key="acme", runtime="opencode")
```

The same flow runs from a generated command line, inside a host application, or
on an event loop. [Getting started](docs/usage/getting-started.md) walks through
it.

## Capabilities

**Building flows**

- **Flows as data** — a pipeline is a serializable definition, validated before
  it runs; your code (checks, exports, components) is registered by name and
  referenced from it.
- **Node kinds** — a node runs a coding agent, your own Python code, an external
  program (a scanner, a converter), or a whole other flow.
- **Subflows** — reuse a flow as one node: it gets the node's inputs, returns
  its declared outputs, and is tracked and resumed inside the calling run.
- **Flow results** — a flow declares what it returns, from its params and its
  nodes' results.
- **Typed input and output** — schemas for a node's inputs and its result,
  validated on the way in and out.
- **Exports** — a node publishes values from its result for later nodes to use.

**Controlling a run**

- **Parallel steps and dependencies** — independent nodes run concurrently,
  bounded by a concurrency limit; cycles and unknown dependencies fail before
  the run.
- **Checks after a node** — continue, re-run, jump back to an earlier node,
  suspend for a human, or stop. Ready-made checks cover required files and
  valid JSON.
- **Decisions before a node** — skip work that is not needed, rule a node out,
  or halt before it starts.
- **Agent-requested re-runs** — a verifier agent may ask to re-run the step it
  checked, within limits the flow grants.
- **Human in the loop** — a check, a pre-condition, or the node's own work can
  suspend the run; resuming continues there, optionally with the human's answer
  handed to that node.
- **Retries and criticality** — a hung or crashed agent is retried; a failing
  node either stops the run or degrades and lets it continue.

**Running and resuming**

- **Persist and resume** — an optional state store checkpoints the run after
  every step; running again continues where it stopped, with the real upstream
  results. Restart from the top, start partway, or run a single node as a probe.
- **Supervision** — agents and programs are stopped when they go silent or the
  run is cancelled, with their whole process group.
- **Live progress** — a live table or a per-event stream on the command line,
  and the same events for a host application.
- **A command line for your flows** — run, inspect the nodes, and version one or
  many pipelines, with layered settings (flags, environment, config files).
- **Async-first, sync-friendly** — embed a flow in your own event loop; agents,
  checks and components may be sync or async.

**Agents**

- **In-process agents** — a Python agent (e.g. PydanticAI) runs as a node with
  the same contract as a coding agent, typed at both ends, reporting its own
  token usage.
- **Pluggable harnesses** — a harness (opencode, Claude Code, oh-my-pi, Codex, or
  one you bring) bundles its runtimes, how it defines agents, how it is
  configured and how it is installed. agent-flow's own are registered like a
  plug-in, so an in-process runtime (PydanticAI, say) or an external harness
  plugs in from your code or an installed package — and the registry answers
  which harnesses are registered and installed, in which versions.
- **Agent catalog** — read what coding harnesses define in a repository (its
  `AGENTS.md`/`CLAUDE.md` rules, agent definitions, skills, tool permissions) as
  neutral data, so an in-process agent reuses an existing definition instead of
  restating it.
- **Mock agents** — deterministic stand-ins that run a whole pipeline without
  tokens, for tests and development.

## Installation

```bash
pip install "petrarca-agent-flow[cli]"
```

Requires Python 3.14+. For real runs, the coding agent you target must be
installed and configured with model access. The core install is lean; the
command line and live display come with the `[cli]` extra. Details:
[getting started](docs/usage/getting-started.md).

## Documentation

- **Using the library** — getting started, writing agents, recipes, testing,
  your own CLI, the agent catalog: [`docs/usage/`](docs/usage/index.md).
- **Design** — the architecture and why, one document per concept:
  [`docs/design/`](docs/design/index.md).
- **Decisions** — the architecture decision records: [`docs/adr/`](docs/adr/index.md).
- **Examples** — runnable flows in [`examples/`](examples/), each with a
  token-free mock mode.

## Development

`task fct` is the local loop (format, lint, typecheck, unit tests). The full
task list and the coding standards are in [`CONTRIBUTING.md`](CONTRIBUTING.md).

## Contributing & License

Contributions are welcome — see [`CONTRIBUTING.md`](CONTRIBUTING.md) for the
workflow and conventions (and [`AGENTS.md`](AGENTS.md) if you use an AI coding
assistant). Licensed under the Apache License 2.0 — see [`LICENSE`](LICENSE).
