+==================================================================================+
|                          IMBUE DARWINIAN EVOLVER                                  |
+==================================================================================+
|                                                                                   |
|  +----------------------------+       +-------------------------------------+     |
|  |     TASK INPUT             |       |     EVOLUTIONARY ENGINE             |     |
|  |  - Training pairs (I/O)   |       |                                     |     |
|  |  - Test input grid(s)     |------>|  1. INITIALIZATION                  |     |
|  +----------------------------+       |     - Seed population from LLM      |     |
|                                       |     - Random diverse programs       |     |
|  +----------------------------+       |                                     |     |
|  |     LLM POOL              |       |  2. EVALUATION                      |     |
|  |  - Claude 3.5 Sonnet      |       |     - Run programs on train pairs   |     |
|  |  - GPT-4o                 |       |     - Pixel-match fitness score     |     |
|  |  - DeepSeek               |       |                                     |     |
|  |  - Gemini                 |<----->|  3. SELECTION                       |     |
|  +----------------------------+       |     - Tournament selection          |     |
|                                       |     - Fitness-proportionate        |     |
|  +----------------------------+       |                                     |     |
|  |     DSL / PRIMITIVES      |       |  4. MUTATION (via LLM)             |     |
|  |  - Grid operations        |       |     - Code modification prompts     |     |
|  |  - Numpy/scipy helpers    |       |     - Error-guided repair           |     |
|  |  - Color transforms       |       |     - Crossover of parents         |     |
|  +----------------------------+       |                                     |     |
|                                       |  5. POPULATION MANAGEMENT          |     |
|                                       |     - Elitism (keep best)          |     |
|                                       |     - Diversity maintenance        |     |
|                                       |     - Population size control      |     |
|                                       |                                     |     |
|                                       |  6. TERMINATION                    |     |
|                                       |     - Perfect fitness found        |     |
|                                       |     - Budget exhausted             |     |
|                                       |     - Max generations reached      |     |
|                                       +-------------------------------------+     |
|                                                    |                              |
|                                                    v                              |
|                                       +-------------------------------------+     |
|                                       |     OUTPUT                          |     |
|                                       |  - Top-K programs                  |     |
|                                       |  - Predicted test output(s)       |     |
|                                       |  - 2 guesses per task             |     |
|                                       +-------------------------------------+     |
+==================================================================================+

Generation t                         Generation t+1
   +-----------+                        +-----------+
   | Program 1 |---fitness=0.8------+   | Program 1'|  (mutated from P1)
   | Program 2 |---fitness=0.4--+   |   | Program 4 |  (elite, kept)
   | Program 3 |---fitness=0.2  |   +-->| Program 5 |  (crossover P1xP4)
   | Program 4 |---fitness=0.9--+------>| Program 6 |  (mutated from P4)
   +-----------+    |           |       | Program 7 |  (new seed from LLM)
                    |           |       +-----------+
                    v           v
               SELECTED     ELIMINATED
            (tournament)   (low fitness)

darwinian_evolver/
+-- README.md                    # Setup and usage instructions
+-- requirements.txt             # Python dependencies
+-- config.yaml                  # Configuration (models, params)
+-- main.py                      # Entry point, orchestrates evolution
+-- evolver.py                   # Core evolutionary engine
+-- population.py                # Population management
+-- individual.py                # Individual program representation
+-- fitness.py                   # Fitness evaluation (grid comparison)
+-- mutation.py                  # LLM-based mutation operators
+-- selection.py                 # Selection strategies
+-- crossover.py                 # Crossover operators
+-- llm_client.py                # Multi-model LLM interface
+-- prompts/                     # Prompt templates
|   +-- seed_prompt.txt          # Initial program generation
|   +-- mutate_prompt.txt        # Mutation prompt template
|   +-- crossover_prompt.txt     # Crossover prompt template
|   +-- repair_prompt.txt        # Error-guided repair prompt
+-- utils/                       # Utility functions
|   +-- grid_utils.py            # Grid manipulation helpers
|   +-- arc_loader.py            # ARC task loading
|   +-- budget.py                # Cost tracking and budget control
+-- tests/                       # Test suite

