ShinkaEvolve

┌─────────────────────────────────────────────────────────────────┐
│                     ShinkaEvolve Framework                       │
│                                                                  │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐       │
│  │  shinka_launch│    │  shinka_run  │    │shinka_visualize│      │
│  │  (Hydra CLI)  │    │ (Agent CLI)  │    │   (WebUI)     │      │
│  └──────┬───────┘    └──────┬───────┘    └──────┬───────┘       │
│         │                    │                    │               │
│  ┌──────▼────────────────────▼────────────────────▼──────┐      │
│  │              Evolution Runner (sync/async)             │      │
│  │  ┌─────────────────┐  ┌──────────────────────────┐    │      │
│  │  │EvolutionRunner  │  │ AsyncEvolutionRunner      │    │      │
│  │  │(sequential gen) │  │ (concurrent gen+eval)     │    │      │
│  │  │                 │  │ 5-10x speedup             │    │      │
│  │  └─────────────────┘  └──────────────────────────┘    │      │
│  └───────────────────────────┬───────────────────────────┘      │
│                              │                                   │
│  ┌───────────┬───────────────┼───────────────┬───────────┐      │
│  ▼           ▼               ▼               ▼           ▼      │
│ ┌────┐  ┌────────┐  ┌──────────────┐  ┌─────────┐  ┌────────┐ │
│ │LLM │  │Novelty │  │  Population  │  │Evaluator│  │ Prompt │ │
│ │Ens.│  │ Judge  │  │   Database   │  │ Wrapper │  │Evolver │ │
│ │    │  │        │  │              │  │         │  │        │ │
│ │Prov│  │Embed + │  │Islands + Arch│  │Parallel │  │Sys.Prom│ │
│ │ider│  │LLM-as- │  │ive + Migrat.│  │Exec +   │  │Archive │ │
│ │Mod.│  │Judge   │  │Island Sampl.│  │E.Stop   │  │Mutation│ │
│ └────┘  └────────┘  └──────────────┘  └─────────┘  └────────┘ │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                    Bandit Controller                       │   │
│  │   Thompson/UCB-based LLM selection + meta-recommendations │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

shinka/
├── core/               # Evolution runners (sync + async), novelty judge
│   ├── evolution_runner.py     # Main synchronous loop
│   ├── async_runner.py         # Async concurrent pipeline
│   ├── async_summarizer.py     # Async result summarization
│   ├── async_novelty_judge.py  # Async novelty evaluation
│   └── wrap_eval.py            # Evaluation wrapper with parallelism
├── database/           # Population management
│   ├── database.py             # Island-based population database
│   ├── async_dbase.py          # Async database operations
│   ├── island_sampler.py       # Island selection strategies
│   └── prompt_dbase.py         # Prompt population storage
├── edit/               # Code editing operations
├── embed/              # Embedding providers for novelty
├── llm/                # LLM provider-based modules
│   └── providers/              # OpenAI, Google, local model support
├── prompts/            # Prompt templates
│   ├── prompts_fix.py          # Fix-mode for incorrect populations
│   └── prompts_prompt_evo.py   # Prompt evolution templates
├── plots/              # Visualization modules
│   ├── plot_costs.py, plot_evals.py, plot_time.py, plot_llm.py
├── webui/              # Dashboard and compare views
│   ├── index.html, compare.html
└── utils/              # Utility functions

# Example: Initial program with evolve markers
# === EVOLVE-BLOCK-START ===
def optimize(problem):
    """Optimize the given problem instance."""
    solution = greedy_initialize(problem)
    for i in range(1000):
        neighbor = random_perturbation(solution)
        if evaluate(neighbor) > evaluate(solution):
            solution = neighbor
    return solution
# === EVOLVE-BLOCK-END ===

# Python implementation of power-law parent selection
import numpy as np

def power_law_selection(population, scores, alpha=2.0):
    """Select parent using power-law distribution over ranked programs."""
    # Rank programs by score (highest first)
    ranked_indices = np.argsort(scores)[::-1]
    ranks = np.arange(1, len(ranked_indices) + 1)

    # Compute power-law probabilities
    probs = ranks.astype(float) ** (-alpha)
    probs /= probs.sum()

    # Sample parent
    selected_rank = np.random.choice(len(ranks), p=probs)
    return population[ranked_indices[selected_rank]]

