Skip to content

Summarization for Pydantic AI

Summarization for Pydantic AI

Unlimited context for long-running agents.

PyPI version PyPI Downloads GitHub Stars Python 3.10+ License: MIT Coverage Status CI Pydantic AI

Upstreamed to pydantic-ai-harness

Working together with the Pydantic team, we moved this library's functionality into the official pydantic-ai-harness — it now lives in pydantic_ai_harness/compaction (PR #465, merged).

For new projects, use the harness. This library stays on PyPI and keeps working for everyone already depending on it. See the README for a mapping from each processor here to its harness capability.

Python
from pydantic_ai import Agent
from pydantic_ai_harness.compaction import SummarizingCompaction

agent = Agent(
    "anthropic:claude-sonnet-4-6",
    capabilities=[SummarizingCompaction(max_fraction=0.9, keep_messages=20)],
)

Part of Pydantic Deep Agents

Summarization for Pydantic AI is one library in Pydantic Deep Agents — the open-source Claude Code alternative & Python agent framework. Use it standalone, or get every library wired together in a single create_deep_agent() call.

Context Management for Pydantic AI helps your agents handle long conversations without exceeding model context limits. Choose between intelligent LLM summarization or fast sliding window trimming.

  • Intelligent Summarization

    LLM-powered compression that preserves key information

  • Sliding Window

    Zero-cost message trimming for maximum speed

  • Safe Cutoff

    Never breaks tool call/response pairs

  • Flexible Configuration

    Message, token, or fraction-based triggers

The recommended way to add context management:

Python
from pydantic_ai import Agent
from pydantic_ai_summarization import ContextManagerCapability

agent = Agent(
    "openai:gpt-4.1",
    capabilities=[ContextManagerCapability(max_tokens=100_000)],
)

Combine with limit warnings:

Python
from pydantic_ai_summarization import ContextManagerCapability, LimitWarnerCapability

agent = Agent(
    "openai:gpt-4.1",
    capabilities=[
        LimitWarnerCapability(max_iterations=40, max_context_tokens=100_000),
        ContextManagerCapability(max_tokens=100_000),
    ],
)

Available Options

Option Type LLM Cost Best For
ContextManagerCapability Capability Per compression Production apps (recommended)
SummarizationCapability Capability High Quality-focused apps
SlidingWindowCapability Capability Zero Speed/cost-focused apps
LimitWarnerCapability Capability Zero Warning before limits hit
SummarizationProcessor Processor High Standalone use
SlidingWindowProcessor Processor Zero Standalone use
LimitWarnerProcessor Processor Zero Standalone use

Alternative: Processor API

Python
from pydantic_ai import Agent
from pydantic_ai_summarization import create_summarization_processor

processor = create_summarization_processor(
    trigger=("tokens", 100000),
    keep=("messages", 20),
)

agent = Agent(
    "openai:gpt-4o",
    history_processors=[processor],
)

result = await agent.run("Hello!")

Zero-Cost Sliding Window

Simply discards old messages — no LLM calls:

Python
from pydantic_ai import Agent
from pydantic_ai_summarization import create_sliding_window_processor

processor = create_sliding_window_processor(
    trigger=("messages", 100),
    keep=("messages", 50),
)

agent = Agent(
    "openai:gpt-4o",
    history_processors=[processor],
)

result = await agent.run("Hello!")

Choosing a Processor

Use SummarizationProcessor when:

  • Context quality is critical
  • You need to preserve key information from long conversations
  • LLM cost is acceptable for your use case

Use SlidingWindowProcessor when:

  • Speed and cost are priorities
  • Recent context is most important
  • You're running many parallel conversations
  • You want deterministic, predictable behavior
Package Description
Pydantic Deep Agents Full agent framework (uses this library)
pydantic-ai-backend File storage and Docker sandbox
pydantic-ai-todo Task planning toolset
subagents-pydantic-ai Multi-agent orchestration
pydantic-ai The foundation — agent framework by Pydantic

Next Steps