class Mutator:
    def __init__(self, llm_client, prompts, config):
        self.llm = llm_client
        self.prompts = prompts
        self.config = config

    def mutate(self, individual, task, error_info=None):
        """Generate a mutated child from a parent individual."""
        # Build the mutation prompt with context
        prompt = self.build_mutation_prompt(
            parent_code=individual.code,
            task_examples=task.train_pairs,
            fitness=individual.fitness,
            error_info=error_info,
            predicted_outputs=individual.predictions,
            expected_outputs=task.expected_outputs
        )

        # Call LLM to generate mutated code
        response = self.llm.generate(
            prompt=prompt,
            temperature=self.config.mutation_temperature,  # typically 0.7-1.0
            max_tokens=self.config.max_code_tokens
        )

        # Extract code from LLM response
        mutated_code = self.extract_code(response)

        # Validate syntax before returning
        if self.is_valid_python(mutated_code):
            return Individual(
                code=mutated_code,
                generation=individual.generation + 1,
                parent_id=individual.id,
                mutation_type="guided"
            )
        return None  # Mutation failed, discard

def build_mutation_prompt(self, parent_code, task_examples,
                          fitness, error_info, predicted_outputs,
                          expected_outputs):
    """Build a detailed prompt for LLM-guided mutation."""
    prompt_parts = []

    # System context
    prompt_parts.append(
        "You are an expert Python programmer helping to evolve "
        "a program that transforms input grids to output grids. "
        "Your task is to modify the given program to improve its "
        "accuracy on the training examples."
    )

    # Task examples (input/output pairs)
    for i, (inp, out) in enumerate(task_examples):
        prompt_parts.append(f"Example {i+1}:")
        prompt_parts.append(f"Input:\n{self.grid_to_str(inp)}")
        prompt_parts.append(f"Expected Output:\n{self.grid_to_str(out)}")
        if predicted_outputs and i < len(predicted_outputs):
            prompt_parts.append(
                f"Current Program Output:\n"
                f"{self.grid_to_str(predicted_outputs[i])}"
            )

    # Current program
    prompt_parts.append(f"Current program (fitness={fitness:.3f}):")
    prompt_parts.append(f"```python\n{parent_code}\n```")

    # Error information if available
    if error_info:
        prompt_parts.append(f"The program produced this error:\n{error_info}")

    # Mutation instruction
    prompt_parts.append(
        "Please modify the program to better match the expected "
        "outputs. Focus on understanding the pattern in the "
        "input-output pairs and adjusting the logic accordingly. "
        "Return ONLY the modified Python function."
    )

    return "\n\n".join(prompt_parts)

def adaptive_temperature(self, fitness, gen, max_gen):
    """Compute mutation temperature based on fitness and progress."""
    # Base: high fitness -> low temperature (exploit)
    # Low fitness -> high temperature (explore)
    fitness_factor = 1.0 - fitness  # fitness in [0, 1]
    progress_factor = gen / max_gen  # how far along we are

    temperature = (
        self.config.temp_min +
        (self.config.temp_max - self.config.temp_min) *
        fitness_factor * (1.0 - 0.3 * progress_factor)
    )
    return max(self.config.temp_min, min(self.config.temp_max, temperature))

class TournamentSelection:
    def __init__(self, tournament_size=3):
        self.tournament_size = tournament_size

    def select(self, population, n_parents=1):
        """Select n_parents from population via tournament selection."""
        parents = []
        for _ in range(n_parents):
            # Sample k random individuals
            tournament = random.sample(population.individuals,
                                        min(self.tournament_size,
                                            len(population)))
            # Select the one with highest fitness
            winner = max(tournament, key=lambda ind: ind.fitness)
            parents.append(winner)
        return parents

class FitnessProportionateSelection:
    def select(self, population, n_parents=1):
        """Select parents with probability proportional to fitness."""
        fitnesses = [ind.fitness for ind in population.individuals]
        total = sum(fitnesses)
        if total == 0:
            # All zero fitness -- select uniformly
            return random.sample(population.individuals, n_parents)

        probabilities = [f / total for f in fitnesses]
        selected = random.choices(
            population.individuals,
            weights=probabilities,
            k=n_parents
        )
        return selected

def apply_elitism(population, n_elite=2):
    """Preserve the top n_elite individuals across generations."""
    sorted_pop = sorted(
        population.individuals,
        key=lambda ind: ind.fitness,
        reverse=True
    )
    return sorted_pop[:n_elite]

def scheduled_tournament_size(generation, max_generations,
                              min_k=2, max_k=5):
    """Increase tournament size over evolutionary run."""
    progress = generation / max_generations
    k = int(min_k + (max_k - min_k) * progress)
    return max(min_k, min(max_k, k))

