penguiflow 2.2.0__tar.gz → 2.2.2__tar.gz

{penguiflow-2.2.0 → penguiflow-2.2.2}/PKG-INFO

@@ -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 → penguiflow-2.2.2}/README.md

@@ -5,21 +5,11 @@
 </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**
@@ -33,6 +23,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`)
@@ -321,69 +312,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 → penguiflow-2.2.2}/penguiflow/__init__.py

@@ -105,4 +105,4 @@ __all__ = [
     "TrajectoryStep",
 ]
 
-__version__ = "2.2.0"
+__version__ = "2.2.2"

penguiflow-2.2.2/penguiflow/planner/__init__.py

@@ -0,0 +1,27 @@
+"""Planner entry points."""
+
+from __future__ import annotations
+
+from .react import (
+    ParallelCall,
+    ParallelJoin,
+    PlannerAction,
+    PlannerFinish,
+    PlannerPause,
+    ReactPlanner,
+    Trajectory,
+    TrajectoryStep,
+    TrajectorySummary,
+)
+
+__all__ = [
+    "ParallelCall",
+    "ParallelJoin",
+    "PlannerAction",
+    "PlannerFinish",
+    "PlannerPause",
+    "ReactPlanner",
+    "Trajectory",
+    "TrajectoryStep",
+    "TrajectorySummary",
+]

penguiflow-2.2.2/penguiflow/planner/prompts.py

@@ -0,0 +1,243 @@
+"""Prompt helpers for the React planner."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+
+def render_summary(summary: Mapping[str, Any]) -> str:
+    return "Trajectory summary: " + _compact_json(summary)
+
+
+def render_resume_user_input(user_input: str) -> str:
+    return f"Resume input: {user_input}"
+
+
+def render_planning_hints(hints: Mapping[str, Any]) -> str:
+    lines: list[str] = []
+    constraints = hints.get("constraints")
+    if constraints:
+        lines.append(f"Respect the following constraints: {constraints}")
+    preferred = hints.get("preferred_order")
+    if preferred:
+        lines.append(f"Preferred order (if feasible): {preferred}")
+    parallels = hints.get("parallel_groups")
+    if parallels:
+        lines.append(f"Allowed parallel groups: {parallels}")
+    disallowed = hints.get("disallow_nodes")
+    if disallowed:
+        lines.append(f"Disallowed tools: {disallowed}")
+    preferred_nodes = hints.get("preferred_nodes")
+    if preferred_nodes:
+        lines.append(f"Preferred tools: {preferred_nodes}")
+    budget = hints.get("budget")
+    if budget:
+        lines.append(f"Budget hints: {budget}")
+    if not lines:
+        return ""
+    return "\n".join(lines)
+
+
+def render_disallowed_node(node_name: str) -> str:
+    return (
+        f"tool '{node_name}' is not permitted by constraints. "
+        "Choose an allowed tool or revise the plan."
+    )
+
+
+def render_ordering_hint_violation(expected: Sequence[str], proposed: str) -> str:
+    order = ", ".join(expected)
+    return (
+        "Ordering hint reminder: follow the preferred sequence "
+        f"[{order}]. Proposed: {proposed}. Revise the plan."
+    )
+
+
+def render_parallel_limit(max_parallel: int) -> str:
+    return (
+        f"Parallel action exceeds max_parallel={max_parallel}. Reduce parallel fan-out."
+    )
+
+
+def render_sequential_only(node_name: str) -> str:
+    return (
+        f"tool '{node_name}' must run sequentially. "
+        "Do not include it in a parallel plan."
+    )
+
+
+def render_parallel_setup_error(errors: Sequence[str]) -> str:
+    detail = "; ".join(errors)
+    return f"Parallel plan invalid: {detail}. Revise the plan and retry."
+
+
+def render_empty_parallel_plan() -> str:
+    return "Parallel plan must include at least one branch in 'plan'."
+
+
+def render_parallel_with_next_node(next_node: str) -> str:
+    return (
+        f"Parallel plan cannot set next_node='{next_node}'. "
+        "Use 'join' to continue or finish the run explicitly."
+    )
+
+
+def render_parallel_unknown_failure(node_name: str) -> str:
+    return (
+        f"tool '{node_name}' failed during parallel execution. "
+        "Investigate the tool and adjust the plan."
+    )
+
+
+def build_summarizer_messages(
+    query: str,
+    history: Sequence[Mapping[str, Any]],
+    base_summary: Mapping[str, Any],
+) -> list[dict[str, str]]:
+    return [
+        {
+            "role": "system",
+            "content": (
+                "You are a summariser producing compact JSON state. "
+                "Respond with valid JSON matching the TrajectorySummary schema."
+            ),
+        },
+        {
+            "role": "user",
+            "content": _compact_json(
+                {
+                    "query": query,
+                    "history": list(history),
+                    "current_summary": dict(base_summary),
+                }
+            ),
+        },
+    ]
+
+
+def _compact_json(data: Any) -> str:
+    return json.dumps(data, ensure_ascii=False, sort_keys=True)
+
+
+def render_tool(record: Mapping[str, Any]) -> str:
+    args_schema = _compact_json(record["args_schema"])
+    out_schema = _compact_json(record["out_schema"])
+    tags = ", ".join(record.get("tags", ()))
+    scopes = ", ".join(record.get("auth_scopes", ()))
+    parts = [
+        f"- name: {record['name']}",
+        f"  desc: {record['desc']}",
+        f"  side_effects: {record['side_effects']}",
+        f"  args_schema: {args_schema}",
+        f"  out_schema: {out_schema}",
+    ]
+    if tags:
+        parts.append(f"  tags: {tags}")
+    if scopes:
+        parts.append(f"  auth_scopes: {scopes}")
+    if record.get("cost_hint"):
+        parts.append(f"  cost_hint: {record['cost_hint']}")
+    if record.get("latency_hint_ms") is not None:
+        parts.append(f"  latency_hint_ms: {record['latency_hint_ms']}")
+    if record.get("safety_notes"):
+        parts.append(f"  safety_notes: {record['safety_notes']}")
+    if record.get("extra"):
+        parts.append(f"  extra: {_compact_json(record['extra'])}")
+    return "\n".join(parts)
+
+
+def build_system_prompt(
+    catalog: Sequence[Mapping[str, Any]],
+    *,
+    extra: str | None = None,
+    planning_hints: Mapping[str, Any] | None = None,
+) -> str:
+    rendered_tools = "\n".join(render_tool(item) for item in catalog)
+    prompt = [
+        "You are PenguiFlow ReactPlanner, a JSON-only planner.",
+        "Follow these rules strictly:",
+        "1. Respond with valid JSON matching the PlannerAction schema.",
+        "2. Use the provided tools when necessary; never invent new tool names.",
+        "3. Keep 'thought' concise and factual.",
+        "4. When the task is complete, set 'next_node' to null "
+        "and include the final payload in 'args'.",
+        "5. Do not emit plain text outside JSON.",
+        "",
+        "Available tools:",
+        rendered_tools or "(none)",
+    ]
+    if extra:
+        prompt.extend(["", "Additional guidance:", extra])
+    if planning_hints:
+        rendered_hints = render_planning_hints(planning_hints)
+        if rendered_hints:
+            prompt.extend(["", rendered_hints])
+    return "\n".join(prompt)
+
+
+def build_user_prompt(query: str, context_meta: Mapping[str, Any] | None = None) -> str:
+    if context_meta:
+        return _compact_json({"query": query, "context": dict(context_meta)})
+    return _compact_json({"query": query})
+
+
+def render_observation(
+    *,
+    observation: Any | None,
+    error: str | None,
+    failure: Mapping[str, Any] | None = None,
+) -> str:
+    payload: dict[str, Any] = {}
+    if observation is not None:
+        payload["observation"] = observation
+    if error:
+        payload["error"] = error
+    if failure:
+        payload["failure"] = dict(failure)
+    if not payload:
+        payload["observation"] = None
+    return _compact_json(payload)
+
+
+def render_hop_budget_violation(limit: int) -> str:
+    return (
+        "Hop budget exhausted; you have used all available tool calls. "
+        "Finish with the best answer so far or reply with no_path."
+        f" (limit={limit})"
+    )
+
+
+def render_deadline_exhausted() -> str:
+    return (
+        "Deadline reached. Provide the best available conclusion or return no_path."
+    )
+
+
+def render_validation_error(node_name: str, error: str) -> str:
+    return (
+        f"args for tool '{node_name}' did not validate: {error}. "
+        "Return corrected JSON."
+    )
+
+
+def render_output_validation_error(node_name: str, error: str) -> str:
+    return (
+        f"tool '{node_name}' returned data that did not validate: {error}. "
+        "Ensure the tool output matches the declared schema."
+    )
+
+
+def render_invalid_node(node_name: str, available: Sequence[str]) -> str:
+    options = ", ".join(sorted(available))
+    return (
+        f"tool '{node_name}' is not in the catalog. Choose one of: {options}."
+    )
+
+
+def render_repair_message(error: str) -> str:
+    return (
+        "Previous response was invalid JSON or schema mismatch: "
+        f"{error}. Reply with corrected JSON only."
+    )