feat: warn when max_metric_calls is below the budget floor (closes #375 partially)

[LakshyAAAgrawal]

Summary

Implements most of the proposals in #375 — the failure where a coding agent ran GEPA via /goal with max_metric_calls=8 against a 6-row valset, got exactly one proposal step, and reported "done" because the single accepted candidate happened to beat the baseline on external validation.

The root cause is that max_metric_calls is the only knob controlling iteration count, but the relationship between budget, valset size, and actual proposal depth is implicit and not surfaced. This PR makes both ends of the run loud about the problem without breaking any existing API.

What's added

API (no breaking changes)

• gepa.GEPABudgetWarning (subclass of UserWarning) — exported at the top level so callers can silence with the standard warnings.filterwarnings mechanism.
• Pre-flight check at the start of gepa.optimize: if
  max_metric_calls < len(valset) + 3 * (reflection_minibatch_size + len(valset)),
  warn with the recommended floor, the implied proposal count under the current budget, and a link to the new budget guide. Silent when no budget is set (custom stop_callbacks path) or when the valset loader doesn't expose __len__.
• Post-run summary: logs GEPA finished: N proposal(s) accepted over M metric call(s); final candidate pool size = K and warns again if fewer than 3 proposals were accepted — that's the exact num_candidates=2 symptom the reporting agent missed in its post-mortem.
• Docstring rewrite on max_metric_calls calling out that it's the only iteration knob.

Docs

• New docs/docs/guides/budget.md — Choosing max_metric_calls. Formula, a worked-example floor table for common configurations, how to read the warnings, how to silence them, how to diagnose retrospectively.
• New docs/docs/guides/coding-agents.md — Running GEPA inside autonomous coding agents. Includes a copy-paste prompt block users can drop into Claude Code / Codex /goal / Cursor agent mode.
• Quickstart admonition next to max_metric_calls=50 explaining why that value is on the low side and linking to the budget guide.
• New FAQ entry: "My GEPA run finished with only one proposal — what happened?"
• mkdocs nav entries for both new guides.

AGENTS.md

A new "Running GEPA from inside an autonomous loop" section. AGENTS.md is the file Claude Code / Codex / Cursor read first when they enter the repo, so the budget formula + verify-num_candidates + treat-GEPABudgetWarning-as-failure rules live there directly. Issue #375 was caused by an agent that didn't have this context — putting it in AGENTS.md fixes it at the source for any agent that operates inside this repo (and is exactly the kind of thing you asked about).

Tests

tests/test_budget_warnings.py — 18 tests covering: the floor formula, loader-length probing, pre-flight warning conditions (including silence cases for None budget / streaming loader / empty valset), post-run summary behavior (including the exact incident config of num_candidates=2), logger interaction, public re-export, and the warnings.filterwarnings silence/error round-trip. All pass locally.

Deferred from #375 (worth their own discussion)

You asked whether to do "all of these changes" — I picked the highest-leverage subset and left these out for follow-ups so this PR isn't trying to make too many design decisions at once:

• min_proposals parameter on optimize. A meaningful API addition (separate from max_metric_calls) that lets callers say "don't return until you've tried at least N proposals." Needs an interaction analysis with the existing stop_callbacks machinery and with composite stoppers — better as a focused PR.
• Making max_metric_calls non-default. Invasive backwards-compatibility change; the warning is the much lower-risk way to get the same effect.
• Standalone agent skill on agentskills.io. Yes, this is worth doing and you raised it explicitly — but it lives outside this repo. Happy to follow up with a separate skill manifest that wraps the prompt block from coding-agents.md and the budget formula. The AGENTS.md section in this PR handles the in-repo coverage; a skill would extend it to any agent invoking GEPA from outside the repo.

Test plan

• uv run pytest tests/test_budget_warnings.py — 18/18 pass
• uv run pytest tests/test_data_loader.py — no regression
• uv run ruff check src/gepa/api.py src/gepa/__init__.py tests/test_budget_warnings.py — clean
• uv run pyright src/gepa/api.py — 0 errors
• mkdocs serve and confirm the budget and coding-agents pages render in the Guides nav
• One manual gepa.optimize smoke run with max_metric_calls=8, valset_size=6 to confirm both warnings fire and the post-run summary line is logged

Linked issue

Closes #375 (partially — see "Deferred" section above for what's left for follow-ups).

🤖 Generated with Claude Code

[semanticdiff-com]

Review changes with  

Changed Files

File	Status
src/gepa/__init__.py	6% smaller
src/gepa/api.py	3% smaller
AGENTS.md	Unsupported file format
docs/docs/guides/budget.md	Unsupported file format
docs/docs/guides/coding-agents.md	Unsupported file format
docs/docs/guides/faq.md	Unsupported file format
docs/docs/guides/quickstart.md	Unsupported file format
docs/mkdocs.yml	0% smaller
tests/test_budget_warnings.py	0% smaller