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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: penguiflow
-Version: 2.2.0
+Version: 2.2.2
 Summary: Async agent orchestration primitives.
 Author: PenguiFlow Team
 License: MIT License
@@ -53,21 +53,11 @@ Dynamic: license-file
 </p>
 
 <p align="center">
-  <a href="https://github.com/penguiflow/penguiflow/actions/workflows/ci.yml">
-    <img src="https://github.com/penguiflow/penguiflow/actions/workflows/ci.yml/badge.svg" alt="CI Status">
-  </a>
-  <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>
-  <a href="https://github.com/penguiflow/penguiflow/blob/main/LICENSE">
-    <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License">
-  </a>
+  <a href="https://github.com/hurtener/penguiflow/actions/workflows/ci.yml"><img src="https://github.com/hurtener/penguiflow/actions/workflows/ci.yml/badge.svg" alt="CI Status"></a>
+  <a href="https://github.com/hurtener/penguiflow"><img src="https://img.shields.io/badge/coverage-85%25-brightgreen" alt="Coverage"></a>
+  <a href="https://nightly.link/hurtener/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>
+  <a href="https://github.com/hurtener/penguiflow/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
 </p>
 
 **Async-first orchestration library for multi-agent and data pipelines**
@@ -81,6 +71,7 @@ It provides:
 * **Retries, timeouts, backpressure**
 * **Streaming chunks** (LLM-style token emission with `Context.emit_chunk`)
 * **Dynamic loops** (controller nodes)
+* **LLM-driven orchestration** (`ReactPlanner` for autonomous multi-step workflows with tool selection, parallel execution, and pause/resume)
 * **Runtime playbooks** (callable subflows with shared metadata)
 * **Per-trace cancellation** (`PenguiFlow.cancel` with `TraceCancelled` surfacing in nodes)
 * **Deadlines & budgets** (`Message.deadline_s`, `WM.budget_hops`, and `WM.budget_tokens` guardrails that you can leave unset/`None`)
@@ -369,69 +360,52 @@ 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)
+### React Planner - LLM-Driven Orchestration
 
-Phase A introduces a lightweight planner loop that keeps PenguiFlow typed and
-deterministic:
+Build autonomous agents that select and execute tools dynamically using the ReAct (Reasoning + Acting) pattern:
 
-* `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.
+```python
+from penguiflow import ReactPlanner, tool, build_catalog
 
-All three features are exercised in `examples/react_pause_resume/`, which runs
-entirely offline with stubbed LLM responses.
+@tool(desc="Search documentation")
+async def search_docs(args: Query, ctx) -> Documents:
+    return Documents(results=await search(args.text))
 
-### Adaptive re-planning & budgets (Phase C)
+@tool(desc="Summarize results")
+async def summarize(args: Documents, ctx) -> Summary:
+    return Summary(text=await llm_summarize(args.results))
 
-Phase C closes the loop when things go sideways:
+planner = ReactPlanner(
+    llm="gpt-4",
+    catalog=build_catalog([search_docs, summarize], registry),
+    max_iters=10
+)
 
-* **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.
+result = await planner.run("Explain PenguiFlow routing")
+print(result.payload)  # LLM orchestrated search → summarize automatically
+```
 
-The new `examples/react_replan/` sample shows a retrieval timeout automatically
-recover via a cached index without leaving the JSON-only contract.
+**Key capabilities:**
 
-### Parallel fan-out & joins (Phase D)
+* **Autonomous tool selection** — LLM decides which tools to call and in what order based on your query
+* **Type-safe execution** — All tool inputs/outputs validated with Pydantic, JSON schemas auto-generated from models
+* **Parallel execution** — LLM can fan out to multiple tools concurrently with automatic result joining
+* **Pause/resume workflows** — Add approval gates with `await ctx.pause()`, resume later with user input
+* **Adaptive replanning** — Tool failures feed structured error suggestions back to LLM for recovery
+* **Constraint enforcement** — Set hop budgets, deadlines, and token limits to prevent runaway execution
+* **Planning hints** — Guide LLM behavior with ordering preferences, parallel groups, and tool filters
 
-Phase D lets the planner propose sets of independent tool calls and join them
-without leaving the typed surface area:
+**Model support:**
+* Install `penguiflow[planner]` for LiteLLM integration (100+ models: OpenAI, Anthropic, Azure, etc.)
+* Or inject a custom `llm_client` for deterministic/offline testing
 
-* **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.
+**Examples:**
+* `examples/react_minimal/` — Basic sequential flow with stub LLM
+* `examples/react_parallel/` — Parallel shard fan-out with join node
+* `examples/react_pause_resume/` — Approval workflow with planning hints
+* `examples/react_replan/` — Adaptive recovery from tool failures
 
-See `examples/react_parallel/` for a shard fan-out that merges responses in one
-round-trip.
+See **manual.md Section 19** for complete documentation.
 
 
 ## 🧭 Repo Structure

{penguiflow-2.2.0.dist-info → penguiflow-2.2.2.dist-info}/RECORD

@@ -1,4 +1,4 @@
-penguiflow/__init__.py,sha256=Hsoc0UtuilT77kVd0VKPlgnliaRlHgkA3XYd_PvQOYw,2435
+penguiflow/__init__.py,sha256=DX6MR_htAwn0VSZpMQiT3bqqNVcnJvin5fMvgvGMQ8Q,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
@@ -17,11 +17,14 @@ 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/planner/__init__.py,sha256=y-dCNIQmkqEgzrnVqQSU6i2tB0dwqjb7LgG2lhtLJJ8,459
+penguiflow/planner/prompts.py,sha256=R9LveYlp6JbSIBcZiRjTZYu-eKk3fgrKZH0Jf3pNVvM,7551
+penguiflow/planner/react.py,sha256=WP0WvoDShKf5k0jHLiFtUT4ns5YAgWW348C1YEdkSXo,50321
+penguiflow-2.2.2.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.2.dist-info/METADATA,sha256=bVu1DkWE8uXM3y2tcoFpiyjA7CBsEYlpDnirDXQNtUo,27930
+penguiflow-2.2.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+penguiflow-2.2.2.dist-info/entry_points.txt,sha256=F2KxANLEVGRbpWLmcHcvYrTVLWbKWdmk3VOe98a7t9I,59
+penguiflow-2.2.2.dist-info/top_level.txt,sha256=K-fTwLA14n0u_LDxDBCV7FmeBnJffhTOtUbTtOymQns,26
+penguiflow-2.2.2.dist-info/RECORD,,