penguiflow 2.2.2__py3-none-any.whl → 2.2.4__py3-none-any.whl

examples/react_parallel/main.py

@@ -0,0 +1,121 @@
+"""Parallel fan-out example for the React planner."""
+
+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 ShardRequest(BaseModel):
+    topic: str
+    shard: int
+
+
+class ShardResult(BaseModel):
+    shard: int
+    text: str
+
+
+class MergeArgs(BaseModel):
+    expect: int
+    results: list[ShardResult]
+
+
+class Documents(BaseModel):
+    documents: list[str]
+
+
+@tool(desc="Fetch from the primary shard", tags=["parallel"])
+async def fetch_primary(args: ShardRequest, ctx: Any) -> ShardResult:
+    await asyncio.sleep(0.1)
+    return ShardResult(shard=args.shard, text=f"{args.topic}-primary")
+
+
+@tool(desc="Fetch from the secondary shard", tags=["parallel"])
+async def fetch_secondary(args: ShardRequest, ctx: Any) -> ShardResult:
+    await asyncio.sleep(0.1)
+    return ShardResult(shard=args.shard, text=f"{args.topic}-secondary")
+
+
+@tool(desc="Merge shard payloads")
+async def merge_results(args: MergeArgs, ctx: Any) -> Documents:
+    # The planner stores rich branch metadata in ctx.meta for joins.
+    assert ctx.meta["parallel_success_count"] == args.expect
+    merged = [item.text for item in args.results]
+    return Documents(documents=merged)
+
+
+class SequenceLLM:
+    """Deterministic stub returning scripted 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("fetch_primary", ShardRequest, ShardResult)
+    registry.register("fetch_secondary", ShardRequest, ShardResult)
+    registry.register("merge_results", MergeArgs, Documents)
+
+    nodes = [
+        Node(fetch_primary, name="fetch_primary"),
+        Node(fetch_secondary, name="fetch_secondary"),
+        Node(merge_results, name="merge_results"),
+    ]
+
+    client = SequenceLLM(
+        [
+            {
+                "thought": "fan out",
+                "plan": [
+                    {
+                        "node": "fetch_primary",
+                        "args": {"topic": "penguins", "shard": 0},
+                    },
+                    {
+                        "node": "fetch_secondary",
+                        "args": {"topic": "penguins", "shard": 1},
+                    },
+                ],
+                "join": {"node": "merge_results"},
+            },
+            {
+                "thought": "finish",
+                "next_node": None,
+                "args": {"documents": ["penguins-primary", "penguins-secondary"]},
+            },
+        ]
+    )
+
+    planner = ReactPlanner(
+        llm_client=client,
+        catalog=build_catalog(nodes, registry),
+    )
+
+    result = await planner.run("Compile penguin metrics")
+    print(json.dumps(result.model_dump(), indent=2, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/react_pause_resume/main.py

@@ -0,0 +1,157 @@
+"""Phase B demo: summarisation + pause/resume + planning hints."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from pydantic import BaseModel
+
+from penguiflow.catalog import build_catalog, tool
+from penguiflow.node import Node
+from penguiflow.planner import PlannerPause, ReactPlanner
+from penguiflow.registry import ModelRegistry
+
+
+class Query(BaseModel):
+    topic: str
+
+
+class Intent(BaseModel):
+    intent: str
+
+
+class Documents(BaseModel):
+    documents: list[str]
+
+
+class Answer(BaseModel):
+    answer: str
+
+
+@tool(desc="Detect the type of request", tags=["triage"])
+async def triage(args: Query, ctx: object) -> Intent:
+    return Intent(intent="docs")
+
+
+@tool(desc="Approval checkpoint before side-effects", side_effects="external")
+async def approval(args: Intent, ctx: Any) -> Intent:
+    # Pause the planner for human approval. This raises internally and
+    # returns control to the caller as a PlannerPause.
+    await ctx.pause("approval_required", {"intent": args.intent})
+    return args  # unreachable but keeps type checkers happy
+
+
+@tool(desc="Retrieve supporting documents", side_effects="read")
+async def retrieve(args: Intent, ctx: object) -> Documents:
+    return Documents(documents=[f"weekly metrics summary for {args.intent}"])
+
+
+@tool(desc="Compose the final response", tags=["summary"])
+async def respond(args: Answer, ctx: object) -> Answer:
+    return args
+
+
+class StubPlannerLLM:
+    """Deterministic LiteLLM-style stub that serves pre-built actions."""
+
+    def __init__(self, actions: Sequence[Mapping[str, Any]]) -> None:
+        self._payloads = [json.dumps(item) for item in actions]
+
+    async def complete(
+        self,
+        *,
+        messages: Sequence[Mapping[str, str]],
+        response_format: Mapping[str, Any] | None = None,
+    ) -> str:
+        return self._payloads.pop(0)
+
+
+class StubSummariser:
+    """Cheap summariser used when history exceeds the token budget."""
+
+    async def complete(
+        self,
+        *,
+        messages: Sequence[Mapping[str, str]],
+        response_format: Mapping[str, Any] | None = None,
+    ) -> str:
+        return json.dumps(
+            {
+                "goals": ["Send weekly metrics to stakeholders"],
+                "facts": {"status": "awaiting approval"},
+                "pending": ["approval"],
+                "last_output_digest": "approval pending",
+                "note": "stub",
+            }
+        )
+
+
+async def build_planner() -> ReactPlanner:
+    registry = ModelRegistry()
+    registry.register("triage", Query, Intent)
+    registry.register("approval", Intent, Intent)
+    registry.register("retrieve", Intent, Documents)
+    registry.register("respond", Answer, Answer)
+
+    nodes = [
+        Node(triage, name="triage"),
+        Node(approval, name="approval"),
+        Node(retrieve, name="retrieve"),
+        Node(respond, name="respond"),
+    ]
+    catalog = build_catalog(nodes, registry)
+
+    scripted_actions = [
+        {"thought": "triage", "next_node": "triage", "args": {"topic": "metrics"}},
+        {"thought": "approval", "next_node": "approval", "args": {"intent": "docs"}},
+        {"thought": "retrieve", "next_node": "retrieve", "args": {"intent": "docs"}},
+        {
+            "thought": "respond",
+            "next_node": "respond",
+            "args": {"answer": "Metrics sent to Slack with highlights."},
+        },
+        {"thought": "finish", "next_node": None, "args": {"answer": "done"}},
+    ]
+
+    planner = ReactPlanner(
+        llm_client=StubPlannerLLM(scripted_actions),
+        catalog=catalog,
+        pause_enabled=True,
+        token_budget=160,
+        planning_hints={
+            "ordering_hints": ["triage", "approval", "retrieve", "respond"],
+            "disallow_nodes": ["broken_tool"],
+            "budget_hints": {"max_parallel": 1},
+        },
+    )
+    planner._summarizer_client = StubSummariser()  # type: ignore[attr-defined]
+    return planner
+
+
+async def main() -> None:
+    planner = await build_planner()
+    result = await planner.run("Share weekly metrics with approvals")
+
+    if isinstance(result, PlannerPause):
+        print("Planner paused:")
+        print(f"  reason: {result.reason}")
+        print(f"  payload: {result.payload}")
+        print("Resuming with approval...\n")
+        final = await planner.resume(
+            result.resume_token,
+            user_input="approved by finance",
+        )
+        print("Final planner payload:")
+        print(final.payload)
+        print("Summary note:")
+        print(final.metadata["steps"][-1])
+    else:
+        print("Planner finished in one pass:")
+        print(result.payload)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/react_replan/main.py