from dataclasses import dataclass, field
from typing import List, Optional
import uuid

@dataclass
class Individual:
    """A candidate solution program."""
    code: str                        # Python source code of transform()
    fitness: float = 0.0             # Pixel-match accuracy [0, 1]
    generation: int = 0              # Which generation it was created
    id: str = field(default_factory=  # Unique identifier
                    lambda: str(uuid.uuid4())[:8])
    parent_id: Optional[str] = None # Parent's ID (None for seeds)
    mutation_type: str = "seed"      # How this individual was created
    error_info: Optional[str] = None # Runtime error if any
    predictions: List = field(       # Predicted outputs on train set
                  default_factory=list)
    model_used: str = ""             # Which LLM generated this
    cost: float = 0.0               # API cost to generate this
    code_hash: str = ""              # Hash for deduplication

class Population:
    """Manages the evolutionary population."""

    def __init__(self, max_size=20, elite_count=2):
        self.individuals: List[Individual] = []
        self.max_size = max_size
        self.elite_count = elite_count
        self.history: List[Individual] = []  # All ever created
        self.seen_hashes: set = set()   # For deduplication
        self.best_ever: Optional[Individual] = None

    def add(self, individual: Individual) -> bool:
        """Add individual if not duplicate. Returns success."""
        code_hash = hashlib.md5(
            individual.code.encode()
        ).hexdigest()
        if code_hash in self.seen_hashes:
            return False  # Duplicate, reject

        individual.code_hash = code_hash
        self.seen_hashes.add(code_hash)
        self.individuals.append(individual)
        self.history.append(individual)

        # Track best ever
        if (self.best_ever is None or
            individual.fitness > self.best_ever.fitness):
            self.best_ever = individual

        return True

    def cull(self):
        """Remove worst individuals to maintain population size."""
        if len(self.individuals) <= self.max_size:
            return

        # Sort by fitness descending
        self.individuals.sort(
            key=lambda ind: ind.fitness, reverse=True
        )

        # Keep elites + diverse selection of remainder
        elites = self.individuals[:self.elite_count]
        remainder = self.individuals[self.elite_count:]

        # From remainder, keep diverse subset
        kept = self.diverse_subset(
            remainder,
            self.max_size - self.elite_count
        )
        self.individuals = elites + kept

    def get_best(self, n=1) -> List[Individual]:
        """Return top-n individuals by fitness."""
        return sorted(
            self.individuals,
            key=lambda ind: ind.fitness,
            reverse=True
        )[:n]

Generation 0 (Seeding):
  LLM generates N diverse initial programs
  |
  v
Evaluate all -> Assign fitness scores
  |
  v
Generation 1..G (Evolution Loop):
  1. Select parents (tournament / proportionate)
  2. Mutate parents via LLM -> children
  3. Evaluate children -> fitness
  4. Add children to population
  5. Cull population to max_size (keep elites + diverse)
  6. Check termination (perfect fitness? budget? max gen?)
  |
  v
Final: Return top-2 programs for submission

import hashlib

def is_duplicate(code, seen_hashes):
    """Check if functionally identical code already exists."""
    # Normalize whitespace and comments for comparison
    normalized = normalize_code(code)
    h = hashlib.md5(normalized.encode()).hexdigest()
    return h in seen_hashes

def normalize_code(code):
    """Strip comments and normalize whitespace."""
    lines = []
    for line in code.split('\n'):
        stripped = line.strip()
        if stripped and not stripped.startswith('#'):
            lines.append(stripped)
    return '\n'.join(lines)

def behavioral_distance(ind_a, ind_b):
    """Compute behavioral distance between two individuals."""
    if not ind_a.predictions or not ind_b.predictions:
        return 1.0  # Max distance if no predictions

    distances = []
    for pred_a, pred_b in zip(ind_a.predictions, ind_b.predictions):
        if pred_a is None or pred_b is None:
            distances.append(1.0)
            continue
        # Pixel-wise comparison of predicted outputs
        a = np.array(pred_a)
        b = np.array(pred_b)
        if a.shape != b.shape:
            distances.append(1.0)
        else:
            distances.append(np.mean(a != b))
    return np.mean(distances)

