pyagentic-core 2.13.0a1__tar.gz → 2.14.1.dev1__tar.gz

{pyagentic_core-2.13.0a1/pyagentic_core.egg-info → pyagentic_core-2.14.1.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyagentic-core
-Version: 2.13.0a1
+Version: 2.14.1.dev1
 Summary: Build LLM Agents in a Pythonic way
 Author-email: Ryan Mikulec <rmikulec.dev@gmail.com>
 License: MIT

{pyagentic_core-2.13.0a1 → pyagentic_core-2.14.1.dev1}/docs/index.md

@@ -48,13 +48,13 @@ Dive deeper into PyAgentic's powerful features:
 
     [:octicons-arrow-right-24: Learn about phases](phases.md)
 
-- :material-shield-check: **[Policies](policies.md)**
+- :material-shield-check: **[Policies](policies/index.md)**
 
     ---
 
-    React to state changes with validation, history tracking, persistence, and custom behaviors.
+    React to state and message-context changes with validation, transformation, context management, and custom behaviors.
 
-    [:octicons-arrow-right-24: Learn about policies](policies.md)
+    [:octicons-arrow-right-24: Learn about policies](policies/index.md)
 
 - :material-chat-processing: **[Agent Responses](responses.md)**
 

pyagentic_core-2.14.1.dev1/docs/policies/built-in.md

@@ -0,0 +1,211 @@
+# Built-in Policies
+
+PyAgentic ships four ready-to-use policies, all focused on **context management** —
+keeping the message history sent to the LLM small so long-running agents don't
+blow up their context window (or your token bill).
+
+All of them live in `pyagentic.policies`:
+
+```python
+from pyagentic.policies import (
+    ToolOutputClipPolicy,
+    ToolEvictionPolicy,
+    SlidingWindowPolicy,
+    CompactionPolicy,
+)
+```
+
+Attach them to an agent with the `__message_policies__` class attribute:
+
+```python
+class ResearchAgent(BaseAgent):
+    __system_message__ = "You research topics using tools."
+    __message_policies__ = [
+        ToolOutputClipPolicy(max_chars=8000),
+        ToolEvictionPolicy(keep_last_n=5),
+        CompactionPolicy(max_input_tokens=80_000),
+    ]
+```
+
+They compose — the list above clips oversized tool outputs the moment they enter
+context, stubs out stale tool results as the conversation moves on, and
+summarizes old history if the context still crosses the token threshold.
+
+!!! note
+    Policies only ever shape the **working context** (`state._context`) that
+    providers consume. The raw history (`state._messages` / `state.raw_messages`)
+    always keeps every message untouched, for debugging and auditing. See the
+    [Policies overview](index.md#dual-history-raw-log-vs-working-context) for
+    how the dual history works.
+
+---
+
+## ToolOutputClipPolicy
+
+Clips oversized tool results **at append time**, so a huge output never occupies
+context in the first place. This is the cheapest, highest-impact guard — a single
+tool call returning a large JSON payload is the most common cause of context
+explosion.
+
+```python
+ToolOutputClipPolicy(
+    max_chars=8000,                     # max content length for a tool result
+    suffix="\n…[output clipped]",       # marker so the model knows it saw a slice
+)
+```
+
+| Parameter | Default | Description |
+|---|---|---|
+| `max_chars` | `8000` | Maximum content length for a `ToolResultMessage`. |
+| `suffix` | `"\n…[output clipped]"` | Appended to clipped content. |
+
+**Behavior**
+
+- Runs on `on_append`; only `ToolResultMessage` (and its subclass
+  `AgentResultMessage`) are affected — user/assistant messages pass through.
+- The raw, unclipped result is still recorded in the raw history.
+
+**When to use:** always, essentially. Any agent whose tools can return
+unbounded output (API calls, file reads, search results).
+
+---
+
+## ToolEvictionPolicy
+
+Evicts old tool results from the context, keeping only the most recent N intact.
+Old results are usually only useful for the turn they served — after that they're
+dead weight.
+
+```python
+ToolEvictionPolicy(
+    keep_last_n=5,                                   # recent results kept intact
+    stub="[tool result evicted to save context]",    # replacement content
+    include_agent_results=True,                      # also evict linked-agent results
+)
+```
+
+| Parameter | Default | Description |
+|---|---|---|
+| `keep_last_n` | `5` | Number of most-recent tool results kept verbatim. |
+| `stub` | `"[tool result evicted to save context]"` | Replacement content for evicted results. |
+| `include_agent_results` | `True` | Whether `AgentResultMessage`s are also subject to eviction. |
+
+**Behavior**
+
+- Runs on `on_compile`, right before each inference.
+- **Stubs, never deletes**: the message and its `tool_call_id` survive, because
+  providers reject histories with orphaned call/result pairs.
+- Idempotent — already-stubbed results are left alone, so it does no repeated
+  work on later turns.
+- Set `include_agent_results=False` to exempt linked-agent responses (useful
+  when sub-agent findings need to stay in context longer than raw tool output).
+
+**When to use:** tool-heavy agents with many calls per conversation. Pair it
+with `ToolOutputClipPolicy` — clipping bounds each result, eviction bounds how
+many results linger.
+
+---
+
+## SlidingWindowPolicy
+
+Bounds the context to the most recent `max_messages` messages, dropping from the
+front.
+
+```python
+SlidingWindowPolicy(max_messages=50)
+```
+
+| Parameter | Default | Description |
+|---|---|---|
+| `max_messages` | `50` | Maximum number of messages kept in context. |
+
+**Behavior**
+
+- Runs on `on_compile`.
+- The cut is **pair-boundary-safe**: it advances past any tool results whose
+  calls were dropped, so no result ever survives without the call that produced
+  it.
+- Blunt but predictable — older turns disappear entirely rather than being
+  summarized.
+
+**When to use:** simple bounded-memory agents where old turns genuinely stop
+mattering (chat companions, per-session assistants). Prefer `CompactionPolicy`
+when older context contains facts the agent must not forget.
+
+---
+
+## CompactionPolicy
+
+Summarizes older history into a single `CompactionSummaryMessage` when the
+context grows past a token threshold — the "keep the gist, drop the transcript"
+strategy.
+
+```python
+CompactionPolicy(
+    max_input_tokens=100_000,    # threshold that triggers compaction
+    keep_recent=10,              # most-recent messages kept verbatim
+    summary_prompt=DEFAULT_COMPACTION_PROMPT,
+)
+```
+
+| Parameter | Default | Description |
+|---|---|---|
+| `max_input_tokens` | `100_000` | Input-token threshold that triggers compaction. |
+| `keep_recent` | `10` | Number of most-recent messages kept verbatim. |
+| `summary_prompt` | `DEFAULT_COMPACTION_PROMPT` | System prompt for the summarization call. |
+
+**Behavior**
+
+- Runs on `on_compile`. The trigger is the **previous inference's reported
+  input tokens** (`event.last_usage`) — no tokenizer dependency. When usage
+  isn't available, it falls back to a chars/4 estimate.
+- Splits history at `len - keep_recent`, nudged forward so no tool call/result
+  pair straddles the boundary, renders the older half into a transcript, and
+  summarizes it with **one LLM call** via the same provider the agent uses.
+- The result replaces the old messages with a single
+  `CompactionSummaryMessage(compacted_count=N)`. Because the compiled context
+  is written back, compaction fires **once per threshold crossing**, not every
+  turn, and prior summaries are folded into the next one.
+- Override `summary_prompt` to control what survives compaction (e.g. "always
+  preserve file paths and error messages" for a coding agent). The default
+  prompt (`pyagentic.policies.DEFAULT_COMPACTION_PROMPT`) preserves key facts,
+  user goals, decisions, tool findings, and open tasks.
+
+**When to use:** long-running agents where old context carries facts that must
+survive (research, planning, multi-session work). Costs one extra LLM call per
+compaction.
+
+!!! tip "State survives compaction for free"
+    Anything stored in typed `State` fields is rendered into the system prompt
+    from state, not from message history — so it is never lost to compaction.
+    Put durable facts in state; let the transcript be compactable.
+
+---
+
+## Choosing and combining
+
+| Goal | Policy |
+|---|---|
+| One tool call returns megabytes | `ToolOutputClipPolicy` |
+| Many tool calls accumulate | `ToolEvictionPolicy` |
+| Hard cap on history length, forgetting is fine | `SlidingWindowPolicy` |
+| Long sessions, must remember the gist | `CompactionPolicy` |
+| Linked-agent responses flooding the parent | `ToolOutputClipPolicy` / `ToolEvictionPolicy` (they match `AgentResultMessage` too) |
+
+A sensible default stack for a tool-using agent:
+
+```python
+__message_policies__ = [
+    ToolOutputClipPolicy(max_chars=8000),       # bound each result (append time)
+    ToolEvictionPolicy(keep_last_n=5),          # bound how many linger (compile time)
+    CompactionPolicy(max_input_tokens=80_000),  # last resort when context still grows
+]
+```
+
+Order matters at compile time: policies run in declaration order, each seeing
+the previous one's output. Put cheap, targeted policies before expensive,
+sweeping ones so compaction sees an already-slimmed context.
+
+All built-in policies are **stateless** (config-only), as required — policy
+instances are shared across agent instances and forks. To write your own, see
+[Writing Custom Policies](custom.md).

pyagentic_core-2.14.1.dev1/docs/policies/custom.md

@@ -0,0 +1,342 @@
+# Writing Custom Policies
+
+A policy is a plain class implementing the `Policy` protocol. Subclass it,
+implement **only the handlers you need**, and take configuration in
+`__init__` — every handler you don't implement is skipped.
+
+```python
+from pyagentic.policies import Policy
+from pyagentic.policies._events import (
+    GetEvent, SetEvent, AppendEvent, CompileEvent,
+)
+
+class Policy(Protocol[T]):
+    # sync — block and may transform or veto
+    def on_get(self, event: GetEvent, value: T) -> T | None: ...
+    def on_set(self, event: SetEvent, value: T) -> T | None: ...
+    def on_append(self, event: AppendEvent, item: Any) -> Any | None: ...
+
+    # async — runs before each LLM inference, result written back
+    async def on_compile(self, event: CompileEvent, items: list) -> list | None: ...
+
+    # async — fire-and-forget side effects after the operation
+    async def background_get(self, event: GetEvent, value: T) -> None: ...
+    async def background_set(self, event: SetEvent, value: T) -> None: ...
+    async def background_append(self, event: AppendEvent, item: Any) -> None: ...
+```
+
+Three return conventions, everywhere:
+
+| Handler returns | Meaning |
+|---|---|
+| a value | Replace the value/item/list with it |
+| `None` | No change |
+| *raises* | Veto — the write is aborted / the appended item is skipped |
+
+---
+
+## State policy examples
+
+### Validation (veto by raising)
+
+```python
+class RangePolicy(Policy[int]):
+    """Keep an int field within [min_val, max_val]."""
+
+    def __init__(self, min_val: int, max_val: int):
+        self.min_val, self.max_val = min_val, max_val
+
+    def on_set(self, event: SetEvent, value: int) -> int | None:
+        if not (self.min_val <= value <= self.max_val):
+            raise ValueError(
+                f"{event.name} must be between {self.min_val} and {self.max_val}"
+            )
+        return None
+
+
+class GameAgent(BaseAgent):
+    __system_message__ = "You run a text adventure."
+
+    score: State[int] = spec.State(
+        default=0,
+        access="write",   # autogenerates a set_score tool
+        policies=[RangePolicy(0, 100)],
+    )
+```
+
+When the LLM calls `set_score(150)`, the policy raises, the write is aborted,
+and the tool error propagates back to the LLM — which can retry with a valid
+value:
+
+```mermaid
+sequenceDiagram
+    participant LLM
+    participant State as AgentState
+    participant Policy as RangePolicy
+
+    LLM->>State: set score = 150
+    State->>Policy: on_set(event, 150)
+    Policy--xState: raise ValueError("score must be between 0 and 100")
+    State--xLLM: Tool error (state unchanged)
+
+    LLM->>State: set score = 100
+    State->>Policy: on_set(event, 100)
+    Policy-->>State: None (keep)
+    State-->>LLM: ✓ "Score updated to 100"
+```
+
+### Transformation (return a replacement)
+
+```python
+class NormalizeTagPolicy(Policy[str]):
+    """Store tags in a canonical form."""
+
+    def on_set(self, event: SetEvent, value: str) -> str:
+        return value.strip().lower().replace(" ", "-")
+```
+
+### Background persistence (side effects, non-blocking)
+
+```python
+import json, asyncio
+from pathlib import Path
+
+class JSONAuditPolicy(Policy):
+    """Append every change to an audit file, off the hot path."""
+
+    def __init__(self, filepath: str):
+        self.filepath = Path(filepath)
+
+    async def background_set(self, event: SetEvent, value) -> None:
+        record = {
+            "ts": event.timestamp.isoformat(),
+            "field": event.name,
+            "old": str(event.previous),
+            "new": str(value),
+        }
+
+        def write():
+            existing = (
+                json.loads(self.filepath.read_text()) if self.filepath.exists() else []
+            )
+            existing.append(record)
+            self.filepath.write_text(json.dumps(existing, indent=2))
+
+        await asyncio.to_thread(write)
+```
+
+Background handlers run after the value is committed — they can't veto or
+change it, and failures are logged rather than raised.
+
+### List fields (mutation tracking)
+
+Policies on list-typed fields fire on **in-place mutations** — appends run
+`on_append` per item, other mutations run `on_set` over the whole list:
+
+```python
+class NoEmptyStrings(Policy):
+    def on_append(self, event: AppendEvent, item) -> None:
+        if isinstance(item, str) and not item.strip():
+            raise ValueError("empty entries not allowed")
+
+
+class NotesAgent(BaseAgent):
+    __system_message__ = "You keep notes."
+
+    notes: State[list] = spec.State(default_factory=list, policies=[NoEmptyStrings()])
+
+# agent.notes.append("real note")  -> stored
+# agent.notes.append("   ")        -> vetoed, list unchanged
+```
+
+---
+
+## Message policy examples
+
+Message policies attach via `__message_policies__` and receive the semantic
+message types from `pyagentic.models.llm` — filter with `isinstance`.
+
+### Redaction (transform on append)
+
+Scrub secrets from tool output *before* it ever enters the context. The raw
+history still holds the original for auditing.
+
+```python
+import re
+from pyagentic.models.llm import ToolResultMessage
+
+class RedactSecretsPolicy(Policy):
+    """Mask API keys / bearer tokens in tool results."""
+
+    PATTERN = re.compile(r"(sk-[A-Za-z0-9]{8,}|Bearer\s+\S+)")
+
+    def on_append(self, event: AppendEvent, item):
+        if isinstance(item, ToolResultMessage) and item.content:
+            redacted = self.PATTERN.sub("[REDACTED]", item.content)
+            if redacted != item.content:
+                return item.model_copy(update={"content": redacted})
+        return None
+```
+
+### Linked-agent response budget (targeted transform)
+
+`AgentResultMessage` subclasses `ToolResultMessage`, so you can target linked
+agents specifically and give them their own context budget:
+
+```python
+from pyagentic.models.llm import AgentResultMessage
+
+class AgentResultBudgetPolicy(Policy):
+    """Keep any single sub-agent response under a size budget."""
+
+    def __init__(self, max_chars: int = 2000):
+        self.max_chars = max_chars
+
+    def on_append(self, event: AppendEvent, item):
+        if isinstance(item, AgentResultMessage) and len(item.content or "") > self.max_chars:
+            return item.model_copy(
+                update={"content": item.content[: self.max_chars] + "…[truncated]"}
+            )
+        return None
+```
+
+### Context metrics (observe on compile, change nothing)
+
+`on_compile` sees the whole context plus the last inference's token usage —
+return `None` and it's a pure observer:
+
+```python
+import logging
+from pyagentic.models.llm import ToolResultMessage
+
+logger = logging.getLogger(__name__)
+
+class ContextMetricsPolicy(Policy):
+    """Log context size before every inference; warn near a budget."""
+
+    def __init__(self, warn_at_tokens: int = 80_000):
+        self.warn_at_tokens = warn_at_tokens
+
+    async def on_compile(self, event: CompileEvent, items: list) -> None:
+        tool_chars = sum(
+            len(m.content or "") for m in items if isinstance(m, ToolResultMessage)
+        )
+        used = event.last_usage.input_tokens if event.last_usage else 0
+        logger.info(
+            f"context: {len(items)} messages, {tool_chars} tool chars, "
+            f"{used} input tokens last call"
+        )
+        if used > self.warn_at_tokens:
+            logger.warning(f"context nearing budget: {used}/{self.warn_at_tokens}")
+        return None
+```
+
+### Custom compile transforms
+
+`on_compile` may also rewrite the list — the result is written back, so the
+effect persists across turns. Two rules to respect:
+
+1. **Never orphan a tool call/result pair.** Providers reject a
+   `ToolResultMessage` whose `ToolCallMessage` is missing (and vice versa).
+   Stub content instead of deleting messages, or move your cut past the pair —
+   see how the [built-in policies](built-in.md) handle this.
+2. **Be idempotent.** Your policy runs before *every* inference; a second pass
+   over already-processed context should return `None`.
+
+```python
+from pyagentic.models.llm import UserMessage
+
+class KeepFirstUserTurnPolicy(Policy):
+    """Always retain the original task statement when trimming."""
+
+    def __init__(self, max_messages: int = 40):
+        self.max_messages = max_messages
+
+    async def on_compile(self, event: CompileEvent, items: list) -> list | None:
+        if len(items) <= self.max_messages:
+            return None
+        first_user = next((m for m in items if isinstance(m, UserMessage)), None)
+        tail = items[-(self.max_messages - 1):]
+        if first_user is None or first_user in tail:
+            return tail
+        return [first_user] + tail
+```
+
+---
+
+## Rules of the road
+
+### Policies must be stateless
+
+Policy instances are attached at **class-definition time** and shared across
+all agent instances and forks. Configuration in `__init__` is fine; per-agent
+mutable state on the policy is a bug (two agents would share it).
+
+Derive anything per-agent from what the event gives you:
+
+- the list contents themselves (e.g. check for an existing stub or
+  `CompactionSummaryMessage` marker instead of remembering "already ran")
+- `event.state` for state fields, `event.last_usage` for token counts
+
+### Ordering
+
+Policies run in declaration order, each seeing the previous one's output —
+validate first, transform second, side effects last:
+
+```python
+score: State[int] = spec.State(
+    default=0,
+    policies=[
+        RangePolicy(0, 100),        # 1. validate
+        # transformation would go here
+        JSONAuditPolicy("audit.json"),  # 2. persist (background)
+    ],
+)
+```
+
+The first exception in a sync pipeline aborts the operation; later handlers do
+not run.
+
+### Keep sync handlers fast
+
+`on_get`/`on_set`/`on_append` block the operation. Anything that does I/O
+belongs in a `background_*` handler, or in `on_compile` (which is async and
+runs once per inference rather than once per access).
+
+---
+
+## Testing your policies
+
+Events are plain dataclasses and handlers are plain methods — unit-test them
+directly, no agent required:
+
+```python
+import pytest
+from pyagentic.policies._events import AppendEvent
+from pyagentic.models.llm import ToolResultMessage
+
+def test_redaction_masks_keys():
+    policy = RedactSecretsPolicy()
+    msg = ToolResultMessage(tool_call_id="c1", name="fetch", content="key=sk-abcdef123456")
+
+    result = policy.on_append(AppendEvent(name="messages", value=msg), msg)
+
+    assert "[REDACTED]" in result.content
+    assert "sk-" not in result.content
+```
+
+For end-to-end behavior, run an agent against the mock provider
+(`model="_mock::test-model"`) and assert on `agent.state._context` (what the
+LLM saw) versus `agent.state._messages` (what actually happened):
+
+```python
+@pytest.mark.asyncio
+async def test_budget_policy_in_agent():
+    class _Agent(BaseAgent):
+        __system_message__ = "test"
+        __message_policies__ = [AgentResultBudgetPolicy(max_chars=100)]
+
+    agent = _Agent(model="_mock::test-model", api_key="k")
+    await agent.run("hello")
+    ...
+```