Optimize With Environments

[[endpoint]]
endpoint_id = "my-proxy"
model = "gpt-4.1-mini"
url = "https://api.example/v1"
key = "OPENAI_API_KEY"
headers = { "X-Custom-Header" = "value" }

Core Workflow

1. Verify baseline first with prime eval run. Keep the default save behavior and do not add --skip-upload unless the user explicitly requests that deviation:

prime eval run my-env -m gpt-4.1-mini -n 50 -r 3 -s

2. Run GEPA:

prime gepa run my-env -m gpt-4.1-mini -M gpt-4.1-mini -B 500 -n 100 -N 50

3. Or run from config:

prime gepa run configs/gepa/wordle.toml

4. Re-evaluate with optimized prompt and compare against baseline.

High-Value Settings

1. -B/--max-calls: total optimization budget.
2. -n/--num-train and -N/--num-val: train/validation split sizes.
3. --minibatch-size: reflection granularity.
4. --perfect-score: skip already-solved minibatches when max score is known.
5. --state-columns: include environment-specific context in reflection data.

Output Artifacts

Expect and inspect:

1. best_prompt.txt
2. pareto_frontier.jsonl
3. metadata.json

Quality Rules

1. Do not optimize on top of broken reward logic.
2. For weak deterministic checks, fix rubric quality before GEPA tuning.
3. Keep model, sampling, and dataset conditions stable during baseline-vs-GEPA comparison.
4. Report limitations directly when feature gaps block requested optimization.

Deliverable

Return:

1. Baseline metrics.
2. Optimized metrics.
3. Prompt diff summary.
4. Recommendation to adopt, iterate, or stop.