{"id":24669,"library":"summarization-pydantic-ai","title":"summarization-pydantic-ai","description":"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.","status":"active","version":"0.1.4","language":"python","source_language":"en","source_url":"https://github.com/vstorm-co/summarization-pydantic-ai","tags":["pydantic-ai","summarization","conversation","history-management","context-window","agents"],"install":[{"cmd":"pip install summarization-pydantic-ai","lang":"bash","label":"default"}],"dependencies":[{"reason":"Core dependency; version >=1.74.0 required for async get_instructions support in toolsets","package":"pydantic-ai-slim","optional":false},{"reason":"Default token counter uses tiktoken; optional if custom counter provided","package":"openai","optional":true}],"imports":[{"note":"Processors are re-exported from top-level package since 0.1.0","wrong":"from summarization_pydantic_ai.processors import SummarizationProcessor","symbol":"SummarizationProcessor","correct":"from summarization_pydantic_ai import SummarizationProcessor"},{"note":"Internal module names changed between 0.0.x and 0.1.x","wrong":"from summarization_pydantic_ai.sliding_window import SlidingWindowProcessor","symbol":"SlidingWindowProcessor","correct":"from summarization_pydantic_ai import SlidingWindowProcessor"},{"note":"Capabilities live in a separate module, not directly in top-level package","wrong":"from summarization_pydantic_ai import ContextManagerCapability","symbol":"ContextManagerCapability","correct":"from summarization_pydantic_ai.capabilities import ContextManagerCapability"},{"note":"","wrong":"","symbol":"SummarizationCapability","correct":"from summarization_pydantic_ai.capabilities import SummarizationCapability"},{"note":"","wrong":"","symbol":"SlidingWindowCapability","correct":"from summarization_pydantic_ai.capabilities import SlidingWindowCapability"},{"note":"","wrong":"","symbol":"LimitWarnerCapability","correct":"from summarization_pydantic_ai.capabilities import LimitWarnerCapability"}],"quickstart":{"code":"from pydantic_ai import Agent\nfrom summarization_pydantic_ai import SummarizationProcessor\n\n# Create a summarization processor that triggers at 10 messages\nprocessor = SummarizationProcessor(\n    trigger=(\"messages\", 10),\n    retention=(\"messages\", 5),\n    summary_model=\"openai:gpt-4o-mini\",\n)\n\nagent = Agent(\n    model=\"openai:gpt-4o-mini\",\n    system_prompt=\"You are a helpful assistant.\",\n    history_processor=processor,\n)\n\n# Start a conversation; messages will be summarized when limit reached\nresult = agent.run_sync(\"Hello!\")\nprint(result.data)","lang":"python","description":"Basic usage with SummarizationProcessor as a history processor."},"warnings":[{"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()`.","message":"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.","severity":"breaking","affected_versions":"< 0.1.0"},{"fix":"If unintended, set `include_compact_tool=False` (default) or control tool availability via system prompt.","message":"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.","severity":"breaking","affected_versions":">= 0.1.3"},{"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.","message":"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).","severity":"gotcha","affected_versions":">= 0.1.4"},{"fix":"Explicitly set a capable model (e.g., `'openai:gpt-4o-mini'`) for summarization to ensure quality.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Install with `pip install summarization-pydantic-ai` and import as `summarization_pydantic_ai` (underscores, not hyphens).","cause":"Package not installed or imported with wrong case.","error":"ModuleNotFoundError: No module named 'summarization_pydantic_ai'"},{"fix":"Upgrade to latest version: `pip install --upgrade summarization-pydantic-ai`. Then use top-level import as shown in quickstart.","cause":"Using an older version (<0.1.0) where the processor was in a submodule.","error":"AttributeError: module 'summarization_pydantic_ai' has no attribute 'SummarizationProcessor'"},{"fix":"Pass a valid model string (e.g., `'openai:gpt-4o-mini'`) to `SummarizationProcessor(summary_model=...)`.","cause":"The `summary_model` argument was not provided or is None, and the agent's model cannot be used automatically.","error":"TypeError: 'NoneType' object is not callable"},{"fix":"Use one of: `('messages', int)`, `('tokens', int)`, or `('fraction', float)`. Example: `trigger=('messages', 10)`.","cause":"Using a tuple with incorrect syntax for trigger/retention/keep_head.","error":"ValueError: Invalid ContextSize format: ..."}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}