### Install GEPA from PyPI

Source: https://github.com/gepa-ai/gepa/blob/main/docs/docs/guides/quickstart.md

Installs the GEPA package using pip.

```bash
pip install gepa
```

--------------------------------

### GEPA DefaultAdapter Example

Source: https://github.com/gepa-ai/gepa/blob/main/docs/docs/guides/quickstart.md

Demonstrates how to use GEPA's DefaultAdapter for optimizing prompts in single-turn LLM tasks. It shows the expected format for training data and how to run the optimization process.

```python
import gepa

# The DefaultAdapter expects each example as a TypedDict with three fields:
#   input               — the user question
#   additional_context  — dict of extra context (can be empty {})
#   answer              — the expected answer (used for substring match)
trainset = [
    {"input": "What is 2+2?", "additional_context": {}, "answer": "4"},
    {"input": "What is the capital of France?", "additional_context": {}, "answer": "Paris"},
    # ... more examples
]

# Define your seed prompt
seed_prompt = {
    "system_prompt": "You are a helpful assistant. Answer questions concisely."
}

# Run optimization
result = gepa.optimize(
    seed_candidate=seed_prompt,
    trainset=trainset,
    task_lm="openai/gpt-4o-mini",      # Model to optimize
    reflection_lm="openai/gpt-4o",      # Model for reflection
    max_metric_calls=50,                # Budget
)

# Get the optimized prompt and best score
print("Best prompt:", result.best_candidate['system_prompt'])
print("Best score:", result.val_aggregate_scores[result.best_idx])
```

--------------------------------

### Setup for Ollama

Source: https://github.com/gepa-ai/gepa/blob/main/src/gepa/adapters/mcp_adapter/README.md

Instructions to install Ollama and pull necessary models for local execution.

```bash
Install Ollama: https://ollama.com

# Pull models
ollama pull llama3.1:8b
ollama pull llama3.2:1b
```

--------------------------------

### Setup environment with uv

Source: https://github.com/gepa-ai/gepa/blob/main/docs/docs/guides/contributing.md

Recommended installation method using the uv package manager to clone, sync, and verify the project.

```bash
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and setup
git clone https://github.com/gepa-ai/gepa
cd gepa
uv sync --extra dev --python 3.11

# Verify installation
uv run pytest tests/
```

--------------------------------

### Install Latest Development Version

Source: https://github.com/gepa-ai/gepa/blob/main/docs/docs/guides/quickstart.md

Installs the latest development version of GEPA directly from its GitHub repository.

```bash
pip install git+https://github.com/gepa-ai/gepa.git
```

--------------------------------

### Setup Environment for Circle Packing

Source: https://github.com/gepa-ai/gepa/blob/main/examples/circle_packing/README.md

Install the necessary dependencies and set up the virtual environment from the repository root.

```bash
uv venv
uv pip install -r examples/circle_packing/requirements.txt
uv pip install -e .
```

--------------------------------

### Install Dependencies

Source: https://github.com/gepa-ai/gepa/blob/main/examples/adrs/cloudcast/README.md

Installs the necessary Python packages for the Cloudcast example. Ensure you have the requirements.txt file in the specified path.

```bash
pip install -r examples/adrs/cloudcast/requirements.txt
```

```bash
pip install google-genai
```

--------------------------------

### Setup GEPA environment

Source: https://github.com/gepa-ai/gepa/blob/main/examples/blackbox/README.md

Install necessary dependencies including numpy, scipy, optuna, and scikit-learn from the repository root.

```bash
uv venv
uv pip install numpy scipy optuna scikit-learn
uv pip install -e .
```

--------------------------------

### Setup environment with conda and pip

Source: https://github.com/gepa-ai/gepa/blob/main/docs/docs/guides/contributing.md

Alternative installation method using conda for environment management and pip for package installation.

```bash
conda create -n gepa-dev python=3.11
conda activate gepa-dev
pip install -e ".[dev]"

# Verify installation
pytest tests/
```

--------------------------------

### Install GEPA and Jupyter

Source: https://github.com/gepa-ai/gepa/blob/main/docs/docs/tutorials/index.md

Commands to install GEPA with full dependencies and Jupyter, then start a Jupyter notebook server.

```bash
# Install GEPA with full dependencies
pip install gepa[full]

# Install Jupyter
pip install jupyter

# Start Jupyter
jupyter notebook
```

