penguiflow 2.1.0__tar.gz → 2.2.1__tar.gz

{penguiflow-2.1.0 → penguiflow-2.2.1}/PKG-INFO

@@ -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 → penguiflow-2.2.1}/README.md

@@ -5,18 +5,11 @@
 </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**
@@ -30,6 +23,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`)
@@ -52,6 +46,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?
@@ -301,6 +312,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
 
@@ -581,6 +639,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 → penguiflow-2.2.1}/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-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-2.1.0 → penguiflow-2.2.1}/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-2.2.1/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-2.1.0 → penguiflow-2.2.1}/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-2.2.1/penguiflow/middlewares.py

@@ -0,0 +1,87 @@
+"""Middleware hooks for PenguiFlow."""
+
+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."""
+
+    async def __call__(self, event: FlowEvent) -> None: ...
+
+
+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"]