def diverse_subset(self, candidates, n):
    """Select n diverse individuals using greedy farthest-first."""
    if len(candidates) <= n:
        return candidates

    # Start with highest fitness
    selected = [candidates[0]]
    remaining = candidates[1:]

    while len(selected) < n and remaining:
        # Pick individual most different from already selected
        best_candidate = None
        best_min_dist = -1

        for cand in remaining:
            min_dist = min(
                behavioral_distance(cand, sel)
                for sel in selected
            )
            if min_dist > best_min_dist:
                best_min_dist = min_dist
                best_candidate = cand

        selected.append(best_candidate)
        remaining.remove(best_candidate)

    return selected

def maybe_inject_fresh_seed(self, population, task, generation):
    """Periodically inject completely new programs."""
    if generation % self.config.immigration_interval == 0:
        fresh = self.mutator.generate_seed(task)
        if fresh:
            population.add(fresh)

class LLMClient:
    """Unified multi-model LLM interface."""

    def __init__(self, config):
        self.models = config.models  # List of model configs
        self.total_cost = 0.0
        self.model_stats = {}  # Track success rate per model

    def select_model(self, mutation_type, budget_remaining):
        """Select which model to use for this mutation."""
        if budget_remaining < self.config.low_budget_threshold:
            # Switch to cheapest model when budget is low
            return self.cheapest_model()

        if mutation_type == "strategy":
            # Use strongest model for strategic changes
            return self.strongest_model()

        # Default: rotate models for diversity
        return random.choice(self.models)

    def generate(self, prompt, model=None, temperature=0.8,
                 max_tokens=4096):
        """Generate completion from selected model."""
        if model is None:
            model = self.select_model("default", self.budget_remaining)

        # Route to appropriate API
        if model.provider == "anthropic":
            response = self._call_anthropic(prompt, model, temperature)
        elif model.provider == "openai":
            response = self._call_openai(prompt, model, temperature)
        elif model.provider == "deepseek":
            response = self._call_deepseek(prompt, model, temperature)
        elif model.provider == "google":
            response = self._call_google(prompt, model, temperature)

        # Track cost
        cost = self.compute_cost(response, model)
        self.total_cost += cost
        self.budget_remaining -= cost

        return response

Island 1 (Claude-based)     Island 2 (GPT-based)     Island 3 (DeepSeek-based)
  +---------+                 +---------+               +---------+
  | Pop 1   |                 | Pop 2   |               | Pop 3   |
  | evolve  |                 | evolve  |               | evolve  |
  | evolve  |                 | evolve  |               | evolve  |
  +----+----+                 +----+----+               +----+----+
       |                           |                         |
       +------- Migration --------+-------- Migration ------+
       |      (every M gens)       |      (every M gens)     |
       v                           v                         v
  Best from I2,I3              Best from I1,I3          Best from I1,I2
  injected into I1             injected into I2         injected into I3

class AdaptiveStrategy:
    """Adaptively choose between exploration and exploitation."""

    def __init__(self):
        self.stagnation_counter = 0
        self.best_fitness_history = []

    def choose_strategy(self, population, generation):
        """Decide mutation strategy based on evolutionary progress."""
        current_best = population.get_best()[0].fitness

        # Track stagnation
        if (self.best_fitness_history and
            current_best <= self.best_fitness_history[-1]):
            self.stagnation_counter += 1
        else:
            self.stagnation_counter = 0

        self.best_fitness_history.append(current_best)

        # If stagnating, increase exploration
        if self.stagnation_counter >= 3:
            return "explore"   # High temp, strategy mutations
        elif current_best > 0.8:
            return "exploit"  # Low temp, parameter tweaks
        else:
            return "balanced" # Default mixed strategy

def maybe_restart(self, population, stagnation_count):
    """Restart population if hopelessly stuck."""
    if stagnation_count >= self.config.restart_threshold:
        best = population.best_ever
        population.clear()
        if best:
            population.add(best)
        # Re-seed rest of population
        for _ in range(self.config.seed_count - 1):
            seed = self.mutator.generate_seed(self.task)
            if seed:
                population.add(seed)
        return True
    return False

import numpy as np
import signal
import traceback