--------------------------------

### Logging and Tracking Configuration

Source: https://github.com/gepa-ai/gepa/blob/main/docs/docs/guides/quickstart.md

Illustrates how to enable logging and tracking for GEPA optimization runs using Weights & Biases, MLflow, and saving to disk.

```python
result = gepa.optimize(
    # ... other args ...
    use_wandb=True,                    # Log to Weights & Biases
    use_mlflow=True,                   # Log to MLflow
    run_dir="./gepa_runs/my_exp",      # Save state to disk
    display_progress_bar=True,         # Show progress
)
```

--------------------------------

### Run Terminal-bench Training Example

Source: https://github.com/gepa-ai/gepa/blob/main/src/gepa/adapters/terminal_bench_adapter/README.md

Install the terminal-bench package and execute this command to train the Terminus agent with the optimized system prompt. Ensure you have the necessary model name specified.

```bash
python src/gepa/examples/terminal-bench/train_terminus.py --model_name=gpt-5-mini
```

--------------------------------

### GEPA with DSPy Example

Source: https://github.com/gepa-ai/gepa/blob/main/docs/docs/guides/quickstart.md

Demonstrates how to integrate GEPA with DSPy for optimizing more complex programs. It highlights the importance of using a metric function that provides textual feedback.

```python
import dspy

# Configure the task LM
lm = dspy.LM("openai/gpt-4o-mini")
dspy.configure(lm=lm)

# Define your program
class QAProgram(dspy.Module):
    def __init__(self):
        self.generate = dspy.ChainOfThought("question -> answer")
    
    def forward(self, question):
        return self.generate(question=question)

# Define a metric WITH feedback - this is key for GEPA!
def metric_with_feedback(example, pred, trace=None):
    correct = example.answer.lower() in pred.answer.lower()
    score = 1.0 if correct else 0.0
    
    # Provide textual feedback to guide GEPA's reflection
    if correct:
        feedback = f"Correct! The answer '{pred.answer}' matches the expected answer '{example.answer}'."
    else:
        feedback = (
            f"Incorrect. Expected '{example.answer}' but got '{pred.answer}'. "
            f"Think about how to reason more carefully to arrive at the correct answer."
        )
    
    return dspy.Prediction(score=score, feedback=feedback)

# Prepare data (aim for 30-300 examples for best results)
trainset = [
    dspy.Example(question="What is 2+2?", answer="4").with_inputs("question"),
    dspy.Example(question="What is the capital of France?", answer="Paris").with_inputs("question"),
    # ... more examples
]

# Optimize with GEPA
optimizer = dspy.GEPA(
    metric=metric_with_feedback,
    reflection_lm=dspy.LM("openai/gpt-4o"),  # Strong model for reflection
    auto="light",  # Automatic budget configuration
    num_threads=8,
    track_stats=True,
)

optimized_program = optimizer.compile(QAProgram(), trainset=trainset)
```

--------------------------------

### Install Documentation Dependencies

Source: https://github.com/gepa-ai/gepa/blob/main/docs/README.md

Install the required Python packages for documentation using uv.

```bash
cd docs
uv pip install -r requirements.txt
```

--------------------------------

### View the optimized prompt

Source: https://github.com/gepa-ai/gepa/blob/main/docs/docs/guides/quickstart.md

Prints the optimized instructions generated by GEPA.

```python
print(optimized_program.generate.signature.instructions)
```

--------------------------------

### Setup Ollama for Local Models

Source: https://github.com/gepa-ai/gepa/blob/main/src/gepa/examples/rag_adapter/RAG_GUIDE.md

Install Ollama and pull the necessary models for RAG operations.

```bash
# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Pull models used in examples
ollama pull qwen3:8b
ollama pull llama3.1:8b
ollama pull nomic-embed-text:latest
```

--------------------------------

### Weaviate Vector Store Initialization

Source: https://github.com/gepa-ai/gepa/blob/main/src/gepa/adapters/generic_rag_adapter/GEPA_RAG.md

Examples for creating Weaviate vector stores, including local Docker setup and connection to Weaviate Cloud Services (WCS).

