fancy-flow 0.1.0__tar.gz

fancy_flow-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+.venv/
+venv/
+.env

fancy_flow-0.1.0/AGENTS.md

@@ -0,0 +1,196 @@
+# AGENTS.md — fancy-flow-py
+
+Python runtime for `fancy-flow` workflow graphs. The framework-free twin of
+`@particle-academy/fancy-flow`'s TypeScript engine and of
+`particle-academy/fancy-flow-php`. `CLAUDE.md` symlinks here.
+
+This file describes **this package's code**. Process rules — publishing, kit
+versioning, backports, the issue protocol — live in the envelope's `AGENTS.md`
+and are deliberately not repeated.
+
+## What this package is
+
+A faithful **port**, not a redesign. Behaviour questions are settled against the
+peers, in this order: `@particle-academy/fancy-flow`'s `src/runtime/run-flow.ts`
+and `src/registry/*` for the contract, `particle-academy/fancy-flow-php` for how
+a *server* twin realises it.
+
+The guarantee: **same `WorkflowSchema` JSON in, same `RunResult.outputs` out**
+on Node, PHP and Python. Don't break it.
+
+Where this port deliberately differs from a peer, the difference is in a
+docstring at the point of divergence and in the envelope plan. There are three
+as of 0.1.0, and all three are listed under "Deliberate divergences" below.
+
+## Architecture
+
+Pure core, `src/` layout, **zero runtime dependencies**.
+
+- `workflow.py` — import / export / validate WorkflowSchema v1.
+- `engine/runner.py` — `FlowRunner`, the `runFlow` port. Kahn topo, ports,
+  branching, cycles, timeout, resume. **A node runs when ≥1 incoming edge is
+  active** (merge-after-decision, `#1`) and `_collect_inputs` reads only active
+  edges. Don't regress either.
+- `registry/` — `NodeKindRegistry`, `NodeKind`, `ConfigField`, `kind_id`, and
+  `builtin` (the 24 authorable kinds, plus structural `note` and `subgraph`,
+  and a default executor for each one that executes -- `note` never does).
+- `executors.py` — `ExecutorRegistry`; resolves node id → kind → `*`.
+- `runtime/` — `RunEvent`, `RunOptions`, `RunResult`, `ExecutionContext`,
+  `Port`, `Pause`, `AbortSignal`, `RunIdentity`.
+  **`RunIdentity` is what a WRITING node keys an idempotent call on.**
+  `ctx.run.step_key(ctx.node.id)` is the same on every retry of one step and
+  different for every other execution of the same node — which is why `attempt`
+  is carried on it and is NOT part of the key. `(run, node)` alone is
+  insufficient: a node runs once per subflow invocation and once per loop
+  iteration, so the key composes the invocation `path` and an optional
+  `occurrence`. `is_replay_safe()` says whether a retry is still inside the
+  provider's dedup window; past it the caller must REFUSE, because resending the
+  key and minting a fresh one both write twice. Pinned by
+  `shared/flow-run-identity`; the other two runtimes implement the same table.
+- `nodes/` — the default executors by domain, plus `nodes/support/` (injectable
+  client protocols, offline fakes, the `{{ }}` resolver, structured output).
+- `capabilities/` — the HOST seam: `LlmClient` (`choose_route`, used by
+  `llm_router`) and `WorkflowResolver` (used by `subflow`).
+- `durable/` — resumable runs with **no queue library**: the claim contract, the
+  frontier, per-node replay, retry policy, human gates, and the coordinator.
+- `security/policy.py` — `GraphPolicy`, for a graph that arrived over the wire.
+- `marketplace/manifest.py` — node-manifest validation and `satisfies_range`.
+
+### The engine is one walk, driven two ways
+
+TypeScript executors may be `async`; PHP's are synchronous. Python has both, and
+writing the loop twice would put two copies of the routing rules in the file
+that exists to have exactly one.
+
+So `FlowRunner._walk` is a **generator**: it yields a node to execute and is sent
+the outcome back. `run()` drives it synchronously; `arun()` drives the same
+generator while awaiting awaitable results. Add behaviour to `_walk`, never to a
+driver.
+
+`run()` refuses an awaitable rather than storing it. A coroutine object sitting
+in `outputs[node]` looks like success and reaches every downstream node as a
+value nothing can read.
+
+### The durable layer, and why it is not Temporal
+
+Durability is **checkpoint-per-node, keyed by node id**, in the host's own
+store — the same shape as `fancy-flow-php`'s `node_outputs`.
+
+Event-sourced replay (Temporal, Restate) exists to police *arbitrary user code*
+for non-determinism, and charges a sandbox, history-size limits and permanent
+versioning for it. An interpreter over a declarative JSON graph is deterministic
+by construction, so none of that is bought. Worse, checkpoint identity in those
+systems is positional (DBOS keys on a call ordinal); ours is the node id, which
+is what lets a graph be edited while a run is parked on an approval.
+
+Three rules hold the per-node driver together, and each exists because the
+alternative fails silently:
+
+1. **The engine is not reimplemented.** `durable/replay.py` executes a node by
+   replaying the graph *through* `FlowRunner` with completed nodes fed back as
+   `resume_outputs` and every other node fenced off with `bind_node`. Inputs,
+   branching and skips are therefore the engine's, not a driver's copy.
+2. **Activated ports come from the engine's own `node-output` events**, stored on
+   the claim row. `Frontier` reads them; it must never compute them. A second
+   copy of `_activated_ports` would agree for a year and then disagree on one
+   branch.
+3. **The claim is a unique constraint, not a check.** A lost race is a NO-OP.
+   `NodeClaimStore.claim()` must be atomic, and must let an owner re-enter its
+   OWN claim — that is what lets a retry resume instead of deadlocking against
+   the row it wrote itself, and it is also what makes the retry's idempotency
+   key identical to the first attempt's, since both read the same row.
+4. **`NodeState.first_attempt_at` is the retry clock and must never move.** It
+   is stamped on the first claim only. A store that refreshed it per attempt
+   would report a retry 25 hours late as seconds old, and a connector would
+   reuse a key the provider forgot yesterday.
+
+A failed node whose attempts are not exhausted is left **CLAIMED**, never
+recorded FAILED: a FAILED node settles, and settling one mid-retry skips
+everything downstream while the run reports a tidy finish. `NodeOutcome.retryable`
+is how a queue adapter learns to re-dispatch — with the SAME owner token.
+
+`Coordinator.run_to_completion()` drives both operations in-process. It is a real
+durable runner over a persistent store, not a stand-in for one.
+
+### Kind ids
+
+Canonical ids are `@particle-academy/<name>`; old spellings live on as aliases.
+**Anything keyed by kind name must key on EVERY id a kind answers to** —
+registry lookups, executor bindings, retry overrides and `GraphPolicy` all do.
+Getting this wrong once cost a human gate: a durable override bound under the
+bare name only never matched a node saved as `@particle-academy/user_input`, so
+the run went straight past the person it was meant to stop for, and nothing
+errored.
+
+## Deliberate divergences
+
+Three, all tested and all recorded in `.ai/plans/fancy-flow-py.md`:
+
+1. **`GraphPolicy.untrusted()` fails closed.** The PHP twin returns a policy
+   whose allowlist is *absent*, and an absent allowlist permits every kind — so
+   a caller who forgets `allowKinds()` gets size caps and byte hygiene from a
+   method named `untrusted`. Here the allowlist starts empty. No correctly
+   configured policy changes verdict.
+2. **No LLM auto-detection.** PHP probes for Prism / laravel-ai with
+   `class_exists()`, which is free. The Python equivalent is importing a
+   candidate to find out whether it is there: side effects, start-up cost, and a
+   provider the author never named. A missing client aborts with
+   `llm_unavailable_message()` instead.
+3. **`{{ x.length }}` on a list is `None`.** JavaScript resolves it because
+   arrays carry a `length` property; PHP does not, and neither does this. The
+   shared table has no row for it — promoting one is in the plan.
+
+## Parity is a test result, not a claim
+
+- `tests/conformance/` runs `shared/expr` **and** `shared/satisfies-range` from
+  `particle-academy/fancy-conformance` through `tests/conformance/loader.py`.
+  A missing conformance checkout is a **failure**, never a skip.
+- `tests/parity/test_graph_fixtures.py` runs the 23 golden `WorkflowSchema`
+  fixtures. Read `tests/parity/fixtures/SOURCE.md` before touching them: they
+  are a COPY of the PHP twin's, because those goldens are not in the shared
+  package and nothing on the Node side runs them at all.
+- `tests/parity/test_fixture_provenance.py` fails if that copy has drifted from
+  the twin's, whenever the twin is on disk.
+- `tests/parity/test_durable_driver_parity.py` runs **every fixture through the
+  per-node durable driver too** and requires the same answer. That is what pins
+  "what is unblocked?" against "what is next?".
+
+`tests/conformance/loader.py` is a **third loader for a package that ships two**.
+It belongs in `fancy-conformance`; until it lands there, treat this file as a
+bridge and keep it behaviourally identical to the Node and PHP loaders.
+
+## Conventions
+
+- **Python 3.11 floor.** Frozen dataclasses, `Protocol` over base classes,
+  `X | None`.
+- **No runtime dependencies in the core.** Injectable protocols with offline
+  defaults, never a hard dep. An adapter takes its dependency behind an extra.
+- **Faithfulness first.** If in doubt, match `run-flow.ts` semantics and add a
+  fixture. Divergence from the TS *code* (never the TS *contract*) gets a
+  docstring at the point of divergence.
+- **Regenerate fixtures deliberately.** They are golden files; only regenerate
+  when behaviour legitimately changes, and eyeball the diff.
+
+## Commands
+
+```bash
+python -m pip install -e . --group dev
+pytest                              # unit + parity + conformance
+pytest tests/unit/test_engine.py    # one file
+ruff check . && ruff format --check .
+mypy
+```
+
+`FANCY_CONFORMANCE_ROOT` and `FANCY_FLOW_PHP_FIXTURES` override the sibling-repo
+discovery when the checkouts are somewhere unusual.
+
+## Status
+
+**0.1.0 — core parity, unreleased.** The engine, the registries, the 24 built-in
+kinds plus structural `note` / `subgraph` and their executors, `{{ }}`,
+capabilities, the node manifest, `GraphPolicy`, and the durable core (claims /
+frontier / replay / retries / human gates / coordinator) are built and tested.
+
+**Not built, and staged in the plan:** queue adapters (Celery, Dramatiq, Taskiq,
+Procrastinate), a persistent `NodeClaimStore`, a web-framework integration, the
+`agent` executor, and the Human+ / MCP surface.

