Metadata-Version: 2.5
Name: pydantic-gepa
Version: 0.1.1
Summary: GEPA adapters and optimization utilities for Pydantic AI and Pydantic Evals.
Project-URL: Documentation, https://vcoderun.github.io/pydantic-gepa/
Project-URL: Repository, https://github.com/vcoderun/pydantic-gepa
Project-URL: Changelog, https://github.com/vcoderun/pydantic-gepa/blob/main/CHANGELOG.md
License: Apache-2.0
License-File: LICENSE
Keywords: gepa,prompt-optimization,pydantic-ai,pydantic-evals
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: pydantic>=2.7
Requires-Dist: pyyaml>=6
Requires-Dist: rich>=13
Requires-Dist: typing-extensions>=4.12
Provides-Extra: dev
Requires-Dist: basedpyright; extra == 'dev'
Requires-Dist: gepa<0.2,>=0.1.4; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pydantic-ai>=0.1.0; extra == 'dev'
Requires-Dist: pydantic-evals>=0.1.0; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-asyncio; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: rich>=13; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: ty; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocstrings-python; extra == 'docs'
Requires-Dist: zensical; extra == 'docs'
Provides-Extra: examples
Requires-Dist: gepa[full]<0.2,>=0.1.4; extra == 'examples'
Requires-Dist: logfire>=3; extra == 'examples'
Requires-Dist: pydantic-ai>=0.1.0; extra == 'examples'
Requires-Dist: pydantic-evals>=0.1.0; extra == 'examples'
Requires-Dist: python-dotenv>=1; extra == 'examples'
Provides-Extra: integrations
Requires-Dist: gepa<0.2,>=0.1.4; extra == 'integrations'
Requires-Dist: pydantic-ai>=0.1.0; extra == 'integrations'
Requires-Dist: pydantic-evals>=0.1.0; extra == 'integrations'
Provides-Extra: logfire
Requires-Dist: logfire>=3; extra == 'logfire'
Provides-Extra: optimize-anything
Requires-Dist: gepa[full]<0.2,>=0.1.4; extra == 'optimize-anything'
Requires-Dist: pydantic-ai>=0.1.0; extra == 'optimize-anything'
Requires-Dist: pydantic-evals>=0.1.0; extra == 'optimize-anything'
Provides-Extra: progress
Requires-Dist: rich>=13; extra == 'progress'
Description-Content-Type: text/markdown

# pydantic-gepa

`pydantic-gepa` provides a typed optimization runtime over GEPA, Pydantic AI,
and internally managed Pydantic Evals execution.

Full documentation: **https://vcoderun.github.io/pydantic-gepa/**

```python
from pydantic_gepa import AgentInstructionsInjection, Component, Example, optimize

instructions = Component(name="instructions", initial_text="Answer precisely.")

result = optimize(
    train=training_examples,
    validation=validation_examples,
    task=run_subject,
    score=score_subject,
    components=[instructions],
    injections=[
        AgentInstructionsInjection(agent=agent, candidate_component=instructions)
    ],
    reflection="openai:gpt-5-mini",
    budget=50,
)
```

The package starts with a Python API:

- typed GEPA candidate wrappers
- typed candidate component catalogs with include/exclude selection
- raw-text candidate values by default, with explicit JSON-string codecs when required
- candidate injection helpers for Pydantic AI agents
- generic candidate context/value injections for runtime schema or config overrides
- high-level `optimize(...)`, `Example`, and `Optimization.from_examples(...)` APIs that keep
  Pydantic Evals as internal runtime plumbing for common optimization flows
- synchronous or asynchronous task and score functions, plus built-in
  `model_field_accuracy(...)` helpers, with custom Pydantic Evals evaluators still available as
  an advanced escape hatch
- Pydantic Evals harness normalization
- score extraction from named evaluator scores
- `MetricResult(score, feedback, side_info)` for richer reflection signals
- reflective dataset construction for GEPA side information, case metadata, expected output,
  assertion failures, metric feedback, metric side info, success flags, and failure categories
- YAML-first candidate save/load helpers
- Pydantic-AI-compatible tool/output schema description component extraction
- Pydantic model field-description component extraction for structured outputs
- optional recorder hooks for higher-level systems and GEPA callback bridging
- deterministic sequential/grouped plans, typed events, Rich progress, and
  compatibility-checked checkpoint/resume
- a Click CLI over typed Python targets, without a second optimization DSL

Install with `uv`:

```bash
uv add pydantic-gepa
```

Or with `pip`:

```bash
pip install pydantic-gepa
```

Development setup:

```bash
uv sync --extra dev --extra integrations
make prod
```

Build the documentation with:

```bash
make docs
```

Serve it locally with:

```bash
make docs-serve
```

Run a configured Python target from the CLI:

```bash
pydantic-gepa my_app.optimization:pipeline inspect target
pydantic-gepa my_app.optimization:pipeline run --run-dir runs/demo
```

## Acknowledgements

`pydantic-gepa` builds on GEPA, Pydantic AI, and Pydantic Evals, and its design
has benefited from studying other open-source optimization integrations. See
[Acknowledgements And Design Influences](docs/acknowledgements.md) for explicit
credits, project relationships, and licensing boundaries.
