API Reference¶

This reference documents all public APIs in gepa-adk.

Quick Navigation¶

Start here for most use cases:

Core Evolution Functions¶

• evolve() — Async single-agent evolution
• evolve_sync() — Sync single-agent evolution
• evolve_group() — Multi-agent co-evolution
• evolve_workflow() — Workflow agent evolution

Configuration & Results¶

• EvolutionConfig — Evolution parameters
• EvolutionResult — Single-agent results
• MultiAgentEvolutionResult — Multi-agent results
• TrajectoryConfig — Trajectory capture settings
• StateGuard — State token preservation

Module Organization¶

gepa-adk follows hexagonal architecture (see ADR-000):

Core Modules¶

• gepa_adk.api — Public API entry points (start here!)
• gepa_adk.domain — Core models, types, and exceptions

Advanced Modules¶

• gepa_adk.adapters — External integrations (ADK, multi-agent, workflows)
• gepa_adk.engine — Evolution orchestration and mutation
• gepa_adk.ports — Protocol interfaces for extensibility
• gepa_adk.utils — Helper utilities (state guard, trajectory extraction)

Detailed Documentation¶

For complete documentation of all modules, classes, and functions:

• Core API — Main evolution functions
• Domain Models — Data structures
• Configuration Types — Configuration and trajectory settings
• Exceptions — Exception hierarchy
• Full Module Index — Browse all modules

Common Use Cases¶

Single-agent evolution:

from gepa_adk import evolve_sync
result = evolve_sync(agent, trainset, critic=critic)

Multi-agent evolution:

from gepa_adk import evolve_group
result = await evolve_group(agents, primary="final_agent", trainset=trainset)

State token preservation:

from gepa_adk.utils import StateGuard
guard = StateGuard(state_keys=["conversation_id", "user_id"])
result = evolve_sync(agent, trainset, state_guard=guard)