pydantic-ai-gepa

GEPA-driven prompt optimization tools for pydantic-ai. The library wraps GEPA's reflective search so agent authors can iterate on prompts, signatures, and evaluation metrics without leaving the pydantic-ai ecosystem. This is heavily influenced by dspy. We've adapted their concept of a Signature to work with pydantic-ai's inputs / outputs.

This is still very much an experimental work in progress and depends on this PR awaiting to be merged to pydantic-ai: pydantic/pydantic-ai#2926.

Highlights

• High-level optimizer: optimize_agent_prompts coordinates training/validation datasets, scoring callbacks, and reflection-enabled candidate selection.
• Adapter layer: PydanticAIGEPAAdapter and SignatureAgent bridge GEPA's rollout interfaces with pydantic-ai agents and structured outputs.
• Caching + telemetry: Optional cache (CacheManager, create_cached_metric) and logging hooks keep optimization runs reproducible.

Quick Start

1. Install dependencies: uv sync --all-extras
2. Run the sentiment example: uv run python examples/classification.py
3. Inspect outputs under optimization_results/ to compare candidates and scores.

Project Layout

• Library code in src/pydantic_ai_gepa/ (runner, components, caching, signature helpers)
• Tests in tests/ mirroring module names; run with uv run pytest
• Examples in examples/ for end-to-end GEPA agent workflows

Contributing

See AGENTS.md for coding standards, test expectations, and pull request guidelines before opening changes.