levi-evolve 0.1.0__py3-none-any.whl

levi/__init__.py

@@ -0,0 +1,124 @@
+"""
+Levi: Evolutionary optimization framework for algorithms.
+
+Simple usage::
+
+    import levi
+
+    result = levi.evolve_code(
+        "Optimize bin packing to minimize wasted space",
+        function_signature="def pack(items, bin_capacity):",
+        seed_program="def pack(items, bin_capacity): ...",
+        score_fn=my_scorer,
+        model="openai/gpt-4o-mini",
+        budget_dollars=5.0,
+    )
+
+Power users can pass any LeviConfig field as a keyword argument::
+
+    result = levi.evolve_code(
+        ...,
+        paradigm_model="openai/gpt-4o",
+        mutation_model="openai/gpt-4o-mini",
+        budget_dollars=10.0,
+        punctuated_equilibrium=levi.PunctuatedEquilibriumConfig(enabled=True),
+        pipeline=levi.PipelineConfig(n_llm_workers=8),
+    )
+"""
+
+# Core types
+# Behavior
+from .behavior import BehaviorExtractor, FeatureVector
+from .clients import LM, BaseClient, ClaudeCodeClient, ClientResult, CodexClient
+
+# Config types
+from .config import (
+    BehaviorConfig,
+    BudgetConfig,
+    CascadeConfig,
+    CVTConfig,
+    InitConfig,
+    LeviConfig,
+    LeviResult,
+    MetaAdviceConfig,
+    PipelineConfig,
+    PromptOptConfig,
+    ProxyBenchmarkConfig,
+    PunctuatedEquilibriumConfig,
+    SamplerModelPair,
+)
+from .core import EvaluationResult, MetricDict, Program
+
+# Methods
+from .methods import evolve_code, evolve_prompts
+
+# Protocols and pools
+from .pool import CVTMAPElitesPool, ProgramPool, SampleResult
+
+# Prompts
+from .prompts import (
+    OutputMode,
+    ProgramWithScore,
+    PromptBuilder,
+    PromptBundle,
+)
+
+# Selection
+from .selection import (
+    ComponentSelector,
+    RoundRobinComponentSelector,
+    StagnationComponentSelector,
+    UCBComponentSelector,
+    make_component_selector,
+)
+
+__version__ = "0.1.0"
+
+
+__all__ = [
+    # Core
+    "Program",
+    "EvaluationResult",
+    "MetricDict",
+    # Pool
+    "ProgramPool",
+    "SampleResult",
+    "CVTMAPElitesPool",
+    # Clients
+    "BaseClient",
+    "LM",
+    "ClientResult",
+    "CodexClient",
+    "ClaudeCodeClient",
+    # Prompts
+    "PromptBuilder",
+    "ProgramWithScore",
+    "OutputMode",
+    "PromptBundle",
+    # Selection
+    "ComponentSelector",
+    "UCBComponentSelector",
+    "RoundRobinComponentSelector",
+    "StagnationComponentSelector",
+    "make_component_selector",
+    # Behavior
+    "BehaviorExtractor",
+    "FeatureVector",
+    # Config types
+    "LeviConfig",
+    "LeviResult",
+    "BudgetConfig",
+    "SamplerModelPair",
+    "CVTConfig",
+    "InitConfig",
+    "MetaAdviceConfig",
+    "BehaviorConfig",
+    "CascadeConfig",
+    "PipelineConfig",
+    "PunctuatedEquilibriumConfig",
+    "PromptOptConfig",
+    "ProxyBenchmarkConfig",
+    # Methods
+    "evolve_code",
+    "evolve_prompts",
+]

levi/artifacts/__init__.py

@@ -0,0 +1,7 @@
+"""Internal artifact adapters."""
+
+from .base import ArtifactAdapter
+from .code import CodeAdapter, apply_diff
+from .prompt import PromptAdapter
+
+__all__ = ["ArtifactAdapter", "CodeAdapter", "PromptAdapter", "apply_diff"]

levi/artifacts/base.py

