GEPA AI Optimization Framework

Warnings

• breaking Version 0.1.0 introduced `optimize_anything` as a new, universal API for optimizing any text-representable artifact, including code and agent architectures. While `gepa.optimize` remains a valid entry point for prompt optimization, users migrating from pre-0.1.0 versions or seeking more general text optimization should consult the `optimize_anything` documentation.
  Fix: For new projects or general text optimization, consider using `from gepa.optimize_anything import optimize_anything`. For prompt optimization, `gepa.optimize` is still directly available and commonly used in examples.
• gotcha GEPA requires Python versions 3.10 or later, but strictly less than 3.15. Using incompatible Python versions will lead to installation or runtime errors.
  Fix: Ensure your Python environment meets the requirement of `>=3.10, <3.15`. Use tools like `pyenv` or `conda` to manage Python versions if needed.
• gotcha GEPA relies on LiteLLM for LLM interactions. You must set appropriate API keys for your chosen LLM provider (e.g., `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`) as environment variables before running optimizations.
  Fix: Set your LLM provider's API key as an environment variable (e.g., `export OPENAI_API_KEY='your_key_here'`). Refer to LiteLLM documentation for a complete list of supported providers and their respective environment variables.
• gotcha Optimization runs, especially with large `max_metric_calls` or slower LLMs, can be time and resource-intensive. For initial experiments, reduce `max_metric_calls` (e.g., to 50), use faster task models, or reduce the training set size (e.g., to 20-30 examples).
  Fix: Start with `max_metric_calls=50` or lower. Use faster, cheaper LLMs for `task_lm` and `reflection_lm` during development. Consider reducing the size of your `trainset` for quick iteration.

Install

• pip install gepa Core package
• pip install gepa[full] With experiment tracking (MLflow, WandB) and dataset utilities

Imports

• optimize

  import gepa
  ...
  gepa.optimize(...)

  The primary prompt optimization API is accessed via `gepa.optimize` after importing the top-level `gepa` package. Direct import `from gepa import optimize` might not work or is not the documented pattern.
• optimize_anything

  from gepa.optimize_anything import optimize_anything

  Introduced in v0.1.0 as GEPA's universal API for optimizing any text-representable artifact. Can also be imported as `import gepa.optimize_anything as oa`.

Quickstart

This quickstart optimizes a system prompt for math problems using GEPA's built-in AIME dataset. It demonstrates how to initialize a seed prompt and run the `gepa.optimize` function, which leverages LLM-based reflection to iteratively improve the prompt. Ensure relevant LLM API keys are set as environment variables (e.g., `OPENAI_API_KEY`) as GEPA uses LiteLLM.

import gepa
import os

# Set your LLM API key as an environment variable (e.g., in your shell or .env file)
# export OPENAI_API_KEY='your_openai_key_here'
# GEPA uses LiteLLM, supporting many providers. Adjust 'task_lm' and 'reflection_lm' accordingly.

# Load the AIME math dataset (built-in example)
trainset, valset, _ = gepa.examples.aime.init_dataset()

# Start with a basic prompt
seed_prompt = {
    "system_prompt": "You are a helpful assistant. Answer the question. "
    "Put your final answer in the format '### <answer>'"
}

# Optimize the prompt
# Ensure OPENAI_API_KEY or relevant API key is set in environment
result = gepa.optimize(
    seed_candidate=seed_prompt,
    trainset=trainset,
    valset=valset,
    task_lm=os.environ.get('GEPA_TASK_LM', 'openai/gpt-4o-mini'), # Model being optimized
    reflection_lm=os.environ.get('GEPA_REFLECTION_LM', 'openai/gpt-4o-mini'), # Model that generates improvements
    max_metric_calls=10 # Reduced for quick demo
)

print("\nOptimized prompt:", result.best_candidate['system_prompt'])
# Expected result shows improved accuracy (e.g., 46.6% -> 56.6% on AIME 2025 with GPT-4.1 Mini in full runs)