class FitnessEvaluator:
    def __init__(self, timeout_seconds=5):
        self.timeout = timeout_seconds

    def evaluate(self, individual, task):
        """Evaluate individual on all training examples."""
        scores = []
        predictions = []
        error_info = None

        for inp, expected_out in task.train_pairs:
            try:
                # Execute program in sandboxed environment
                predicted = self.run_program(
                    individual.code, inp
                )
                predictions.append(predicted)

                # Compare predicted vs expected
                score = self.pixel_accuracy(predicted, expected_out)
                scores.append(score)

            except TimeoutError:
                scores.append(0.0)
                predictions.append(None)
                error_info = "Timeout: program exceeded time limit"
            except Exception as e:
                scores.append(0.0)
                predictions.append(None)
                error_info = traceback.format_exc()

        individual.fitness = np.mean(scores) if scores else 0.0
        individual.predictions = predictions
        individual.error_info = error_info
        return individual

    def pixel_accuracy(self, predicted, expected):
        """Compute pixel-level match accuracy."""
        pred = np.array(predicted)
        exp = np.array(expected)

        if pred.shape != exp.shape:
            return 0.0  # Shape mismatch = zero fitness

        matches = np.sum(pred == exp)
        total = exp.size
        return matches / total if total > 0 else 0.0

    def run_program(self, code, input_grid):
        """Execute transform function in a sandboxed environment."""
        # Create isolated namespace
        namespace = {
            'np': np,
            'numpy': np,
            'input_grid': input_grid,
        }

        # Set timeout via signal
        signal.alarm(self.timeout)
        try:
            exec(code, namespace)
            transform_fn = namespace['transform']
            result = transform_fn(input_grid)
            return result
        finally:
            signal.alarm(0)  # Cancel alarm

