penguiflow 2.2.3__tar.gz → 2.2.4__tar.gz

{penguiflow-2.2.3 → penguiflow-2.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: penguiflow
-Version: 2.2.3
+Version: 2.2.4
 Summary: Async agent orchestration primitives.
 Author: PenguiFlow Team
 License: MIT License
@@ -687,9 +687,12 @@ 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/roadmap_status_updates/`: roadmap-aware agent scaffold that streams status updates and final chunks.
+* `examples/status_roadmap_flow/`: roadmap-driven websocket status updates with FlowResponse scaffolding.
 * `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.
 
+
 ---
 
 ## 🤝 Contributing

{penguiflow-2.2.3 → penguiflow-2.2.4}/README.md

@@ -639,9 +639,12 @@ 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/roadmap_status_updates/`: roadmap-aware agent scaffold that streams status updates and final chunks.
+* `examples/status_roadmap_flow/`: roadmap-driven websocket status updates with FlowResponse scaffolding.
 * `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.
 
+
 ---
 
 ## 🤝 Contributing

penguiflow-2.2.4/examples/controller_multihop/flow.py

@@ -0,0 +1,54 @@
+"""Controller loop example."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+
+from penguiflow import WM, FinalAnswer, Headers, Message, Node, NodePolicy, create
+
+
+async def controller(msg: Message, ctx) -> Message:
+    wm = msg.payload
+    assert isinstance(wm, WM)
+
+    if wm.hops >= 3:
+        final = FinalAnswer(text=f"answer after {wm.hops} hops: {wm.facts[-1]}")
+        return msg.model_copy(update={"payload": final})
+
+    token_cost = 5
+    updated_wm = wm.model_copy(
+        update={
+            "facts": wm.facts + [f"fact-{wm.hops}"],
+            "tokens_used": wm.tokens_used + token_cost,
+        }
+    )
+    return msg.model_copy(update={"payload": updated_wm})
+
+
+async def main() -> None:
+    controller_node = Node(
+        controller,
+        name="controller",
+        allow_cycle=True,
+        policy=NodePolicy(validate="none"),
+    )
+    flow = create(controller_node.to(controller_node))
+    flow.run()
+
+    wm = WM(query="latest metrics", budget_hops=5, budget_tokens=12)
+    message = Message(
+        payload=wm,
+        headers=Headers(tenant="acme"),
+        deadline_s=time.time() + 5,
+    )
+
+    await flow.emit(message)
+    final_msg = await flow.fetch()
+    print(final_msg.payload.text)
+
+    await flow.stop()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    asyncio.run(main())

penguiflow-2.2.4/examples/fanout_join/flow.py

@@ -0,0 +1,54 @@
+"""Fan-out and join example with join_k."""
+
+from __future__ import annotations
+
+import asyncio
+
+from penguiflow import Headers, Message, Node, NodePolicy, create, join_k
+
+
+async def fan(msg: Message, ctx) -> Message:
+    return msg
+
+
+async def work_a(msg: Message, ctx) -> Message:
+    return msg.model_copy(update={"payload": msg.payload + "::A"})
+
+
+async def work_b(msg: Message, ctx) -> Message:
+    return msg.model_copy(update={"payload": msg.payload + "::B"})
+
+
+async def summarize(batch: Message, ctx) -> str:
+    return ",".join(batch.payload)
+
+
+async def main() -> None:
+    fan_node = Node(fan, name="fan", policy=NodePolicy(validate="none"))
+    worker_a = Node(work_a, name="work_a", policy=NodePolicy(validate="none"))
+    worker_b = Node(work_b, name="work_b", policy=NodePolicy(validate="none"))
+    join_node = join_k("join", 2)
+    summarize_node = Node(
+        summarize,
+        name="summarize",
+        policy=NodePolicy(validate="none"),
+    )
+
+    flow = create(
+        fan_node.to(worker_a, worker_b),
+        worker_a.to(join_node),
+        worker_b.to(join_node),
+        join_node.to(summarize_node),
+        summarize_node.to(),
+    )
+    flow.run()
+
+    message = Message(payload="task", headers=Headers(tenant="acme"))
+    await flow.emit(message)
+    print(await flow.fetch())  # task::A,task::B
+
+    await flow.stop()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    asyncio.run(main())

penguiflow-2.2.4/examples/map_concurrent/flow.py

@@ -0,0 +1,56 @@
+"""Demonstrate the map_concurrent helper inside a node."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from penguiflow import Headers, Message, Node, NodePolicy, create, map_concurrent
+
+
+async def seed(msg: Message, ctx) -> Message:
+    """Attach a batch of document ids to the message payload."""
+
+    docs = [f"doc-{i}" for i in range(1, 6)]
+    return msg.model_copy(update={"payload": {"query": msg.payload, "docs": docs}})
+
+
+async def score(msg: Message, ctx) -> Message:
+    """Score each document concurrently with a bounded semaphore."""
+
+    docs = msg.payload["docs"]
+
+    async def worker(doc_id: str) -> dict[str, Any]:
+        await asyncio.sleep(0.05)
+        return {"doc_id": doc_id, "score": len(doc_id) / 10}
+
+    scored = await map_concurrent(docs, worker, max_concurrency=2)
+    return msg.model_copy(update={"payload": {**msg.payload, "scores": scored}})
+
+
+async def summarize(msg: Message, ctx) -> str:
+    top = max(msg.payload["scores"], key=lambda item: item["score"])
+    return f"top doc: {top['doc_id']} score={top['score']:.2f}"
+
+
+async def main() -> None:
+    seed_node = Node(seed, name="seed", policy=NodePolicy(validate="none"))
+    score_node = Node(score, name="score", policy=NodePolicy(validate="none"))
+    summary_node = Node(summarize, name="summary", policy=NodePolicy(validate="none"))
+
+    flow = create(
+        seed_node.to(score_node),
+        score_node.to(summary_node),
+        summary_node.to(),
+    )
+    flow.run()
+
+    message = Message(payload="antarctic krill", headers=Headers(tenant="acme"))
+    await flow.emit(message)
+    print(await flow.fetch())
+
+    await flow.stop()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    asyncio.run(main())

penguiflow-2.2.4/examples/metadata_propagation/flow.py

@@ -0,0 +1,61 @@
+"""Metadata propagation demo for PenguiFlow."""
+
+from __future__ import annotations
+
+import asyncio
+
+from penguiflow import Headers, Message, Node, create
+
+
+async def annotate_cost(message: Message, _ctx) -> Message:
+    """Add retrieval cost metadata without mutating payload."""
+
+    message.meta["retrieval_cost_ms"] = 87
+    return message
+
+
+async def summarize(message: Message, _ctx) -> Message:
+    """Read metadata and add summarizer details."""
+
+    cost = message.meta.get("retrieval_cost_ms", 0)
+    new_meta = dict(message.meta)
+    new_meta["summary_model"] = "penguin-x1"
+    new_meta["summary_tokens"] = 128
+    return message.model_copy(
+        update={
+            "payload": f"Summary(cost={cost}ms): {message.payload}",
+            "meta": new_meta,
+        }
+    )
+
+
+async def sink(message: Message, _ctx) -> Message:
+    """Forward the final message to Rookery."""
+
+    return message
+
+
+async def main() -> None:
+    annotate_node = Node(annotate_cost, name="annotate_cost")
+    summarize_node = Node(summarize, name="summarize")
+    sink_node = Node(sink, name="sink")
+
+    flow = create(
+        annotate_node.to(summarize_node),
+        summarize_node.to(sink_node),
+    )
+    flow.run()
+
+    headers = Headers(tenant="acme", topic="metadata-demo")
+    message = Message(payload="documents about penguins", headers=headers)
+
+    await flow.emit(message)
+    result = await flow.fetch()
+    await flow.stop()
+
+    print("Payload:", result.payload)
+    print("Metadata:", result.meta)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

penguiflow-2.2.4/examples/mlflow_metrics/__init__.py

@@ -0,0 +1 @@
+"""MLflow observability example."""

penguiflow-2.2.4/examples/mlflow_metrics/flow.py

@@ -0,0 +1,120 @@
+"""Demo flow that records node events to MLflow (or stdout fallback)."""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+from penguiflow import (
+    FinalAnswer,
+    Headers,
+    Message,
+    Node,
+    NodePolicy,
+    PenguiFlow,
+    create,
+)
+from penguiflow.metrics import FlowEvent
+
+
+class MlflowMiddleware:
+    """Forward runtime events to MLflow if available, otherwise print them."""
+
+    def __init__(
+        self,
+        *,
+        run_name: str = "penguiflow-demo",
+        tracking_dir: str | None = None,
+    ) -> None:
+        self.run_name = run_name
+        self.events: list[FlowEvent] = []
+        self._warned = False
+        self._tracking_dir = tracking_dir
+        try:  # pragma: no cover - optional dependency
+            import mlflow
+        except ModuleNotFoundError:  # pragma: no cover - optional dependency
+            self._mlflow = None
+        else:  # pragma: no cover - optional dependency
+            self._mlflow = mlflow
+            if tracking_dir is not None:
+                tracking_path = Path(tracking_dir).resolve()
+                tracking_path.mkdir(parents=True, exist_ok=True)
+                mlflow.set_tracking_uri(f"file:{tracking_path}")
+            self._active_run = mlflow.start_run(run_name=run_name)
+
+    async def __call__(self, event: FlowEvent) -> None:
+        self.events.append(event)
+
+        if self._mlflow is None:
+            if not self._warned:
+                print("MLflow not installed; capturing events locally only.")
+                self._warned = True
+            metrics = event.metric_samples()
+            print(
+                f"{event.event_type} | node={event.node_name} | metrics={metrics}"
+            )
+            return
+
+        assert self._mlflow is not None  # for type-checkers
+        self._mlflow.set_tags(event.tag_values())
+        metrics = event.metric_samples()
+        for key, value in metrics.items():
+            self._mlflow.log_metric(key, value, step=int(event.ts * 1000))
+
+    def close(self) -> None:
+        if getattr(self, "_mlflow", None) is not None:
+            self._mlflow.end_run()
+
+
+def build_flow(middleware: MlflowMiddleware) -> tuple[PenguiFlow, Node]:
+    """Assemble the demo flow and attach the provided middleware."""
+
+    async def prepare(message: Message, _ctx) -> Message:
+        meta = dict(message.meta)
+        meta["prepared"] = True
+        cleaned = str(message.payload).strip()
+        return message.model_copy(update={"payload": cleaned, "meta": meta})
+
+    async def score(message: Message, _ctx) -> Message:
+        await asyncio.sleep(0.05)
+        meta = dict(message.meta)
+        meta["score"] = len(str(message.payload))
+        enriched = str(message.payload).upper()
+        return message.model_copy(update={"payload": enriched, "meta": meta})
+
+    async def respond(message: Message, _ctx) -> Message:
+        final = FinalAnswer(text=f"Tracked: {message.payload}", citations=["mlflow"])
+        return message.model_copy(update={"payload": final})
+
+    prepare_node = Node(prepare, name="prepare", policy=NodePolicy(validate="none"))
+    score_node = Node(score, name="score", policy=NodePolicy(validate="none"))
+    respond_node = Node(respond, name="respond", policy=NodePolicy(validate="none"))
+
+    flow = create(prepare_node.to(score_node), score_node.to(respond_node))
+    flow.add_middleware(middleware)
+    return flow, respond_node
+
+
+async def main() -> None:
+    middleware = MlflowMiddleware(tracking_dir=Path(__file__).parent / "mlruns")
+    flow, _ = build_flow(middleware)
+    flow.run()
+
+    headers = Headers(tenant="demo", topic="metrics")
+    message = Message(payload="observe penguiflow", headers=headers)
+
+    await flow.emit(message)
+    result = await flow.fetch()
+    await flow.stop()
+    middleware.close()
+
+    if isinstance(result, Message) and isinstance(result.payload, FinalAnswer):
+        print(f"Final answer: {result.payload.text}")
+    else:
+        print(f"Result: {result}")
+
+    print(f"Captured {len(middleware.events)} events.")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

penguiflow-2.2.4/examples/playbook_retrieval/flow.py

@@ -0,0 +1,61 @@
+"""Playbook-driven retrieval and compression example."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from penguiflow import Headers, Message, Node, NodePolicy, create
+
+
+def build_retrieval_playbook() -> tuple[Any, Any]:
+    async def retrieve(msg: Message, ctx) -> Message:
+        query = msg.payload["query"]
+        docs = [f"{query}-doc-{i}" for i in range(1, 4)]
+        return msg.model_copy(update={"payload": docs})
+
+    async def rerank(msg: Message, ctx) -> Message:
+        reranked = sorted(msg.payload, key=len)
+        return msg.model_copy(update={"payload": reranked})
+
+    async def compress(msg: Message, ctx) -> Message:
+        summary = f"{msg.payload[0]} :: compressed"
+        return msg.model_copy(update={"payload": summary})
+
+    retrieve_node = Node(retrieve, name="retrieve", policy=NodePolicy(validate="none"))
+    rerank_node = Node(rerank, name="rerank", policy=NodePolicy(validate="none"))
+    compress_node = Node(compress, name="compress", policy=NodePolicy(validate="none"))
+
+    flow = create(
+        retrieve_node.to(rerank_node),
+        rerank_node.to(compress_node),
+        compress_node.to(),
+    )
+    return flow, None
+
+
+async def controller(msg: Message, ctx) -> Message:
+    request = msg.model_copy(update={"payload": {"query": msg.payload}})
+    summary = await ctx.call_playbook(build_retrieval_playbook, request)
+    return msg.model_copy(update={"payload": summary})
+
+
+async def main() -> None:
+    controller_node = Node(
+        controller,
+        name="controller",
+        policy=NodePolicy(validate="none"),
+    )
+    flow = create(controller_node.to())
+    flow.run()
+
+    message = Message(payload="antarctic krill", headers=Headers(tenant="acme"))
+    await flow.emit(message)
+    final = await flow.fetch()
+    print(final.payload)
+
+    await flow.stop()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    asyncio.run(main())

penguiflow-2.2.4/examples/quickstart/flow.py

@@ -0,0 +1,74 @@
+"""Typed quickstart example for PenguiFlow."""
+
+from __future__ import annotations
+
+import asyncio
+
+from pydantic import BaseModel
+
+from penguiflow import Headers, Message, ModelRegistry, Node, NodePolicy, create
+
+
+class TriageIn(BaseModel):
+    text: str
+
+
+class TriageOut(BaseModel):
+    text: str
+    topic: str
+
+
+class RetrieveOut(BaseModel):
+    topic: str
+    docs: list[str]
+
+
+class PackOut(BaseModel):
+    prompt: str
+
+
+async def triage(msg: TriageIn, ctx) -> TriageOut:
+    topic = "metrics" if "metric" in msg.text else "general"
+    return TriageOut(text=msg.text, topic=topic)
+
+
+async def retrieve(msg: TriageOut, ctx) -> RetrieveOut:
+    docs = [f"doc_{i}_{msg.topic}" for i in range(2)]
+    return RetrieveOut(topic=msg.topic, docs=docs)
+
+
+async def pack(msg: RetrieveOut, ctx) -> PackOut:
+    prompt = f"[{msg.topic}] summarize {len(msg.docs)} docs"
+    return PackOut(prompt=prompt)
+
+
+async def main() -> None:
+    triage_node = Node(triage, name="triage", policy=NodePolicy(validate="both"))
+    retrieve_node = Node(retrieve, name="retrieve", policy=NodePolicy(validate="both"))
+    pack_node = Node(pack, name="pack", policy=NodePolicy(validate="both"))
+
+    registry = ModelRegistry()
+    registry.register("triage", TriageIn, TriageOut)
+    registry.register("retrieve", TriageOut, RetrieveOut)
+    registry.register("pack", RetrieveOut, PackOut)
+
+    flow = create(
+        triage_node.to(retrieve_node),
+        retrieve_node.to(pack_node),
+    )
+    flow.run(registry=registry)
+
+    message = Message(
+        payload=TriageIn(text="show marketing metrics"),
+        headers=Headers(tenant="acme"),
+    )
+
+    await flow.emit(message)
+    result = await flow.fetch()
+    print(result.prompt)
+
+    await flow.stop()
+
+
+if __name__ == "__main__":  # pragma: no cover - example entrypoint
+    asyncio.run(main())

penguiflow-2.2.4/examples/react_minimal/main.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import Mapping
+from typing import Any
+
+from pydantic import BaseModel
+
+from penguiflow.catalog import build_catalog, tool
+from penguiflow.node import Node
+from penguiflow.planner import ReactPlanner
+from penguiflow.registry import ModelRegistry
+
+
+class Question(BaseModel):
+    text: str
+
+
+class Intent(BaseModel):
+    intent: str
+
+
+class Documents(BaseModel):
+    documents: list[str]
+
+
+class FinalAnswer(BaseModel):
+    answer: str
+
+
+@tool(desc="Detect the caller intent", tags=["planner"])
+async def triage(args: Question, ctx: object) -> Intent:
+    return Intent(intent="docs")
+
+
+@tool(desc="Retrieve supporting documents", side_effects="read")
+async def retrieve(args: Intent, ctx: object) -> Documents:
+    return Documents(documents=[f"PenguiFlow remains lightweight for {args.intent}"])
+
+
+@tool(desc="Summarise retrieved documents")
+async def summarise(args: FinalAnswer, ctx: object) -> FinalAnswer:
+    return args
+
+
+class SequenceLLM:
+    """Deterministic stub that returns pre-authored planner actions."""
+
+    def __init__(self, responses: list[Mapping[str, Any]]) -> None:
+        self._responses = [json.dumps(item) for item in responses]
+
+    async def complete(
+        self,
+        *,
+        messages: list[Mapping[str, str]],
+        response_format: Mapping[str, Any] | None = None,
+    ) -> str:
+        del messages, response_format
+        if not self._responses:
+            raise RuntimeError("SequenceLLM has no responses left")
+        return self._responses.pop(0)
+
+
+async def main() -> None:
+    registry = ModelRegistry()
+    registry.register("triage", Question, Intent)
+    registry.register("retrieve", Intent, Documents)
+    registry.register("summarise", FinalAnswer, FinalAnswer)
+
+    nodes = [
+        Node(triage, name="triage"),
+        Node(retrieve, name="retrieve"),
+        Node(summarise, name="summarise"),
+    ]
+
+    client = SequenceLLM(
+        [
+            {
+                "thought": "triage",
+                "next_node": "triage",
+                "args": {"text": "How does PenguiFlow stay lightweight?"},
+            },
+            {
+                "thought": "retrieve",
+                "next_node": "retrieve",
+                "args": {"intent": "docs"},
+            },
+            {
+                "thought": "wrap up",
+                "next_node": None,
+                "args": {
+                    "answer": "PenguiFlow uses async orchestration and minimal deps."
+                },
+            },
+        ]
+    )
+
+    planner = ReactPlanner(
+        llm_client=client,
+        catalog=build_catalog(nodes, registry),
+    )
+
+    result = await planner.run("Explain PenguiFlow's lightweight design")
+    print(json.dumps(result.model_dump(), indent=2, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    asyncio.run(main())