```python
from gepa.adapters.generic_rag_adapter import WeaviateVectorStore

# Local Weaviate instance
vector_store = WeaviateVectorStore.create_local(
    host="localhost",
    port=8080,
    collection_name="Documents"
)

# Weaviate Cloud Services (WCS)
vector_store = WeaviateVectorStore.create_cloud(
    cluster_url="https://your-cluster.weaviate.network",
    auth_credentials=weaviate.AuthApiKey("your-api-key"),
    collection_name="Documents"
)
```

--------------------------------

### Verify Qdrant Installation

Source: https://github.com/gepa-ai/gepa/blob/main/src/gepa/examples/rag_adapter/RAG_GUIDE.md

Check Qdrant client installation and install necessary dependencies.

```bash
python -c "import qdrant_client; print('Qdrant client OK')"
pip install litellm qdrant-client
```

--------------------------------

### Install RAG Adapter with Qdrant

Source: https://github.com/gepa-ai/gepa/blob/main/src/gepa/examples/rag_adapter/requirements-rag.txt

Install the common dependency and Qdrant client. Ensure litellm and qdrant-client are at the specified versions.

```bash
pip install litellm>=1.64.0 qdrant-client>=1.15.0
```

--------------------------------

### Full Example: Q&A Prompt Optimization with `claude -p`

Source: https://github.com/gepa-ai/gepa/blob/main/docs/docs/guides/claude-cli-as-proposer.md

A complete script demonstrating the setup and usage of `claude -p` as both the task and reflection LM within `gepa.optimize` for optimizing a Q&A prompt. Includes necessary imports, helper functions, a sample dataset, and optimization parameters.

```python
import subprocess
import gepa


def claude_cli_lm(prompt: str) -> str:
    result = subprocess.run(
        ["claude", "-p", prompt],
        capture_output=True, text=True, timeout=120,
    )
    if result.returncode != 0:
        raise RuntimeError(f"claude -p failed: {result.stderr}")
    return result.stdout


def claude_cli_chat(messages: list) -> str:
    parts = []
    for m in messages:
        if m["role"] == "system":
            parts.append(f"[System]\n{m['content']}")
        elif m["role"] == "user":
            parts.append(f"[User]\n{m['content']}")
    return claude_cli_lm("\n\n".join(parts))


dataset = [
    {"input": "What is 2+2?", "answer": "4", "additional_context": {}},
    {"input": "What is the capital of France?", "answer": "Paris", "additional_context": {}},
    {"input": "What color is the sky on a clear day?", "answer": "blue", "additional_context": {}},
]

result = gepa.optimize(
    seed_candidate={"instructions": "Answer the question correctly."},
    trainset=dataset,
    task_lm=claude_cli_chat,
    reflection_lm=claude_cli_lm,
    max_metric_calls=20,
    reflection_minibatch_size=1,
    display_progress_bar=True,
)

print(f"Best instructions: {result.best_candidate}")
print(f"Best score: {result.val_aggregate_scores[result.best_idx]:.3f}")
```

--------------------------------

### Complete Fitness Function Example

Source: https://github.com/gepa-ai/gepa/blob/main/docs/docs/guides/gskill.md

A simplified gskill fitness function demonstrating the full pattern, including Docker harness setup, agent execution, patch verification, and side info generation.

```python
from gepa.optimize_anything import optimize_anything, GEPAConfig, EngineConfig

def create_fitness_fn(model_name: str, n_workers: int):
    """Create a fitness function with a pool of Docker harnesses."""
    harness_pool = [SWEHarness() for _ in range(n_workers)]
    # ... pool management code ...

    def fitness_fn(candidate: dict[str, str], example: dict[str, Any]) -> tuple[float, dict]:
        skills = candidate["skills"]
        harness = get_available_harness()

        try:
            # 1. Setup Docker container with the task
            harness.setup_task(task_instance=example)

            # 2. Run the agent with current skills
            patch, trace, metrics = harness.run_agent(
                example["problem_statement"], skills, model_name=model_name
            )

            # 3. Verify the patch with tests
            passed, test_output = harness.verify_with_patch(patch)
            score = 1.0 if passed else 0.0

            # 4. Return score + diagnostic info for reflection
            side_info = {
                "Input": {"Problem": example["problem_statement"][:200]},
                "Generated Outputs": {"Patch": patch[:500], "Agent Trace": trace},
                "Feedback": {"Status": "passed" if passed else "failed", "Test Output": test_output},
                "scores": {"correctness": score},
            }
            return score, side_info

        finally:
            harness.cleanup()
            release_harness(harness)

    return fitness_fn

# Use it
fitness_fn = create_fitness_fn("gpt-5-mini", n_workers=6)

result = optimize_anything(
    seed_candidate={"skills": ""},
    evaluator=fitness_fn,
    dataset=train_data,
    valset=val_data,
    config=GEPAConfig(
        engine=EngineConfig(parallel=True, max_workers=6, max_metric_calls=600),
    ),
)
```

