penguiflow 2.0.0__tar.gz → 2.2.0__tar.gz

{penguiflow-2.0.0 → penguiflow-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: penguiflow
-Version: 2.0.0
+Version: 2.2.0
 Summary: Async agent orchestration primitives.
 Author: PenguiFlow Team
 License: MIT License
@@ -36,7 +36,14 @@ Requires-Dist: pytest>=7.4; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
 Requires-Dist: pytest-cov>=4.0; extra == "dev"
 Requires-Dist: coverage[toml]>=7.0; extra == "dev"
+Requires-Dist: hypothesis>=6.103; extra == "dev"
 Requires-Dist: ruff>=0.2; extra == "dev"
+Requires-Dist: fastapi>=0.118; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Provides-Extra: a2a-server
+Requires-Dist: fastapi>=0.118; extra == "a2a-server"
+Provides-Extra: planner
+Requires-Dist: litellm>=1.77.3; extra == "planner"
 Dynamic: license-file
 
 # PenguiFlow 🐧❄️
@@ -52,6 +59,9 @@ Dynamic: license-file
   <a href="https://github.com/penguiflow/penguiflow">
     <img src="https://img.shields.io/badge/coverage-85%25-brightgreen" alt="Coverage">
   </a>
+  <a href="https://nightly.link/penguiflow/penguiflow/workflows/benchmarks/main/benchmarks.json.zip">
+    <img src="https://img.shields.io/badge/benchmarks-latest-orange" alt="Benchmarks">
+  </a>
   <a href="https://pypi.org/project/penguiflow/">
     <img src="https://img.shields.io/pypi/v/penguiflow.svg" alt="PyPI version">
   </a>
@@ -77,10 +87,39 @@ It provides:
 * **Observability hooks** (`FlowEvent` callbacks for logging, MLflow, or custom metrics sinks)
 * **Policy-driven routing** (optional policies steer routers without breaking existing flows)
 * **Traceable exceptions** (`FlowError` captures node/trace metadata and optionally emits to Rookery)
+* **Distribution hooks (opt-in)** — plug a `StateStore` to persist trace history and a
+  `MessageBus` to publish floe traffic for remote workers without changing existing flows.
+* **Remote calls (opt-in)** — `RemoteNode` bridges the runtime to external agents through a
+  pluggable `RemoteTransport` interface (A2A-ready) while propagating streaming chunks and
+  cancellation.
+* **A2A server adapter (opt-in)** — wrap a PenguiFlow graph in a FastAPI surface using
+  `penguiflow_a2a.A2AServerAdapter` so other agents can call `message/send`,
+  `message/stream`, and `tasks/cancel` while reusing the runtime's backpressure and
+  cancellation semantics.
+* **Observability & ops polish** — remote calls emit structured metrics (latency, payload
+  sizes, cancel reasons) and the `penguiflow-admin` CLI replays trace history from any
+  configured `StateStore` for debugging.
 
 Built on pure `asyncio` (no threads), PenguiFlow is small, predictable, and repo-agnostic.
 Product repos only define **their models + node functions** — the core stays dependency-light.
 
+## Gold Standard Scorecard
+
+| Area | Metric | Target | Current |
+| --- | --- | --- | --- |
+| Hop overhead | µs per hop | ≤ 500 | 398 |
+| Streaming order | gaps/dupes | 0 | 0 |
+| Cancel leakage | orphan tasks | 0 | 0 |
+| Coverage | lines | ≥85% | 87% |
+| Deps | count | ≤2 | 2 |
+| Import time | ms | ≤220 | 203 |
+
+## 📑 Core Behavior Spec
+
+* [Core Behavior Spec](docs/core_behavior_spec.md) — single-page rundown of ordering,
+  streaming, cancellation, deadline, and fan-in invariants with pointers to regression
+  tests.
+
 ---
 
 ## ✨ Why PenguiFlow?
@@ -168,6 +207,10 @@ print(out.payload)            # PackOut(...)
 await flow.stop()
 ```
 
+> **Opt-in distribution:** pass `state_store=` and/or `message_bus=` when calling
+> `penguiflow.core.create(...)` to persist trace history and publish floe traffic
+> without changing node logic.
+
 ---
 
 ## 🧭 Design Principles
@@ -222,6 +265,60 @@ sacrificing backpressure or ordering guarantees.  The helper wraps the payload i
 increments per-stream sequence numbers.  See `tests/test_streaming.py` and
 `examples/streaming_llm/` for an end-to-end walk-through.
 
+### Remote orchestration
+
+Phase 2 introduces `RemoteNode` and the `RemoteTransport` protocol so flows can delegate
+work to remote agents (e.g., the A2A JSON-RPC/SSE ecosystem) without changing existing
+nodes.  The helper records remote bindings via the `StateStore`, mirrors streaming
+partials back into the graph, and propagates per-trace cancellation to remote tasks via
+`RemoteTransport.cancel`.  See `tests/test_remote.py` for reference in-memory transports.
+
+### Exposing a flow over A2A
+
+Install the optional extra to expose PenguiFlow as an A2A-compatible FastAPI service:
+
+```bash
+pip install "penguiflow[a2a-server]"
+```
+
+Create the adapter and mount the routes:
+
+```python
+from penguiflow import Message, Node, create
+from penguiflow_a2a import A2AAgentCard, A2AServerAdapter, A2ASkill, create_a2a_app
+
+async def orchestrate(message: Message, ctx):
+    await ctx.emit_chunk(parent=message, text="thinking...")
+    return {"result": "done"}
+
+node = Node(orchestrate, name="main")
+flow = create(node.to())
+
+card = A2AAgentCard(
+    name="Main Agent",
+    description="Primary entrypoint for orchestration",
+    version="2.1.0",
+    skills=[A2ASkill(name="orchestrate", description="Handles orchestration")],
+)
+
+adapter = A2AServerAdapter(
+    flow,
+    agent_card=card,
+    agent_url="https://agent.example",
+)
+app = create_a2a_app(adapter)
+```
+
+The generated FastAPI app implements:
+
+* `GET /agent` for discovery (Agent Card)
+* `POST /message/send` for unary execution
+* `POST /message/stream` for SSE streaming
+* `POST /tasks/cancel` to mirror cancellation into PenguiFlow traces
+
+`A2AServerAdapter` reuses the runtime's `StateStore` hooks, so bindings between trace IDs
+and external `taskId`/`contextId` pairs are persisted automatically.
+
 ### Reliability & guardrails
 
 PenguiFlow enforces reliability boundaries out of the box:
@@ -272,6 +369,70 @@ The new `penguiflow.testkit` module keeps unit tests tiny:
 The harness is covered by `tests/test_testkit.py` and demonstrated in
 `examples/testkit_demo/`.
 
+### JSON-only ReAct planner (Phase A)
+
+Phase A introduces a lightweight planner loop that keeps PenguiFlow typed and
+deterministic:
+
+* `penguiflow.catalog.NodeSpec` + `build_catalog` turn registered nodes into
+  tool descriptors with JSON Schemas derived from your Pydantic models.
+* `penguiflow.planner.ReactPlanner` drives a JSON-only ReAct loop over those
+  descriptors, validating every LLM action with Pydantic and replaying invalid
+  steps to request corrections.
+* LiteLLM stays optional—install `penguiflow[planner]` or inject a custom
+  `llm_client` for deterministic/offline runs.
+
+See `examples/react_minimal/` for a stubbed end-to-end run.
+
+### Trajectory summarisation & pause/resume (Phase B)
+
+Phase B adds the tools you need for longer-running, approval-driven flows:
+
+* **Token-aware summaries** — `Trajectory.compress()` keeps a compact state and
+  the planner can route summaries through a cheaper `summarizer_llm` before
+  asking for the next action.
+* **`PlannerPause` contract** — nodes can call `await ctx.pause(...)` to return a
+  typed pause payload. Resume the run later with `ReactPlanner.resume(token, user_input=...)`.
+* **Developer hints** — pass `planning_hints={...}` to enforce disallowed tools,
+  preferred ordering, or parallelism ceilings.
+
+All three features are exercised in `examples/react_pause_resume/`, which runs
+entirely offline with stubbed LLM responses.
+
+### Adaptive re-planning & budgets (Phase C)
+
+Phase C closes the loop when things go sideways:
+
+* **Structured failure feedback** — if a tool raises after exhausting its retries,
+  the planner records `{failure: {node, args, error_code, suggestion}}` and feeds
+  it back to the LLM, prompting a constrained re-plan instead of aborting.
+* **Hard guardrails** — configure wall-clock deadlines and hop budgets directly
+  on `ReactPlanner`; attempts beyond the allotted hops surface deterministic
+  violations and ultimately finish with `reason="budget_exhausted"` alongside a
+  constraint snapshot.
+* **Typed exit reasons** — runs now finish with one of
+  `answer_complete`, `no_path`, or `budget_exhausted`, keeping downstream code
+  simple and machine-checkable.
+
+The new `examples/react_replan/` sample shows a retrieval timeout automatically
+recover via a cached index without leaving the JSON-only contract.
+
+### Parallel fan-out & joins (Phase D)
+
+Phase D lets the planner propose sets of independent tool calls and join them
+without leaving the typed surface area:
+
+* **Parallel `plan` blocks** — the LLM can return `{"plan": [...]}` actions
+  where each branch is validated against the catalog and executed concurrently.
+* **Typed joins** — provide a `{"join": {"node": ...}}` descriptor and the
+  planner will aggregate results, auto-populate fields like `expect`, `results`,
+  or `failures`, and feed branch metadata through `ctx.meta` for the join node.
+* **Deterministic telemetry** — branch errors, pauses, and joins are recorded as
+  structured observations so follow-up actions can re-plan or finish cleanly.
+
+See `examples/react_parallel/` for a shard fan-out that merges responses in one
+round-trip.
+
 
 ## 🧭 Repo Structure
 
@@ -478,9 +639,15 @@ docs or diagramming pipelines.
 * **Structured `FlowEvent`s**: every node event carries `{ts, trace_id, node_name, event,
   latency_ms, q_depth_in, q_depth_out, attempt}` plus a mutable `extra` map for custom
   annotations.
+* **Remote call telemetry**: `RemoteNode` executions emit extra metrics (latency, request
+  and response bytes, context/task identifiers, cancel reasons) so remote hops can be
+  traced end-to-end.
 * **Middleware hooks**: subscribe observers (e.g., MLflow) to the structured `FlowEvent`
   stream. See `examples/mlflow_metrics/` for an MLflow integration and
   `examples/reliability_middleware/` for a concrete timeout + retry walkthrough.
+* **`penguiflow-admin` CLI**: inspect or replay stored trace history from any configured
+  `StateStore` (`penguiflow-admin history <trace>` or `penguiflow-admin replay <trace>`)
+  when debugging distributed runs.
 
 ---
 
@@ -488,9 +655,9 @@ docs or diagramming pipelines.
 
 - **In-process runtime**: there is no built-in distribution layer yet. Long-running CPU work should be delegated to your own pools or services.
 - **Registry-driven typing**: nodes default to validation. Provide a `ModelRegistry` when calling `flow.run(...)` or set `validate="none"` explicitly for untyped hops.
-- **Observability**: structured `FlowEvent` callbacks power logs/metrics; integrations with
-  third-party stacks (OTel, Prometheus, Datadog) remain DIY. See the MLflow middleware
-  example for a lightweight pattern.
+- **Observability**: structured `FlowEvent` callbacks and the `penguiflow-admin` CLI power
+  local debugging; integrations with third-party stacks (OTel, Prometheus, Datadog) remain
+  DIY. See the MLflow middleware example for a lightweight pattern.
 - **Roadmap**: follow-up releases focus on optional distributed backends, deeper observability integrations, and additional playbook patterns. Contributions and proposals are welcome!
 
 ---
@@ -546,6 +713,8 @@ pytest -q
 * `examples/streaming_llm/`: mock LLM emitting streaming chunks to an SSE sink.
 * `examples/metadata_propagation/`: attaching and consuming `Message.meta` context.
 * `examples/visualizer/`: exports Mermaid + DOT diagrams with loop/subflow annotations.
+* `examples/react_minimal/`: JSON-only ReactPlanner loop with a stubbed LLM.
+* `examples/react_pause_resume/`: Phase B planner features with pause/resume and developer hints.
 
 ---
 

{penguiflow-2.0.0 → penguiflow-2.2.0}/README.md

@@ -11,6 +11,9 @@
   <a href="https://github.com/penguiflow/penguiflow">
     <img src="https://img.shields.io/badge/coverage-85%25-brightgreen" alt="Coverage">
   </a>
+  <a href="https://nightly.link/penguiflow/penguiflow/workflows/benchmarks/main/benchmarks.json.zip">
+    <img src="https://img.shields.io/badge/benchmarks-latest-orange" alt="Benchmarks">
+  </a>
   <a href="https://pypi.org/project/penguiflow/">
     <img src="https://img.shields.io/pypi/v/penguiflow.svg" alt="PyPI version">
   </a>
@@ -36,10 +39,39 @@ It provides:
 * **Observability hooks** (`FlowEvent` callbacks for logging, MLflow, or custom metrics sinks)
 * **Policy-driven routing** (optional policies steer routers without breaking existing flows)
 * **Traceable exceptions** (`FlowError` captures node/trace metadata and optionally emits to Rookery)
+* **Distribution hooks (opt-in)** — plug a `StateStore` to persist trace history and a
+  `MessageBus` to publish floe traffic for remote workers without changing existing flows.
+* **Remote calls (opt-in)** — `RemoteNode` bridges the runtime to external agents through a
+  pluggable `RemoteTransport` interface (A2A-ready) while propagating streaming chunks and
+  cancellation.
+* **A2A server adapter (opt-in)** — wrap a PenguiFlow graph in a FastAPI surface using
+  `penguiflow_a2a.A2AServerAdapter` so other agents can call `message/send`,
+  `message/stream`, and `tasks/cancel` while reusing the runtime's backpressure and
+  cancellation semantics.
+* **Observability & ops polish** — remote calls emit structured metrics (latency, payload
+  sizes, cancel reasons) and the `penguiflow-admin` CLI replays trace history from any
+  configured `StateStore` for debugging.
 
 Built on pure `asyncio` (no threads), PenguiFlow is small, predictable, and repo-agnostic.
 Product repos only define **their models + node functions** — the core stays dependency-light.
 
+## Gold Standard Scorecard
+
+| Area | Metric | Target | Current |
+| --- | --- | --- | --- |
+| Hop overhead | µs per hop | ≤ 500 | 398 |
+| Streaming order | gaps/dupes | 0 | 0 |
+| Cancel leakage | orphan tasks | 0 | 0 |
+| Coverage | lines | ≥85% | 87% |
+| Deps | count | ≤2 | 2 |
+| Import time | ms | ≤220 | 203 |
+
+## 📑 Core Behavior Spec
+
+* [Core Behavior Spec](docs/core_behavior_spec.md) — single-page rundown of ordering,
+  streaming, cancellation, deadline, and fan-in invariants with pointers to regression
+  tests.
+
 ---
 
 ## ✨ Why PenguiFlow?
@@ -127,6 +159,10 @@ print(out.payload)            # PackOut(...)
 await flow.stop()
 ```
 
+> **Opt-in distribution:** pass `state_store=` and/or `message_bus=` when calling
+> `penguiflow.core.create(...)` to persist trace history and publish floe traffic
+> without changing node logic.
+
 ---
 
 ## 🧭 Design Principles
@@ -181,6 +217,60 @@ sacrificing backpressure or ordering guarantees.  The helper wraps the payload i
 increments per-stream sequence numbers.  See `tests/test_streaming.py` and
 `examples/streaming_llm/` for an end-to-end walk-through.
 
+### Remote orchestration
+
+Phase 2 introduces `RemoteNode` and the `RemoteTransport` protocol so flows can delegate
+work to remote agents (e.g., the A2A JSON-RPC/SSE ecosystem) without changing existing
+nodes.  The helper records remote bindings via the `StateStore`, mirrors streaming
+partials back into the graph, and propagates per-trace cancellation to remote tasks via
+`RemoteTransport.cancel`.  See `tests/test_remote.py` for reference in-memory transports.
+
+### Exposing a flow over A2A
+
+Install the optional extra to expose PenguiFlow as an A2A-compatible FastAPI service:
+
+```bash
+pip install "penguiflow[a2a-server]"
+```
+
+Create the adapter and mount the routes:
+
+```python
+from penguiflow import Message, Node, create
+from penguiflow_a2a import A2AAgentCard, A2AServerAdapter, A2ASkill, create_a2a_app
+
+async def orchestrate(message: Message, ctx):
+    await ctx.emit_chunk(parent=message, text="thinking...")
+    return {"result": "done"}
+
+node = Node(orchestrate, name="main")
+flow = create(node.to())
+
+card = A2AAgentCard(
+    name="Main Agent",
+    description="Primary entrypoint for orchestration",
+    version="2.1.0",
+    skills=[A2ASkill(name="orchestrate", description="Handles orchestration")],
+)
+
+adapter = A2AServerAdapter(
+    flow,
+    agent_card=card,
+    agent_url="https://agent.example",
+)
+app = create_a2a_app(adapter)
+```
+
+The generated FastAPI app implements:
+
+* `GET /agent` for discovery (Agent Card)
+* `POST /message/send` for unary execution
+* `POST /message/stream` for SSE streaming
+* `POST /tasks/cancel` to mirror cancellation into PenguiFlow traces
+
+`A2AServerAdapter` reuses the runtime's `StateStore` hooks, so bindings between trace IDs
+and external `taskId`/`contextId` pairs are persisted automatically.
+
 ### Reliability & guardrails
 
 PenguiFlow enforces reliability boundaries out of the box:
@@ -231,6 +321,70 @@ The new `penguiflow.testkit` module keeps unit tests tiny:
 The harness is covered by `tests/test_testkit.py` and demonstrated in
 `examples/testkit_demo/`.
 
+### JSON-only ReAct planner (Phase A)
+
+Phase A introduces a lightweight planner loop that keeps PenguiFlow typed and
+deterministic:
+
+* `penguiflow.catalog.NodeSpec` + `build_catalog` turn registered nodes into
+  tool descriptors with JSON Schemas derived from your Pydantic models.
+* `penguiflow.planner.ReactPlanner` drives a JSON-only ReAct loop over those
+  descriptors, validating every LLM action with Pydantic and replaying invalid
+  steps to request corrections.
+* LiteLLM stays optional—install `penguiflow[planner]` or inject a custom
+  `llm_client` for deterministic/offline runs.
+
+See `examples/react_minimal/` for a stubbed end-to-end run.
+
+### Trajectory summarisation & pause/resume (Phase B)
+
+Phase B adds the tools you need for longer-running, approval-driven flows:
+
+* **Token-aware summaries** — `Trajectory.compress()` keeps a compact state and
+  the planner can route summaries through a cheaper `summarizer_llm` before
+  asking for the next action.
+* **`PlannerPause` contract** — nodes can call `await ctx.pause(...)` to return a
+  typed pause payload. Resume the run later with `ReactPlanner.resume(token, user_input=...)`.
+* **Developer hints** — pass `planning_hints={...}` to enforce disallowed tools,
+  preferred ordering, or parallelism ceilings.
+
+All three features are exercised in `examples/react_pause_resume/`, which runs
+entirely offline with stubbed LLM responses.
+
+### Adaptive re-planning & budgets (Phase C)
+
+Phase C closes the loop when things go sideways:
+
+* **Structured failure feedback** — if a tool raises after exhausting its retries,
+  the planner records `{failure: {node, args, error_code, suggestion}}` and feeds
+  it back to the LLM, prompting a constrained re-plan instead of aborting.
+* **Hard guardrails** — configure wall-clock deadlines and hop budgets directly
+  on `ReactPlanner`; attempts beyond the allotted hops surface deterministic
+  violations and ultimately finish with `reason="budget_exhausted"` alongside a
+  constraint snapshot.
+* **Typed exit reasons** — runs now finish with one of
+  `answer_complete`, `no_path`, or `budget_exhausted`, keeping downstream code
+  simple and machine-checkable.
+
+The new `examples/react_replan/` sample shows a retrieval timeout automatically
+recover via a cached index without leaving the JSON-only contract.
+
+### Parallel fan-out & joins (Phase D)
+
+Phase D lets the planner propose sets of independent tool calls and join them
+without leaving the typed surface area:
+
+* **Parallel `plan` blocks** — the LLM can return `{"plan": [...]}` actions
+  where each branch is validated against the catalog and executed concurrently.
+* **Typed joins** — provide a `{"join": {"node": ...}}` descriptor and the
+  planner will aggregate results, auto-populate fields like `expect`, `results`,
+  or `failures`, and feed branch metadata through `ctx.meta` for the join node.
+* **Deterministic telemetry** — branch errors, pauses, and joins are recorded as
+  structured observations so follow-up actions can re-plan or finish cleanly.
+
+See `examples/react_parallel/` for a shard fan-out that merges responses in one
+round-trip.
+
 
 ## 🧭 Repo Structure
 
@@ -437,9 +591,15 @@ docs or diagramming pipelines.
 * **Structured `FlowEvent`s**: every node event carries `{ts, trace_id, node_name, event,
   latency_ms, q_depth_in, q_depth_out, attempt}` plus a mutable `extra` map for custom
   annotations.
+* **Remote call telemetry**: `RemoteNode` executions emit extra metrics (latency, request
+  and response bytes, context/task identifiers, cancel reasons) so remote hops can be
+  traced end-to-end.
 * **Middleware hooks**: subscribe observers (e.g., MLflow) to the structured `FlowEvent`
   stream. See `examples/mlflow_metrics/` for an MLflow integration and
   `examples/reliability_middleware/` for a concrete timeout + retry walkthrough.
+* **`penguiflow-admin` CLI**: inspect or replay stored trace history from any configured
+  `StateStore` (`penguiflow-admin history <trace>` or `penguiflow-admin replay <trace>`)
+  when debugging distributed runs.
 
 ---
 
@@ -447,9 +607,9 @@ docs or diagramming pipelines.
 
 - **In-process runtime**: there is no built-in distribution layer yet. Long-running CPU work should be delegated to your own pools or services.
 - **Registry-driven typing**: nodes default to validation. Provide a `ModelRegistry` when calling `flow.run(...)` or set `validate="none"` explicitly for untyped hops.
-- **Observability**: structured `FlowEvent` callbacks power logs/metrics; integrations with
-  third-party stacks (OTel, Prometheus, Datadog) remain DIY. See the MLflow middleware
-  example for a lightweight pattern.
+- **Observability**: structured `FlowEvent` callbacks and the `penguiflow-admin` CLI power
+  local debugging; integrations with third-party stacks (OTel, Prometheus, Datadog) remain
+  DIY. See the MLflow middleware example for a lightweight pattern.
 - **Roadmap**: follow-up releases focus on optional distributed backends, deeper observability integrations, and additional playbook patterns. Contributions and proposals are welcome!
 
 ---
@@ -505,6 +665,8 @@ pytest -q
 * `examples/streaming_llm/`: mock LLM emitting streaming chunks to an SSE sink.
 * `examples/metadata_propagation/`: attaching and consuming `Message.meta` context.
 * `examples/visualizer/`: exports Mermaid + DOT diagrams with loop/subflow annotations.
+* `examples/react_minimal/`: JSON-only ReactPlanner loop with a stubbed LLM.
+* `examples/react_pause_resume/`: Phase B planner features with pause/resume and developer hints.
 
 ---
 

{penguiflow-2.0.0 → penguiflow-2.2.0}/penguiflow/__init__.py

@@ -3,6 +3,8 @@
 from __future__ import annotations
 
 from . import testkit
+from .bus import BusEnvelope, MessageBus
+from .catalog import NodeSpec, SideEffect, build_catalog, tool
 from .core import (
     DEFAULT_QUEUE_MAXSIZE,
     Context,
@@ -11,13 +13,29 @@ from .core import (
     call_playbook,
     create,
 )
+from .debug import format_flow_event
 from .errors import FlowError, FlowErrorCode
 from .metrics import FlowEvent
-from .middlewares import Middleware
+from .middlewares import LatencyCallback, Middleware, log_flow_events
 from .node import Node, NodePolicy
 from .patterns import join_k, map_concurrent, predicate_router, union_router
+from .planner import (
+    PlannerAction,
+    PlannerFinish,
+    ReactPlanner,
+    Trajectory,
+    TrajectoryStep,
+)
 from .policies import DictRoutingPolicy, RoutingPolicy, RoutingRequest
 from .registry import ModelRegistry
+from .remote import (
+    RemoteCallRequest,
+    RemoteCallResult,
+    RemoteNode,
+    RemoteStreamEvent,
+    RemoteTransport,
+)
+from .state import RemoteBinding, StateStore, StoredEvent
 from .streaming import (
     chunk_to_ws_json,
     emit_stream_events,
@@ -36,10 +54,19 @@ __all__ = [
     "Node",
     "NodePolicy",
     "ModelRegistry",
+    "NodeSpec",
+    "SideEffect",
+    "build_catalog",
+    "tool",
     "Middleware",
+    "log_flow_events",
+    "LatencyCallback",
     "FlowEvent",
+    "format_flow_event",
     "FlowError",
     "FlowErrorCode",
+    "MessageBus",
+    "BusEnvelope",
     "call_playbook",
     "Headers",
     "Message",
@@ -63,6 +90,19 @@ __all__ = [
     "flow_to_dot",
     "create",
     "testkit",
+    "StateStore",
+    "StoredEvent",
+    "RemoteBinding",
+    "RemoteTransport",
+    "RemoteCallRequest",
+    "RemoteCallResult",
+    "RemoteStreamEvent",
+    "RemoteNode",
+    "ReactPlanner",
+    "PlannerAction",
+    "PlannerFinish",
+    "Trajectory",
+    "TrajectoryStep",
 ]
 
-__version__ = "2.0.0"
+__version__ = "2.2.0"