summarization-pydantic-ai

raw JSON →
0.1.4 verified Fri May 01 auth: no python

Automatic conversation summarization and history management for Pydantic AI. Provides history processors and Pydantic AI capabilities (0.1.x) to compress, trim, and warn about conversation context windows. Current version 0.1.4, requires Python >=3.10. This library replaces the older pydantic-ai-middleware pattern with native capabilities. Active development.

pip install summarization-pydantic-ai

Common errors

error ModuleNotFoundError: No module named 'summarization_pydantic_ai' ↓
cause Package not installed or imported with wrong case.
fix
Install with pip install summarization-pydantic-ai and import as summarization_pydantic_ai (underscores, not hyphens).
error AttributeError: module 'summarization_pydantic_ai' has no attribute 'SummarizationProcessor' ↓
cause Using an older version (<0.1.0) where the processor was in a submodule.
fix
Upgrade to latest version: pip install --upgrade summarization-pydantic-ai. Then use top-level import as shown in quickstart.
error TypeError: 'NoneType' object is not callable ↓
cause The `summary_model` argument was not provided or is None, and the agent's model cannot be used automatically.
fix
Pass a valid model string (e.g., 'openai:gpt-4o-mini') to SummarizationProcessor(summary_model=...).
error ValueError: Invalid ContextSize format: ... ↓
cause Using a tuple with incorrect syntax for trigger/retention/keep_head.
fix
Use one of: ('messages', int), ('tokens', int), or ('fraction', float). Example: trigger=('messages', 10).

Warnings

breaking Version 0.1.0 replaced the middleware-based API (ContextManagerMiddleware) with capabilities (SummarizationCapability, SlidingWindowCapability, LimitWarnerCapability, ContextManagerCapability). Old code using `create_context_manager_middleware()` or `ContextManagerMiddleware` must be migrated to the new capability system. ↓
fix Replace `ContextManagerMiddleware` with the appropriate capability. For example, if you used `history_processor`, switch to `SummarizationProcessor` or `SlidingWindowProcessor`. If you used the middleware's agent integration, use the new capabilities via `Agent.set_capabilities()`.
breaking The `ContextManagerCapability` now includes a `compact_conversation` tool when `include_compact_tool=True`. This tool is available to the model and may be called unexpectedly, leading to conversation compression the agent did not explicitly request. ↓
fix If unintended, set `include_compact_tool=False` (default) or control tool availability via system prompt.
gotcha When using `keep_head` on `SlidingWindowProcessor`, specifying a high number may cause the head to be larger than the retention, resulting in undefined behavior or errors. Always ensure `keep_head < retention` (or at least less than the total window size). ↓
fix Check your logic: `keep_head` should be a small number (e.g., 2-5) to preserve system prompts and initial instructions, not exceed retention.
gotcha The `summary_model` parameter in `SummarizationProcessor` defaults to the agent's model if not set. If the agent's model is not capable of summarization (e.g., a very small local model), compression may fail silently or produce poor summaries. ↓
fix Explicitly set a capable model (e.g., `'openai:gpt-4o-mini'`) for summarization to ensure quality.

Imports

Quickstart

Basic usage with SummarizationProcessor as a history processor.

from pydantic_ai import Agent
from summarization_pydantic_ai import SummarizationProcessor

# Create a summarization processor that triggers at 10 messages
processor = SummarizationProcessor(
    trigger=("messages", 10),
    retention=("messages", 5),
    summary_model="openai:gpt-4o-mini",
)

agent = Agent(
    model="openai:gpt-4o-mini",
    system_prompt="You are a helpful assistant.",
    history_processor=processor,
)

# Start a conversation; messages will be summarized when limit reached
result = agent.run_sync("Hello!")
print(result.data)
last verified Fri May 01
next check Thu Jul 30