petrarca-agent-flow 0.1.0__tar.gz

petrarca_agent_flow-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,97 @@
+name: CI
+
+# Build-only CI: lint, format-check, tests, and build the package.
+# Publishing to PyPI + the GitHub Release happen on a version tag (v*) via
+# publish.yml / release.yml, not here.
+
+on:
+  push:
+    branches: [main]
+    paths-ignore:
+      - '**/*.md'
+  pull_request:
+    branches: [main]
+    paths-ignore:
+      - '**/*.md'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Lint + Test
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    strategy:
+      matrix:
+        python-version: ['3.14']
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0  # setuptools-scm needs full history for the version
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+        with:
+          enable-cache: true
+
+      - name: Install Task
+        uses: arduino/setup-task@v3.0.0
+        with:
+          version: 3.x
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install dependencies (editable + dev extras)
+        run: task install
+
+      - name: Lint + format check (read-only)
+        run: task verify
+
+      - name: Unit + integration tests (mock; opencode e2e is skipped)
+        run: task test:all
+
+  build:
+    name: Build package
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    needs: test
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python 3.14
+        uses: actions/setup-python@v7
+        with:
+          python-version: '3.14'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+        with:
+          enable-cache: true
+
+      - name: Install Task
+        uses: arduino/setup-task@v3.0.0
+        with:
+          version: 3.x
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build sdist + wheel
+        run: task build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v7
+        with:
+          name: dist-${{ github.sha }}
+          path: dist/
+          retention-days: 7

petrarca_agent_flow-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,82 @@
+name: Publish to PyPI
+
+# Publish on a version tag. setuptools-scm derives the version from the tag
+# (see [tool.setuptools_scm] tag_regex "^v..."), so tagging vX.Y.Z is the release
+# trigger. Trusted publishing (OIDC) is used — no API token secret needed; the
+# PyPI project must have this repo configured as a trusted publisher for the
+# `pypi` environment.
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: read
+  id-token: write  # Required for trusted publishing (OIDC)
+
+jobs:
+  test:
+    name: Lint + Test
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0  # setuptools-scm needs full history for the version
+
+      - name: Set up Python 3.14
+        uses: actions/setup-python@v7
+        with:
+          python-version: '3.14'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+        with:
+          enable-cache: true
+
+      - name: Install Task
+        uses: arduino/setup-task@v3.0.0
+        with:
+          version: 3.x
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install dependencies (editable + dev extras)
+        run: task install
+
+      - name: Lint + format check (read-only)
+        run: task verify
+
+      - name: Unit + integration tests (mock; opencode e2e is skipped)
+        run: task test:all
+
+  publish:
+    name: Build + Publish to PyPI
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    needs: test
+    environment: pypi
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0  # Required for setuptools-scm
+
+      - name: Set up Python 3.14
+        uses: actions/setup-python@v7
+        with:
+          python-version: '3.14'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v9.0.0
+        with:
+          enable-cache: true
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

petrarca_agent_flow-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,29 @@
+name: Release
+
+# Create a GitHub Release with auto-generated notes on a version tag. Runs
+# alongside publish.yml (both trigger on 'v*'); this one only creates the
+# Release entry, publish.yml uploads to PyPI.
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v3
+        with:
+          generate_release_notes: true

