{"id":2044,"library":"gepa","title":"GEPA AI Optimization Framework","description":"GEPA (Genetic-Pareto) is a Python framework for optimizing textual system components like AI prompts, code snippets, and agent architectures. It employs LLM-based reflection and Pareto-efficient evolutionary search to improve performance against any evaluation metric. The library, currently at version 0.1.1, has an active development cadence with frequent releases, with recent focus on a universal API for optimizing any text parameter and enhanced visualization tools.","status":"active","version":"0.1.1","language":"en","source_language":"en","source_url":"https://github.com/gepa-ai/gepa","tags":["llm","optimization","prompt engineering","ai","pareto","evolutionary algorithms","code optimization","agent systems","reflection"],"install":[{"cmd":"pip install gepa","lang":"bash","label":"Core package"},{"cmd":"pip install gepa[full]","lang":"bash","label":"With experiment tracking (MLflow, WandB) and dataset utilities"}],"dependencies":[{"reason":"Required Python version range.","package":"python","version":"<3.15,>=3.10"},{"reason":"Handles LLM API calls to 100+ providers. Included with `gepa[full]` or can be installed separately.","package":"litellm","optional":true},{"reason":"Dataset loading utilities. Included with `gepa[full]`.","package":"datasets","optional":true},{"reason":"Experiment tracking. Included with `gepa[full]`.","package":"mlflow","optional":true},{"reason":"Weights & Biases integration. Included with `gepa[full]`.","package":"wandb","optional":true},{"reason":"Progress bars. Included with `gepa[full]`.","package":"tqdm","optional":true}],"imports":[{"note":"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.","wrong":"from gepa import optimize","symbol":"optimize","correct":"import gepa\n...\ngepa.optimize(...)"},{"note":"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`.","symbol":"optimize_anything","correct":"from gepa.optimize_anything import optimize_anything"}],"quickstart":{"code":"import gepa\nimport os\n\n# Set your LLM API key as an environment variable (e.g., in your shell or .env file)\n# export OPENAI_API_KEY='your_openai_key_here'\n# GEPA uses LiteLLM, supporting many providers. Adjust 'task_lm' and 'reflection_lm' accordingly.\n\n# Load the AIME math dataset (built-in example)\ntrainset, valset, _ = gepa.examples.aime.init_dataset()\n\n# Start with a basic prompt\nseed_prompt = {\n    \"system_prompt\": \"You are a helpful assistant. Answer the question. \"\n    \"Put your final answer in the format '### <answer>'\"\n}\n\n# Optimize the prompt\n# Ensure OPENAI_API_KEY or relevant API key is set in environment\nresult = gepa.optimize(\n    seed_candidate=seed_prompt,\n    trainset=trainset,\n    valset=valset,\n    task_lm=os.environ.get('GEPA_TASK_LM', 'openai/gpt-4o-mini'), # Model being optimized\n    reflection_lm=os.environ.get('GEPA_REFLECTION_LM', 'openai/gpt-4o-mini'), # Model that generates improvements\n    max_metric_calls=10 # Reduced for quick demo\n)\n\nprint(\"\\nOptimized prompt:\", result.best_candidate['system_prompt'])\n# Expected result shows improved accuracy (e.g., 46.6% -> 56.6% on AIME 2025 with GPT-4.1 Mini in full runs)","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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).","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}