--------------------------------

### Install AnyMaths Adapter Requirements (uv)

Source: https://github.com/gepa-ai/gepa/blob/main/src/gepa/adapters/anymaths_adapter/README.md

Installs the necessary Python packages for the AnyMaths Adapter using uv. Ensure requirements.txt is present.

```bash
uv pip install -r src/gepa/adapters/anymaths_adapter/requirements.txt
```

--------------------------------

### Install All RAG Dependencies

Source: https://github.com/gepa-ai/gepa/blob/main/src/gepa/examples/rag_adapter/requirements-rag.txt

Install all RAG adapter dependencies by referencing the requirements-rag.txt file.

```bash
pip install -r requirements-rag.txt
```

--------------------------------

### Inspect Training Example

Source: https://github.com/gepa-ai/gepa/blob/main/docs/docs/tutorials/dspy_full_program_evolution.ipynb

Retrieves and prints the question and answer of the first example from the training set.

```python
example = dataset.train[0]
print("Question:", example.question)
print("Answer:", example.answer)
```

--------------------------------

### Install DSPy

Source: https://github.com/gepa-ai/gepa/blob/main/docs/docs/tutorials/index.md

Command to install DSPy for tutorials that specifically use it.

```bash
pip install dspy
```

--------------------------------

### Install GEPA and dependencies

Source: https://github.com/gepa-ai/gepa/blob/main/examples/confidence_adapter/README.md

Installs the GEPA library and necessary dependencies for running the confidence adapter benchmark. Ensure you are in the repository root.

```bash
uv venv
uv pip install -e ".[confidence]"
uv pip install datasets matplotlib scikit-learn python-dotenv
```

--------------------------------

### Install GEPA with full dependencies

Source: https://github.com/gepa-ai/gepa/blob/main/docs/docs/tutorials/index.md

Command to install GEPA with all its dependencies.

```bash
pip install gepa[full]
```

--------------------------------

### Install RAG Adapter with ChromaDB

Source: https://github.com/gepa-ai/gepa/blob/main/src/gepa/examples/rag_adapter/requirements-rag.txt

Install the common dependency and ChromaDB client. Ensure litellm and chromadb are at the specified versions.

```bash
pip install litellm>=1.64.0 chromadb>=0.4.0
```

--------------------------------

### Install gskill and Dependencies

Source: https://github.com/gepa-ai/gepa/blob/main/docs/docs/guides/gskill.md

Install the gskill package along with mini-swe-agent and swebench. Ensure you have Docker running and your OpenAI API key is set.

```bash
pip install gepa[gskill]
pip install mini-swe-agent swebench
```

```bash
export OPENAI_API_KEY=<your-key>

# Docker must be running
docker ps

# Download SWE-smith images for your target repo
python -m swesmith.build_repo.download_images
```

--------------------------------

### Install AnyMaths Adapter Requirements (pip)

Source: https://github.com/gepa-ai/gepa/blob/main/src/gepa/adapters/anymaths_adapter/README.md

Installs the necessary Python packages for the AnyMaths Adapter using pip. Ensure requirements.txt is present.

```bash
pip install -r src/gepa/adapters/anymaths_adapter/requirements.txt
```

--------------------------------

### Serve Documentation Locally

Source: https://github.com/gepa-ai/gepa/blob/main/docs/README.md

Start a local development server with live reloading.

```bash
uv run mkdocs serve
```

--------------------------------

### Build documentation locally

Source: https://github.com/gepa-ai/gepa/blob/main/docs/docs/guides/contributing.md

Steps to install documentation dependencies and serve the site locally.

```bash
cd docs
pip install -r requirements.txt
python scripts/generate_api_docs.py
mkdocs serve
```

--------------------------------

### Install Dependencies

