Skip to content

Installation

Requirements

  • Python 3.10+
  • uv (recommended) or pip
Bash
uv add summarization-pydantic-ai

Install with pip

Bash
pip install summarization-pydantic-ai

Optional Dependencies

Extra Description Use Case
tiktoken Accurate token counting OpenAI models
hybrid Context manager middleware Real-time token tracking + tool truncation

Tiktoken for Accurate Token Counting

For more accurate token counting (especially with OpenAI models):

Bash
uv add summarization-pydantic-ai[tiktoken]
Bash
pip install summarization-pydantic-ai[tiktoken]

When to use tiktoken

The default token counter uses a heuristic (~4 chars per token). For production applications with OpenAI models, tiktoken provides exact token counts.

Hybrid for Context Manager Middleware

The hybrid extra installs pydantic-ai-middleware, which is required for the ContextManagerMiddleware. This middleware provides real-time token tracking, auto-compression, and tool output truncation.

Bash
uv add summarization-pydantic-ai[hybrid]
Bash
pip install summarization-pydantic-ai[hybrid]

When to use hybrid

Use the hybrid extra when you need real-time token budget tracking with on_usage_update callbacks, automatic tool output truncation, or dual-protocol middleware that combines history processing with tool interception.

Multiple Extras

You can install multiple extras at once:

Bash
uv add summarization-pydantic-ai[tiktoken,hybrid]
Bash
pip install summarization-pydantic-ai[tiktoken,hybrid]

Environment Setup

API Key

summarization-pydantic-ai uses Pydantic AI which supports multiple model providers. Set your API key:

Bash
export OPENAI_API_KEY=your-api-key
Bash
export ANTHROPIC_API_KEY=your-api-key
Bash
export GOOGLE_API_KEY=your-api-key

Verify Installation

Python
import asyncio
from pydantic_ai import Agent
from pydantic_ai_summarization import create_summarization_processor, __version__

print(f"summarization-pydantic-ai version: {__version__}")

async def main():
    processor = create_summarization_processor(
        trigger=("messages", 50),
        keep=("messages", 10),
    )

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

    result = await agent.run("Hello!")
    print(f"Agent response: {result.output}")

asyncio.run(main())

Troubleshooting

Import Errors

If you get import errors, ensure you have the correct Python version:

Bash
python --version  # Should be 3.10+

API Key Not Found

Make sure your API key is set in the environment:

Bash
echo $OPENAI_API_KEY

pydantic-ai Not Found

Ensure pydantic-ai is installed:

Bash
pip install pydantic-ai
# or
uv add pydantic-ai

Next Steps