penguiflow 1.0.0__tar.gz → 1.0.3__tar.gz

{penguiflow-1.0.0 → penguiflow-1.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: penguiflow
-Version: 1.0.0
+Version: 1.0.3
 Summary: Async agent orchestration primitives.
 Author: PenguiFlow Team
 License: MIT License
@@ -99,7 +99,7 @@ from penguiflow.node import Node
 class QueryOut(BaseModel):
     topic: str
 
-async def triage(m: QueryIn) -> QueryOut:
+async def triage(msg: QueryIn, ctx) -> QueryOut:
     return QueryOut(topic="metrics")
 
 triage_node = Node(triage, name="triage")
@@ -147,11 +147,13 @@ await flow.stop()
    * Flows are orchestrators, mostly I/O-bound.
    * Async tasks are cheap, predictable, and cancellable.
    * Heavy CPU work should be offloaded inside a node (process pool, Ray, etc.), not in PenguiFlow itself.
+   * v1 intentionally stays in-process; scaling out or persisting state will arrive with future pluggable backends.
 
 2. **Typed contracts.**
 
    * In/out models per node are defined with Pydantic.
    * Validated at runtime via cached `TypeAdapter`s.
+   * `flow.run(registry=...)` verifies every validating node is registered so misconfigurations fail fast.
 
 3. **Reliability first.**
 
@@ -326,11 +328,42 @@ flow focused on high-level orchestration logic.
 
 ---
 
+### Visualization
+
+Need a quick view of the flow topology? Call `flow_to_mermaid(flow)` to render the graph
+as a Mermaid diagram ready for Markdown or docs tools:
+
+```python
+from penguiflow import flow_to_mermaid
+
+print(flow_to_mermaid(flow, direction="LR"))
+```
+
+---
+
 ## 🛡️ Reliability & Observability
 
 * **NodePolicy**: set validation scope plus per-node timeout, retries, and backoff curves.
 * **Structured logs**: enrich every node event with `{ts, trace_id, node_name, event, latency_ms, q_depth_in, attempt}`.
 * **Middleware hooks**: subscribe observers (e.g., MLflow) to the structured event stream.
+* See `examples/reliability_middleware/` for a concrete timeout + retry walkthrough.
+
+---
+
+## ⚠️ Current Constraints
+
+- **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 logs + middleware hooks are available, but integrations with third-party stacks (OTel, Prometheus) are DIY for now.
+- **Roadmap**: v2 targets streaming, distributed backends, richer observability, and test harnesses. Contributions and proposals are welcome!
+
+---
+
+## 📊 Benchmarks
+
+Lightweight benchmarks live under `benchmarks/`. Run them via `uv run python benchmarks/<name>.py`
+to capture baselines for fan-out throughput, retry/timeout overhead, and controller
+playbook latency. Copy them into product repos to watch for regressions over time.
 
 ---
 

{penguiflow-1.0.0 → penguiflow-1.0.3}/README.md

@@ -60,7 +60,7 @@ from penguiflow.node import Node
 class QueryOut(BaseModel):
     topic: str
 
-async def triage(m: QueryIn) -> QueryOut:
+async def triage(msg: QueryIn, ctx) -> QueryOut:
     return QueryOut(topic="metrics")
 
 triage_node = Node(triage, name="triage")
@@ -108,11 +108,13 @@ await flow.stop()
    * Flows are orchestrators, mostly I/O-bound.
    * Async tasks are cheap, predictable, and cancellable.
    * Heavy CPU work should be offloaded inside a node (process pool, Ray, etc.), not in PenguiFlow itself.
+   * v1 intentionally stays in-process; scaling out or persisting state will arrive with future pluggable backends.
 
 2. **Typed contracts.**
 
    * In/out models per node are defined with Pydantic.
    * Validated at runtime via cached `TypeAdapter`s.
+   * `flow.run(registry=...)` verifies every validating node is registered so misconfigurations fail fast.
 
 3. **Reliability first.**
 
@@ -287,11 +289,42 @@ flow focused on high-level orchestration logic.
 
 ---
 
+### Visualization
+
+Need a quick view of the flow topology? Call `flow_to_mermaid(flow)` to render the graph
+as a Mermaid diagram ready for Markdown or docs tools:
+
+```python
+from penguiflow import flow_to_mermaid
+
+print(flow_to_mermaid(flow, direction="LR"))
+```
+
+---
+
 ## 🛡️ Reliability & Observability
 
 * **NodePolicy**: set validation scope plus per-node timeout, retries, and backoff curves.
 * **Structured logs**: enrich every node event with `{ts, trace_id, node_name, event, latency_ms, q_depth_in, attempt}`.
 * **Middleware hooks**: subscribe observers (e.g., MLflow) to the structured event stream.
+* See `examples/reliability_middleware/` for a concrete timeout + retry walkthrough.
+
+---
+
+## ⚠️ Current Constraints
+
+- **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 logs + middleware hooks are available, but integrations with third-party stacks (OTel, Prometheus) are DIY for now.
+- **Roadmap**: v2 targets streaming, distributed backends, richer observability, and test harnesses. Contributions and proposals are welcome!
+
+---
+
+## 📊 Benchmarks
+
+Lightweight benchmarks live under `benchmarks/`. Run them via `uv run python benchmarks/<name>.py`
+to capture baselines for fan-out throughput, retry/timeout overhead, and controller
+playbook latency. Copy them into product repos to watch for regressions over time.
 
 ---
 

{penguiflow-1.0.0 → penguiflow-1.0.3}/penguiflow/__init__.py

@@ -15,6 +15,7 @@ from .node import Node, NodePolicy
 from .patterns import join_k, map_concurrent, predicate_router, union_router
 from .registry import ModelRegistry
 from .types import WM, FinalAnswer, Headers, Message, PlanStep, Thought
+from .viz import flow_to_mermaid
 
 __all__ = [
     "__version__",
@@ -37,7 +38,8 @@ __all__ = [
     "join_k",
     "predicate_router",
     "union_router",
+    "flow_to_mermaid",
     "create",
 ]
 
-__version__ = "1.0.0"
+__version__ = "1.0.3"

{penguiflow-1.0.0 → penguiflow-1.0.3}/penguiflow/core.py

@@ -288,6 +288,8 @@ class PenguiFlow:
             raise RuntimeError("PenguiFlow already running")
         self._running = True
         self._registry = registry
+        if registry is not None:
+            self._ensure_registry_covers_nodes(registry)
         loop = asyncio.get_running_loop()
 
         for node in self._nodes:
@@ -542,6 +544,26 @@ class PenguiFlow:
                     },
                 )
 