Source: https://github.com/gepa-ai/gepa/blob/main/examples/adrs/can_be_late/README.md

Install the necessary Python packages for the GEPA repository and the specific example requirements.

```bash
pip install -e .
```

```bash
pip install -r examples/adrs/can_be_late/requirements.txt
```

```bash
pip install google-genai
```

--------------------------------

### Setup Weaviate

Source: https://github.com/gepa-ai/gepa/blob/main/src/gepa/examples/rag_adapter/RAG_GUIDE.md

Verify Weaviate meta endpoint and run the Docker container.

```bash
curl http://localhost:8080/v1/meta
docker run -p 8080:8080 -p 50051:50051 cr.weaviate.io/semitechnologies/weaviate:1.26.1
```

--------------------------------

### Set Up Environment with uv

Source: https://github.com/gepa-ai/gepa/blob/main/CONTRIBUTING.md

Use uv to synchronize dependencies and set up the Python environment. Specify the desired Python version.

```shell
uv sync --extra dev --python 3.11
```

--------------------------------

### Build Documentation for Production

Source: https://github.com/gepa-ai/gepa/blob/main/docs/README.md

Generate the static site files in the site/ directory.

```bash
uv run mkdocs build
```

--------------------------------

### Verify Installation with conda

Source: https://github.com/gepa-ai/gepa/blob/main/CONTRIBUTING.md

Run unit tests to verify the conda-based development environment setup.

```shell
pytest tests/
```

--------------------------------

### Install Dependencies

Source: https://github.com/gepa-ai/gepa/blob/main/AGENTS.md

Use uv to synchronize the project environment with development dependencies.

```bash
uv sync --extra dev
```

--------------------------------

### Run Optimization Example

Source: https://github.com/gepa-ai/gepa/blob/main/examples/adrs/can_be_late/README.md

Execute the optimization script with specified model and configuration parameters.

```bash
python examples/adrs/can_be_late/main.py --model <model_name>
```

```bash
python examples/adrs/can_be_late/main.py \
    --model gpt-4o-mini \
    --max-traces 10 \
    --max-metric-calls 20
```

```bash
python examples/adrs/can_be_late/main.py \
    --model gpt-4o \
    --max-metric-calls 100
```

--------------------------------

### GEPAResult object attributes

Source: https://github.com/gepa-ai/gepa/blob/main/docs/docs/guides/quickstart.md

Explains the attributes of the GEPAResult object, which contains the results of the optimization process.

```python
result.best_candidate                          # the optimized text components (or str when seed was a str)
result.best_idx                                # int — index of the best candidate
result.val_aggregate_scores                    # list[float] — per-candidate average validation score
result.val_aggregate_scores[result.best_idx]   # float — best score
result.candidates                              # list of all explored candidates
result.per_val_instance_best_candidates        # dict mapping val_id -> set of candidates on the Pareto frontier
result.total_metric_calls                      # int — total evaluation calls used
result.run_dir                                 # str | None — run directory if one was set
```

--------------------------------

### General optimize_anything Usage

Source: https://github.com/gepa-ai/gepa/blob/main/docs/docs/blog/posts/2026-02-18-introducing-optimize-anything/index.md

A basic example of using the `optimize_anything` function. Replace `<your artifact>` with your starting code or description and `your_evaluator` with your custom evaluation function.

```python
import gepa.optimize_anything as oa

result = oa.optimize_anything(
    seed_candidate="<your artifact>",
    evaluator=your_evaluator,
)
```

--------------------------------

### Configure environment and download images

Source: https://github.com/gepa-ai/gepa/blob/main/src/gepa/gskill/README.md

Set the necessary API keys and download the required SWE-smith Docker images.

```bash
export OPENAI_API_KEY=<your-key>

# Docker must be running
docker ps

# Download SWE-smith images for target repo
python -m swesmith.build_repo.download_images
```

--------------------------------

### Stop Conditions Configuration

Source: https://github.com/gepa-ai/gepa/blob/main/docs/docs/guides/quickstart.md

Demonstrates how to configure stop conditions for the GEPA optimization process, such as maximum metric calls, timeout, and no improvement.