@@ -0,0 +1,133 @@
+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 Answer(BaseModel):
+    answer: str
+
+
+class RemoteTimeout(RuntimeError):
+    """Exception carrying a suggestion for the planner."""
+
+    def __init__(self, message: str, suggestion: str) -> None:
+        super().__init__(message)
+        self.suggestion = suggestion
+
+
+@tool(desc="Detect the caller intent", tags=["planner"])
+async def triage(args: Question, ctx: object) -> Intent:
+    return Intent(intent="docs")
+
+
+@tool(desc="Call remote retriever", side_effects="external")
+async def remote_docs(args: Intent, ctx: object) -> Documents:
+    raise RemoteTimeout("remote search timed out", "use_cached_index")
+
+
+@tool(desc="Fallback to cached index", side_effects="read")
+async def cached_docs(args: Intent, ctx: object) -> Documents:
+    return Documents(documents=[f"Cached snippet covering {args.intent}"])
+
+
+@tool(desc="Compose final answer")
+async def summarise(args: Answer, ctx: object) -> Answer:
+    return args
+
+
+class SequenceLLM:
+    """Deterministic stub returning 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("remote_docs", Intent, Documents)
+    registry.register("cached_docs", Intent, Documents)
+    registry.register("summarise", Answer, Answer)
+
+    nodes = [
+        Node(triage, name="triage"),
+        Node(remote_docs, name="remote_docs"),
+        Node(cached_docs, name="cached_docs"),
+        Node(summarise, name="summarise"),
+    ]
+
+    client = SequenceLLM(
+        [
+            {
+                "thought": "triage",
+                "next_node": "triage",
+                "args": {"text": "Summarise latest metrics"},
+            },
+            {
+                "thought": "try remote",
+                "next_node": "remote_docs",
+                "args": {"intent": "docs"},
+            },
+            {
+                "thought": "fallback cache",
+                "next_node": "cached_docs",
+                "args": {"intent": "docs"},
+            },
+            {
+                "thought": "wrap up",
+                "next_node": "summarise",
+                "args": {"answer": "Used cached docs after timeout."},
+            },
+            {
+                "thought": "final",
+                "next_node": None,
+                "args": {"answer": "Cached docs describe the latest metrics."},
+            },
+        ]
+    )
+
+    planner = ReactPlanner(
+        llm_client=client,
+        catalog=build_catalog(nodes, registry),
+        hop_budget=3,
+    )
+
+    result = await planner.run("Summarise metrics with fallback")
+    print(json.dumps(result.model_dump(), indent=2, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

examples/reliability_middleware/flow.py

@@ -0,0 +1,67 @@
+"""Showcase retries, timeouts, and middleware hooks."""
+
+from __future__ import annotations
+
+import asyncio
+
+from penguiflow import (
+    FlowEvent,
+    Headers,
+    Message,
+    Node,
+    NodePolicy,
+    PenguiFlow,
+    create,
+)
+
+
+def build_flow() -> PenguiFlow:
+    attempts = {"count": 0}
+
+    async def flaky(msg: Message, ctx) -> Message:
+        attempts["count"] += 1
+        attempt = attempts["count"]
+
+        if attempt == 1:
+            await asyncio.sleep(0.2)  # exceeds timeout -> triggers retry
+        elif attempt == 2:
+            raise RuntimeError("transient failure")
+
+        return msg.model_copy(update={"payload": f"success on attempt {attempt}"})
+
+    flaky_node = Node(
+        flaky,
+        name="flaky",
+        policy=NodePolicy(
+            validate="none",
+            timeout_s=0.05,
+            max_retries=2,
+            backoff_base=0.05,
+        ),
+    )
+
+    flow = create(flaky_node.to())
+
+    async def middleware(event: FlowEvent) -> None:
+        attempt = event.attempt
+        latency = event.latency_ms
+        print(f"mw:{event.event_type}:attempt={attempt} latency={latency}")
+
+    flow.add_middleware(middleware)
+    return flow
+
+
+async def main() -> None:
+    flow = build_flow()
+    flow.run()
+
+    message = Message(payload="ping", headers=Headers(tenant="acme"))
+    await flow.emit(message)
+    result = await flow.fetch()
+    print(f"result payload: {result.payload}")
+
+    await flow.stop()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    asyncio.run(main())