+    def _ensure_registry_covers_nodes(self, registry: ModelRegistry) -> None:
+        missing: list[str] = []
+        for node in self._nodes:
+            if node.policy.validate == "none":
+                continue
+            node_name = node.name
+            if node_name is None:
+                continue
+            try:
+                registry.adapters(node_name)
+            except KeyError:
+                missing.append(node_name)
+
+        if missing:
+            formatted = ", ".join(sorted(missing))
+            raise RuntimeError(
+                "ModelRegistry is missing entries for nodes requiring validation: "
+                f"{formatted}"
+            )
+
 
 PlaybookFactory = Callable[[], tuple["PenguiFlow", ModelRegistry | None]]
 

penguiflow-1.0.3/penguiflow/viz.py

@@ -0,0 +1,76 @@
+"""Visualization helpers for PenguiFlow graphs."""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+from .core import Endpoint
+from .node import Node
+
+if TYPE_CHECKING:  # pragma: no cover - type checking only
+    from .core import PenguiFlow
+
+__all__ = ["flow_to_mermaid"]
+
+
+def flow_to_mermaid(flow: PenguiFlow, *, direction: str = "TD") -> str:
+    """Render the flow graph as a Mermaid diagram string.
+
+    Parameters
+    ----------
+    flow:
+        The `PenguiFlow` instance to visualize.
+    direction:
+        Mermaid graph direction ("TD", "LR", etc.). Defaults to top-down.
+    """
+
+    lines: list[str] = [f"graph {direction}"]
+    nodes: set[object] = set()
+
+    for floe in flow._floes:  # noqa: SLF001 - visualization accesses internals by design
+        if floe.source is not None:
+            nodes.add(floe.source)
+        if floe.target is not None:
+            nodes.add(floe.target)
+
+    id_lookup: dict[object, str] = {}
+    used_ids: set[str] = set()
+
+    for entity in nodes:
+        label = _display_label(entity)
+        node_id = _unique_id(label, used_ids)
+        used_ids.add(node_id)
+        id_lookup[entity] = node_id
+        lines.append(f"    {node_id}[\"{label}\"]")
+
+    for floe in flow._floes:  # noqa: SLF001
+        source = floe.source
+        target = floe.target
+        if source is None or target is None:
+            continue
+        src_id = id_lookup.get(source)
+        tgt_id = id_lookup.get(target)
+        if src_id is None or tgt_id is None:
+            continue
+        lines.append(f"    {src_id} --> {tgt_id}")
+
+    return "\n".join(lines)
+
+
+def _display_label(entity: object) -> str:
+    if isinstance(entity, Node):
+        return entity.name or entity.node_id
+    if isinstance(entity, Endpoint):
+        return entity.name
+    return str(entity)
+
+
+def _unique_id(label: str, used: set[str]) -> str:
+    base = re.sub(r"[^0-9A-Za-z_]", "_", label) or "node"
+    candidate = base
+    index = 1
+    while candidate in used:
+        index += 1
+        candidate = f"{base}_{index}"
+    return candidate

