penguiflow 2.0.0__py3-none-any.whl → 2.2.0__py3-none-any.whl

{penguiflow-2.0.0.dist-info → penguiflow-2.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: penguiflow
-Version: 2.0.0
+Version: 2.2.0
 Summary: Async agent orchestration primitives.
 Author: PenguiFlow Team
 License: MIT License
@@ -36,7 +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.118; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Provides-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 🐧❄️
@@ -52,6 +59,9 @@ Dynamic: license-file
   <a href="https://github.com/penguiflow/penguiflow">
     <img src="https://img.shields.io/badge/coverage-85%25-brightgreen" alt="Coverage">
   </a>
+  <a href="https://nightly.link/penguiflow/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>
@@ -77,10 +87,39 @@ It provides:
 * **Observability hooks** (`FlowEvent` callbacks for logging, MLflow, or custom metrics sinks)
 * **Policy-driven routing** (optional policies steer routers without breaking existing flows)
 * **Traceable exceptions** (`FlowError` captures node/trace metadata and optionally emits to Rookery)
+* **Distribution hooks (opt-in)** — plug a `StateStore` to persist trace history and a
+  `MessageBus` to publish floe traffic for remote workers without changing existing flows.
+* **Remote calls (opt-in)** — `RemoteNode` bridges the runtime to external agents through a
+  pluggable `RemoteTransport` interface (A2A-ready) while propagating streaming chunks and
+  cancellation.
+* **A2A server adapter (opt-in)** — wrap a PenguiFlow graph in a FastAPI surface using
+  `penguiflow_a2a.A2AServerAdapter` so other agents can call `message/send`,
+  `message/stream`, and `tasks/cancel` while reusing the runtime's backpressure and
+  cancellation semantics.
+* **Observability & ops polish** — remote calls emit structured metrics (latency, payload
+  sizes, cancel reasons) and the `penguiflow-admin` CLI replays trace history from any
+  configured `StateStore` for debugging.
 
 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?
@@ -168,6 +207,10 @@ print(out.payload)            # PackOut(...)
 await flow.stop()
 ```
 
+> **Opt-in distribution:** pass `state_store=` and/or `message_bus=` when calling
+> `penguiflow.core.create(...)` to persist trace history and publish floe traffic
+> without changing node logic.
+
 ---
 
 ## 🧭 Design Principles
@@ -222,6 +265,60 @@ sacrificing backpressure or ordering guarantees.  The helper wraps the payload i
 increments per-stream sequence numbers.  See `tests/test_streaming.py` and
 `examples/streaming_llm/` for an end-to-end walk-through.
 
+### Remote orchestration
+
+Phase 2 introduces `RemoteNode` and the `RemoteTransport` protocol so flows can delegate
+work to remote agents (e.g., the A2A JSON-RPC/SSE ecosystem) without changing existing
+nodes.  The helper records remote bindings via the `StateStore`, mirrors streaming
+partials back into the graph, and propagates per-trace cancellation to remote tasks via
+`RemoteTransport.cancel`.  See `tests/test_remote.py` for reference in-memory transports.
+
+### Exposing a flow over A2A
+
+Install the optional extra to expose PenguiFlow as an A2A-compatible FastAPI service:
+
+```bash
+pip install "penguiflow[a2a-server]"
+```
+
+Create the adapter and mount the routes:
+
+```python
+from penguiflow import Message, Node, create
+from penguiflow_a2a import A2AAgentCard, A2AServerAdapter, A2ASkill, create_a2a_app
+
+async def orchestrate(message: Message, ctx):
+    await ctx.emit_chunk(parent=message, text="thinking...")
+    return {"result": "done"}
+
+node = Node(orchestrate, name="main")
+flow = create(node.to())
+
+card = A2AAgentCard(
+    name="Main Agent",
+    description="Primary entrypoint for orchestration",
+    version="2.1.0",
+    skills=[A2ASkill(name="orchestrate", description="Handles orchestration")],
+)
+
+adapter = A2AServerAdapter(
+    flow,
+    agent_card=card,
+    agent_url="https://agent.example",
+)
+app = create_a2a_app(adapter)
+```
+
+The generated FastAPI app implements:
+
+* `GET /agent` for discovery (Agent Card)
+* `POST /message/send` for unary execution
+* `POST /message/stream` for SSE streaming
+* `POST /tasks/cancel` to mirror cancellation into PenguiFlow traces
+
+`A2AServerAdapter` reuses the runtime's `StateStore` hooks, so bindings between trace IDs
+and external `taskId`/`contextId` pairs are persisted automatically.
+
 ### Reliability & guardrails
 
 PenguiFlow enforces reliability boundaries out of the box:
@@ -272,6 +369,70 @@ The new `penguiflow.testkit` module keeps unit tests tiny:
 The harness is covered by `tests/test_testkit.py` and demonstrated in
 `examples/testkit_demo/`.
 
+### JSON-only ReAct planner (Phase A)
+
+Phase A introduces a lightweight planner loop that keeps PenguiFlow typed and
+deterministic:
+
+* `penguiflow.catalog.NodeSpec` + `build_catalog` turn registered nodes into
+  tool descriptors with JSON Schemas derived from your Pydantic models.
+* `penguiflow.planner.ReactPlanner` drives a JSON-only ReAct loop over those
+  descriptors, validating every LLM action with Pydantic and replaying invalid
+  steps to request corrections.
+* LiteLLM stays optional—install `penguiflow[planner]` or inject a custom
+  `llm_client` for deterministic/offline runs.
+
+See `examples/react_minimal/` for a stubbed end-to-end run.
+
+### Trajectory summarisation & pause/resume (Phase B)
+
+Phase B adds the tools you need for longer-running, approval-driven flows:
+
+* **Token-aware summaries** — `Trajectory.compress()` keeps a compact state and
+  the planner can route summaries through a cheaper `summarizer_llm` before
+  asking for the next action.
+* **`PlannerPause` contract** — nodes can call `await ctx.pause(...)` to return a
+  typed pause payload. Resume the run later with `ReactPlanner.resume(token, user_input=...)`.
+* **Developer hints** — pass `planning_hints={...}` to enforce disallowed tools,
+  preferred ordering, or parallelism ceilings.
+
+All three features are exercised in `examples/react_pause_resume/`, which runs
+entirely offline with stubbed LLM responses.
+
+### Adaptive re-planning & budgets (Phase C)
+
+Phase C closes the loop when things go sideways:
+
+* **Structured failure feedback** — if a tool raises after exhausting its retries,
+  the planner records `{failure: {node, args, error_code, suggestion}}` and feeds
+  it back to the LLM, prompting a constrained re-plan instead of aborting.
+* **Hard guardrails** — configure wall-clock deadlines and hop budgets directly
+  on `ReactPlanner`; attempts beyond the allotted hops surface deterministic
+  violations and ultimately finish with `reason="budget_exhausted"` alongside a
+  constraint snapshot.
+* **Typed exit reasons** — runs now finish with one of
+  `answer_complete`, `no_path`, or `budget_exhausted`, keeping downstream code
+  simple and machine-checkable.
+
+The new `examples/react_replan/` sample shows a retrieval timeout automatically
+recover via a cached index without leaving the JSON-only contract.
+
+### Parallel fan-out & joins (Phase D)
+
+Phase D lets the planner propose sets of independent tool calls and join them
+without leaving the typed surface area:
+
+* **Parallel `plan` blocks** — the LLM can return `{"plan": [...]}` actions
+  where each branch is validated against the catalog and executed concurrently.
+* **Typed joins** — provide a `{"join": {"node": ...}}` descriptor and the
+  planner will aggregate results, auto-populate fields like `expect`, `results`,
+  or `failures`, and feed branch metadata through `ctx.meta` for the join node.
+* **Deterministic telemetry** — branch errors, pauses, and joins are recorded as
+  structured observations so follow-up actions can re-plan or finish cleanly.
+
+See `examples/react_parallel/` for a shard fan-out that merges responses in one
+round-trip.
+
 
 ## 🧭 Repo Structure
 
@@ -478,9 +639,15 @@ docs or diagramming pipelines.
 * **Structured `FlowEvent`s**: every node event carries `{ts, trace_id, node_name, event,
   latency_ms, q_depth_in, q_depth_out, attempt}` plus a mutable `extra` map for custom
   annotations.
+* **Remote call telemetry**: `RemoteNode` executions emit extra metrics (latency, request
+  and response bytes, context/task identifiers, cancel reasons) so remote hops can be
+  traced end-to-end.
 * **Middleware hooks**: subscribe observers (e.g., MLflow) to the structured `FlowEvent`
   stream. See `examples/mlflow_metrics/` for an MLflow integration and
   `examples/reliability_middleware/` for a concrete timeout + retry walkthrough.
+* **`penguiflow-admin` CLI**: inspect or replay stored trace history from any configured
+  `StateStore` (`penguiflow-admin history <trace>` or `penguiflow-admin replay <trace>`)
+  when debugging distributed runs.
 
 ---
 
@@ -488,9 +655,9 @@ docs or diagramming pipelines.
 
 - **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 `FlowEvent` callbacks power logs/metrics; integrations with
-  third-party stacks (OTel, Prometheus, Datadog) remain DIY. See the MLflow middleware
-  example for a lightweight pattern.
+- **Observability**: structured `FlowEvent` callbacks and the `penguiflow-admin` CLI power
+  local debugging; integrations with third-party stacks (OTel, Prometheus, Datadog) remain
+  DIY. See the MLflow middleware example for a lightweight pattern.
 - **Roadmap**: follow-up releases focus on optional distributed backends, deeper observability integrations, and additional playbook patterns. Contributions and proposals are welcome!
 
 ---
@@ -546,6 +713,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.2.0.dist-info/RECORD

@@ -0,0 +1,27 @@
+penguiflow/__init__.py,sha256=Hsoc0UtuilT77kVd0VKPlgnliaRlHgkA3XYd_PvQOYw,2435
+penguiflow/admin.py,sha256=093xFkE4bM_2ZhLrzhrEUKtmKHi_yVfMPyaGfwi1rcA,5382
+penguiflow/bus.py,sha256=mb29509_n97A6zwC-6EDpYorfAWFSpwqsMu_WeZhLE8,732
+penguiflow/catalog.py,sha256=z-Drf6PbEkvd65PcBvsVJZBBnM9GwT8ctcMdiIoQ5HY,4673
+penguiflow/core.py,sha256=7w3fbyfQspt0aRt5nfDcr2kzPzX7Tf7O83v-U64DfHI,53960
+penguiflow/debug.py,sha256=KPdpWbascsi1ghu-2HPqRORPM2iqkuV6qWyPc0mAalY,945
+penguiflow/errors.py,sha256=mXpCqZ3zdvz7J7Dck_kcw2BGTIm9yrJAjxp_L8KMY7o,3419
+penguiflow/metrics.py,sha256=KsxH9tUqrYfs3EyccLcM0-haYySAByq7RMnK7q61eRA,3989
+penguiflow/middlewares.py,sha256=cB4SrRciNcKHyLanaMVsfMElt3El0LNCj_3dyik07x4,2864
+penguiflow/node.py,sha256=0NOs3rU6t1tHNNwwJopqzM2ufGcp82JpzhckynWBRqs,3563
+penguiflow/patterns.py,sha256=qtzRSNRKxV5_qEPXhffd15PuCZs0YnoGF80nNUsrcxw,5512
+penguiflow/policies.py,sha256=3w8ionnpTyuA0ZCc3jPpB011L7_i1qlbiO6escY024s,4385
+penguiflow/registry.py,sha256=1nR3J1A6jzuevH8EMn83vCkSnnNKgE28CCO6fXMA3wE,2001
+penguiflow/remote.py,sha256=0-2aW48P8OB8KLEC_7_F_RHtzVJk3huyAMBGdXjmWeA,16426
+penguiflow/state.py,sha256=fBY5d_48hR4XHWVG08FraaQ7u4IVPJwooewfVLmzu1Q,1773
+penguiflow/streaming.py,sha256=RKMm4VfaDA2ceEM_pB2Cuhmpwtdcjj7og-kjXQQDcbc,3863
+penguiflow/testkit.py,sha256=pIFYpu1RfJnW2mbGvUkPhMpL-xDAw0E959oTMxLkLh8,11806
+penguiflow/types.py,sha256=Fl56-b7OwIEUbPMDD1CY09nbOG_tmBw3FUhioojeG5M,1503
+penguiflow/viz.py,sha256=KbBb9kKoL223vj0NgJV_jo5ny-0RTc2gcSBACm0jG8w,5508
+penguiflow-2.2.0.dist-info/licenses/LICENSE,sha256=JSvodvLXxSct_kI9IBsZOBpVKoESQTB_AGbkClwZ7HI,1065
+penguiflow_a2a/__init__.py,sha256=JuK_ov06yS2H97D2OVXhgX8LcgdOqE3EujUPaDKaduc,342
+penguiflow_a2a/server.py,sha256=VMBO-oGjB6Z9mtRBU0z7ZFGprDUC_kihZJukh3budbs,25932
+penguiflow-2.2.0.dist-info/METADATA,sha256=Rp0MN4Yovee2HoJOKpio9PE8A2UBTNUsECAsXBt6lLk,28872
+penguiflow-2.2.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+penguiflow-2.2.0.dist-info/entry_points.txt,sha256=F2KxANLEVGRbpWLmcHcvYrTVLWbKWdmk3VOe98a7t9I,59
+penguiflow-2.2.0.dist-info/top_level.txt,sha256=K-fTwLA14n0u_LDxDBCV7FmeBnJffhTOtUbTtOymQns,26
+penguiflow-2.2.0.dist-info/RECORD,,

penguiflow-2.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+penguiflow-admin = penguiflow.admin:main

penguiflow-2.2.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+penguiflow
+penguiflow_a2a

penguiflow_a2a/__init__.py

@@ -0,0 +1,19 @@
+"""Optional A2A adapters for PenguiFlow."""
+
+from .server import (
+    A2AAgentCard,
+    A2AMessagePayload,
+    A2AServerAdapter,
+    A2ASkill,
+    A2ATaskCancelRequest,
+    create_a2a_app,
+)
+
+__all__ = [
+    "A2AAgentCard",
+    "A2ASkill",
+    "A2AMessagePayload",
+    "A2ATaskCancelRequest",
+    "A2AServerAdapter",
+    "create_a2a_app",
+]