petrarca_agent_flow-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+.venv/
+.prefect/
+.env
+__pycache__/
+*.pyc
+*.egg-info/
+.ruff_cache/
+dist/
+build/
+
+.DS_Store
+
+# Example RUN ARTIFACTS — reports/sidecars agents write during a demo run when
+# run_dir/REPORT resolves into the example dir (normal runs go to /tmp). Agent
+# DEFINITIONS under examples/**/.opencode/agent/ are tracked and NOT ignored.
+examples/*/*.md
+examples/*/*.json
+examples/*/*.control.json
+
+# JS deps accidentally created under an example's .opencode/
+node_modules/

petrarca_agent_flow-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,37 @@
+###############################
+# pre-commit configuration
+#
+# Strategy:
+# - Use only "local" hooks so we orchestrate via Taskfile tasks (single source
+#   of truth for how we lint/format/test).
+# - Split fast feedback (pre-commit) from deeper validation (pre-push).
+# - pass_filenames: false because the tasks already know what to operate on.
+#
+# Tips:
+# - Skip all hooks:     git commit -m "msg" --no-verify
+# - Run manually:       task fct
+# - Install the hooks:  task pre-commit:install
+# - Update the hooks:   task pre-commit:update
+###############################
+repos:
+  - repo: local
+    hooks:
+      # Pre-commit (fast): format + lint(+fix) + unit tests.
+      - id: fct
+        name: "format + check + unit tests (quick)"
+        entry: bash -c 'task fct'
+        language: system
+        pass_filenames: false
+        files: \.py$
+
+      # Pre-push (deeper): read-only lint/format gate + unit tests. Integration
+      # (mock subprocess) and the real-opencode e2e are deliberately NOT run here
+      # — they are slower / opt-in; run them explicitly with `task test:all` /
+      # `task test:opencode` when needed.
+      - id: verify-and-test
+        name: "pre-push: verify + unit tests"
+        entry: bash -c 'task verify && task test'
+        language: system
+        pass_filenames: false
+        files: \.py$
+        stages: [pre-push]

petrarca_agent_flow-0.1.0/AGENTS.md

@@ -0,0 +1,193 @@
+# Agent Instructions
+
+This file contains project-specific rules and conventions for AI coding
+assistants working on **agent-flow**.
+
+## Project Overview
+
+agent-flow is a Python library for **deterministic orchestration of coding-agent
+pipelines**. It replaces the fragile "LLM orchestrator agent" pattern with a
+deterministic engine that supervises coding-agent subprocesses (opencode today)
+and runs them as a graph — with parallelism, bounded re-runs, cross-node
+jump-back, telemetry, and optional typed output. The execution backend
+(in-process default / opt-in Prefect) and the agent runtime (opencode / Claude
+Code / …) are both pluggable.
+
+### The three usage tiers (high level → low level)
+
+- **Tier 3 — declarative**: declare `Node`s, call `build_flow` → a runnable flow
+  callable that dispatches execution to the selected backend. `agent_node` builds
+  a node that runs one agent in one call.
+- **Tier 2 — primitives in your own flow**: call `run_agent` as the leaf of a
+  hand-written flow (a consumer may hand-write a Prefect flow around it — the toy
+  example does).
+- **Tier 1 — engine core**: `run_agent` spawns + liveness-supervises + kills +
+  reads the control sidecar. Runtime-agnostic; no Prefect.
+
+The dependency direction is strictly downward: **Tier 3 (`engine.py`) must not
+import Tier 1** (`core.agent_runtime`/`runners`) — they meet only through a
+node's `run` callable. `batteries.py` is the single module allowed to bridge
+both.
+
+## Project Structure
+
+```
+src/agent_flow/
+  __init__.py            # Public API exports (keep in sync with what ships)
+  engine.py              # Node / RunContext / build_flow / plan_groups / interpret / _walk (Tier 3)
+  batteries.py           # agent_node — one-call node (bridges engine + run_agent)
+  gates.py               # Directive (Continue/Restart/GoTo/Stop) + GateContext + ready gates
+  run_config.py          # RunConfig (pydantic-settings) / build_run_config / get_settings lifecycle
+  run_context.py         # RunContextService — open domain params + exports
+  preflight.py           # runtime pre-flight checks (opencode/agent_dir/prefect) -> Check results
+  utils.py               # resolve_run_dir / default_temp_base / require_extra (pure top-level leaf)
+  core/                  # Tier-1 primitives, GUARANTEED backend-free (run_agent,
+                         #   control protocol, result-schema, context ingestion, env)
+  runners/               # agent-runtime seam (AgentRunner Protocol) + get_runner registry
+  backends/              # execution seam (FlowBackend ABC) + get_backend;
+                         #   inprocess default, prefect opt-in (DEFAULT_BACKEND="inprocess")
+  cli/                   # run_cli + display helpers (typer/rich, opt-in [cli] extra)
+examples/
+  toy_pipeline/          # Tier-2 demo (hand-written flow) + its .opencode/agent/*.md
+  tech_assessment/       # Tier-3 demo (declared graph) + its .opencode/agent/*.md
+docs/
+  usage/                 # consumer OKF bundle (getting-started, writing-agents, recipes)
+  design/orchestrator/   # design OKF bundle (one concept per file; start at index.md)
+deploy/                  # docker-compose (Prefect server + Postgres) for persistent mode
+```
+
+## Running commands (full output)
+
+When running a command whose output matters, capture and read the FULL output —
+do not truncate with `tail`, `head`, `grep`, or similar. Truncation hides errors,
+stack traces, and warnings that appear outside the visible window. Prefer piping
+through `tee` to a file and reading the whole file:
+
+```bash
+some-command 2>&1 | tee /tmp/out.log   # then read /tmp/out.log in full
+```
+
+This is especially important for `task fct`, the examples, and any run that can
+fail partway — the interesting line is rarely the last one.
+
+## Build & Test
+
+House-standard task names (same across petrarca repos):
+
+```bash
+task setup         # create the venv
+task install       # editable install with dev tools
+task fct           # format + check (lint) + test — run before committing
+task format        # ruff format
+task check         # ruff check --fix
+task verify        # CI gate: lint + format check, read-only
+task test          # unit tests (fast)
+task test:unit     # unit tests only
+task test:integration  # integration (mock subprocess)
+task test:all      # unit + integration
+task test:opencode # opt-in real-opencode e2e (needs opencode; run OUTSIDE an opencode session)
+task build         # build sdist + wheel
+task rebuild:all   # clean + install + format + check + test:all + build
+task clean         # remove build artifacts and caches
+task pre-commit:install   # install git pre-commit + pre-push hooks
+task pre-commit:update    # update pinned hook versions
+task pre-commit:run       # run all hooks against the tree
+```
+
+Run the examples:
+
+```bash
+task example:toy:mock  TOPIC="Ports and Adapters"
+task example:tech:mock PRODUCT=my-product
+task example:tech      PRODUCT=my-product RUNTIME=opencode SHOW_EVENTS=--show-events
+```
+
+> Real-opencode runs must start from a normal shell **outside** an opencode
+> session (a nested opencode raises `UnknownError`).
+
+## Core Concepts (do not violate)
+
+### The control-file contract
+
+An agent signals completion by writing a JSON **control sidecar** — the SOLE
+verdict. The library injects the protocol into the prompt
+(`build_control_preamble`); agent `.md` files carry only domain instructions.
+
+- **Envelope (engine reads):** `status` (`ok`/`verified`/`error`), `agent`,
+  `reason`, and `rerun_required` (a flow-control signal a gate consumes).
+- **Payload (only gates/consumers read):** `result` — free-form dict. The engine
+  never looks inside.
+- **No `artifact` field** — what an agent produces is expressed in the files it
+  was told to write, not reported back.
+- **No sidecar → error.** The engine never inspects artifacts to guess success.
+
+### Two directories (never conflate)
+
+- **`run_dir`** — where control sidecars + relative artifact paths resolve. NOT a
+  cwd. Unset → a fresh temp dir under `<temp>/agent-flow/` (ephemeral; pass an
+  explicit `run_dir` for output you keep). Resolved once per run via
+  `utils.resolve_run_dir`.
+- **`agent_dir`** — where agent DEFINITIONS live (opencode `--dir`); becomes the
+  subprocess cwd. Global default via `build_flow(agent_dir=)`, per-node override
+  via `agent_node(agent_dir=)`.
+
+### Gates are the consumer's optional hook
+
+A gate `(GateContext) -> Directive` decides flow control AFTER an agent runs. The
+engine never auto-fails on schema/artifact issues — a gate does. A verifier is
+NOT a library concept: it is just another node that `depends_on` its subject and
+returns `GoTo(subject)`.
+
+### Typed output
+
+`result_schema` is an opt-in convenience. `ctx.result["result"]` is always the
+dict (validated if a schema was attached). `ctx.result["_result_obj"]` is a
+Pydantic model instance ONLY when a `PydanticSchema` was used, else `None` (a
+dict schema / no schema add no new object).
+
+### The input plane (prompt composition order)
+
+`[control protocol] [run-wide context] [run-wide brief] [per-node context]
+[per-node instructions] [work order]`. "Context" = FILE CONTENT ingested by the
+library (the fix for "agents don't read the rules"); "instructions" = inline
+text. Any `pipeline(**params)` key is a `{name}` template usable in
+inputs/context/paths. To hand a value TO the agent, put it in `inputs`.
+
+## Code Quality
+
+- Ruff `E, F, B, I, C90`, line length **150**, McCabe max-complexity **10**.
+- No bare `except Exception`; catch concrete types. `except A, B:` (no `as`) is
+  valid Python 3.14 (PEP 758) — do not flag it.
+- Dependencies are a lean core plus opt-in extras. Core (always installed):
+  pydantic, pydantic-settings, pyyaml, jsonschema, python-dotenv — enough to
+  declare a pipeline and run it on the default InProcessBackend. The heavy pieces are
+  extras matching the runtime seams: `[prefect]` (the opt-in PrefectBackend) and
+  `[cli]` (typer + rich for `run_cli` / display); `[all]` is both, `[dev]` adds
+  the tooling. An optional dep is lazy-imported at its entry point only — prefect
+  inside `backends/prefect.py`, rich/typer inside `cli/` — guarded by
+  `utils.require_extra(...)` so a missing extra fails with an actionable
+  "install agent-flow[...]" message.
+- When adding a public symbol, export it in `src/agent_flow/__init__.py` and keep
+  the module-docstring "Public API" example current.
+
+## Git Conventions
+
+- Commit prefixes: `feat:`, `fix:`, `refactor:`, `chore:`, `docs:`, `test:`.
+- Short messages, max ~two sentences per point.
+- **Run `task fct` (format + check + test) before every commit** and make sure it
+  passes. The pre-commit hook enforces this, but run it yourself first — never
+  commit code that has not passed `task fct`.
+- **Never commit or push implicitly.** Do not run any git write operation
+  (`commit`, `push`, `merge`, `rebase`, `tag`, `reset --hard`, etc.) unless the
+  user has explicitly instructed it for that specific action. Do not chain a
+  commit/push onto another task on your own initiative. When in doubt, stop and
+  ask. Read-only git (`status`, `log`, `diff`) is fine without asking.
+- `main` is the default branch. Do not commit `work*`, `.venv`, `.env`, caches,
+  or `node_modules` (all gitignored).
+
+## Documentation
+
+Docs are OKF bundles (`docs/usage/`, `docs/design/orchestrator/`) — every file
+has a `type` frontmatter field. When you change behavior, update the matching
+concept doc and verify code snippets run. The README covers install + the three
+tiers + running the examples.

petrarca_agent_flow-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,121 @@
+# Contributing to agent-flow
+
+Thank you for considering contributing to agent-flow! This document outlines the
+process for contributing and the conventions that keep the project consistent.
+
+## Code of Conduct
+
+By participating in this project, you agree to maintain a respectful and
+inclusive environment for everyone.
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.14+
+- [`uv`](https://docs.astral.sh/uv/) package manager
+- [`task`](https://taskfile.dev/) (go-task)
+- For real (non-mock) runs: `opencode` on `PATH`, configured with model access
+
+### Setting up the development environment
+
+```bash
+git clone <your-fork-url>
+cd agent-flow
+task install       # editable install with dev tools (ruff, pytest, pydantic, jsonschema, typer, rich, pyyaml)
+```
+
+## Development workflow
+
+### Branch naming
+
+Use descriptive branch names with prefixes:
+
+- `feat/` — new features
+- `fix/` — bug fixes
+- `docs/` — documentation changes
+- `refactor/` — code refactoring
+- `test/` — tests only
+
+Example: `feat/claude-code-runner`
+
+### Coding standards
+
+- Ruff for linting and formatting, rules `E, F, B, I, C90`, line length **150**.
+- McCabe max complexity **10** — refactor complex functions into helpers.
+- Type-annotate public functions.
+- No bare `except Exception` — catch concrete types (note: `except A, B:` without
+  `as` is valid Python 3.14 per PEP 758; do not "fix" it to parentheses).
+- Keep the **core** dependency-light. Core deps (always installed): `pydantic`,
+  `pydantic-settings`, `pyyaml`, `jsonschema`, `python-dotenv`. Optional extras:
+  `[prefect]` (the Prefect backend) and `[cli]` (`typer` + `rich`). An optional
+  dep must be **lazy-imported at its entry point**, never at module-import time —
+  `prefect` only inside `backends/prefect.py`, `rich`/`typer` only inside `cli/`.
+  Guard the entry-point import with `utils.require_extra(...)` so a missing extra
+  fails with an actionable "install agent-flow[...]" message. The
+  `test_prefect_isolation` guard proves core + runners + InProcessBackend import and
+  run with `prefect` blocked.
+- Respect the layering: the engine (Tier 3) must not import the runtime core
+  (Tier 1); they meet only through a node's `run` callable (`batteries` is the
+  one bridge). See `docs/design/orchestrator/index.md`.
+
+### Testing
+
+```bash
+task test              # unit tests (fast, no subprocess)
+task test:all          # unit + integration (mock subprocess; opencode e2e skipped)
+task test:opencode     # opt-in real-opencode e2e (needs opencode + creds; run OUTSIDE an opencode session)
+```
+
+Run real-opencode examples/e2e from a normal shell **outside** an opencode
+session — a nested opencode raises `UnknownError`.
+
+### The local loop
+
+```bash
+task fct     # format + check (lint) + test — run before every commit
+task verify  # CI gate: lint + format check, read-only (no fixes)
+```
+
+## Documentation
+
+Design docs and consumer docs are [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
+bundles under `docs/`:
+
+- `docs/usage/` — task-oriented consumer guides (start at `index.md`)
+- `docs/design/orchestrator/` — architecture + one concept per file
+
+When you change behavior, update the relevant doc and keep every OKF file's
+`type` frontmatter intact. Verify code snippets actually run.
+
+## Pull request process
+
+1. Update docs and the README for any behavior/API change.
+2. Run `task fct` — lint, format, and tests must pass.
+3. Submit a PR with a clear description of the change.
+4. Address review feedback.
+
+## Commit messages
+
+Short, clear, category-prefixed (conventional-commits style):
+
+```
+<type>(<optional scope>): <description>
+```
+
+Types: `feat`, `fix`, `docs`, `refactor`, `test`, `chore`.
+Example: `feat(cli): add --config run-file support`.
+
+## Reporting bugs
+
+Include: a clear title, steps to reproduce, expected vs. actual behavior, and
+environment details (OS, Python version, opencode version if relevant).
+
+## Feature requests
+
+Provide a clear description, the motivation, and any implementation thoughts.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the
+Apache License 2.0 (see `LICENSE`).