{penguiflow-1.0.0 → penguiflow-1.0.3}/penguiflow.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: penguiflow
-Version: 1.0.0
+Version: 1.0.3
 Summary: Async agent orchestration primitives.
 Author: PenguiFlow Team
 License: MIT License
@@ -99,7 +99,7 @@ from penguiflow.node import Node
 class QueryOut(BaseModel):
     topic: str
 
-async def triage(m: QueryIn) -> QueryOut:
+async def triage(msg: QueryIn, ctx) -> QueryOut:
     return QueryOut(topic="metrics")
 
 triage_node = Node(triage, name="triage")
@@ -147,11 +147,13 @@ await flow.stop()
    * Flows are orchestrators, mostly I/O-bound.
    * Async tasks are cheap, predictable, and cancellable.
    * Heavy CPU work should be offloaded inside a node (process pool, Ray, etc.), not in PenguiFlow itself.
+   * v1 intentionally stays in-process; scaling out or persisting state will arrive with future pluggable backends.
 
 2. **Typed contracts.**
 
    * In/out models per node are defined with Pydantic.
    * Validated at runtime via cached `TypeAdapter`s.
+   * `flow.run(registry=...)` verifies every validating node is registered so misconfigurations fail fast.
 
 3. **Reliability first.**
 
@@ -326,11 +328,42 @@ flow focused on high-level orchestration logic.
 
 ---
 
+### Visualization
+
+Need a quick view of the flow topology? Call `flow_to_mermaid(flow)` to render the graph
+as a Mermaid diagram ready for Markdown or docs tools:
+
+```python
+from penguiflow import flow_to_mermaid
+
+print(flow_to_mermaid(flow, direction="LR"))
+```
+
+---
+
 ## 🛡️ Reliability & Observability
 
 * **NodePolicy**: set validation scope plus per-node timeout, retries, and backoff curves.
 * **Structured logs**: enrich every node event with `{ts, trace_id, node_name, event, latency_ms, q_depth_in, attempt}`.
 * **Middleware hooks**: subscribe observers (e.g., MLflow) to the structured event stream.
