penguiflow 1.0.2__py3-none-any.whl → 1.0.3__py3-none-any.whl

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.2"
+__version__ = "1.0.3"

penguiflow/viz.py

@@ -2,4 +2,75 @@
 
 from __future__ import annotations
 
-__all__: list[str] = []
+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.2.dist-info → penguiflow-1.0.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: penguiflow
-Version: 1.0.2
+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")
@@ -328,6 +328,19 @@ 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.
@@ -346,6 +359,14 @@ flow focused on high-level orchestration logic.
 
 ---
 
+## 📊 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.
+
+---
+
 ## 🔮 Roadmap
 
 * **v1 (current)**: safe core runtime, type-safety, retries, timeouts, routing, controller loops, playbooks via examples.

{penguiflow-1.0.2.dist-info → penguiflow-1.0.3.dist-info}/RECORD

@@ -1,13 +1,13 @@
-penguiflow/__init__.py,sha256=BIBAYJZtOHQ7AZMBWD0g7d1RTCR9qWLQGwcUuKa5GMo,874
+penguiflow/__init__.py,sha256=fiQsp6-xYG2UjvuIhu71zvEiTeAjdfEjtoLRwZ8wROs,930
 penguiflow/core.py,sha256=fO5GXF7Hih-gEcUPbyXVJilgUmwbvd72j337r5oOWME,20908
 penguiflow/middlewares.py,sha256=LUlK4FrMScK3oaNSrAYNw3s4KcAZ716DTLAUqvsOkL8,319
 penguiflow/node.py,sha256=0NOs3rU6t1tHNNwwJopqzM2ufGcp82JpzhckynWBRqs,3563
 penguiflow/patterns.py,sha256=Ivuuy0on0OMsdYd5DRFZm1EgujXKPEaIIMH0ZWlJ1s0,4199
 penguiflow/registry.py,sha256=4lrGDMFjM7c8pfZFc_YG0YHg-F80JyF4c-j0UbAf150,1419
 penguiflow/types.py,sha256=QV2JvB_QnohfBATSaviPWm0HSR9B6dTc3UOwFIYyaqg,1154
-penguiflow/viz.py,sha256=_puIEJevq2DrfNuydm3DG1V1o4PgICxd5pA-Es_IyWY,112
-penguiflow-1.0.2.dist-info/licenses/LICENSE,sha256=JSvodvLXxSct_kI9IBsZOBpVKoESQTB_AGbkClwZ7HI,1065
-penguiflow-1.0.2.dist-info/METADATA,sha256=SBuhdqSVKIwo9_vVV2bW2IsmGiia84q59ESqHl8zgR0,13090
-penguiflow-1.0.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-penguiflow-1.0.2.dist-info/top_level.txt,sha256=F-5jgzPP4Mo_ErgtzGDFJdRT4CIfFjFBnxxcn-RpWBU,11
-penguiflow-1.0.2.dist-info/RECORD,,
+penguiflow/viz.py,sha256=B9T2O5A6nHBLn7JuEeujqDC6ZcwP5s6M2rpsUrj5Ul0,2091
+penguiflow-1.0.3.dist-info/licenses/LICENSE,sha256=JSvodvLXxSct_kI9IBsZOBpVKoESQTB_AGbkClwZ7HI,1065
+penguiflow-1.0.3.dist-info/METADATA,sha256=GISwzSiycpzXy0kmoP3mWeMAeutgNITeTKVGz2YRb1A,13658
+penguiflow-1.0.3.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+penguiflow-1.0.3.dist-info/top_level.txt,sha256=F-5jgzPP4Mo_ErgtzGDFJdRT4CIfFjFBnxxcn-RpWBU,11
+penguiflow-1.0.3.dist-info/RECORD,,