@@ -0,0 +1,80 @@
+"""Internal artifact adapter abstractions for Levi."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from ..clients.base import ClientSpec
+from ..core import Program
+from ..prompts import ProgramWithScore
+from ..utils import ResilientProcessPool
+
+
+class ArtifactAdapter(ABC):
+    """Internal boundary between the generic engine and an artifact domain."""
+
+    artifact_type: str = "artifact"
+
+    @abstractmethod
+    def make_program(self, content: str, metadata: dict[str, Any] | None = None) -> Program:
+        """Wrap raw artifact content into a Program."""
+
+    @abstractmethod
+    def snapshot_content(self, elite_data: Mapping[str, Any]) -> str:
+        """Extract canonical content from a serialized snapshot entry."""
+
+    @abstractmethod
+    async def evaluate(
+        self,
+        executor: ResilientProcessPool,
+        content: str,
+        *,
+        inputs: list[Any] | None = None,
+        timeout: float | None = None,
+    ) -> dict[str, Any]:
+        """Evaluate artifact content with the domain-specific harness."""
+
+    @abstractmethod
+    def build_mutation_prompt(
+        self,
+        parents: Sequence[ProgramWithScore],
+        *,
+        meta_advice: str | None = None,
+        model: ClientSpec | None = None,
+        use_diff: bool = False,
+    ) -> str:
+        """Build the main mutation prompt for the producer pipeline."""
+
+    @abstractmethod
+    def extract_candidate(
+        self,
+        response_text: str,
+        *,
+        parent_content: str | None = None,
+        use_diff: bool = False,
+    ) -> str | None:
+        """Extract candidate content from a model response."""
+
+    @abstractmethod
+    def build_diversity_prompt(self, existing_candidates: Sequence[tuple[str, float]]) -> str:
+        """Build the init-phase diversity prompt."""
+
+    @abstractmethod
+    def build_init_variant_prompt(self, parents: Sequence[ProgramWithScore]) -> str:
+        """Build the init-phase local-variation prompt."""
+
+    @abstractmethod
+    def build_paradigm_shift_prompt(
+        self,
+        representatives: Sequence[tuple[int, Any]],
+        *,
+        n_evaluations: int,
+        budget_progress: float = 0.0,
+    ) -> str:
+        """Build the punctuated-equilibrium paradigm prompt."""
+
+    @abstractmethod
+    def build_variant_prompt(self, base_content: str, base_score: float) -> str:
+        """Build a local-variation prompt around a paradigm-shift result."""

levi/artifacts/code.py

@@ -0,0 +1,231 @@
+"""Code artifact adapter for Levi's existing public API."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from ..clients.base import ClientSpec, client_name
+from ..config import LeviConfig
+from ..core import Program
+from ..equilibrium.prompts import PARADIGM_SHIFT_PROMPTS, VARIANT_GENERATION_PROMPT, get_budget_stage
+from ..prompts import OutputMode, ProgramWithScore, PromptBuilder
+from ..utils import ResilientProcessPool, evaluate_code, extract_code, extract_fn_name
+from .base import ArtifactAdapter
+
+DIVERSITY_SEED_PROMPT = """# {problem_title}
+
+## Problem
+{problem_description}
+
+## Function Signature
+```python
+{function_signature}
+```
+
+## Your Task: ALGORITHMIC DIVERSITY
+
+You MUST design a solution using a **FUNDAMENTALLY DIFFERENT ALGORITHM** than the existing seeds.
+
+**DO NOT:**
+- Make minor variations or parameter tweaks to existing approaches
+- Use the same core algorithm with different constants
+- Reorder or refactor existing logic
+
+**DO:**
+- Analyze what algorithmic paradigm each existing seed uses
+- Identify what aspects of the problem they exploit (or ignore)
+- Design from first principles using a completely different strategy
+- Think about what information in the problem they are NOT using
+- Consider entirely different ways to model or decompose the problem
+
+The goal is to explore different regions of the algorithm design space. A population of diverse algorithms will outperform a population of similar ones.
+
+## Existing Seeds (analyze their algorithms, then do something DIFFERENT):
+{existing_seeds}
+
+## Output
+Output ONLY the complete Python code in a ```python block.
+"""
+
+
+def apply_diff(original: str, diff_response: str) -> str | None:
+    """Apply SEARCH/REPLACE diff blocks to original code."""
+    result = original
+
+    pattern = r"<<<<<<< SEARCH\s*(.*?)\s*=======\s*(.*?)\s*>>>>>>> REPLACE"
+    matches = re.findall(pattern, diff_response, re.DOTALL)
+
+    if not matches:
+        return extract_code(diff_response)
+
+    for search, replace in matches:
+        search = search.strip()
+        replace = replace.strip()
+        if search in result:
+            result = result.replace(search, replace, 1)
+        else:
+            return None
+
+    return result
+
+
+class CodeAdapter(ArtifactAdapter):
+    """Adapter for Levi's existing code-evolution behavior."""
+
+    artifact_type = "code"
+
+    def __init__(self, config: LeviConfig):
+        self.config = config
+        self.fn_name = extract_fn_name(config.function_signature)
+
+    def make_program(self, content: str, metadata: dict[str, Any] | None = None) -> Program:
+        return Program(content=content, metadata=metadata or {})
+
+    def snapshot_content(self, elite_data: Mapping[str, Any]) -> str:
+        content = elite_data.get("content")
+        if isinstance(content, str):
+            return content
+
+        legacy_code = elite_data.get("code")
+        if isinstance(legacy_code, str):
+            return legacy_code
+
+        raise KeyError("content")
+
+    async def evaluate(
+        self,
+        executor: ResilientProcessPool,
+        content: str,
+        *,
+        inputs: list[Any] | None = None,
+        timeout: float | None = None,
+    ) -> dict[str, Any]:
+        return await executor.run(
+            evaluate_code,
+            content,
+            self.config.score_fn,
+            self.config.inputs if inputs is None else inputs,
+            self.fn_name,
+            timeout=self.config.pipeline.eval_timeout if timeout is None else timeout,
+        )
+
+    def build_mutation_prompt(
+        self,
+        parents: Sequence[ProgramWithScore],
+        *,
+        meta_advice: str | None = None,
+        model: ClientSpec | None = None,
+        use_diff: bool = False,
+    ) -> str:
+        builder = PromptBuilder()
+        builder.add_section("Problem", self.config.problem_description, priority=10)
+        builder.add_section("Signature", f"```python\n{self.config.function_signature}\n```", priority=20)
+        builder.add_parents(list(parents), priority=30)
+
+        mutation_overrides = self.config.prompt_overrides.get("mutation", {})
+        model_key = client_name(model) if model is not None else None
+        if model_key and model_key in mutation_overrides:
+            builder.set_custom_output(mutation_overrides[model_key])
+        else:
+            builder.set_output_mode(OutputMode.DIFF if use_diff else OutputMode.FULL)
+
+        if meta_advice:
+            builder.add_section("Meta-Advice", meta_advice, priority=100)
+
+        return builder.build()
+
+    def extract_candidate(
+        self,
+        response_text: str,
+        *,
+        parent_content: str | None = None,
+        use_diff: bool = False,
+    ) -> str | None:
+        if use_diff:
+            if parent_content is None:
+                raise ValueError("parent_content is required when use_diff=True")
+            return apply_diff(parent_content, response_text)
+        return extract_code(response_text)
+
+    def build_diversity_prompt(self, existing_candidates: Sequence[tuple[str, float]]) -> str:
+        existing_seeds_text = "\n\n---\n\n".join(
+            [
+                f"### Seed {idx + 1} (Score: {score:.17g}):\n```python\n{content}\n```"
+                for idx, (content, score) in enumerate(existing_candidates)
+            ]
+        )
+        prompt_template = self.config.init.diversity_prompt or DIVERSITY_SEED_PROMPT
+        return prompt_template.format(
+            problem_title="Algorithm Optimization",
+            problem_description=self.config.problem_description,
+            function_signature=self.config.function_signature,
+            existing_seeds=existing_seeds_text,
+        )
+
+    def build_init_variant_prompt(self, parents: Sequence[ProgramWithScore]) -> str:
+        builder = PromptBuilder()
+        builder.add_section("Problem", self.config.problem_description, priority=10)
+        builder.add_section("Signature", f"```python\n{self.config.function_signature}\n```", priority=20)
+        builder.add_parents(list(parents), priority=30)
+        builder.set_output_mode(OutputMode.FULL)
+        return builder.build()
+
+    def build_paradigm_shift_prompt(
+        self,
+        representatives: Sequence[tuple[int, Any]],
+        *,
+        n_evaluations: int,
+        budget_progress: float = 0.0,
+    ) -> str:
+        stage = get_budget_stage(budget_progress)
+
+        rep_text_parts = []
+        for idx, (cluster_id, elite) in enumerate(representatives):
+            score = elite.result.primary_score
+            content = elite.program.content
+            rep_text_parts.append(
+                f"### Region {idx + 1} (Cluster {cluster_id}, Score: {score:.17g})\n```python\n{content}\n```"
+            )
+
+        representative_solutions = "\n\n".join(rep_text_parts)
+
+        override = self.config.prompt_overrides.get("paradigm_shift")
+        if override:
+            return f"""# Algorithmic Paradigm Shift Challenge
+
+## Problem
+{self.config.problem_description}
+
+## Function Signature
+```python
+{self.config.function_signature}
+```
+
+## Current Best Solutions ({len(representatives)} regions, {n_evaluations} evaluations)
+
+{representative_solutions}
+
+## Your Task
+{override}
+
+Output ONLY complete, runnable Python code in a ```python block.
+"""
+
+        template = PARADIGM_SHIFT_PROMPTS[stage]
+        return template.format(
+            problem_description=self.config.problem_description,
+            function_signature=self.config.function_signature,
+            n_evaluations=n_evaluations,
+            n_regions=len(representatives),
+            representative_solutions=representative_solutions,
+        )
+
+    def build_variant_prompt(self, base_content: str, base_score: float) -> str:
+        return VARIANT_GENERATION_PROMPT.format(
+            problem_description=self.config.problem_description,
+            function_signature=self.config.function_signature,
+            base_code=base_content,
+            base_score=base_score,
+        )