```python
from gepa import MaxMetricCallsStopper, TimeoutStopCondition, NoImprovementStopper

result = gepa.optimize(
    # ... other args ...
    max_metric_calls=100,                          # Stop after 100 evaluations
    stop_callbacks=[
        TimeoutStopCondition(timeout_seconds=3600),  # Or after 1 hour
        NoImprovementStopper(max_iterations_without_improvement=10),         # Or after 10 iterations without improvement
    ],
)
```

--------------------------------

### Qdrant Vector Store Initialization

Source: https://github.com/gepa-ai/gepa/blob/main/src/gepa/adapters/generic_rag_adapter/GEPA_RAG.md

Examples for creating Qdrant vector stores, covering in-memory, local persistent storage, and remote server connections.

```python
from gepa.adapters.generic_rag_adapter import QdrantVectorStore

# In-memory (default, no setup required)
vector_store = QdrantVectorStore.create_memory("documents")

# Local persistent storage
vector_store = QdrantVectorStore.create_local("./qdrant_db", "documents")

# Remote Qdrant server
vector_store = QdrantVectorStore.create_remote(
    host="localhost", port=6333, collection_name="documents"
)
```

--------------------------------

### optimize_anything with Richer Feedback

Source: https://github.com/gepa-ai/gepa/blob/main/docs/docs/guides/quickstart.md

Shows how to provide richer feedback from the evaluator function in `optimize_anything` by returning a tuple of (score, side_info_dict). This allows for more detailed diagnostics.

```python
def evaluate(candidate: str) -> tuple[float, dict]:
    result = run_my_system(candidate)
    return result.score, {
        "Error": result.stderr,
        "Output": result.stdout,
    }
```

--------------------------------

### Initialize Supported Vector Stores

Source: https://github.com/gepa-ai/gepa/blob/main/src/gepa/adapters/generic_rag_adapter/GEPA_RAG.md

Examples of how to initialize different vector store implementations for use with the GenericRAGAdapter.

```python
# ChromaDB (local development, no Docker required)
vector_store = ChromaVectorStore.create_local("./kb", "docs")

# Weaviate (production with hybrid search, Docker required)
vector_store = WeaviateVectorStore.create_local(
    host="localhost", port=8080, collection_name="KnowledgeBase"
)

# Qdrant (high performance, Docker optional)
vector_store = QdrantVectorStore.create_local("./qdrant_db", "KnowledgeBase")

# Milvus (cloud-native, uses Milvus Lite by default)
vector_store = MilvusVectorStore.create_local("KnowledgeBase")

# LanceDB (serverless, no Docker required)
vector_store = LanceDBVectorStore.create_local("./lancedb", "KnowledgeBase")

# Same optimization pipeline works with all!
```

--------------------------------

### Candidate Selection Strategies Configuration

Source: https://github.com/gepa-ai/gepa/blob/main/docs/docs/guides/quickstart.md

Shows different strategies for selecting candidates during the GEPA optimization process, including Pareto frontier, current best, and epsilon-greedy.

```python
result = gepa.optimize(
    # ... other args ...
    candidate_selection_strategy="pareto",      # Default: sample from Pareto frontier
    # candidate_selection_strategy="current_best",  # Always use best candidate
    # candidate_selection_strategy="epsilon_greedy", # Explore vs exploit
)
```

--------------------------------

### Milvus Vector Store Initialization

Source: https://github.com/gepa-ai/gepa/blob/main/src/gepa/adapters/generic_rag_adapter/GEPA_RAG.md

Examples for creating Milvus vector stores, demonstrating Milvus Lite for local use and connection to a full Milvus server.

```python
from gepa.adapters.generic_rag_adapter import MilvusVectorStore

# Milvus Lite (local SQLite-based, no Docker required)
vector_store = MilvusVectorStore.create_local("documents")

# Full Milvus server (Docker required)
vector_store = MilvusVectorStore.create_remote(
    uri="http://localhost:19530", collection_name="documents"
)
```

--------------------------------

### GEPA Configuration Example

Source: https://github.com/gepa-ai/gepa/blob/main/docs/docs/guides/faq.md

Example of how to configure GEPA's runtime and budget using GEPAConfig and EngineConfig, including custom stop conditions.

```python
from gepa.optimize_anything import GEPAConfig, EngineConfig
from gepa.utils import TimeoutStopCondition, NoImprovementStopper

config = GEPAConfig(
    engine=EngineConfig(max_metric_calls=200),
    stop_callbacks=[
        TimeoutStopCondition(timeout_seconds=3600),
        NoImprovementStopper(max_iterations_without_improvement=10),
    ],
)
```

