Changelog¶

All notable changes to this project will be documented in this file.

This changelog is automatically generated by release-please.

2.8.0 (2026-10-22)¶

Features¶

• adapter: forward critic objective scores (2d51b89), closes #609

Bug Fixes¶

• api: honor evaluation concurrency limits (c9914ae), closes #608
• docs: exclude generated revision timestamps (aff8482), closes #603

Documentation¶

• api: align contracts with execution (8e74cd7), closes #604
• stoppers: bound the evaluation-cap overshoot by one iteration, not one batch (1facd4a)

2.7.7 (2026-10-21)¶

Documentation¶

• concepts: describe the engine's actual loop, acceptance rule and opt-in frontier (652177f), closes #540
• contributing: make the docstring templates pass docvet (bc9d371), closes #550
• glossary: match the critic feedback table and glossary shapes to the code (f6c16eb), closes #536
• guides: document merge, Pareto selection, objective scores and the other evolve() options (c70992b), closes #541
• multi-agent: match the group and workflow pages to evolve_group and evolve_workflow (bc8b73d), closes #537
• reference: fix stale counts, retired views, the retry contradiction and nav gaps (f6a851c), closes #542
• stoppers: list every StopReason and fix the evaluation-count wording (1ff2730), closes #538

2.7.6 (2026-10-21)¶

Bug Fixes¶

• utils: type the extracted field annotation as Any for pydantic 2.14 (fb67b19), closes #590

2.7.5 (2026-10-20)¶

Bug Fixes¶

• deps: bump certifi and pillow to clear uv audit advisories (97994d0)

2.7.4 (2026-10-20)¶

Bug Fixes¶

• deps: bump aiohttp and mcp to clear uv audit advisories (742115d)

Documentation¶

• reflection: drop the deprecation notice (0f5b620), closes #363

2.7.3 (2026-10-09)¶

Bug Fixes¶