+* See `examples/reliability_middleware/` for a concrete timeout + retry walkthrough.
+
+---
+
+## ⚠️ Current Constraints
+
+- **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 logs + middleware hooks are available, but integrations with third-party stacks (OTel, Prometheus) are DIY for now.
+- **Roadmap**: v2 targets streaming, distributed backends, richer observability, and test harnesses. Contributions and proposals are welcome!
+
+---
+
+## 📊 Benchmarks
+
+Lightweight benchmarks live under `benchmarks/`. Run them via `uv run python benchmarks/<name>.py`
+to capture baselines for fan-out throughput, retry/timeout overhead, and controller
+playbook latency. Copy them into product repos to watch for regressions over time.
 
 ---
 

{penguiflow-1.0.0 → penguiflow-1.0.3}/penguiflow.egg-info/SOURCES.txt

@@ -18,4 +18,5 @@ tests/test_controller.py
 tests/test_core.py
 tests/test_patterns.py
 tests/test_registry.py
-tests/test_types.py
+tests/test_types.py
+tests/test_viz.py

{penguiflow-1.0.0 → penguiflow-1.0.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "penguiflow"
-version = "1.0.0"
+version = "1.0.3"
 description = "Async agent orchestration primitives."
 readme = "README.md"
 requires-python = ">=3.12"

{penguiflow-1.0.0 → penguiflow-1.0.3}/tests/test_core.py

@@ -6,9 +6,11 @@ import asyncio
 import logging
 
 import pytest
+from pydantic import BaseModel
 
 from penguiflow.core import CycleError, PenguiFlow, create
 from penguiflow.node import Node, NodePolicy
+from penguiflow.registry import ModelRegistry
 
 
 @pytest.mark.asyncio
@@ -249,3 +251,44 @@ async def test_middlewares_receive_events() -> None:
 
     events_names = [name for name, _ in events]
     assert "node_success" in events_names
+
+
+@pytest.mark.asyncio
+async def test_run_with_registry_requires_registered_nodes() -> None:
+    async def handler(msg: str, ctx) -> str:
+        return msg
+
+    node = Node(handler, name="handler")
+    flow = create(node.to())
+    registry = ModelRegistry()
+
+    with pytest.raises(RuntimeError) as exc:
+        flow.run(registry=registry)
+
+    assert "handler" in str(exc.value)
+
+
+@pytest.mark.asyncio
+async def test_run_with_registry_accepts_registered_nodes() -> None:
+    class EchoModel(BaseModel):
+        text: str
+
+    async def handler(msg: EchoModel, ctx) -> EchoModel:
+        return msg
+
+    node = Node(handler, name="echo")
+    flow = create(node.to())
+
+    registry = ModelRegistry()
+    registry.register("echo", EchoModel, EchoModel)
+
+    flow.run(registry=registry)
+
+    message = EchoModel(text="hi")
+    await flow.emit(message)
+    result = await flow.fetch()
+
+    assert isinstance(result, EchoModel)
+    assert result.text == "hi"
+
+    await flow.stop()

penguiflow-1.0.3/tests/test_viz.py

@@ -0,0 +1,29 @@
+"""Tests for visualization helpers."""
+
+from __future__ import annotations
+
+import pytest
+
+from penguiflow import Node, NodePolicy, create
+from penguiflow.viz import flow_to_mermaid
+
+
+@pytest.mark.asyncio
+async def test_flow_to_mermaid_renders_edges() -> None:
+    async def fan(msg: str, ctx) -> str:
+        return msg
+
+    async def sink(msg: str, ctx) -> str:
+        return msg
+
+    fan_node = Node(fan, name="fan", policy=NodePolicy(validate="none"))
+    sink_node = Node(sink, name="sink", policy=NodePolicy(validate="none"))
+
+    flow = create(fan_node.to(sink_node))
+
+    mermaid = flow_to_mermaid(flow)
+
+    assert mermaid.startswith("graph TD")
+    assert "fan" in mermaid
+    assert "sink" in mermaid
+    assert "-->" in mermaid

penguiflow-1.0.0/penguiflow/viz.py

@@ -1,5 +0,0 @@
-"""Visualization helpers for PenguiFlow graphs."""
-
-from __future__ import annotations
-
-__all__: list[str] = []