--------------------------------

### optimize_anything Basic Usage

Source: https://github.com/gepa-ai/gepa/blob/main/docs/docs/guides/quickstart.md

Illustrates the basic usage of the `optimize_anything` API, which can optimize any text artifact. It requires a custom evaluator function that returns a score and optionally diagnostic feedback.

```python
import gepa.optimize_anything as oa
from gepa.optimize_anything import optimize_anything, GEPAConfig, EngineConfig

def evaluate(candidate: str) -> float:
    """Score a candidate and log diagnostics as ASI."""
    result = run_my_system(candidate)
    oa.log(f"Output: {result.output}")
    oa.log(f"Error: {result.error}")
    return result.score

result = optimize_anything(
    seed_candidate="<your initial artifact>",
    evaluator=evaluate,
    objective="Describe what you want to optimize for.",
    config=GEPAConfig(engine=EngineConfig(max_metric_calls=100)),
)

print("Best candidate:", result.best_candidate)
```

--------------------------------

### Define DSPy Signature for Matrix Transformation Code Generation

Source: https://github.com/gepa-ai/gepa/blob/main/src/gepa/examples/dspy_full_program_evolution/arc_agi.ipynb

This signature is used to guide a language model in generating a Python function that transforms matrices. It specifies the input format (JSON of training examples and test input shapes) and the desired output (a Python function string).

```python
import dspy
from typing import List
import pydantic
import json
import traceback
import copy

# Define the type for a matrix, which is a list of lists of integers.
MATRIX = List[List[int]]

# Define a Pydantic model for a single training example, containing an input and output matrix.
class TrainingExample(pydantic.BaseModel):
    input: MATRIX
    output: MATRIX

# This signature defines the code generation sub-task. It's highly detailed to guide the LM.
class GenerateTransformerCode(dspy.Signature):
    """
    Analyze pairs of input/output matrices to deduce the transformation logic.
    Then, generate a self-contained Python function that implements this logic.

    Successful strategies:
    - Carefully observe the differences between input and output grids. Look for patterns related to shapes, colors (numbers), positions, counts, and spatial relationships.
    - Common transformations include: moving objects, changing colors, filling areas, finding objects with unique properties (e.g., most isolated, largest area), and applying geometric rules (e.g., symmetry, rotation).
    - Formulate a clear, step-by-step hypothesis for the transformation rule before writing the code.

    Pitfalls to avoid:
    - Do not hardcode solutions for the specific examples. The function must be general enough to solve new test cases.
    - The generated code MUST define a single function named `transform_matrix`.
    - This function must take exactly one argument: `matrix` (a list of lists of integers).
    - It must return the transformed matrix (a list of lists of integers).
    - Do not include any code outside the function definition. Do not call the function.
    - Do not use external libraries like numpy or pandas. Standard Python libraries like 'copy' are acceptable.
    """
    examples_json: str = dspy.InputField(desc="A JSON string representing the list of training examples.")
    test_input_shapes: str = dspy.InputField(desc="A string describing the shapes of the test input matrices, e.g., '12x12, 10x10'.")
    python_code: str = dspy.OutputField(desc="A string containing a single Python function `transform_matrix(matrix)` that implements the task logic.")

```

--------------------------------

### Verify Milvus Installation

Source: https://github.com/gepa-ai/gepa/blob/main/src/gepa/examples/rag_adapter/RAG_GUIDE.md

Check PyMilvus installation and install necessary dependencies.

```bash
python -c "import pymilvus; print('PyMilvus OK')"
pip install litellm pymilvus
```

--------------------------------

### Basic Example

Source: https://github.com/gepa-ai/gepa/blob/main/docs/docs/index.md

A basic example demonstrating how to load a dataset, define a seed prompt, and run optimization with GEPA.

```python
import gepa

# Load your dataset
trainset, valset, _ = gepa.examples.aime.init_dataset()

# Define your initial prompt
seed_prompt = {"system_prompt": "You are a helpful assistant..."}

# Run optimization
result = gepa.optimize(
    seed_candidate=seed_prompt,
    trainset=trainset,
    valset=valset,
    task_lm="openai/gpt-4.1-mini",
    max_metric_calls=150,
    reflection_lm="openai/gpt-5",
)

print(result.best_candidate['system_prompt'])
```