• deps: bump cairosvg and multidict to clear uv audit advisories (#573) (36ad76a)

2.7.2 (2026-10-05)¶

Bug Fixes¶

• publish: attest the distributions before uv publish uploads them (#570) (3bcdaee), closes #567

2.7.1 (2026-10-01)¶

Bug Fixes¶

• publish: smoke-test the wheel by import now that the console script is gone (ac21107), closes #564

2.7.0 (2026-10-01)¶

Features¶

• domain: record rows_evaluated on every IterationRecord (1d9e407), closes #464
• engine: abort after repeated identical reflection errors (a41e7f3), closes #463
• engine: bound the error text on proposer.error_retry (c8bf301), closes #488
• engine: inspect a checkpoint without resuming (951aa31), closes #440

Bug Fixes¶

• adapters: count a non-raising failed multi-agent execution as failed (864029f), closes #411
• deps: bump pyjwt and urllib3 to clear uv-secure advisories (ca668d4), closes #479
• engine: feed RegressionStopper the latest iteration score (6952524), closes #555
• engine: report StopReason.PATIENCE for a patience stop (90deb34), closes #429
• executor: copy overridden LlmAgents with model_copy (afdf603), closes #500
• tests: fail the session when a configured live-model probe raises (0e171d4), closes #361

Documentation¶

• ci: document execution and cost guidance (49a7e28), closes #281
• contributing: add the docvet freshness rule and the staged recipe to the brief checklist (0de4f36), closes #523
• entry: use local model ids, the Python cap, the db extra and the full example list (ff1c6a7), closes #539
• policy: make the gate table and rule files state what the hooks run (4fc80f8), closes #553
• policy: write the Copilot blocker path into the PR cycle (bc6814f), closes #554
• triage: adopt the P1-P4 impact scale with fit, size and ready labels (9f5f6f1)
• workflow: define integration ownership (5aba46c), closes #470
• workflow: reconcile the delegation and agent workflow with the sister repos (9e3ca90), closes #477

Dependencies¶

• deps: raise the floors to google-adk 1.39.1 and litellm 1.84, and declare the db extra that DatabaseSessionService needs on ADK 2.x (ad202dd)
• deps: raise the pydantic floor to what google-adk requires (64f9ab9)

2.6.0 (2026-09-25)¶

Features¶

• api: let evolve() take a component registry so two rounds in one process keep their own handlers (2edc9ba), closes #451
• engine: add a proposal validator that skips a reflector answer instead of scoring it (cec4255), closes #452
• engine: count the reflection agent's token usage in the rollup under a reflection split (e995468), closes #428
• engine: skip the full trainset pass after a minibatch gate when the valset is separate (2d39886), closes #439

Bug Fixes¶

• api: return the engine's result from evolve() so its counters and token usage survive (078ff8e), closes #444
• engine: treat a LiteLLM connection error raised inside a RuntimeError as retryable (0dd92df), closes #450

2.5.1 (2026-09-25)¶

Bug Fixes¶

• engine: record the parent a proposal was mutated from, not a second selector draw (df24937), closes #431
• engine: retry a provider error from the reflection agent once, then skip the iteration (e40d189), closes #424
• engine: skip a reflection whose output was cut off at the token limit (f0b5800), closes #432
• executor: retry a transient sqlite lock from the session service instead of failing the row (ea860b3), closes #423

2.5.0 (2026-09-25)¶

Features¶

• components: evolve a caller-owned mapping of prompt strings held by a tool (5274ddc), closes #401
• domain: roll up the token usage the executor observed per iteration and per run (2710fe9), closes #339
• engine: checkpoint the run after each iteration and resume it from the file (d23d3ab), closes #340
• engine: gate each proposal on a seeded trainset minibatch before its full evaluation (088b1c8), closes #416
• engine: take the reflection timeout from EvolutionConfig and skip a timed-out reflection (85ca36a), closes #408
• scoring: pass the trajectory to scorers that declare it and add RequireToolScorer (fcb13d8), closes #415

Bug Fixes¶

• engine: record a schema-validation skip and re-check the stop conditions (fcbe62e), closes #397

2.4.0 (2026-09-25)¶

Features¶

• api: accept a BaseLlm instance as EvolutionConfig.reflection_model (e8bf45d), closes #395
• api: warn when a schema agent self-grades over a labelled trainset (4dbbbaf), closes #387
• engine: add the on_iteration callback to EvolutionConfig (b00f237), closes #134
• engine: cap the trials sent to the reflection prompt (6c70098), closes #394
• engine: give Candidate a stable short id for log correlation (fcd9f0c), closes #390
• engine: report the number of evaluations that raised (2d223cf), closes #393
• engine: skip evaluating a proposal identical to one already scored (e79f94f), closes #380

Bug Fixes¶

• engine: reject an evaluation_policy given without a candidate_selector (0f335a6), closes #388
• engine: retry an empty reflection once, then skip the iteration (e5b02c9), closes #392
• utils: serialise pydantic models nested in state output as JSON (b535184), closes #389

2.3.0 (2026-09-25)¶

Features¶

• api: accept a scorer= keyword on the three evolve entry points (5ea0608), closes #373
• api: export Scorer from the package root (d646875), closes #374
• scoring: add LabelAgreementScorer for labelled trainsets (11f7dbe), closes #377

Bug Fixes¶

• logging: keep import gepa_adk silent on stdout (b2a1dac), closes #375
• replace retiring Gemini model identifiers and guard the selection path (#365) (c1f6ab4)
• scoring: render a schema agent's state output as JSON for the critic (ad22fe2), closes #378

Performance¶

• engine: evaluate each candidate once when the valset is the trainset (e785b2c), closes #379

2.2.0 (2026-09-03)¶

Features¶

• adk: adopt google-adk 2.x with deprecation-warning bridge (d8f2dbd), closes #345 #336
• stoppers: add RegressionStopper with score decline detection (#316) (461155d)

Bug Fixes¶

• tests: relax flaky wall-clock budget in frontier performance test (a067450)

Documentation¶

• claude: repair corrupted Commands section in CLAUDE.md (a067450)

2.1.0 (2026-03-08)¶

Features¶

• scoring: add create_critic() preset factory with three MVP presets (#308) (ac59411)

Bug Fixes¶

• contracts: address code review findings in protocol contract tests (30d7deb)
• docs: correct broken API references in extension point guides (af20038)

Documentation¶

• contributing: add extension point guides for ComponentHandler and AgentProvider (#312) (af20038)
• docstrings: resolve all 41 docvet findings and upgrade to v1.11.0 (30d7deb)
• planning: add tech debt note for critic preset parallel dicts (ac59411)

2.0.0 (2026-03-07)¶

⚠ BREAKING CHANGES¶

• api: optional parameters for evolve(), evolve_group(), and evolve_workflow() are now keyword-only after positional required args. Callers passing optional args positionally will get TypeError.

Features¶

• api: add pre-flight validation enhancements (#299) (b019f7a)
• api: add universal sync wrapper and keyword-only signatures (#300) (0befe0a)
• domain: add default credential redaction keys to TrajectoryConfig (#304) (1cb9ef1)
• domain: add display methods and original_components to evolution results (#297) (66cc7a4)
• domain: add result serialization with to_dict/from_dict (6589a0b)
• domain: add StopReason enum and schema versioning to evolution results (536073a)
• engine: add graceful interrupt handling with partial results (#298) (e892fc0)
• engine: add mutation rationale capture to iteration records (#302) (151a89f)
• engine: add seed-based determinism for reproducible evolution (#301) (e1241dc)

Bug Fixes¶

• api: address code review findings for pre-flight validation (b019f7a)
• docs: correct MkDocs cross-references to scoring sub-package (e1b38e4)
• engine: remove misleading reasoning fallback and add integration (151a89f)
• test: strengthen interrupt test assertions and reduce duplication (e892fc0)

Documentation¶

• examples: fix runtime errors and audit all examples for 2.0 (#306) (3f0d526)
• fix broken imports, migrate evolve_sync, and update for 2.0 release (#305) (e1b38e4)

1.0.1 (2026-03-04)¶

Bug Fixes¶

• engine: correct stale docstrings from review of ty workaround (05b1e54)

Code Refactoring¶

• engine: eliminate all 7 ty type-narrowing workarounds (#274) (05b1e54)

1.0.0 (2026-03-04)¶

Features¶

• ci: add hexagonal boundary enforcement scripts and CI workflow (#261) (c0130cb)
• compat: lower ADK dependency floor to 1.20.0 with CI version matrix (#264) (0f26e57)
• ports: define EvolutionResultProtocol for unified result types (#259) (ff343ac)

Bug Fixes¶

• ci: add explicit target-branch and full bootstrap-sha (f4cf65b)
• ci: adopt TestPyPI staging publish pipeline (0cf9bac)
• ci: remove unsafe-best-match index strategy from smoke test (68afeea)
• release: guard fromJSON with short-circuit to prevent empty parse (#258) (7b930ef)

Code Refactoring¶

• adapters: reorganize into concern-based sub-packages (#255) (21f2951)
• arch: fix all 7 pre-existing hexagonal boundary violations (1e430ba)
• ports: split selector.py into one-Protocol-per-file modules (#253) (f8d900e)

Documentation¶

• architecture: add architecture and UX specifications (7f06990)
• epics: add Story 1B.6 trunk-based migration and 1.0.0 release (d081dd5)
• planning: add BMAD planning artifacts for gepa-adk (#252) (7f06990)
• research: add domain, market, and technical research (7f06990)
• sprint: add sprint planning artifacts (7f06990)
• sprint: add Story 1B.3 for ty type-check cleanup (#254) (9164e57)

Maintenance¶

• release: bootstrap release-please for 1.0.0 (b6bf54d)

0.3.5 (2026-01-28)¶

Bug Fixes¶

• api: propagate runner app_name to AgentExecutor (#240) (aa1102b), closes #239

0.3.4 (2026-01-27)¶

Features¶

• api: add multimodal input support for video files (#236) (d5f092e)

0.3.3 (2026-01-25)¶

Features¶

• api: add App/Runner pattern for evolution infrastructure integration (#232) (4ab4186)
• api: expose session_service parameter (#229) (0a7d64f)

Documentation¶

• audit static documentation for accuracy and consistency (#233) (3404b56)
• concepts: fix import paths and model patterns in code examples (3404b56)
• guides: rewrite single-agent, multi-agent, critic-agents, (3404b56)
• reference: fix StateGuard link path (3404b56)

0.3.2 (2026-01-24)¶

Features¶

• api: add round_robin flag to evolve_workflow() (#225) (7c97025), closes #214
• schema: add schema constraints for output schema evolution (#208) (505b2ab), closes #190
• workflow: preserve structure during evolution (#228) (62a210c)

Bug Fixes¶

• executor: add get-or-create session semantics (#222) (cb19b13)
• utils: return LAST final response in extract_final_output (#223) (25703f4)

Documentation¶

• concepts: add Diátaxis explanation section (#221) (643467d)

0.3.1 (2026-01-22)¶

Features¶

• engine: integrate stop_callbacks into AsyncGEPAEngine (#196) (#206) (50488e6)
• ports: add StopperProtocol for pluggable stop conditions (#198) (6a0c160)
• stoppers: add MaxEvaluationsStopper and FileStopper (#207) (86fcba7), closes #197
• stoppers: add SignalStopper for graceful Ctrl+C termination (#204) (2727d49), closes #194
• stoppers: implement CompositeStopper for combining stop conditions (#205) (f188ba9)
• stoppers: implement ScoreThresholdStopper (#203) (74c4be2)
• stoppers: implement TimeoutStopper (#192) (#200) (f44f605)

Bug Fixes¶

• tests: rename mock_ fixtures to test_ in multi-agent routing (#202) (9e1315a)

0.3.0 (2026-01-22)¶

⚠ BREAKING CHANGES¶

• adapter: evolve_group() now requires agents as dict[str, LlmAgent] instead of list[LlmAgent]. The evolved_components dict now uses qualified names (agent.component) instead of just agent names.

Features¶

• adapter: add per-agent component routing for multi-agent evolution (#178) (50bb4f3)
• adapter: implement per-agent trajectory extraction from SequentialAgent events (#187) (6a7b419), closes #46
• types: add multi-agent component addressing scheme (#176) (51a4469), closes #165

Bug Fixes¶

• adapter: wrap exceptions in EvaluationError per ADR-009 (#189) (10d0995)
• api: use component handlers for seed candidate building (#182) (ee01d04)
• api: wrap reflection_model with LiteLlm for non-native providers (#185) (6674885), closes #173
• tests: update assertions to use qualified component names (6674885)

Documentation¶

• adapter: clarify _build_pipeline execution flow (#183) (ac3317a)
• guides: add migration guide for multi-agent v0.3 API (50bb4f3)
• readme: streamline for lowest-friction usage (50bb4f3)

0.2.2 (2026-01-21)¶

Features¶

• handlers: add ComponentHandler protocol and registry for component management (#170) (bdd8489)
• handlers: add generate_content_config evolution support (#175) (e2472ac)
• reflection: add component-aware reflection with schema validation (#167) (31dd288), closes #83 #133
• utils: add validate_output_schema tool for reflection agents (31dd288)

Code Refactoring¶

• adapters: use ComponentHandler registry for candidate application (#174) (ebf219f)

Documentation¶

• guides: add schema evolution section to single-agent guide (31dd288)

0.2.1 (2026-01-20)¶

Features¶

• adapter: add unified AgentExecutor for consistent session management (#138) (bfa1fae)
• adapter: add unified executor to MultiAgentAdapter and evolve_group (#139) (8b042fb)
• adapters: standardize critic feedback schema with normalization (#160) (32e43e7), closes #141
• models: add evolved_components dictionary for multi-component tracking (#142) (a4eee45)
• schema: enable output_schema evolution as a component (#132) (9bfd3e3), closes #83
• tests: enhance contract tests for evolve_group() executor creation and logging (96faaef)

Bug Fixes¶

• api: wrap reflection model in LiteLlm for consistency (32e43e7)
• logging: standardize logger initialization to use name (#149) (1762b71)
• publish: update attestations action to use 'paths' instead of 'attestations' (aaf09d2)
• reflection: use REFLECTION_INSTRUCTION as default fallback (#158) (995287a)
• utils: add cross-platform encoding support for Windows consoles (#130) (75430c6)

Code Refactoring¶

• adapter: remove legacy execution paths and require AgentExecutor (#145) (9b8ebd9)
• reflection: deprecate direct LiteLLM reflection in favor of ADK agents (#151) (97b3819), closes #144
• reflection: remove deprecated LiteLLM reflection path (#156) (a4ef3cb)
• tests: consolidate MockAdapter variants into factory pattern (#153) (d4d4fc1), closes #147
• tests: consolidate MockScorer into shared fixture (#152) (af46a5c), closes #146
• tests: improve error message clarity in ADKAdapter reflection tests (5e2bb2a)
• trial-builder: consolidate trial-building logic into shared TrialBuilder class (#154) (a6567ef)

Documentation¶

• adr: document shared test utilities in ADR-005 (af46a5c)
• guides: add output schema evolution section to single-agent guide (9bfd3e3)

0.2.0 (2026-01-18)¶

⚠ BREAKING CHANGES¶

• engine: IterationRecord.instruction → component_text, EvolutionResult.evolved_instruction → evolved_component_text, MultiAgentEvolutionResult.evolved_instructions → evolved_components

Features¶

• docs: integrate mkdocs-ezglossary for cross-referenced glossary (#123) (8f01dac), closes #114
• engine: add ADK session state template substitution (#115) (d738b51)
• reflection: add ADK session state management for reflection agent (#128) (39baef5), closes #100

Bug Fixes¶

• tests: improve pytest marker and skip logic for external service tests (#126) (0b75304)

Code Refactoring¶

• api: fix line-too-long lint errors (055c8db)
• ci: replace deprecation detection workflow with pytest filterwarnings (#122) (b28cb17), closes #98
• docstrings: improve Note section clarity in changed files (d738b51)
• tests: clean up conftest.py warning handling (b28cb17)

Documentation¶

• contributing: add deprecation warning handling section (b28cb17)
• glossary: add ADK integration concepts and terminology scope (39baef5)
• index: add GEPA paper reference (8f01dac)
• reference: add glossary for terminology consistency (d738b51)
• security: add SECURITY.md (055c8db)

0.1.2 (2026-01-18)¶

Features¶

• engine: add ADK reflection agents with component_text/trials terminology (#101) (567a4ff)

Documentation¶

• update PR template to clarify scope formatting guidelines (116d8af)

0.1.1 (2026-01-17)¶

Features¶

• 032-reflection-prompt-config: add reflection_prompt configuration (#93) (ef9b369)
• adapters: wire reflection_model config to proposer (#92) (85eafbd)
• add changelog sections to release-please config (43326cd)
• add project management workflow documentation (a31ef68)
• ci: add maintainer guidance to issue templates (#91) (f92bcae)
• ci: add release-please for automated releases and changelogs (3c49646)
• utils: add shared extract_final_output utility for ADK event extraction (#96) (7f1d341)

Bug Fixes¶

• ensure 'include-component-in-tag' is set to false in release-please config (5760099)

Foundation (0.x Series)¶

The 0.x series established the core architecture and capabilities of gepa-adk:

• Hexagonal Architecture (ADR-000) — Clean separation into domain, ports, adapters, and engine layers with CI-enforced boundary checking
• Async-First Design (ADR-001) — All core APIs are async with sync wrappers only at the API surface
• Protocol-Based Ports — All interfaces use typing.Protocol with @runtime_checkable for structural subtyping
• Single-Agent Evolution — Evolve agent instructions, output schemas, and generation configs using training sets and scorers
• Multi-Agent Evolution — evolve_group() and evolve_workflow() for multi-agent and workflow topology evolution
• Pareto Frontier — Multi-objective optimization tracking across evolution runs
• ADK 1.20.0+ Compatibility — Supports google-adk 1.20.0 through latest with version-adaptive imports
• CI Quality Gates — Automated testing (85% coverage), type checking (ty), docstring coverage (interrogate + docvet), boundary enforcement, and protocol coverage
• 12 Architecture Decision Records — Documented design decisions across domain, testing, logging, and integration

For detailed version history, see individual release tags.