penguiflow 2.1.0__py3-none-any.whl → 2.2.1__py3-none-any.whl

penguiflow/__init__.py

@@ -4,6 +4,7 @@ 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,
@@ -12,11 +13,19 @@ 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 (
@@ -45,8 +54,15 @@ __all__ = [
     "Node",
     "NodePolicy",
     "ModelRegistry",
+    "NodeSpec",
+    "SideEffect",
+    "build_catalog",
+    "tool",
     "Middleware",
+    "log_flow_events",
+    "LatencyCallback",
     "FlowEvent",
+    "format_flow_event",
     "FlowError",
     "FlowErrorCode",
     "MessageBus",
@@ -82,6 +98,11 @@ __all__ = [
     "RemoteCallResult",
     "RemoteStreamEvent",
     "RemoteNode",
+    "ReactPlanner",
+    "PlannerAction",
+    "PlannerFinish",
+    "Trajectory",
+    "TrajectoryStep",
 ]
 
-__version__ = "2.1.0"
+__version__ = "2.2.1"

penguiflow/catalog.py

@@ -0,0 +1,146 @@
+"""Tool catalog helpers for the planner."""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Any, Literal, cast
+
+from pydantic import BaseModel
+
+from .node import Node
+from .registry import ModelRegistry
+
+SideEffect = Literal["pure", "read", "write", "external", "stateful"]
+
+
+@dataclass(frozen=True, slots=True)
+class NodeSpec:
+    """Structured metadata describing a planner-discoverable node."""
+
+    node: Node
+    name: str
+    desc: str
+    args_model: type[BaseModel]
+    out_model: type[BaseModel]
+    side_effects: SideEffect = "pure"
+    tags: Sequence[str] = field(default_factory=tuple)
+    auth_scopes: Sequence[str] = field(default_factory=tuple)
+    cost_hint: str | None = None
+    latency_hint_ms: int | None = None
+    safety_notes: str | None = None
+    extra: Mapping[str, Any] = field(default_factory=dict)
+
+    def to_tool_record(self) -> dict[str, Any]:
+        """Convert the spec to a serialisable record for prompting."""
+
+        return {
+            "name": self.name,
+            "desc": self.desc,
+            "side_effects": self.side_effects,
+            "tags": list(self.tags),
+            "auth_scopes": list(self.auth_scopes),
+            "cost_hint": self.cost_hint,
+            "latency_hint_ms": self.latency_hint_ms,
+            "safety_notes": self.safety_notes,
+            "args_schema": self.args_model.model_json_schema(),
+            "out_schema": self.out_model.model_json_schema(),
+            "extra": dict(self.extra),
+        }
+
+
+def _normalise_sequence(value: Sequence[str] | None) -> tuple[str, ...]:
+    if value is None:
+        return ()
+    return tuple(dict.fromkeys(value))
+
+
+def tool(
+    *,
+    desc: str | None = None,
+    side_effects: SideEffect = "pure",
+    tags: Sequence[str] | None = None,
+    auth_scopes: Sequence[str] | None = None,
+    cost_hint: str | None = None,
+    latency_hint_ms: int | None = None,
+    safety_notes: str | None = None,
+    extra: Mapping[str, Any] | None = None,
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Annotate a node function with catalog metadata."""
+
+    payload: dict[str, Any] = {
+        "desc": desc,
+        "side_effects": side_effects,
+        "tags": _normalise_sequence(tags),
+        "auth_scopes": _normalise_sequence(auth_scopes),
+        "cost_hint": cost_hint,
+        "latency_hint_ms": latency_hint_ms,
+        "safety_notes": safety_notes,
+        "extra": dict(extra) if extra else {},
+    }
+
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        func_ref = cast(Any, func)
+        func_ref.__penguiflow_tool__ = payload
+        return func
+
+    return decorator
+
+
+def _load_metadata(func: Callable[..., Any]) -> dict[str, Any]:
+    raw = getattr(func, "__penguiflow_tool__", None)
+    if not raw:
+        return {
+            "desc": inspect.getdoc(func) or func.__name__,
+            "side_effects": "pure",
+            "tags": (),
+            "auth_scopes": (),
+            "cost_hint": None,
+            "latency_hint_ms": None,
+            "safety_notes": None,
+            "extra": {},
+        }
+    return {
+        "desc": raw.get("desc") or inspect.getdoc(func) or func.__name__,
+        "side_effects": raw.get("side_effects", "pure"),
+        "tags": tuple(raw.get("tags", ())),
+        "auth_scopes": tuple(raw.get("auth_scopes", ())),
+        "cost_hint": raw.get("cost_hint"),
+        "latency_hint_ms": raw.get("latency_hint_ms"),
+        "safety_notes": raw.get("safety_notes"),
+        "extra": dict(raw.get("extra", {})),
+    }
+
+
+def build_catalog(
+    nodes: Sequence[Node],
+    registry: ModelRegistry,
+) -> list[NodeSpec]:
+    """Derive :class:`NodeSpec` objects from runtime nodes."""
+
+    specs: list[NodeSpec] = []
+    for node in nodes:
+        node_name = node.name or node.func.__name__
+        in_model, out_model = registry.models(node_name)
+        metadata = _load_metadata(node.func)
+        specs.append(
+            NodeSpec(
+                node=node,
+                name=node_name,
+                desc=metadata["desc"],
+                args_model=in_model,
+                out_model=out_model,
+                side_effects=metadata["side_effects"],
+                tags=metadata["tags"],
+                auth_scopes=metadata["auth_scopes"],
+                cost_hint=metadata["cost_hint"],
+                latency_hint_ms=metadata["latency_hint_ms"],
+                safety_notes=metadata["safety_notes"],
+                extra=metadata["extra"],
+            )
+        )
+    return specs
+
+
+__all__ = ["NodeSpec", "SideEffect", "build_catalog", "tool"]

penguiflow/core.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 import asyncio
 import logging
 import time
+import warnings
 from collections import deque
 from collections.abc import Awaitable, Callable, Mapping, Sequence
 from contextlib import suppress
@@ -686,6 +687,21 @@ class PenguiFlow:
                     trace_id,
                 )
 
+                if (
+                    result is not None
+                    and self._expects_message_output(node)
+                    and not isinstance(result, Message)
+                ):
+                    node_name = node.name or node.node_id
+                    warning_msg = (
+                        "Node "
+                        f"'{node_name}' is registered for Message -> Message outputs "
+                        f"but returned {type(result).__name__}. "
+                        "Return a penguiflow.types.Message to preserve headers, "
+                        "trace_id, and meta."
+                    )
+                    warnings.warn(warning_msg, RuntimeWarning, stacklevel=2)
+
                 if result is not None:
                     (
                         destination,
@@ -1210,6 +1226,29 @@ class PenguiFlow:
         for waiter in waiters:
             waiter.set()
 
+    def _expects_message_output(self, node: Node) -> bool:
+        registry = self._registry
+        if registry is None:
+            return False
+
+        models = getattr(registry, "models", None)
+        if models is None:
+            return False
+
+        node_name = node.name
+        if not node_name:
+            return False
+
+        try:
+            _in_model, out_model = models(node_name)
+        except Exception:  # pragma: no cover - registry without entry
+            return False
+
+        try:
+            return issubclass(out_model, Message)
+        except TypeError:
+            return False
+
     def _controller_postprocess(
         self,
         node: Node,

penguiflow/debug.py

@@ -0,0 +1,30 @@
+"""Developer-facing debugging helpers for PenguiFlow."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from .metrics import FlowEvent
+
+
+def format_flow_event(event: FlowEvent) -> dict[str, Any]:
+    """Return a structured payload ready for logging.
+
+    The returned dictionary mirrors :meth:`FlowEvent.to_payload` and flattens any
+    embedded ``FlowError`` payload so that log aggregators can index the error
+    metadata (``flow_error_code``, ``flow_error_message``, ...).
+    """
+
+    payload = dict(event.to_payload())
+    error_payload: Mapping[str, Any] | None = event.error_payload
+    if error_payload is not None:
+        # Preserve the original payload for downstream consumers.
+        payload["flow_error"] = dict(error_payload)
+        for key, value in error_payload.items():
+            payload[f"flow_error_{key}"] = value
+    return payload
+
+
+__all__ = ["format_flow_event"]
+

penguiflow/metrics.py

@@ -31,6 +31,15 @@ class FlowEvent:
     def __post_init__(self) -> None:
         object.__setattr__(self, "extra", MappingProxyType(dict(self.extra)))
 
+    @property
+    def error_payload(self) -> Mapping[str, Any] | None:
+        """Return the structured ``FlowError`` payload if present."""
+
+        raw_payload = self.extra.get("flow_error")
+        if isinstance(raw_payload, Mapping):
+            return MappingProxyType(dict(raw_payload))
+        return None
+
     @property
     def queue_depth(self) -> int:
         """Return the combined depth of incoming and outgoing queues."""

penguiflow/middlewares.py

@@ -2,10 +2,14 @@
 
 from __future__ import annotations
 
+import logging
+from collections.abc import Callable
 from typing import Protocol
 
 from .metrics import FlowEvent
 
+LatencyCallback = Callable[[str, float, FlowEvent], None]
+
 
 class Middleware(Protocol):
     """Base middleware signature receiving :class:`FlowEvent` objects."""
@@ -13,4 +17,71 @@ class Middleware(Protocol):
     async def __call__(self, event: FlowEvent) -> None: ...
 
 
-__all__ = ["Middleware", "FlowEvent"]
+def log_flow_events(
+    logger: logging.Logger | None = None,
+    *,
+    start_level: int = logging.INFO,
+    success_level: int = logging.INFO,
+    error_level: int = logging.ERROR,
+    latency_callback: LatencyCallback | None = None,
+) -> Middleware:
+    """Return middleware that emits structured node lifecycle logs.
+
+    Parameters
+    ----------
+    logger:
+        Optional :class:`logging.Logger` instance. When omitted a logger named
+        ``"penguiflow.flow"`` is used.
+    start_level, success_level, error_level:
+        Logging levels for ``node_start``, ``node_success``, and
+        ``node_error`` events respectively.
+    latency_callback:
+        Optional callable invoked with ``(event_type, latency_ms, event)`` for
+        ``node_success`` and ``node_error`` events. Use this hook to connect the
+        middleware to histogram-based metrics backends without
+        re-implementing timing logic.
+    """
+
+    log = logger or logging.getLogger("penguiflow.flow")
+
+    async def _middleware(event: FlowEvent) -> None:
+        if event.event_type not in {"node_start", "node_success", "node_error"}:
+            return
+
+        payload = event.to_payload()
+        log_level = start_level
+
+        if event.event_type == "node_start":
+            log_level = start_level
+        elif event.event_type == "node_success":
+            log_level = success_level
+        else:
+            log_level = error_level
+            if event.error_payload is not None:
+                payload = dict(payload)
+                payload["error_payload"] = dict(event.error_payload)
+
+        log.log(log_level, event.event_type, extra=payload)
+
+        if (
+            latency_callback is not None
+            and event.event_type in {"node_success", "node_error"}
+            and event.latency_ms is not None
+        ):
+            try:
+                latency_callback(event.event_type, float(event.latency_ms), event)
+            except Exception:
+                log.exception(
+                    "log_flow_events_latency_callback_error",
+                    extra={
+                        "event": "log_flow_events_latency_callback_error",
+                        "node_name": event.node_name,
+                        "node_id": event.node_id,
+                        "trace_id": event.trace_id,
+                    },
+                )
+
+    return _middleware
+
+
+__all__ = ["Middleware", "FlowEvent", "log_flow_events", "LatencyCallback"]

penguiflow/registry.py

@@ -15,6 +15,8 @@ ModelT = TypeVar("ModelT", bound=BaseModel)
 class RegistryEntry:
     in_adapter: TypeAdapter[Any]
     out_adapter: TypeAdapter[Any]
+    in_model: type[BaseModel]
+    out_model: type[BaseModel]
 
 
 class ModelRegistry:
@@ -36,6 +38,8 @@ class ModelRegistry:
         self._entries[node_name] = RegistryEntry(
             TypeAdapter(in_model),
             TypeAdapter(out_model),
+            in_model,
+            out_model,
         )
 
     def adapters(self, node_name: str) -> tuple[TypeAdapter[Any], TypeAdapter[Any]]:
@@ -45,5 +49,22 @@ class ModelRegistry:
             raise KeyError(f"Node '{node_name}' not registered") from exc
         return entry.in_adapter, entry.out_adapter
 
+    def models(
+        self, node_name: str
+    ) -> tuple[type[BaseModel], type[BaseModel]]:
+        """Return the registered models for ``node_name``.
+
+        Raises
+        ------
+        KeyError
+            If the node has not been registered.
+        """
+
+        try:
+            entry = self._entries[node_name]
+        except KeyError as exc:
+            raise KeyError(f"Node '{node_name}' not registered") from exc
+        return entry.in_model, entry.out_model
+
 
 __all__ = ["ModelRegistry"]

penguiflow/testkit.py

@@ -21,9 +21,15 @@ from weakref import WeakKeyDictionary
 from .core import PenguiFlow
 from .errors import FlowErrorCode
 from .metrics import FlowEvent
-from .types import Message
+from .types import Headers, Message
 
-__all__ = ["run_one", "assert_node_sequence", "simulate_error"]
+__all__ = [
+    "run_one",
+    "assert_node_sequence",
+    "get_recorded_events",
+    "simulate_error",
+    "assert_preserves_message_envelope",
+]
 
 
 _MAX_TRACE_HISTORY = 64
@@ -102,6 +108,20 @@ class _Recorder:
         await self._state.record(event)
 
 
+class _StubContext:
+    async def emit(self, *_args: Any, **_kwargs: Any) -> None:
+        return None
+
+    def emit_nowait(self, *_args: Any, **_kwargs: Any) -> None:
+        return None
+
+    async def emit_chunk(self, *_args: Any, **_kwargs: Any) -> Any:
+        raise RuntimeError(
+            "FlowTestKit stub context does not support emit_chunk; provide a custom"
+            " context via the 'ctx' parameter"
+        )
+
+
 def _get_state(flow: PenguiFlow) -> _RecorderState:
     state = _RECORDER_STATE.get(flow)
     if state is None:
@@ -150,6 +170,78 @@ async def run_one(
     return result
 
 
+async def assert_preserves_message_envelope(
+    node: Callable[[Message, Any], Awaitable[Any]] | Any,
+    *,
+    message: Message | None = None,
+    ctx: Any | None = None,
+) -> Message:
+    """Execute ``node`` and assert it preserves the ``Message`` envelope.
+
+    Parameters
+    ----------
+    node:
+        Either a bare async callable or a :class:`penguiflow.node.Node` whose
+        first parameter is a :class:`~penguiflow.types.Message` instance.
+    message:
+        Optional sample message. When omitted, a minimal envelope is
+        synthesised.
+    ctx:
+        Optional context object passed to the node. By default a stub context
+        is used that simply no-ops ``emit``/``emit_nowait``.
+
+    Returns
+    -------
+    Message
+        The resulting message from the node, allowing additional assertions.
+
+    Raises
+    ------
+    AssertionError
+        If the node does not return a ``Message`` or mutates core envelope
+        fields (headers or trace_id).
+    TypeError
+        If ``node`` is not awaitable.
+    """
+
+    from .node import Node  # Local import to avoid circular dependency
+
+    if isinstance(node, Node):
+        func = node.func
+        node_name = node.name or node.func.__name__
+    else:
+        func = node
+        node_name = getattr(node, "__name__", "<anonymous>")
+
+    if not inspect.iscoroutinefunction(func):
+        raise TypeError("assert_preserves_message_envelope expects an async node")
+
+    sample = message or Message(payload={}, headers=Headers(tenant="test"))
+    context = ctx if ctx is not None else _StubContext()
+
+    result = await func(sample, context)
+    if not isinstance(result, Message):
+        produced = type(result).__name__
+        raise AssertionError(
+            "Node "
+            f"'{node_name}' must return a Message but produced {produced}"
+        )
+
+    mismatches: list[str] = []
+    if result.headers != sample.headers:
+        mismatches.append("headers")
+    if result.trace_id != sample.trace_id:
+        mismatches.append("trace_id")
+
+    if mismatches:
+        joined = ", ".join(mismatches)
+        raise AssertionError(
+            f"Node '{node_name}' altered Message {joined}; preserve the envelope"
+        )
+
+    return result
+
+
 def assert_node_sequence(trace_id: str, expected: Sequence[str]) -> None:
     """Assert that ``expected`` matches the recorded node start order."""
 
@@ -175,6 +267,19 @@ def assert_node_sequence(trace_id: str, expected: Sequence[str]) -> None:
         )
 
 
+def get_recorded_events(trace_id: str) -> tuple[FlowEvent, ...]:
+    """Return the recorded :class:`FlowEvent` history for ``trace_id``.
+
+    The FlowTestKit recorder maintains a bounded cache of trace histories.
+    This helper exposes the immutable snapshot so tests can assert on
+    diagnostics such as ``node_failed`` payloads or retry attempts without
+    touching the private cache directly.
+    """
+
+    events = _TRACE_HISTORY.get(trace_id, [])
+    return tuple(events)
+
+
 class _ErrorSimulation:
     def __init__(
         self,

{penguiflow-2.1.0.dist-info → penguiflow-2.2.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: penguiflow
-Version: 2.1.0
+Version: 2.2.1
 Summary: Async agent orchestration primitives.
 Author: PenguiFlow Team
 License: MIT License
@@ -36,11 +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.110; extra == "dev"
+Requires-Dist: fastapi>=0.118; extra == "dev"
 Requires-Dist: httpx>=0.27; extra == "dev"
 Provides-Extra: a2a-server
-Requires-Dist: fastapi>=0.110; 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 🐧❄️
@@ -50,18 +53,11 @@ Dynamic: license-file
 </p>
 
 <p align="center">
-  <a href="https://github.com/penguiflow/penguiflow/actions/workflows/ci.yml">
-    <img src="https://github.com/penguiflow/penguiflow/actions/workflows/ci.yml/badge.svg" alt="CI Status">
-  </a>
-  <a href="https://github.com/penguiflow/penguiflow">
-    <img src="https://img.shields.io/badge/coverage-85%25-brightgreen" alt="Coverage">
-  </a>
-  <a href="https://pypi.org/project/penguiflow/">
-    <img src="https://img.shields.io/pypi/v/penguiflow.svg" alt="PyPI version">
-  </a>
-  <a href="https://github.com/penguiflow/penguiflow/blob/main/LICENSE">
-    <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License">
-  </a>
+  <a href="https://github.com/hurtener/penguiflow/actions/workflows/ci.yml"><img src="https://github.com/hurtener/penguiflow/actions/workflows/ci.yml/badge.svg" alt="CI Status"></a>
+  <a href="https://github.com/hurtener/penguiflow"><img src="https://img.shields.io/badge/coverage-85%25-brightgreen" alt="Coverage"></a>
+  <a href="https://nightly.link/hurtener/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>
+  <a href="https://github.com/hurtener/penguiflow/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
 </p>
 
 **Async-first orchestration library for multi-agent and data pipelines**
@@ -75,6 +71,7 @@ It provides:
 * **Retries, timeouts, backpressure**
 * **Streaming chunks** (LLM-style token emission with `Context.emit_chunk`)
 * **Dynamic loops** (controller nodes)
+* **LLM-driven orchestration** (`ReactPlanner` for autonomous multi-step workflows with tool selection, parallel execution, and pause/resume)
 * **Runtime playbooks** (callable subflows with shared metadata)
 * **Per-trace cancellation** (`PenguiFlow.cancel` with `TraceCancelled` surfacing in nodes)
 * **Deadlines & budgets** (`Message.deadline_s`, `WM.budget_hops`, and `WM.budget_tokens` guardrails that you can leave unset/`None`)
@@ -97,6 +94,23 @@ It provides:
 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?
@@ -346,6 +360,53 @@ The new `penguiflow.testkit` module keeps unit tests tiny:
 The harness is covered by `tests/test_testkit.py` and demonstrated in
 `examples/testkit_demo/`.
 
+### React Planner - LLM-Driven Orchestration
+
+Build autonomous agents that select and execute tools dynamically using the ReAct (Reasoning + Acting) pattern:
+
+```python
+from penguiflow import ReactPlanner, tool, build_catalog
+
+@tool(desc="Search documentation")
+async def search_docs(args: Query, ctx) -> Documents:
+    return Documents(results=await search(args.text))
+
+@tool(desc="Summarize results")
+async def summarize(args: Documents, ctx) -> Summary:
+    return Summary(text=await llm_summarize(args.results))
+
+planner = ReactPlanner(
+    llm="gpt-4",
+    catalog=build_catalog([search_docs, summarize], registry),
+    max_iters=10
+)
+
+result = await planner.run("Explain PenguiFlow routing")
+print(result.payload)  # LLM orchestrated search → summarize automatically
+```
+
+**Key capabilities:**
+
+* **Autonomous tool selection** — LLM decides which tools to call and in what order based on your query
+* **Type-safe execution** — All tool inputs/outputs validated with Pydantic, JSON schemas auto-generated from models
+* **Parallel execution** — LLM can fan out to multiple tools concurrently with automatic result joining
+* **Pause/resume workflows** — Add approval gates with `await ctx.pause()`, resume later with user input
+* **Adaptive replanning** — Tool failures feed structured error suggestions back to LLM for recovery
+* **Constraint enforcement** — Set hop budgets, deadlines, and token limits to prevent runaway execution
+* **Planning hints** — Guide LLM behavior with ordering preferences, parallel groups, and tool filters
+
+**Model support:**
+* Install `penguiflow[planner]` for LiteLLM integration (100+ models: OpenAI, Anthropic, Azure, etc.)
+* Or inject a custom `llm_client` for deterministic/offline testing
+
+**Examples:**
+* `examples/react_minimal/` — Basic sequential flow with stub LLM
+* `examples/react_parallel/` — Parallel shard fan-out with join node
+* `examples/react_pause_resume/` — Approval workflow with planning hints
+* `examples/react_replan/` — Adaptive recovery from tool failures
+
+See **manual.md Section 19** for complete documentation.
+
 
 ## 🧭 Repo Structure
 
@@ -626,6 +687,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.1.0.dist-info → penguiflow-2.2.1.dist-info}/RECORD

@@ -1,25 +1,27 @@
-penguiflow/__init__.py,sha256=Ik7scO1qMwAI0iTL2ASII_z2jl7kpkUAhsQ2yAuUstI,1944
+penguiflow/__init__.py,sha256=kc4GWt5h5HFqOWMoL8Holk_QSxhOr8KHKsLSLJEeuz0,2435
 penguiflow/admin.py,sha256=093xFkE4bM_2ZhLrzhrEUKtmKHi_yVfMPyaGfwi1rcA,5382
 penguiflow/bus.py,sha256=mb29509_n97A6zwC-6EDpYorfAWFSpwqsMu_WeZhLE8,732
-penguiflow/core.py,sha256=LRE2TUkAXhiVEO6trD1T1NP_7PRwTFy4MLvzVW0pN24,52631
+penguiflow/catalog.py,sha256=z-Drf6PbEkvd65PcBvsVJZBBnM9GwT8ctcMdiIoQ5HY,4673
+penguiflow/core.py,sha256=7w3fbyfQspt0aRt5nfDcr2kzPzX7Tf7O83v-U64DfHI,53960
+penguiflow/debug.py,sha256=KPdpWbascsi1ghu-2HPqRORPM2iqkuV6qWyPc0mAalY,945
 penguiflow/errors.py,sha256=mXpCqZ3zdvz7J7Dck_kcw2BGTIm9yrJAjxp_L8KMY7o,3419
-penguiflow/metrics.py,sha256=RW76sYDebzix6Hf7mDemOj-4SwsnILu5YVEoUHNUKuA,3675
-penguiflow/middlewares.py,sha256=4mQgkPowTs6II-_UvIFGyMUTvzhxwDYUicvJMpNNlPU,341
+penguiflow/metrics.py,sha256=KsxH9tUqrYfs3EyccLcM0-haYySAByq7RMnK7q61eRA,3989
+penguiflow/middlewares.py,sha256=cB4SrRciNcKHyLanaMVsfMElt3El0LNCj_3dyik07x4,2864
 penguiflow/node.py,sha256=0NOs3rU6t1tHNNwwJopqzM2ufGcp82JpzhckynWBRqs,3563
 penguiflow/patterns.py,sha256=qtzRSNRKxV5_qEPXhffd15PuCZs0YnoGF80nNUsrcxw,5512
 penguiflow/policies.py,sha256=3w8ionnpTyuA0ZCc3jPpB011L7_i1qlbiO6escY024s,4385
-penguiflow/registry.py,sha256=4lrGDMFjM7c8pfZFc_YG0YHg-F80JyF4c-j0UbAf150,1419
+penguiflow/registry.py,sha256=1nR3J1A6jzuevH8EMn83vCkSnnNKgE28CCO6fXMA3wE,2001
 penguiflow/remote.py,sha256=0-2aW48P8OB8KLEC_7_F_RHtzVJk3huyAMBGdXjmWeA,16426
 penguiflow/state.py,sha256=fBY5d_48hR4XHWVG08FraaQ7u4IVPJwooewfVLmzu1Q,1773
 penguiflow/streaming.py,sha256=RKMm4VfaDA2ceEM_pB2Cuhmpwtdcjj7og-kjXQQDcbc,3863
-penguiflow/testkit.py,sha256=wNPqLldHjoq6q7RItSEdKLveSHqXkNj1HAS_FTZDxxs,8581
+penguiflow/testkit.py,sha256=pIFYpu1RfJnW2mbGvUkPhMpL-xDAw0E959oTMxLkLh8,11806
 penguiflow/types.py,sha256=Fl56-b7OwIEUbPMDD1CY09nbOG_tmBw3FUhioojeG5M,1503
 penguiflow/viz.py,sha256=KbBb9kKoL223vj0NgJV_jo5ny-0RTc2gcSBACm0jG8w,5508
-penguiflow-2.1.0.dist-info/licenses/LICENSE,sha256=JSvodvLXxSct_kI9IBsZOBpVKoESQTB_AGbkClwZ7HI,1065
+penguiflow-2.2.1.dist-info/licenses/LICENSE,sha256=JSvodvLXxSct_kI9IBsZOBpVKoESQTB_AGbkClwZ7HI,1065
 penguiflow_a2a/__init__.py,sha256=JuK_ov06yS2H97D2OVXhgX8LcgdOqE3EujUPaDKaduc,342
 penguiflow_a2a/server.py,sha256=VMBO-oGjB6Z9mtRBU0z7ZFGprDUC_kihZJukh3budbs,25932
-penguiflow-2.1.0.dist-info/METADATA,sha256=ep-_5zifZ9G-25TSfCzctVMsiom1QdrZXx_b0tZAaog,24706
-penguiflow-2.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-penguiflow-2.1.0.dist-info/entry_points.txt,sha256=F2KxANLEVGRbpWLmcHcvYrTVLWbKWdmk3VOe98a7t9I,59
-penguiflow-2.1.0.dist-info/top_level.txt,sha256=K-fTwLA14n0u_LDxDBCV7FmeBnJffhTOtUbTtOymQns,26
-penguiflow-2.1.0.dist-info/RECORD,,
+penguiflow-2.2.1.dist-info/METADATA,sha256=ve8PUCCS-W-ws6LYxSaiudqmLeArnH-tYqINRBJS48w,27930
+penguiflow-2.2.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+penguiflow-2.2.1.dist-info/entry_points.txt,sha256=F2KxANLEVGRbpWLmcHcvYrTVLWbKWdmk3VOe98a7t9I,59
+penguiflow-2.2.1.dist-info/top_level.txt,sha256=K-fTwLA14n0u_LDxDBCV7FmeBnJffhTOtUbTtOymQns,26
+penguiflow-2.2.1.dist-info/RECORD,,