--------------------------------

### Verify LanceDB Installation

Source: https://github.com/gepa-ai/gepa/blob/main/src/gepa/examples/rag_adapter/RAG_GUIDE.md

Check PyArrow installation and install necessary dependencies.

```bash
python -c "import pyarrow; print('PyArrow OK')"
pip install litellm lancedb pyarrow
```

--------------------------------

### Weaviate Setup and Usage

Source: https://github.com/gepa-ai/gepa/blob/main/src/gepa/examples/rag_adapter/RAG_GUIDE.md

Set up and run GEPA AI with Weaviate. Docker is required for Weaviate.

```bash
docker run -p 8080:8080 -p 50051:50051 cr.weaviate.io/semitechnologies/weaviate:1.26.1
```

```bash
curl http://localhost:8080/v1/meta
```

```bash
python rag_optimization.py --vector-store weaviate
```

```bash
python rag_optimization.py --vector-store weaviate --model gpt-4o-mini --max-iterations 10
```

```bash
python rag_optimization.py --vector-store weaviate --max-iterations 15
```

--------------------------------

### Quick Start: Local Models (Ollama)

Source: https://github.com/gepa-ai/gepa/blob/main/src/gepa/adapters/mcp_adapter/README.md

Configure an MCP server for local Ollama models and optimize tool descriptions. This option incurs no API costs as it runs entirely locally.

```python
import gepa
from gepa.adapters.mcp_adapter import MCPAdapter
from mcp import StdioServerParameters

# Configure MCP server
server_params = StdioServerParameters(
    command="npx",
    args=["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
)

# Create dataset
dataset = [
    {
        "user_query": "What's in the file notes.txt?",
        "tool_arguments": {"path": "/tmp/notes.txt"},
        "reference_answer": "Meeting at 3pm",
        "additional_context": {},
    },
    # ... more examples
]

# Create adapter with LOCAL Ollama models
adapter = MCPAdapter(
    server_params=server_params,
    tool_names=["read_file", "write_file", "list_files"],  # Multiple tools for selection
    task_model="ollama/llama3.2:1b",  # Local model via Ollama, replace with your model 
    metric_fn=lambda item, output: 1.0 if item["reference_answer"] in output else 0.0,
)

# Optimize with local models - no API costs!
result = gepa.optimize(
    seed_candidate={"tool_description": "Read the contents of a file"},
    trainset=dataset[:20],
    valset=dataset[20:],
    adapter=adapter,
    reflection_lm="ollama/llama3.1:8b",  # Larger local model for reflection replace with our choice 
    max_metric_calls=150,
)

print("Optimized tool description:", result.best_candidate["tool_description"])
# Total cost: $0.00 - runs 100% locally!
```

--------------------------------

### Augmented Example

Source: https://github.com/gepa-ai/gepa/blob/main/docs/docs/guides/faq.md

An example demonstrating how to augment training examples with explanations for better GEPA performance.

```python
dspy.Example(
    question="Is this email urgent?", 
    answer="Yes",
    explanation="The email mentions a deadline of 'end of day today' and uses words like 'critical' and 'ASAP', indicating urgency."
).with_inputs("question")
```

--------------------------------

### Quick Start: OpenAI API

Source: https://github.com/gepa-ai/gepa/blob/main/src/gepa/adapters/mcp_adapter/README.md

Optimize tool descriptions using OpenAI models. Ensure your OPENAI_API_KEY is set as an environment variable.

```python
# Same as above, but use OpenAI models
adapter = MCPAdapter(
    server_params=server_params,
    tool_names=["read_file", "write_file", "list_files"],  # Multiple tools for selection
    task_model="openai/gpt-4o-mini",  # OpenAI API,  replace with your model choice 
    metric_fn=lambda item, output: 1.0 if item["reference_answer"] in output else 0.0,
)

result = gepa.optimize(
    seed_candidate={"tool_description": "Read the contents of a file"},
    trainset=dataset[:20],
    valset=dataset[20:],
    adapter=adapter,
    reflection_lm="openai/gpt-5",  # OpenAI for reflection, replace with yout model choice 
    max_metric_calls=150,
)
```