gepa-adk 0.2.0__tar.gz

gepa_adk-0.2.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.3
+Name: gepa-adk
+Version: 0.2.0
+Summary: Evolutionary optimization for Google ADK agents
+Keywords: ai,agents,evolution,optimization,genetic-algorithm,prompt-engineering,adk,llm
+Author: Alberto-Codes
+Author-email: Alberto-Codes <alberto.codes.dev@gmail.com>
+License: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: google-adk>=1.22.0
+Requires-Dist: litellm>=1.80.13
+Requires-Dist: nest-asyncio>=1.6.0
+Requires-Dist: structlog>=25.5.0
+Maintainer: Alberto-Codes
+Maintainer-email: Alberto-Codes <alberto.codes.dev@gmail.com>
+Requires-Python: >=3.12, <3.13
+Project-URL: Homepage, https://github.com/Alberto-Codes/gepa-adk
+Project-URL: Documentation, https://alberto-codes.github.io/gepa-adk/
+Project-URL: Repository, https://github.com/Alberto-Codes/gepa-adk
+Project-URL: Issues, https://github.com/Alberto-Codes/gepa-adk/issues
+Project-URL: Changelog, https://github.com/Alberto-Codes/gepa-adk/releases
+Description-Content-Type: text/markdown
+
+# gepa-adk
+
+Evolutionary optimization for Google ADK agents.
+
+## What is this?
+
+`gepa-adk` makes your AI agents better automatically. It takes an agent, runs it against examples, gets feedback, and evolves the agent's instructions until performance improves.
+
+Think of it as natural selection for AI prompts—the best instructions survive and improve.
+
+## Who is this for?
+
+Teams building AI agents with Google's Agent Development Kit (ADK) who want to:
+
+- Improve agent performance without manual prompt tweaking
+- Use structured feedback (not just pass/fail) to guide improvements
+- Evolve multiple agents working together
+- Get 3-5x faster optimization through parallel evaluation
+
+## Installation
+
+### Prerequisites
+
+Before installing gepa-adk, you need:
+
+1. **Python 3.12+**
+2. **Ollama** with the `gpt-oss:20b` model:
+   ```bash
+   # Install Ollama (if not already installed)
+   # Visit https://ollama.ai for installation instructions
+
+   # Pull the required model
+   ollama pull gpt-oss:20b
+   ```
+3. **Set environment variable**:
+   ```bash
+   export OLLAMA_API_BASE=http://localhost:11434
+   ```
+
+**Why gpt-oss:20b?** The evolutionary optimization engine uses this model internally to generate improved agent instructions. Without it, evolution will fail.
+
+**Why local models?** Evolutionary optimization makes many LLM calls per run (evaluating multiple candidates across iterations). We recommend Ollama with open-source models to avoid API costs and rate limits. However, gepa-adk works with any Google ADK-supported model (including Gemini) - just be aware of potential costs.
+
+### Install gepa-adk
+
+```bash
+pip install gepa-adk
+```
+
+**For development or if using uv:**
+
+```bash
+uv add gepa-adk
+```
+
+## Quick Start
+
+```python
+from pydantic import BaseModel, Field
+from google.adk.agents import LlmAgent
+from gepa_adk import evolve_sync
+
+class Output(BaseModel):
+    answer: str
+    score: float = Field(ge=0.0, le=1.0)
+
+agent = LlmAgent(name="assistant", model="gemini-2.0-flash",
+                 instruction="You are a helpful assistant.", output_schema=Output)
+trainset = [{"input": "What is 2+2?", "expected": "4"}]
+result = evolve_sync(agent, trainset)
+print(f"Evolved: {result.evolved_instruction}")
+```
+
+## Examples
+
+Complete working examples are available in the `examples/` directory:
+
+- **[basic_evolution.py](examples/basic_evolution.py)** — Simple greeting agent evolution with critic scoring
+- **[critic_agent.py](examples/critic_agent.py)** — Story generation with dedicated critic agent for evaluation
+- **[basic_evolution_adk_reflection.py](examples/basic_evolution_adk_reflection.py)** — Evolution using an ADK LlmAgent as the reflection agent
+
+All examples require Ollama with `gpt-oss:20b` model (see Prerequisites above).
+
+Run an example:
+```bash
+python examples/basic_evolution.py
+```
+
+## Documentation
+
+- [Getting Started Guide](https://alberto-codes.github.io/gepa-adk/getting-started/) — Step-by-step walkthrough from installation to first evolution
+- [Use Case Guides](https://alberto-codes.github.io/gepa-adk/guides/) — Patterns for single-agent, critic agents, multi-agent, and workflows
+- [API Reference](https://alberto-codes.github.io/gepa-adk/reference/) — Complete documentation for all public functions and classes
+
+## Troubleshooting
+
+### "Model not found" or "Connection refused" errors
+
+Ensure Ollama is running and the model is pulled:
+
+```bash
+# Check Ollama is running
+curl http://localhost:11434/api/tags
+
+# Pull the model if not present
+ollama pull gpt-oss:20b
+
+# Verify the model is available
+ollama list | grep gpt-oss
+```
+
+### Evolution is slow or uses too many iterations
+
+Adjust the `EvolutionConfig` parameters:
+
+```python
+from gepa_adk import EvolutionConfig
+
+config = EvolutionConfig(
+    max_iterations=3,  # Reduce iterations
+    patience=2,        # Stop early if no improvement
+)
+
+result = evolve_sync(agent, trainset, config=config)
+```
+
+### Want to use a different model?
+
+**For your agents:** You can use any model supported by Google ADK (Gemini, Ollama models, etc.). The examples use `ollama_chat/gpt-oss:20b` but you can change this to `gemini-2.0-flash` or other ADK-supported models.
+
+**For the evolution engine:** Currently, the reflection model is hardcoded to `ollama_chat/gpt-oss:20b`. Future versions will support custom model configuration. For now, ensure this model is available in your Ollama instance.
+
+**Cost warning:** Using cloud APIs like Gemini for agents during evolution can result in high costs due to the many evaluation calls required.
+
+## Status
+
+**In Development** — Not yet ready for production use.
+
+See [docs/proposals/](docs/proposals/) for technical design and roadmap.
+
+## Credits
+
+This project implements concepts from [GEPA](https://github.com/gepa-ai/gepa) (Genetic-Pareto optimization) and integrates with [Google ADK](https://github.com/google/adk-python).
+
+## License
+
+Apache License 2.0 - see [LICENSE](LICENSE) for details.

gepa_adk-0.2.0/README.md

@@ -0,0 +1,147 @@
+# gepa-adk
+
+Evolutionary optimization for Google ADK agents.
+
+## What is this?
+
+`gepa-adk` makes your AI agents better automatically. It takes an agent, runs it against examples, gets feedback, and evolves the agent's instructions until performance improves.
+
+Think of it as natural selection for AI prompts—the best instructions survive and improve.
+
+## Who is this for?
+
+Teams building AI agents with Google's Agent Development Kit (ADK) who want to:
+
+- Improve agent performance without manual prompt tweaking
+- Use structured feedback (not just pass/fail) to guide improvements
+- Evolve multiple agents working together
+- Get 3-5x faster optimization through parallel evaluation
+
+## Installation
+
+### Prerequisites
+
+Before installing gepa-adk, you need:
+
+1. **Python 3.12+**
+2. **Ollama** with the `gpt-oss:20b` model:
+   ```bash
+   # Install Ollama (if not already installed)
+   # Visit https://ollama.ai for installation instructions
+
+   # Pull the required model
+   ollama pull gpt-oss:20b
+   ```
+3. **Set environment variable**:
+   ```bash
+   export OLLAMA_API_BASE=http://localhost:11434
+   ```
+
+**Why gpt-oss:20b?** The evolutionary optimization engine uses this model internally to generate improved agent instructions. Without it, evolution will fail.
+
+**Why local models?** Evolutionary optimization makes many LLM calls per run (evaluating multiple candidates across iterations). We recommend Ollama with open-source models to avoid API costs and rate limits. However, gepa-adk works with any Google ADK-supported model (including Gemini) - just be aware of potential costs.
+
+### Install gepa-adk
+
+```bash
+pip install gepa-adk
+```
+
+**For development or if using uv:**
+
+```bash
+uv add gepa-adk
+```
+
+## Quick Start
+
+```python
+from pydantic import BaseModel, Field
+from google.adk.agents import LlmAgent
+from gepa_adk import evolve_sync
+
+class Output(BaseModel):
+    answer: str
+    score: float = Field(ge=0.0, le=1.0)
+
+agent = LlmAgent(name="assistant", model="gemini-2.0-flash",
+                 instruction="You are a helpful assistant.", output_schema=Output)
+trainset = [{"input": "What is 2+2?", "expected": "4"}]
+result = evolve_sync(agent, trainset)
+print(f"Evolved: {result.evolved_instruction}")
+```
+
+## Examples
+
+Complete working examples are available in the `examples/` directory:
+
+- **[basic_evolution.py](examples/basic_evolution.py)** — Simple greeting agent evolution with critic scoring
+- **[critic_agent.py](examples/critic_agent.py)** — Story generation with dedicated critic agent for evaluation
+- **[basic_evolution_adk_reflection.py](examples/basic_evolution_adk_reflection.py)** — Evolution using an ADK LlmAgent as the reflection agent
+
+All examples require Ollama with `gpt-oss:20b` model (see Prerequisites above).
+
+Run an example:
+```bash
+python examples/basic_evolution.py
+```
+
+## Documentation
+
+- [Getting Started Guide](https://alberto-codes.github.io/gepa-adk/getting-started/) — Step-by-step walkthrough from installation to first evolution
+- [Use Case Guides](https://alberto-codes.github.io/gepa-adk/guides/) — Patterns for single-agent, critic agents, multi-agent, and workflows
+- [API Reference](https://alberto-codes.github.io/gepa-adk/reference/) — Complete documentation for all public functions and classes
+
+## Troubleshooting
+
+### "Model not found" or "Connection refused" errors
+
+Ensure Ollama is running and the model is pulled:
+
+```bash
+# Check Ollama is running
+curl http://localhost:11434/api/tags
+
+# Pull the model if not present
+ollama pull gpt-oss:20b
+
+# Verify the model is available
+ollama list | grep gpt-oss
+```
+
+### Evolution is slow or uses too many iterations
+
+Adjust the `EvolutionConfig` parameters:
+
+```python
+from gepa_adk import EvolutionConfig
+
+config = EvolutionConfig(
+    max_iterations=3,  # Reduce iterations
+    patience=2,        # Stop early if no improvement
+)
+
+result = evolve_sync(agent, trainset, config=config)
+```
+
+### Want to use a different model?
+
+**For your agents:** You can use any model supported by Google ADK (Gemini, Ollama models, etc.). The examples use `ollama_chat/gpt-oss:20b` but you can change this to `gemini-2.0-flash` or other ADK-supported models.
+
+**For the evolution engine:** Currently, the reflection model is hardcoded to `ollama_chat/gpt-oss:20b`. Future versions will support custom model configuration. For now, ensure this model is available in your Ollama instance.
+
+**Cost warning:** Using cloud APIs like Gemini for agents during evolution can result in high costs due to the many evaluation calls required.
+
+## Status
+
+**In Development** — Not yet ready for production use.
+
+See [docs/proposals/](docs/proposals/) for technical design and roadmap.
+
+## Credits
+
+This project implements concepts from [GEPA](https://github.com/gepa-ai/gepa) (Genetic-Pareto optimization) and integrates with [Google ADK](https://github.com/google/adk-python).
+
+## License
+
+Apache License 2.0 - see [LICENSE](LICENSE) for details.

gepa_adk-0.2.0/pyproject.toml

@@ -0,0 +1,211 @@
+[project]
+name = "gepa-adk"
+version = "0.2.0"
+description = "Evolutionary optimization for Google ADK agents"
+readme = "README.md"
+license = { text = "Apache-2.0" }
+authors = [
+    { name = "Alberto-Codes", email = "alberto.codes.dev@gmail.com" }
+]
+maintainers = [
+    { name = "Alberto-Codes", email = "alberto.codes.dev@gmail.com" }
+]
+requires-python = ">=3.12,<3.13"
+dependencies = [
+    "google-adk>=1.22.0",
+    "litellm>=1.80.13",
+    "nest-asyncio>=1.6.0",
+    "structlog>=25.5.0",
+]
+keywords = [
+    "ai",
+    "agents",
+    "evolution",
+    "optimization",
+    "genetic-algorithm",
+    "prompt-engineering",
+    "adk",
+    "llm",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/Alberto-Codes/gepa-adk"
+Documentation = "https://alberto-codes.github.io/gepa-adk/"
+Repository = "https://github.com/Alberto-Codes/gepa-adk"
+Issues = "https://github.com/Alberto-Codes/gepa-adk/issues"
+Changelog = "https://github.com/Alberto-Codes/gepa-adk/releases"
+
+[project.scripts]
+gepa-adk = "gepa_adk:main"
+
+[build-system]
+requires = ["uv_build>=0.9.22,<0.10.0"]
+build-backend = "uv_build"
+
+# TestPyPI publishing index (for `uv publish --index testpypi`)
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true
+
+[tool.ruff]
+line-length = 88  # Formatter target
+target-version = "py312"
+exclude = [".uv-cache", ".venv", "__pycache__", "*.egg-info"]
+
+[tool.ruff.lint]
+# I = isort (import sorting), D = pydocstyle (docstrings), E501 = line length
+extend-select = ["E501", "I", "D"]
+
+[tool.ruff.lint.pycodestyle]
+max-line-length = 100  # Linter threshold (allow some flexibility)
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*.py" = ["S101"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["agent_workflow_suite"]
+
+[tool.ruff.format]
+quote-style = "double"
+docstring-code-format = true
+docstring-code-line-length = "dynamic"
+
+[tool.interrogate]
+verbose = 1
+fail-under = 95
+ignore-init-method = true
+ignore-init-module = true
+ignore-magic = true
+ignore-private = true
+exclude = ["tests", "scripts"]
+
+# Ty type checker configuration
+# ty is pre-release (0.0.1a33) with known limitations:
+# - SQLModel/SQLAlchemy Session.exec() not fully typed (shows Unknown | Session)
+# - pytest.MonkeyPatch.context() classmethod detection bug (false missing-argument errors)
+# These are false positives confirmed by 700+ passing tests
+[tool.ty.src]
+exclude = [
+    "scripts/",    # Utility scripts - not production code
+]
+
+# Override for test files - still type check but ignore pytest.MonkeyPatch.context() bug
+[[tool.ty.overrides]]
+include = ["tests/**"]
+
+[tool.ty.overrides.rules]
+# pytest.MonkeyPatch.context() is a classmethod but ty thinks it needs `cls` argument
+# This is a ty bug with pytest type stubs - all 88 errors are this same false positive
+missing-argument = "ignore"
+
+[tool.hatch.envs.default.scripts]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4.2",
+    "pytest-asyncio>=1.2.0",
+    "ty>=0.0.1a20",
+    "ruff>=0.13.0",
+    "pytest-xdist>=3.8.0",
+    "python-dotenv>=1.1.1",
+    "pytest-cov>=7.0.0",
+    "arize-phoenix-client",
+    "pytest-timeout>=2.4.0",
+    "pytest-profiling>=1.8.1",
+    "pytest-mock>=3.15.1",
+    "mkdocs-material>=9.7.1",
+    "mkdocstrings>=1.0.0",
+    "mkdocstrings-python>=2.0.1",
+    "mkdocs-gen-files>=0.5.0",
+    "mkdocs-literate-nav>=0.6.1",
+    "mkdocs-section-index>=0.3.9",
+    "mkdocs-git-revision-date-localized-plugin>=1.4.7",
+    "mkdocs-minify-plugin>=0.8.0",
+    "mkdocs-redirects>=1.2.1",
+    "mkdocs-glightbox>=0.4.0",
+    "mkdocs-macros-plugin>=1.3.7",
+    "pillow>=11.0.0",
+    "cairosvg>=2.7.1",
+    "interrogate>=1.7.0",
+    "griffe-warnings-deprecated>=1.1.0",
+    "griffe-inherited-docstrings>=1.1.2",
+    "mkdocs-ezglossary-plugin>=2.1.0",
+    "gepa>=0.0.24",
+    # Pin requests to avoid buggy 2.32.5 version (missing JSONDecodeError/Mapping in compat.py)
+    # See: https://github.com/psf/requests/issues/issues
+    "requests>=2.32.0,!=2.32.5",
+]
+
+[tool.pytest.ini_options]
+markers = [
+    "unit: Unit tests - fast, isolated",
+    "contract: Contract tests verifying interface compliance",
+    "integration: Integration tests with real databases",
+    "slow: Slow-running tests (execution, API calls)",
+    "api: Tests that make real API calls to external services (Gemini, Ollama, etc.) - excluded by default",
+    "requires_ollama: Tests requiring local Ollama service",
+    "requires_gemini: Tests requiring Gemini API (video, native planning)",
+]
+# Exclude API tests by default to avoid accidental quota usage
+addopts = "-m 'not api'"
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+# Deprecation warning strategy: treat all warnings as errors, explicitly ignore third-party issues.
+# Each ignored warning MUST have a tracking issue. See CONTRIBUTING.md for the full process.
+# Pattern: "ignore:message_regex:WarningClass:module_regex"
+filterwarnings = [
+    # Treat all warnings as errors by default - new warnings will fail CI
+    "error",
+    #
+    # === Third-party warning ignores (each with tracking issue) ===
+    #
+    # Pydantic v2 deprecation warnings from LiteLLM/ADK - Issue #118
+    # Upstream uses Pydantic v1 patterns; remove when they migrate to v2
+    "ignore:.*PydanticDeprecatedSince20.*:DeprecationWarning",
+    "ignore:.*Pydantic.*serialization.*:UserWarning",
+    "ignore:.*Pydantic.*serializer.*:UserWarning",
+    "ignore::UserWarning:pydantic.*",
+    "ignore:.*Pydantic.*:UserWarning",
+    "ignore:^deprecated$:DeprecationWarning:pydantic.*",  # Generic "deprecated" from pydantic internals
+    "ignore:^deprecated$:DeprecationWarning:google.adk.*",  # Pydantic deprecated field in ADK RunConfig - Issue #125
+    #
+    # Google genai SDK aiohttp subclassing - Issue #118 (bundled with Pydantic/ADK issues)
+    # google.genai._api_client subclasses aiohttp.ClientSession which is deprecated
+    "ignore:Inheritance class.*from ClientSession is discouraged:DeprecationWarning",
+    #
+    # ADK experimental feature warnings - Issue #119
+    # We intentionally use experimental ADK features (ADR-014); these are informational
+    "ignore:.*adk.*\\[EXPERIMENTAL\\].*:UserWarning",
+    "ignore:.*adk.*experimental.*:UserWarning",
+    #
+    # LiteLLM async cleanup warnings - Issue #120
+    # Known upstream bugs: https://github.com/BerriAI/litellm/issues/8831, #14276
+    "ignore:coroutine.*was never awaited:RuntimeWarning",
+    #
+    # Async test cleanup warnings (unclosed sockets/event loops) - Issue #120
+    # Common with async tests using LiteLLM/ADK; not actionable in test code
+    "ignore::ResourceWarning",
+    "ignore::pytest.PytestUnraisableExceptionWarning",
+    #
+    # Misc third-party async cleanup warnings - Issue #120
+    "ignore:.*tracemalloc.*:UserWarning",
+    "ignore:enable_cleanup_closed.*:DeprecationWarning",
+]

gepa_adk-0.2.0/src/gepa_adk/__init__.py

@@ -0,0 +1,157 @@
+"""GEPA-ADK: Async-first evolution engine for agentic development.
+
+This package provides domain models and utilities for evolving agent
+instructions using the GEPA (Generalized Evolutionary Prompt-programming
+Architecture) approach.
+
+Attributes:
+    __version__ (str): Package version from pyproject.toml.
+    EvolutionConfig (class): Configuration parameters for evolution runs.
+    EvolutionResult (class): Outcome of a completed evolution run.
+    Candidate (class): Instruction candidate being evolved.
+    IterationRecord (class): Metrics for a single evolution iteration.
+    Score (type): Type alias for normalized scores.
+    ComponentName (type): Type alias for component identifiers.
+    ModelName (type): Type alias for model identifiers.
+    TrajectoryConfig (class): Configuration for trajectory extraction.
+    EvolutionError (class): Base exception for all gepa-adk errors.
+    ConfigurationError (class): Raised when configuration validation fails.
+    AsyncGEPAAdapter (protocol): Async adapter protocol for evaluation.
+    EvaluationBatch (class): Evaluation results container for adapters.
+    DataInst (type): Type variable for adapter input instances.
+    Trajectory (type): Type variable for adapter traces.
+    RolloutOutput (type): Type variable for adapter outputs.
+
+Examples:
+    Basic usage with configuration and candidates:
+
+    ```python
+    from gepa_adk import EvolutionConfig, Candidate
+
+    config = EvolutionConfig(max_iterations=10, patience=3)
+    candidate = Candidate(components={"instruction": "Be helpful"})
+    ```
+
+    Configuring trajectory extraction:
+
+    ```python
+    from gepa_adk import TrajectoryConfig
+
+    trajectory_config = TrajectoryConfig(
+        redact_sensitive=True,
+        max_string_length=5000,
+    )
+    ```
+
+See Also:
+    - [`gepa_adk.domain`][gepa_adk.domain]: Core domain layer with models and types.
+    - [`gepa_adk.domain.models`][gepa_adk.domain.models]: Detailed model implementations.
+    - [`gepa_adk.domain.exceptions`][gepa_adk.domain.exceptions]: Exception hierarchy.
+
+Note:
+    This is the main entry point for the gepa-adk package. Domain models
+    are re-exported here for convenient top-level access.
+"""
+
+# Suppress Pydantic serializer warnings from ADK/LiteLLM dependencies
+# These are upstream issues (GH #81) and don't affect functionality
+import warnings
+
+warnings.filterwarnings(
+    "ignore",
+    message=".*Pydantic.*serializer.*",
+    category=UserWarning,
+)
+warnings.filterwarnings(
+    "ignore",
+    message=".*Pydantic.*serialization.*",
+    category=UserWarning,
+)
+
+# Version is read from installed package metadata
+try:
+    from importlib.metadata import version as _get_version
+
+    __version__ = _get_version("gepa-adk")
+except Exception:
+    # Fallback for development environments where package isn't installed
+    __version__ = "0.0.0.dev"
+
+from gepa_adk.adapters.component_selector import (  # noqa: E402
+    AllComponentSelector,
+    RoundRobinComponentSelector,
+    create_component_selector,
+)
+from gepa_adk.api import (  # noqa: E402
+    evolve,
+    evolve_group,
+    evolve_sync,
+    evolve_workflow,
+)
+from gepa_adk.domain import (  # noqa: E402
+    Candidate,
+    ComponentName,
+    ConfigurationError,
+    EvolutionConfig,
+    EvolutionError,
+    EvolutionResult,
+    FrontierType,
+    IterationRecord,
+    ModelName,
+    MultiAgentEvolutionResult,
+    Score,
+    TrajectoryConfig,
+)
+from gepa_adk.engine import AsyncGEPAEngine, MergeProposer  # noqa: E402
+from gepa_adk.ports import (  # noqa: E402
+    AsyncGEPAAdapter,
+    DataInst,
+    EvaluationBatch,
+    RolloutOutput,
+    Trajectory,
+)
+from gepa_adk.ports.selector import ComponentSelectorProtocol  # noqa: E402
+
+__all__ = [
+    # Version
+    "__version__",
+    # Models
+    "EvolutionConfig",
+    "EvolutionResult",
+    "MultiAgentEvolutionResult",
+    "Candidate",
+    "IterationRecord",
+    # Types
+    "Score",
+    "ComponentName",
+    "ModelName",
+    "FrontierType",
+    "TrajectoryConfig",
+    # Exceptions
+    "EvolutionError",
+    "ConfigurationError",
+    # Engine
+    "AsyncGEPAEngine",
+    "MergeProposer",
+    # Ports
+    "AsyncGEPAAdapter",
+    "EvaluationBatch",
+    "DataInst",
+    "Trajectory",
+    "RolloutOutput",
+    # Selectors
+    "ComponentSelectorProtocol",
+    "RoundRobinComponentSelector",
+    "AllComponentSelector",
+    "create_component_selector",
+    # API
+    "evolve",
+    "evolve_sync",
+    "evolve_group",
+    "evolve_workflow",
+]
+
+
+def main() -> None:
+    """Entry point for CLI invocation."""
+    print("Hello from gepa-adk!")