fancy_flow-0.1.0/CHANGELOG.md

@@ -0,0 +1,133 @@
+# Changelog
+
+All notable changes to `fancy-flow` (Python) are documented here, in
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
+
+This package is pre-1.0, so **breaking changes land in MINOR releases**. The
+version number is not a promise it can yet keep; the entries are.
+
+## [Unreleased]
+
+### Added
+
+- **`RunIdentity` on the execution context, so a node that WRITES can send an
+  idempotency key.** `ctx.run` is new, and `ctx.run.step_key(ctx.node.id)` is
+  the key.
+
+  Nothing in `{node, inputs, emit, depth}` could produce a key that is the same
+  on a retry and different on a different execution, so a writing connector had
+  to declare `unsafe-to-replay` and send none — meaning a timed-out payment
+  could never be retried, because retrying it would charge the card twice.
+
+  What identifies a step is deliberately **not** `(run, node)`: a node
+  legitimately runs many times in one run, once per subflow invocation and once
+  per loop iteration. The key is the run key plus the *path of invocations* that
+  led here plus an optional occurrence — `run_9f2c:billing/pay#3` — and
+  `attempt` is carried on the identity but **deliberately absent from the key**.
+
+  `is_replay_safe(window_seconds, now)` answers the other half: providers forget
+  keys (Stripe after 24h), and past that window resending the key and minting a
+  fresh one BOTH write twice, so the caller must refuse. Attempt 1 is always
+  safe, which is what lets a run park on a human gate for a week and then write.
+
+  Pinned across Python, TypeScript and PHP by `shared/flow-run-identity` in
+  `fancy-conformance` (25 rows).
+
+### Fixed
+
+- **`Coordinator.retry` was wired to nothing.** `RetryPolicy` was a declared
+  field with **no read site anywhere in the package** — so a host constructing
+  `Coordinator(retry=RetryPolicy(tries=3))` got exactly one attempt per node and
+  no error to say otherwise. `unsafe-to-replay` appeared to be honoured only
+  because nothing retried at all.
+
+  `run_to_completion()` now consults the policy: a failed node whose attempts
+  are not exhausted is retried under the **same owner token**, so it re-enters
+  its own claim and derives the **same** step key — which is what makes the
+  retry idempotent rather than duplicative. A node declaring `unsafe-to-replay`
+  is still pinned to one attempt whatever `tries` says.
+
+  `NodeOutcome` gains `attempt` and `retryable`. A failed-but-retryable node is
+  deliberately left CLAIMED rather than recorded FAILED: a FAILED node settles,
+  and settling one mid-retry skips everything downstream while the run reports a
+  tidy finish.
+
+### Changed
+
+- **BREAKING (unreleased): `Coordinator.run_key` is now `Coordinator.run`**, and
+  takes a `RunIdentity` or a bare run-key string. *What to do:* rename the
+  keyword — `Coordinator(..., run="run_9f2c")`. `coordinator.run_key` still
+  reads the key.
+- `NodeState` gains `first_attempt_at`, the retry clock. It is stamped on the
+  first claim and **must never move**: a store that refreshed it per attempt
+  would report a retry 25 hours late as seconds old, and a connector would reuse
+  a key the provider forgot yesterday. Adapters constructing `NodeState` get a
+  sane default and need no change.
+
+## [0.1.0] - unreleased
+
+The first cut: the pure engine, the node contracts, the registries, and a
+durable layer that needs no queue library.
+
+### Added
+
+- **`FlowRunner`** — the port of `runFlow`. Kahn topological order, the three
+  port-activation conventions (`__port`, `branch`, declared outputs), cycle
+  detection, timeout, host abort, and `resume_outputs`.
+  - One graph walk, driven two ways: `run()` is synchronous, `arun()` awaits
+    awaitable executors. Both drive the same generator, so the routing rules
+    exist once.
+  - `run()` **refuses** an awaitable rather than storing a coroutine object that
+    would look like success and reach every downstream node.
+- **WorkflowSchema v1** — `import_workflow` / `export_workflow` / `to_json`,
+  with `ImportIssue` diagnostics for unknown kinds, missing required config and
+  dangling edges.
+- **Registries** — `NodeKindRegistry` (kinds, aliases, config defaults and
+  validation) and `ExecutorRegistry` (node id → kind → `*`, alias-aware in both
+  directions, callables / objects / classes through a `Resolver`).
+- **24 built-in kinds** across trigger / logic / data / ai / io / human / output,
+  plus structural `note` and `subgraph`, each with a framework-free default
+  executor and an offline client.
+- **`{{ }}` expressions** — dot-paths only, no evaluation. Scanned rather than
+  matched with a regex, so the linear-time property is structural rather than
+  pattern-dependent.
+- **Capabilities** — `LlmClient` and `WorkflowResolver` as host seams, so core
+  ships an opinionated `llm_router` and `subflow` without any consumer
+  inheriting a provider SDK.
+- **`fancy_flow.durable`** — resumable runs with no queue dependency:
+  `NodeClaimStore` (+ an in-memory reference), `Frontier`, per-node `replay`,
+  `RetryPolicy`, fail-closed human gates, and a `Coordinator` exposing the two
+  operations a queue adapter dispatches.
+- **`GraphPolicy`** — kind allow/deny lists, size caps, byte hygiene and host
+  rules for a graph that arrived over the wire.
+- **Node manifests** — `validate`, `check_runtime_support`,
+  `check_capabilities`, `satisfies_range`. The `runtimes` map is open, so a node
+  can declare a `py` backend with no change to any runtime's validator.
+- **Parity suites** — `shared/expr` and `shared/satisfies-range` from
+  `particle-academy/fancy-conformance`; the 23 golden `WorkflowSchema` fixtures;
+  a provenance check against the PHP twin's copies; and every fixture run a
+  second time through the durable driver.
+
+### Changed
+
+Three deliberate divergences from the PHP twin, each tested and each explained
+at the point of divergence:
+
+- **`GraphPolicy.untrusted()` fails closed.** The PHP twin's leaves the
+  allowlist *absent*, which permits every kind — so a caller who forgets
+  `allowKinds()` gets size caps and byte hygiene from a method named
+  `untrusted`. Here nothing is permitted until something is named.
+  **What you must do:** pass the kinds you permit, either as
+  `GraphPolicy.untrusted(allow=[...])` or with `.allow_kinds([...])`. Any policy
+  that already named its kinds is unaffected.
+- **No LLM auto-detection.** PHP probes for Prism / laravel-ai with
+  `class_exists()`. The Python equivalent is importing a candidate to find out
+  whether it is installed. **What you must do:** call
+  `fancy_flow.capabilities.set_llm_client(...)`. A missing client aborts the
+  node with a message naming that call.
+- **`{{ list.length }}` resolves to `None`,** matching PHP rather than
+  JavaScript. **What you must do:** nothing, unless a graph authored against the
+  Node runtime relied on it — in which case it was already broken on PHP.
+
+[Unreleased]: https://github.com/Particle-Academy/fancy-flow-py/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/Particle-Academy/fancy-flow-py/releases/tag/v0.1.0

