Get a program by ID Args: program_id: Program ID Returns: Program or None if not found

Get and format a smaller text fragment by name.

Calculate the fitness score from a metrics dictionary, giving priority to 'combined_score' and excluding MAP-Elites feature dimensions from t

Add a program to the database Args: program: Program to add iteration: Current iteration (defaults to last_i

Convert the Config object back to a dictionary.

Get a template by name.

Load the database from disk Args: path: Path to load from

Calculate the average of numeric values in a metrics dictionary, safely ignoring non-numeric values like strings. Args: metrics:

Process evaluation result to handle both dict and EvaluationResult returns Args: result: Raw result from evaluation func

Run the evolution process with improved parallel processing Args: iterations: Maximum number of iterations (uses config

Sample a completely random parent from all programs

Safely format a metrics dictionary for logging, handling both numeric and string values. Args: metrics: A dictionary of metric names

Generate text using a system message and conversational context

Check if this result contains any artifacts

Sample a program and inspirations for the next evolution step Args: num_inspirations: Number of inspiration programs to

Determine if program1 has better FITNESS than program2 Uses fitness calculation that excludes MAP-Elites feature dimensions

Scale a feature value according to the configured scaling method Args: feature_name: Name of the feature dimension

Update statistics for a feature dimension Args: feature_name: Name of the feature dimension value: New value

Get the best program based on a metric Args: metric: Metric to use for ranking (uses combined_score or average if None)

Log current status of all islands

Run a coroutine within the pool's concurrency limit. Args: coro: The coroutine function to run. *args: Posit

Update parameters for all models in both evolution and evaluator ensembles.

Calculate feature coordinates for the MAP-Elites grid Args: program: Program to calculate features for Returns:

Directly evaluate a program using the evaluation function with timeout Args: program_path: Path to the program file

Fast approximation of code diversity using simple metrics Returns diversity score (higher = more diverse)

Convert feature coordinates to a string key Args: coords: Feature coordinates Returns: String key

Sample a parent for exploration (from current island)

Sample a parent from a specific island using fitness-weighted selection Args: island_id: The island to sample from

Build a prompt for the LLM. Args: current_program: Current program code. parent_program: Parent program from

Close the tracer and flush remaining data

Evaluate a program and return scores Args: program_code: Code to evaluate program_id: Optional ID for loggin

Export traces to a single JSON file with a metadata wrapper. Args: traces: A list of trace objects. output_path: The path wh

Extract all SEARCH/REPLACE diff blocks from a given text. Args: diff_text: The text containing diff blocks. diff_pattern: Th

Get the top N programs based on a metric Args: n: Number of programs to return metric: Metric to use for ran

Conducts autonomous web research to find the best algorithms or solutions for the task. Args: task_description:

Run evolution with flexible inputs - this is the main library API. Args: initial_program: Can be a path to a program file, the progr

Apply security filtering to artifact text to remove sensitive info. Args: text: Input text. Returns:

Remove stale island best program references Cleans up references to programs that no longer exist in the database or are not

Create rich error context for cascade failures Args: stage: The stage where the error occurred error: The ex

Determine the type/category of an inspiration program Args: program: Program dictionary. feature_dimensions:

Load all templates (.txt files) and fragments (fragments.json) from a directory.

Check if metrics pass a threshold Uses 'combined_score' if available (for consistency with evolution), otherwise falls back

Sample a model from the ensemble based on weights

Save a program to disk Args: program: Program to save base_path: Base path to save to (uses config.db_path i

Submit an iteration to the process pool, optionally pinned to a specific island

Apply a diff to the original code using the specified SEARCH/REPLACE format. Args: original_code: The original source code string.

Calculate improvement deltas between parent and child metrics

A high-level wrapper to export traces to a specified format. Args: traces: A list of trace objects. output_path: The path to

Write buffered traces to file

Create a human-readable summary of the changes in a list of diffs. Args: diff_blocks: A list of (search_text, replace_text) tuples.

Format the feature coordinates (values of MAP-Elites dimensions) for display in prompts. Args: metrics: The dictionary of all metric

Generate text using a randomly selected model based on weights

Retrieve all artifacts for a program Args: program_id: ID of the program Returns: Dictionary of art

Get and clear pending artifacts for a program Args: program_id: Program ID Returns: Artifacts dicti

Load configuration from a YAML file, or create a default config.

Log a prompt for a program. Only logs if self.config.log_prompts is True. Args: program_id: ID of the program to log

Main synchronous entry point for the script. Returns: The exit code from the asynchronous main function.

Extract a complete code block from an LLM response for a full rewrite. Args: llm_response: The full text response from the LLM.

Save the database to disk Args: path: Path to save to (uses config.db_path if None) iteration: Current itera

Set custom templates to use for this sampler instance. Args: system_template: Template name for system message.

Convert to dictionary representation

Apply stochastic variations to the template

Cache a diversity value with LRU eviction

Calculate the bin index for a given complexity value using feature scaling. Args: complexity: The complexity value (code

Calculate the bin index for a given diversity value using feature scaling. Args: diversity: The average fast code divers

Calculate diversity within an island (deterministic version)

Make the actual API call

Run cascade evaluation with increasingly challenging test cases Args: program_path: Path to the program file Re

Remove artifact directories older than the configured retention period. Args: checkpoint_path: The path of the current c

Adapted from SakanaAI/ShinkaEvolve (Apache-2.0 License) Original source: https://github.com/SakanaAI/ShinkaEvolve/blob/main/shinka/da

Create artifact directory for a program

Create a serializable snapshot of the database state

Deserialize feature_stats from loaded JSON Args: stats_dict: Dictionary loaded from JSON Returns: P

Distribute loaded programs across islands when no island metadata exists

Enforce the population size limit by removing worst programs if needed Args: exclude_program_id: Program ID to never rem

Extract unique features of an inspiration program Args: program: Program dictionary. Returns: Strin

Format the evolution history section for the prompt

Format the inspirations section for the prompt Args: inspirations: List of inspiration programs. language: P

Format metrics for the prompt using safe formatting

Get size of an artifact value in bytes

Get diversity score for a program using cache and reference set Args: program: The program to calculate diversity for

Initializes and returns the correct OpenAI or AzureOpenAI client and model name.

Identify improvement areas with proper fitness/feature separation

Determine if a program is novel based on diversity to existing programs Args: program_id: ID of Program to check

Lazily initialize expensive components on first use

Use LLM to evaluate code quality Args: program_code: Code to evaluate program_id: Optional ID for logging

Use LLM to judge if a program is novel compared to a similar existing program

Load artifacts from a directory

Load state from a checkpoint directory

Load the evaluation function from the evaluation file

Load the initial program from file

Helper function to convert the flexible 'evaluator' input into a file path.

Helper function to convert the flexible 'initial_program' input into a file path.

Reconstruct island assignments from saved metadata Args: saved_islands: List of island program ID lists from metadata

Render artifacts for prompt inclusion Args: artifacts: Dictionary of artifact name to content. Returns:

Resolve ${VAR} environment variable reference in a string value. The pattern must match the entire string (e.g., "${OPENAI_API_KEY}"), no

Asynchronous implementation of the run_evolution function.

Run evolution with checkpoint saving support

Safely decode an artifact value to string Args: value: Artifact value (string or bytes). Returns: S

Sample a parent for exploitation (from archive/elite programs)