Metadata-Version: 2.3
Name: gepa-adk
Version: 1.0.1
Summary: Evolutionary optimization for Google ADK agents
Keywords: ai,agents,evolution,optimization,genetic-algorithm,prompt-engineering,adk,llm
Author: Alberto-Codes
Author-email: Alberto-Codes <alberto.codes.dev@gmail.com>
License: Apache-2.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Dist: google-adk>=1.20.0
Requires-Dist: litellm>=1.80.13
Requires-Dist: nest-asyncio>=1.6.0
Requires-Dist: structlog>=25.5.0
Maintainer: Alberto-Codes
Maintainer-email: Alberto-Codes <alberto.codes.dev@gmail.com>
Requires-Python: >=3.12, <3.14
Project-URL: Homepage, https://github.com/Alberto-Codes/gepa-adk
Project-URL: Documentation, https://alberto-codes.github.io/gepa-adk/
Project-URL: Repository, https://github.com/Alberto-Codes/gepa-adk
Project-URL: Issues, https://github.com/Alberto-Codes/gepa-adk/issues
Project-URL: Changelog, https://github.com/Alberto-Codes/gepa-adk/releases
Description-Content-Type: text/markdown

[![CI](https://img.shields.io/github/actions/workflow/status/Alberto-Codes/gepa-adk/tests.yml?branch=main)](https://github.com/Alberto-Codes/gepa-adk/actions/workflows/tests.yml)
[![Coverage](https://codecov.io/gh/Alberto-Codes/gepa-adk/graph/badge.svg)](https://codecov.io/gh/Alberto-Codes/gepa-adk)
[![PyPI](https://img.shields.io/pypi/v/gepa-adk)](https://pypi.org/project/gepa-adk/)
[![Python](https://img.shields.io/pypi/pyversions/gepa-adk)](https://pypi.org/project/gepa-adk/)
[![License](https://img.shields.io/pypi/l/gepa-adk)](https://github.com/Alberto-Codes/gepa-adk/blob/main/LICENSE)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![docs vetted](https://img.shields.io/badge/docs%20vetted-docvet-purple)](https://github.com/Alberto-Codes/docvet)

# gepa-adk

Evolutionary optimization for Google ADK agents.

## What is this?

`gepa-adk` evolves AI agent instructions automatically. Give it an agent and training examples, and it finds better prompts through iterative improvement.

## Installation

```bash
pip install gepa-adk
```

```bash
export GOOGLE_API_KEY=your-api-key  # or other ADK-supported model
```

## Quick Start

Evolve a greeting agent to produce formal, Dickens-style greetings:

```python
import asyncio
from google.adk.agents import LlmAgent
from gepa_adk import evolve, EvolutionConfig, SimpleCriticOutput

agent = LlmAgent(
    name="greeter",
    model="gemini-2.5-flash",
    instruction="Greet the user appropriately.",
)

critic = LlmAgent(
    name="critic",
    model="gemini-2.5-flash",
    instruction="Score for formal, Dickens-style greetings. 0.0-1.0.",
    output_schema=SimpleCriticOutput,
)

trainset = [
    {"input": "I am His Majesty, the King."},
    {"input": "I am your mother."},
    {"input": "I am a close friend."},
]

config = EvolutionConfig(
    max_iterations=5,
    patience=1,
    reflection_model="gemini-2.5-flash",  # Model for generating improvements
)
result = asyncio.run(evolve(agent, trainset, critic=critic, config=config))
print(f"Score: {result.original_score:.2f} -> {result.final_score:.2f}")
print(result.evolved_components["instruction"])
```

## Examples

- [basic_evolution.py](https://github.com/Alberto-Codes/gepa-adk/blob/HEAD/examples/basic_evolution.py) — Single agent with critic
- [critic_agent.py](https://github.com/Alberto-Codes/gepa-adk/blob/HEAD/examples/critic_agent.py) — Custom critic for stories
- [multi_agent.py](https://github.com/Alberto-Codes/gepa-adk/blob/HEAD/examples/multi_agent.py) — Multi-agent evolution

## Documentation

[Getting Started](https://alberto-codes.github.io/gepa-adk/getting-started/) · [Guides](https://alberto-codes.github.io/gepa-adk/guides/single-agent/) · [API Reference](https://alberto-codes.github.io/gepa-adk/reference/)

## Credits

Based on [GEPA](https://arxiv.org/abs/2507.19457) ([source](https://github.com/gepa-ai/gepa)). Built on [Google ADK](https://google.github.io/adk-docs/) ([source](https://github.com/google/adk-python)).

## License

[Apache 2.0](https://github.com/Alberto-Codes/gepa-adk/blob/HEAD/LICENSE)