Island 1          Island 2          Island 3          Island 4
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Pop: 25      │ │ Pop: 25      │ │ Pop: 25      │ │ Pop: 25      │
│ Elite: 8     │ │ Elite: 8     │ │ Elite: 8     │ │ Elite: 8     │
│ Archive: 50  │ │ Archive: 50  │ │ Archive: 50  │ │ Archive: 50  │
│              │ │              │ │              │ │              │
│ Strategy: A  │ │ Strategy: B  │ │ Strategy: C  │ │ Strategy: D  │
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘
       │     Migration (10%)     │                │
       └────────every 10 gen─────┴────────────────┘
                    │
              ┌─────▼──────┐
              │   Global   │
              │  Archive   │
              │ Best-of-All│
              └────────────┘

# Novelty rejection via embedding similarity
def check_novelty_embedding(new_program, population, embedder, threshold=0.15):
    """Reject programs too similar to existing population."""
    new_emb = embedder.encode(new_program.code)
    for existing in population:
        existing_emb = embedder.encode(existing.code)
        similarity = cosine_similarity(new_emb, existing_emb)
        if similarity > (1.0 - threshold):
            return False  # Too similar, reject
    return True  # Novel enough

# LLM-based novelty assessment (async_novelty_judge.py)
async def judge_novelty(parent_code, child_code, llm_client):
    """Use LLM to assess whether mutation is algorithmically novel."""
    prompt = f"""Compare these two programs and assess if the child
    introduces a genuinely novel algorithmic approach:

    Parent: {parent_code}
    Child: {child_code}

    Rate novelty 1-5: 1=cosmetic change, 5=fundamentally new approach.
    Explain your reasoning."""

    response = await llm_client.generate(prompt)
    novelty_score = extract_score(response)
    return novelty_score >= 3  # Accept if genuinely novel

# Bandit-based LLM selection
class BanditLLMSelector:
    def __init__(self, models, exploration_weight=1.4):
        self.models = models
        self.c = exploration_weight
        self.successes = {m: 0 for m in models}
        self.trials = {m: 1 for m in models}  # Avoid div-by-zero
        self.total_trials = len(models)

    def select(self):
        """Select LLM using UCB1 strategy."""
        ucb_scores = {}
        for model in self.models:
            mu = self.successes[model] / self.trials[model]
            exploration = self.c * math.sqrt(
                math.log(self.total_trials) / self.trials[model]
            )
            ucb_scores[model] = mu + exploration
        return max(ucb_scores, key=ucb_scores.get)

    def update(self, model, improvement):
        """Update model statistics after evaluation."""
        self.trials[model] += 1
        self.total_trials += 1
        if improvement > 0:
            self.successes[model] += 1

# Evaluation setup: users provide two files
# evaluate.py - runs experiments and returns metrics
def evaluate(program_path: str) -> dict:
    """Run the program and return metrics."""
    result = run_program(program_path)
    return {
        "combined_score": result.score,  # Required key
        "accuracy": result.accuracy,
        "runtime_ms": result.runtime
    }

# initial.py - starting solution with EVOLVE-BLOCK markers
# === EVOLVE-BLOCK-START ===
def solve(input_data):
    return baseline_solution(input_data)
# === EVOLVE-BLOCK-END ===

# Prompt co-evolution pseudocode
class PromptEvolver:
    def __init__(self, prompt_archive):
        self.archive = prompt_archive  # PromptDatabase

    def evolve_prompt(self, parent_prompt, success_history):
        """Mutate a system prompt based on success history."""
        meta_prompt = f"""This system prompt was used to guide code mutations:
        {parent_prompt}

        History of mutations it produced:
        {format_history(success_history)}

        Improve this prompt to generate better code mutations.
        Focus on what worked and amplify those strategies."""

        return self.llm.generate(meta_prompt)

    def select_prompt(self):
        """Select system prompt using fitness-proportionate selection."""
        prompts = self.archive.get_all()
        scores = [p.avg_improvement for p in prompts]
        return weighted_sample(prompts, scores)

# Cost tracking pseudocode
class CostTracker:
    def __init__(self, max_budget):
        self.max_budget = max_budget
        self.realized_costs = {
            'api_costs': 0.0,    # LLM generation costs
            'embed_cost': 0.0,   # Embedding computation
            'novelty_cost': 0.0, # Novelty judge LLM calls
            'meta_cost': 0.0     # Meta-recommendation costs
        }
        self.in_flight_estimate = 0.0

    @property
    def committed_cost(self):
        return sum(self.realized_costs.values()) + self.in_flight_estimate

    def can_propose(self):
        return self.committed_cost < self.max_budget

# Quick start
git clone https://github.com/SakanaAI/ShinkaEvolve
cd ShinkaEvolve
uv pip install -e .

# Run circle packing example
shinka_launch variant=circle_packing_example

# Or with agent CLI
shinka_run --task-dir examples/circle_packing --num_generations 20

# Customize
shinka_run --set evo.max_parallel_jobs=6 --set db.num_islands=3