Metadata-Version: 2.3
Name: gepa-adk
Version: 2.1.0
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 using genetic algorithms and Pareto frontier selection.

Supports single-agent evolution, multi-agent co-evolution, workflow optimization (Sequential, Loop, Parallel agents), output schema evolution, generation config tuning, and multimodal inputs including video.

## Requirements

- Python 3.12+
- [Ollama](https://ollama.ai) with a local model (recommended for development), or any model supported by [LiteLLM](https://docs.litellm.ai/)

## Installation

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

```bash
# For local models (recommended)
export OLLAMA_API_BASE=http://localhost:11434
```

## Quick Start

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

```python
from google.adk.agents import LlmAgent
from google.adk.models.lite_llm import LiteLlm
from gepa_adk import evolve, run_sync, EvolutionConfig, SimpleCriticOutput

model = LiteLlm(model="ollama_chat/llama3.2:latest")

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

critic = LlmAgent(
    name="critic",
    model=model,
    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="ollama_chat/llama3.2:latest",
)
result = run_sync(evolve(agent, trainset, critic=critic, config=config))
print(f"Score: {result.original_score:.2f} -> {result.final_score:.2f}")
print(result.evolved_components["instruction"])
```

## Examples

**Getting started:**

- [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) — Story generation with dedicated critic
- [custom_reflection_prompt.py](https://github.com/Alberto-Codes/gepa-adk/blob/HEAD/examples/custom_reflection_prompt.py) — Custom reflection prompts

**Multi-agent & workflows:**

- [multi_agent.py](https://github.com/Alberto-Codes/gepa-adk/blob/HEAD/examples/multi_agent.py) — Multi-agent co-evolution
- [loop_agent_evolution.py](https://github.com/Alberto-Codes/gepa-adk/blob/HEAD/examples/loop_agent_evolution.py) — LoopAgent workflow evolution
- [parallel_agent_evolution.py](https://github.com/Alberto-Codes/gepa-adk/blob/HEAD/examples/parallel_agent_evolution.py) — ParallelAgent workflow evolution
- [nested_workflow_evolution.py](https://github.com/Alberto-Codes/gepa-adk/blob/HEAD/examples/nested_workflow_evolution.py) — Nested workflow evolution

**Advanced:**

- [schema_evolution_example.py](https://github.com/Alberto-Codes/gepa-adk/blob/HEAD/examples/schema_evolution_example.py) — Output schema evolution
- [config_evolution_demo.py](https://github.com/Alberto-Codes/gepa-adk/blob/HEAD/examples/config_evolution_demo.py) — Generation config evolution
- [video_transcription_evolution.py](https://github.com/Alberto-Codes/gepa-adk/blob/HEAD/examples/video_transcription_evolution.py) — Video input evolution
- [app_runner_integration.py](https://github.com/Alberto-Codes/gepa-adk/blob/HEAD/examples/app_runner_integration.py) — ADK App/Runner integration

## 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)