fancy_flow-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Particle Academy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fancy_flow-0.1.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.5
+Name: fancy-flow
+Version: 0.1.0
+Summary: Python runtime for fancy-flow workflow graphs - the third twin of @particle-academy/fancy-flow's engine. Same WorkflowSchema JSON in, same outputs out.
+Project-URL: Homepage, https://github.com/Particle-Academy/fancy-flow-py
+Project-URL: Issues, https://github.com/Particle-Academy/fancy-flow-py/issues
+Project-URL: Source, https://github.com/Particle-Academy/fancy-flow-py
+Author: Particle Academy
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agentic,ai,automation,dag,durable-execution,fancy-flow,flow,orchestration,particle-academy,workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# fancy-flow (Python)
+
+The Python runtime for [`fancy-flow`](https://github.com/Particle-Academy/fancy-flow)
+workflow graphs — the third twin of its headless TypeScript engine, alongside
+[`fancy-flow-php`](https://github.com/Particle-Academy/fancy-flow-php).
+
+> A graph an agent or human authors in `<FlowEditor>` runs **unchanged** on
+> Python. Same JSON in, same outputs out. The editor stays the one authoring
+> surface; Python becomes a peer runtime alongside Node and PHP.
+
+**Zero runtime dependencies.** Everything the built-in nodes reach for — HTTP,
+an LLM, a vector store, a queue — is an injected protocol with a deterministic
+offline default, so a workflow app that never calls a model does not inherit a
+provider SDK, and every test runs without a network.
+
+```python
+from fancy_flow import FlowRunner, RunOptions, builtin, import_workflow
+
+builtin.register()  # install the built-in kinds
+result = import_workflow(schema_json)  # WorkflowSchema v1
+
+run = FlowRunner().run(
+    result.graph,
+    builtin.executors(),  # or your own bindings
+    options=RunOptions(initial_inputs={"trigger-1": {"payload": body}}),
+)
+
+run.ok  # bool
+run.outputs  # {node_id: value}
+run.error  # str | None
+```
+
+## Async, without two engines
+
+Executors may be synchronous or `async`. The graph walk is written once and
+driven two ways, so branching, skipping and port routing cannot drift between
+them.
+
+```python
+run = await FlowRunner().arun(graph, executors)  # awaits awaitable executors
+```
+
+The synchronous runner **refuses** an awaitable rather than storing it: a
+coroutine object in `outputs` looks like success and reaches every downstream
+node as a value nothing can read.
+
+## Custom nodes
+
+Two halves, kept in sync — exactly the path every built-in takes.
+
+```python
+from fancy_flow import ConfigField, NodeKind, ExecutorRegistry, default_registry
+
+default_registry().register(
+    NodeKind(
+        name="@acme/send_invoice",
+        category="io",
+        label="Send invoice",
+        aliases=("send_invoice",),
+        config_schema=(ConfigField(type="text", key="to", label="To", required=True),),
+        side_effects="unsafe-to-replay",  # a durable run gives this ONE attempt
+    )
+)
+
+
+def send_invoice(ctx):
+    return {"sent": ctx.option("to")}
+
+
+executors = builtin.executors().bind("@acme/send_invoice", send_invoice)
+```
+
+An executor may be a callable, an object with `.execute(ctx)`, or a class
+resolved through your container.
+
+## Durable runs, with no queue library
+
+Durability is **checkpoint-per-node, keyed by node id**. The core owns the hard
+part — which node may run, and with what inputs — and a queue supplies transport
+and nothing else.
+
+```python
+from fancy_flow.durable import Coordinator
+
+flow = Coordinator(graph=graph, executors=executors, run=run_id, store=store)
+
+ready = flow.advance()  # what is unblocked right now -> dispatch these
+flow.run_node(node_id)  # claim, run through the real engine, checkpoint
+flow.run_to_completion()  # or drive both, here, in this process
+```
+
+`advance()` and `run_node()` are the two operations a Celery / Dramatiq / Taskiq
+job wraps. `Coordinator.run_to_completion()` over a persistent `NodeClaimStore`
+is already a real durable runner: a crash resumes from the same place a crashed
+worker would, because the resume behaviour lives in the checkpoints rather than
+in the loop.
+
+Human gates **fail closed**: `user_input` and `human_approval` pause because
+they *are* human nodes, not because their input port happens to be empty. Only a
+recorded answer for that node resumes the run.
+
+## Accepting a graph you did not write
+
+`import_workflow` answers *is this graph coherent?* `GraphPolicy` answers *is it
+safe to accept?* — kind allowlists (resolved across every id a kind answers to),
+size caps, byte hygiene, structure, and host rules.
+
+```python
+from fancy_flow.security import GraphPolicy
+
+GraphPolicy.untrusted(allow=["manual_trigger", "transform", "output"]).assert_safe(schema)
+```
+
+## Parity
+
+The guarantee is asserted, not asserted-to. The suite runs the shared
+`shared/expr` and `shared/satisfies-range` tables from
+[`fancy-conformance`](https://github.com/Particle-Academy/fancy-conformance),
+the 23 golden `WorkflowSchema` fixtures, and — because a queued run derives
+readiness from the opposite end — every one of those fixtures a second time
+through the per-node durable driver.
+
+```bash
+python -m pip install -e . --group dev
+pytest
+```
+
+## Status
+
+Pre-1.0: breaking changes land in minor releases. See
+[`CHANGELOG.md`](CHANGELOG.md) and, for how the package is built and what is
+staged next, `AGENTS.md`.
+
+MIT.

fancy_flow-0.1.0/README.md

@@ -0,0 +1,134 @@
+# fancy-flow (Python)
+
+The Python runtime for [`fancy-flow`](https://github.com/Particle-Academy/fancy-flow)
+workflow graphs — the third twin of its headless TypeScript engine, alongside
+[`fancy-flow-php`](https://github.com/Particle-Academy/fancy-flow-php).
+
+> A graph an agent or human authors in `<FlowEditor>` runs **unchanged** on
+> Python. Same JSON in, same outputs out. The editor stays the one authoring
+> surface; Python becomes a peer runtime alongside Node and PHP.
+
+**Zero runtime dependencies.** Everything the built-in nodes reach for — HTTP,
+an LLM, a vector store, a queue — is an injected protocol with a deterministic
+offline default, so a workflow app that never calls a model does not inherit a
+provider SDK, and every test runs without a network.
+
+```python
+from fancy_flow import FlowRunner, RunOptions, builtin, import_workflow
+
+builtin.register()  # install the built-in kinds
+result = import_workflow(schema_json)  # WorkflowSchema v1
+
+run = FlowRunner().run(
+    result.graph,
+    builtin.executors(),  # or your own bindings
+    options=RunOptions(initial_inputs={"trigger-1": {"payload": body}}),
+)
+
+run.ok  # bool
+run.outputs  # {node_id: value}
+run.error  # str | None
+```
+
+## Async, without two engines
+
+Executors may be synchronous or `async`. The graph walk is written once and
+driven two ways, so branching, skipping and port routing cannot drift between
+them.
+
+```python
+run = await FlowRunner().arun(graph, executors)  # awaits awaitable executors
+```
+
+The synchronous runner **refuses** an awaitable rather than storing it: a
+coroutine object in `outputs` looks like success and reaches every downstream
+node as a value nothing can read.
+
+## Custom nodes
+
+Two halves, kept in sync — exactly the path every built-in takes.
+
+```python
+from fancy_flow import ConfigField, NodeKind, ExecutorRegistry, default_registry
+
+default_registry().register(
+    NodeKind(
+        name="@acme/send_invoice",
+        category="io",
+        label="Send invoice",
+        aliases=("send_invoice",),
+        config_schema=(ConfigField(type="text", key="to", label="To", required=True),),
+        side_effects="unsafe-to-replay",  # a durable run gives this ONE attempt
+    )
+)
+
+
+def send_invoice(ctx):
+    return {"sent": ctx.option("to")}
+
+
+executors = builtin.executors().bind("@acme/send_invoice", send_invoice)
+```
+
+An executor may be a callable, an object with `.execute(ctx)`, or a class
+resolved through your container.
+
+## Durable runs, with no queue library
+
+Durability is **checkpoint-per-node, keyed by node id**. The core owns the hard
+part — which node may run, and with what inputs — and a queue supplies transport
+and nothing else.
+
+```python
+from fancy_flow.durable import Coordinator
+
+flow = Coordinator(graph=graph, executors=executors, run=run_id, store=store)
+
+ready = flow.advance()  # what is unblocked right now -> dispatch these
+flow.run_node(node_id)  # claim, run through the real engine, checkpoint
+flow.run_to_completion()  # or drive both, here, in this process
+```
+
+`advance()` and `run_node()` are the two operations a Celery / Dramatiq / Taskiq
+job wraps. `Coordinator.run_to_completion()` over a persistent `NodeClaimStore`
+is already a real durable runner: a crash resumes from the same place a crashed
+worker would, because the resume behaviour lives in the checkpoints rather than
+in the loop.
+
+Human gates **fail closed**: `user_input` and `human_approval` pause because
+they *are* human nodes, not because their input port happens to be empty. Only a
+recorded answer for that node resumes the run.
+
+## Accepting a graph you did not write
+
+`import_workflow` answers *is this graph coherent?* `GraphPolicy` answers *is it
+safe to accept?* — kind allowlists (resolved across every id a kind answers to),
+size caps, byte hygiene, structure, and host rules.
+
+```python
+from fancy_flow.security import GraphPolicy
+
+GraphPolicy.untrusted(allow=["manual_trigger", "transform", "output"]).assert_safe(schema)
+```
+
+## Parity
+
+The guarantee is asserted, not asserted-to. The suite runs the shared
+`shared/expr` and `shared/satisfies-range` tables from
+[`fancy-conformance`](https://github.com/Particle-Academy/fancy-conformance),
+the 23 golden `WorkflowSchema` fixtures, and — because a queued run derives
+readiness from the opposite end — every one of those fixtures a second time
+through the per-node durable driver.
+
+```bash
+python -m pip install -e . --group dev
+pytest
+```
+
+## Status
+
+Pre-1.0: breaking changes land in minor releases. See
+[`CHANGELOG.md`](CHANGELOG.md) and, for how the package is built and what is
+staged next, `AGENTS.md`.
+
+MIT.