# Seed prompt template (simplified)
SEED_PROMPT = """You are solving an ARC (Abstraction and Reasoning Corpus) task.
Given input grids, you must write a Python function `transform(grid)` that
produces the correct output grid.

The grid is a 2D list of integers (0-9), where each integer represents a color:
0=black, 1=blue, 2=red, 3=green, 4=yellow, 5=gray, 6=magenta, 7=orange,
8=cyan, 9=maroon

Training examples:
{examples}

Analyze the pattern in these examples, then write a Python function:

```python
import numpy as np

def transform(grid):
    grid = np.array(grid)
    # Your implementation here
    return output.tolist()

### Mutation Prompt Template

{parent_code}

### Error Repair Prompt

{code}

{error_traceback}

### Crossover Prompt

{code_a}

{code_b}

## 13. Crossover Operators

While mutation is the primary operator, crossover combines genetic material from two parent programs:

def crossover(self, parent_a, parent_b, task):
    """Produce a child by combining two parents via LLM."""
    prompt = self.prompts["crossover"].format(
        code_a=parent_a.code,
        code_b=parent_b.code,
        fitness_a=parent_a.fitness,
        fitness_b=parent_b.fitness,
        examples=self.format_examples(task)
    )

    response = self.llm.generate(
        prompt=prompt,
        temperature=0.7,
        max_tokens=4096
    )

    child_code = self.extract_code(response)
    if child_code:
        return Individual(
            code=child_code,
            generation=max(parent_a.generation,
                           parent_b.generation) + 1,
            parent_id=f"{parent_a.id}x{parent_b.id}",
            mutation_type="crossover"
        )
    return None

### Crossover Selection

Crossover is applied less frequently than mutation (typically 20-30% of offspring are from crossover). Parents for crossover are selected from the top half of the population by fitness, ensuring that only reasonably good programs contribute to recombination.


$$
P(crossover) = crossover_rate = 0.2 to 0.3


P(mutation) = 1 - crossover_rate = 0.7 to 0.8


Parent selection for crossover: Both parents from top 50% by fitness
$$

## 14. Cost Control and Budget Management

### Per-Task Budget

def __init__(self, max_budget_per_task=5.0,
             warning_threshold=0.8):
    self.max_budget = max_budget_per_task  # dollars
    self.warning_threshold = warning_threshold
    self.spent = 0.0
    self.calls = 0
    self.cost_per_model = {}

def can_afford(self, estimated_cost):
    """Check if we can afford another API call."""
    return (self.spent + estimated_cost) <= self.max_budget

def record_cost(self, cost, model_name):
    """Record an API call cost."""
    self.spent += cost
    self.calls += 1
    self.cost_per_model[model_name] = (
        self.cost_per_model.get(model_name, 0) + cost
    )

def budget_remaining(self):
    return self.max_budget - self.spent

def should_switch_to_cheap_model(self):
    """Switch to cheaper model when budget is running low."""
    return self.spent >= self.max_budget * self.warning_threshold

### Cost Estimates

| Component | Estimated Cost | Notes |
| --- | --- | --- |
| Seed generation (N=10 programs) | $0.10 - $0.50 | Depends on model used |
| Per mutation (1 LLM call) | $0.01 - $0.10 | Varies by model, prompt length |
| Per generation (pop=20) | $0.20 - $2.00 | ~10-20 mutations per generation |
| Full task (20-50 generations) | $1 - $5 | Typical range with budget control |
| Full ARC-AGI-2 eval (100 tasks) | $100 - $500 | Varies with difficulty |

### Cost Optimization Strategies

- **Early termination:** Stop immediately upon finding a perfect-fitness program.
- **Model cascading:** Start with cheap models (DeepSeek), escalate to expensive ones (Claude) only for harder tasks.
- **Prompt compression:** Minimize token count in prompts by using compact grid representations.
- **Cache deduplication:** Don't re-evaluate programs that have already been seen.
- **Adaptive generation count:** Easy tasks converge in 5-10 generations; hard tasks get up to 50+.

## 15. Meta-Level and Self-Improvement

### Prompt Evolution

A meta-level strategy is to evolve the prompts themselves. If certain prompt phrasings lead to higher-fitness mutations on average, those prompt templates are favored:

def __init__(self, base_prompts, llm_client):
    self.prompt_population = [
        {"template": p, "avg_fitness_gain": 0.0, "uses": 0}
        for p in base_prompts
    ]
    self.llm = llm_client

def select_prompt(self):
    """Select prompt template weighted by past success."""
    # Upper confidence bound (UCB) selection
    best_score = -float('inf')
    best_prompt = None

    for p in self.prompt_population:
        if p["uses"] == 0:
            return p  # Explore unused prompts first
        ucb = (p["avg_fitness_gain"] +
               np.sqrt(2 * np.log(self.total_uses) / p["uses"]))
        if ucb > best_score:
            best_score = ucb
            best_prompt = p
    return best_prompt

def update(self, prompt_entry, fitness_gain):
    """Update prompt statistics after use."""
    n = prompt_entry["uses"]
    prompt_entry["avg_fitness_gain"] = (
        (prompt_entry["avg_fitness_gain"] * n + fitness_gain) / (n + 1)
    )
    prompt_entry["uses"] += 1

### Hyperparameter Adaptation

The system can adapt its own hyperparameters during a run:

- **Population size:** Increase if diversity is low, decrease if budget is tight.
- **Mutation temperature:** Adjust based on stagnation (see Section 5).
- **Tournament size:** Increase over generations (see Section 6).
- **Crossover rate:** Increase if crossover offspring outperform mutations.

### Transfer Learning Across Tasks

Solutions (or partial solutions) from previously solved tasks can serve as seed programs for new similar tasks. Common utility functions discovered during evolution can be extracted and reused:

def __init__(self):
    self.solved_programs = {}  # task_id -> best program
    self.utility_functions = []  # Extracted helpers

def register_solution(self, task_id, program):
    self.solved_programs[task_id] = program
    self.extract_utilities(program)

def get_relevant_seeds(self, task, n=3):
    """Find previously solved programs that might help."""
    # Simple heuristic: tasks with similar grid dimensions
    # or similar color palettes
    candidates = []
    for tid, prog in self.solved_programs.items():
        similarity = self.task_similarity(task, tid)
        candidates.append((similarity, prog))
    candidates.sort(reverse=True)
    return [prog for _, prog in candidates[:n]]

## 16. Main Evolutionary Loop

def __init__(self, config):
    self.config = config
    self.llm = LLMClient(config)
    self.mutator = Mutator(self.llm, config.prompts, config)
    self.crossover = Crossover(self.llm, config.prompts)
    self.selector = TournamentSelection(config.tournament_size)
    self.evaluator = FitnessEvaluator(config.timeout)
    self.budget = BudgetManager(config.max_budget_per_task)
    self.strategy = AdaptiveStrategy()

def solve(self, task):
    """Evolve a solution for the given ARC task."""
    # 1. Initialize population with seed programs
    population = Population(
        max_size=self.config.pop_size,
        elite_count=self.config.elite_count
    )
    self.seed_population(population, task)

    # 2. Evaluate initial population
    for ind in population.individuals:
        self.evaluator.evaluate(ind, task)

    # 3. Evolutionary loop
    for gen in range(self.config.max_generations):
        # Check termination conditions
        best = population.get_best()[0]
        if best.fitness >= 1.0:
            break  # Perfect solution found!
        if not self.budget.can_afford(0.01):
            break  # Budget exhausted

        # Determine strategy
        strategy = self.strategy.choose_strategy(population, gen)

        # Generate offspring
        offspring = []
        for _ in range(self.config.offspring_per_gen):
            if not self.budget.can_afford(0.01):
                break

            if random.random() < self.config.crossover_rate:
                # Crossover
                parents = self.selector.select(population, 2)
                child = self.crossover.crossover(
                    parents[0], parents[1], task
                )
            else:
                # Mutation
                [parent] = self.selector.select(population, 1)
                child = self.mutator.mutate(
                    parent, task, parent.error_info
                )

            if child:
                self.evaluator.evaluate(child, task)
                offspring.append(child)

        # Add offspring to population
        for child in offspring:
            population.add(child)

        # Cull population to max size
        population.cull()

        # Maybe inject fresh seeds
        self.maybe_inject_fresh_seed(population, task, gen)

        # Maybe restart if stuck
        self.maybe_restart(population,
                           self.strategy.stagnation_counter)

    # 4. Return top-2 programs for ARC submission
    top2 = population.get_best(n=2)
    return [self.predict_test(ind, task) for ind in top2]

def seed_population(self, population, task):
    """Generate initial seed programs."""
    for i in range(self.config.seed_count):
        # Use different models for diversity
        model = self.llm.models[i % len(self.llm.models)]
        seed = self.mutator.generate_seed(task, model=model)
        if seed:
            population.add(seed)

def predict_test(self, individual, task):
    """Run best program on test input to get prediction."""
    try:
        result = self.evaluator.run_program(
            individual.code, task.test_input
        )
        return result
    except:
        return <a href="/evolve/ale-agent-ahc058.html">0</a>  # Fallback empty grid

## 17. Memory Management

### Population Storage

- **Active population:** In-memory list of `Individual` objects (typically 10-30 per task).
- **History archive:** All individuals ever created are stored for analysis and potential revival.
- **Deduplication set:** Hash set of all seen program codes to prevent duplicates.
- **Best-ever tracking:** The single best individual across all generations is always preserved.

### Serialization

### Memory Footprint

| Component | Size | Notes |
| --- | --- | --- |
| Single Individual | ~1-10 KB | Code string + metadata |
| Active Population (20) | ~20-200 KB | In memory during evolution |
| History (500 individuals) | ~0.5-5 MB | All programs ever generated |
| Predictions cache | ~1-10 MB | Stored grid predictions for behavioral distance |
| Total per task | <50 MB | Lightweight |

## 18. Reproducibility

### Setup Instructions

### Dependencies

| Package | Version | Purpose |
| --- | --- | --- |
| Python | >=3.10 | Runtime |
| numpy | >=1.24 | Grid operations |
| anthropic | latest | Claude API client |
| openai | latest | GPT-4o API client |
| pyyaml | latest | Configuration parsing |
| scipy | >=1.10 | Optional: advanced grid operations |
| tqdm | latest | Progress bars |

### Configuration (config.yaml)

## 19. Programming Language

#### Framework Language

**Python 3.10+** -- The evolutionary engine, LLM orchestration, fitness evaluation, and all infrastructure code is written in Python.

---

#### Evolved Programs

**Python (numpy-based)** -- The candidate solutions (transform functions) are Python functions using numpy for grid manipulation. Programs are executed via `exec()` in sandboxed namespaces.

---

The choice of Python for both the framework and evolved programs is intentional: LLMs are most proficient at generating Python code, and numpy provides efficient grid operations. The `exec()`-based execution model allows programs to be stored as strings and dynamically evaluated.

## 20. Continued Learning

### Within-Task Learning

The evolutionary process itself is a form of learning: the population accumulates knowledge about the task through the fitness landscape. Each generation's survivors encode "learned" information about the input-output relationship.

### Cross-Task Transfer

- **Utility library accumulation:** Common helper functions (flood fill, connected components, rotation, reflection, color remapping) discovered during evolution are saved and injected as available imports for future tasks.
- **Solution seeding:** Programs from solved tasks can seed the initial population for similar unsolved tasks.
- **Prompt refinement:** Prompt templates that led to high-quality mutations are preserved and reused.

### Model Fine-Tuning (Future Direction)

The evolutionary history (parent program, mutation prompt, successful child program) forms a natural dataset for fine-tuning LLMs to become better mutation operators. This creates a virtuous cycle: