# sakanaai/shinkaevolve architecture

> Architecture diagram of the GitHub repository sakanaai/shinkaevolve, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sakanaai/shinkaevolve
- Repository: https://github.com/sakanaai/shinkaevolve

## Overview

1. **Overall shape**
   - `shinka` is a Python framework for evolutionary program improvement driven by LLMs.
   - The core loop is: start from an `initial.<ext>` program, generate candidate mutations with LLMs, evaluate them with a task-specific verifier, and feed the results back into selection, archive, and novelty mechanisms.

2. **Primary entry points**
   - `shinka_launch` is the Hydra-based launcher for configured experiments.
   - `shinka_run` is a task-directory CLI aimed at agent workflows and simpler ad hoc runs.
   - `ShinkaEvolveRunner` is the main Python API for programmatic control.
   - `shinka_visualize` serves the WebUI for live inspection of a running or completed experiment.

3. **Task boundary**
   - Each task is external to the framework and supplies two key files: `evaluate.py` and the seed program (`initial.py`, `initial.f90`, `initial.jl`, etc.).
   - `evaluate.py` is the verifier/scoring boundary; it executes the program under test, aggregates metrics, and may return text feedback.
   - The framework treats the task program as the evolving artifact and the evaluator as the authoritative source of fitness.

4. **Evolution core**
   - `shinka/core` contains the orchestration logic: proposal generation, async scheduling, timing, runtime slots, novelty checking, summarization, and evaluation wrapping.
   - Candidate generation supports multiple patch styles such as diff-based, full-file, and cross-program edits.
   - There is also a prompt-evolution path, where system prompts themselves can be evolved on a cadence.

5. **LLM and mutation layer**
   - `shinka/llm` provides provider-agnostic access to model backends such as OpenAI, Anthropic, Gemini, DeepSeek, local OpenAI-compatible servers, and a headless CLI-backed mode.
   - This layer also handles model resolution, pricing, retry-related constants, and model-selection prioritization.
   - The rest of the system depends on this abstraction rather than talking to providers directly.

6. **Edit application boundary**
   - `shinka/edit` is responsible for taking an LLM proposal and turning it into an executable candidate program.
   - It supports applying patch diffs, replacing full files, and asynchronous edit execution.
   - This is the boundary where LLM output becomes concrete code that can be evaluated.

7. **Database, archive, and island model**
   - `shinka/database` manages persistent experiment state: archives of evaluated programs, parent/inspiration tracking, island sampling, and diversity-related selection.
   - The architecture is island-based: multiple subpopulations evolve in parallel, with optional migration and dynamic spawning.
   - Selection policies govern parent choice, archive replacement, and diversity/exploitation tradeoffs.

8. **Embeddings and novelty**
   - `shinka/embed` provides code embeddings used for similarity checks and novelty gating.
   - Novelty judgment can combine embedding similarity thresholds with optional LLM-based novelty review.
   - This creates a second evaluation axis beyond raw task score: whether a candidate is sufficiently distinct or interesting.

9. **Launch and execution environments**
   - `shinka/launch` abstracts where evaluation jobs run: locally, through SLURM, via conda activation, shell activation scripts, or Docker-on-SLURM.
   - This is important because the evaluator is executed out-of-process, and the framework is designed to scale from laptop runs to cluster runs.
   - `shinka/cli` and the Hydra configs under `shinka/configs` bind together task, database, cluster, and evolution presets into runnable experiments.

10. **Asynchronous and throughput-focused mode**
   - The async runner path is a major subsystem: it decouples proposal generation, evaluation execution, and DB writes to improve throughput.
   - Concurrency is intentionally split into separate budgets for evaluation jobs, proposal jobs, and database workers.
   - The repo also includes oversubscription controls so proposal generation can be buffered when it is slower than evaluation.

11. **Visualization and outputs**
   - `shinka/webui` contains the browser-based UI for inspecting lineages, trees, timing, costs, and performance trends.
   - `shinka/plots` provides offline plotting utilities for costs, throughput, Pareto fronts, similarity, and lineage trees.
   - The visual layer reads experiment artifacts and database state; it does not drive evolution itself.

12. **Configuration model**
   - The system is heavily configuration-driven through Hydra presets and per-task YAMLs.
   - Config domains are split by concern: `task`, `database`, `evolution`, `cluster`, and `variant`.
   - This separation is what lets the same evolutionary engine run very different scientific tasks without changing core code.

13. **Representative supported workflows**
   - The examples show the intended architecture: scientific or algorithmic tasks in Python, Fortran, or Julia; evaluation scripts; and a task-specific initial solution.
   - The repository also includes “agent skills” wrappers that package common workflows like setup, conversion, run, and inspection for external coding agents.
   - These skills are thin orchestration layers over the same core CLI and runner architecture.

14. **External dependencies that matter architecturally**
   - LLM provider APIs, local OpenAI-compatible endpoints, embeddings services, and optional Headless CLI access are all first-class external integration points.
   - SLURM and Docker are the main infrastructure dependencies for scaled execution.
   - Markdown docs are generated with MkDocs, but that is documentation infrastructure rather than part of the runtime system.

Main entry points: [`shinka/core`](https://github.com/sakanaai/shinkaevolve/tree/main/shinka/core) (Core loop), [`shinka/database`](https://github.com/sakanaai/shinkaevolve/tree/main/shinka/database) (Experiment DB), [`shinka/core/async_runner.py`](https://github.com/sakanaai/shinkaevolve/blob/main/shinka/core/async_runner.py) (Async runner), [`shinka/cli/shinka_run`](https://github.com/sakanaai/shinkaevolve/tree/main/shinka/cli/shinka_run) (Run CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_runtime["Runtime"]
  node_cli_launch["Launch CLI<br/>cli entrypoint"]
  node_cli_run["Run CLI<br/>task CLI"]
  node_cli_visualize["Visualize CLI<br/>webui entrypoint"]
end

subgraph group_group_engine["Evolution engine"]
  node_core_pipeline{{"Core loop<br/>evolution orchestrator"}}
  node_core_async["Async runner<br/>throughput scheduler<br/>[async_runner.py]"]
  node_core_novelty["Novelty gate<br/>novelty judge<br/>[novelty_judge.py]"]
  node_core_prompt["Prompt evo<br/>[prompt_evolver.py]"]
  node_core_wrap["Eval wrapper<br/>evaluation boundary<br/>[wrap_eval.py]"]
  node_edit_boundary{{"Edit apply<br/>mutation applier"}}
end

subgraph group_group_state["State and selection"]
  node_db_layer[("Experiment DB<br/>persistent state")]
end

subgraph group_group_integrations["Integrations"]
  node_llm_layer{{"LLM layer<br/>provider abstraction"}}
  node_launch_layer{{"Launch backends<br/>execution launcher"}}
  node_embed_layer["Embeddings<br/>code similarity"]
end

subgraph group_group_present["Presentation"]
  node_webui_layer["Web UI<br/>inspection UI"]
  node_plots_layer["Plots<br/>offline visualization"]
end

subgraph group_group_config["Config and examples"]
  node_configs_layer["Configs<br/>hydra presets"]
  node_examples_layer["Examples<br/>tasks and demos"]
  node_skills_layer["Skills<br/>agent wrappers"]
end

node_cli_launch -->|"configures"| node_core_pipeline
node_cli_run -->|"starts"| node_core_async
node_cli_visualize -->|"serves"| node_webui_layer
node_core_pipeline -->|"queries"| node_llm_layer
node_core_pipeline -->|"mutates"| node_edit_boundary
node_core_pipeline -->|"evaluates"| node_core_wrap
node_core_pipeline -->|"persists"| node_db_layer
node_core_pipeline -->|"filters"| node_core_novelty
node_core_pipeline -->|"adapts"| node_core_prompt
node_core_async -->|"dispatches"| node_launch_layer
node_core_async -->|"streams"| node_db_layer
node_core_novelty -->|"compares"| node_embed_layer
node_db_layer -->|"indexes"| node_embed_layer
node_db_layer -->|"feeds"| node_core_pipeline
node_launch_layer -->|"executes"| node_core_wrap
node_webui_layer -->|"reads"| node_db_layer
node_plots_layer -->|"analyzes"| node_db_layer
node_configs_layer -->|"binds"| node_cli_launch
node_configs_layer -->|"binds"| node_cli_run
node_examples_layer -->|"defines"| node_core_wrap
node_skills_layer -->|"wraps"| node_cli_run

click node_cli_launch "https://github.com/sakanaai/shinkaevolve/tree/main/shinka/cli/shinka_launch"
click node_cli_run "https://github.com/sakanaai/shinkaevolve/tree/main/shinka/cli/shinka_run"
click node_cli_visualize "https://github.com/sakanaai/shinkaevolve/tree/main/shinka/cli/shinka_visualize"
click node_core_pipeline "https://github.com/sakanaai/shinkaevolve/tree/main/shinka/core"
click node_core_async "https://github.com/sakanaai/shinkaevolve/blob/main/shinka/core/async_runner.py"
click node_core_novelty "https://github.com/sakanaai/shinkaevolve/blob/main/shinka/core/novelty_judge.py"
click node_core_prompt "https://github.com/sakanaai/shinkaevolve/blob/main/shinka/core/prompt_evolver.py"
click node_core_wrap "https://github.com/sakanaai/shinkaevolve/blob/main/shinka/core/wrap_eval.py"
click node_edit_boundary "https://github.com/sakanaai/shinkaevolve/tree/main/shinka/edit"
click node_llm_layer "https://github.com/sakanaai/shinkaevolve/tree/main/shinka/llm"
click node_launch_layer "https://github.com/sakanaai/shinkaevolve/tree/main/shinka/launch"
click node_db_layer "https://github.com/sakanaai/shinkaevolve/tree/main/shinka/database"
click node_embed_layer "https://github.com/sakanaai/shinkaevolve/tree/main/shinka/embed"
click node_webui_layer "https://github.com/sakanaai/shinkaevolve/tree/main/shinka/webui"
click node_plots_layer "https://github.com/sakanaai/shinkaevolve/tree/main/shinka/plots"
click node_configs_layer "https://github.com/sakanaai/shinkaevolve/tree/main/shinka/configs"
click node_examples_layer "https://github.com/sakanaai/shinkaevolve/tree/main/examples"
click node_skills_layer "https://github.com/sakanaai/shinkaevolve/tree/main/skills"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli_launch,node_cli_run,node_cli_visualize toneBlue
class node_core_pipeline,node_core_async,node_core_novelty,node_core_prompt,node_core_wrap,node_edit_boundary toneAmber
class node_db_layer toneMint
class node_llm_layer,node_launch_layer,node_embed_layer toneRose
class node_webui_layer,node_plots_layer toneIndigo
class node_configs_layer,node_examples_layer,node_skills_layer toneTeal
```

## Components

### Runtime

Entry points and execution control

- [Launch CLI](https://github.com/sakanaai/shinkaevolve/tree/main/shinka/cli/shinka_launch): cli entrypoint · Hydra-based experiment launcher · `shinka/cli/shinka_launch`
- [Run CLI](https://github.com/sakanaai/shinkaevolve/tree/main/shinka/cli/shinka_run): task CLI · Task-directory runner for ad hoc and agent workflows · `shinka/cli/shinka_run`
- [Visualize CLI](https://github.com/sakanaai/shinkaevolve/tree/main/shinka/cli/shinka_visualize): webui entrypoint · Serves the browser UI for experiment inspection · `shinka/cli/shinka_visualize`

### Evolution engine

Core loop, mutation, evaluation, and prompt evolution

- [Core loop](https://github.com/sakanaai/shinkaevolve/tree/main/shinka/core): evolution orchestrator · Coordinates proposal generation, scheduling, timing, and evaluation · `shinka/core`
- [Async runner](https://github.com/sakanaai/shinkaevolve/blob/main/shinka/core/async_runner.py): throughput scheduler · Separates proposal, evaluation, and DB work for parallel throughput · `shinka/core/async_runner.py`
- [Novelty gate](https://github.com/sakanaai/shinkaevolve/blob/main/shinka/core/novelty_judge.py): novelty judge · Checks distinctness using similarity and optional LLM review · `shinka/core/novelty_judge.py`
- [Prompt evo](https://github.com/sakanaai/shinkaevolve/blob/main/shinka/core/prompt_evolver.py): prompt evolution · Evolves system prompts on a cadence · `shinka/core/prompt_evolver.py`
- [Eval wrapper](https://github.com/sakanaai/shinkaevolve/blob/main/shinka/core/wrap_eval.py): evaluation boundary · Runs task evaluators and normalizes scoring/feedback · `shinka/core/wrap_eval.py`
- [Edit apply](https://github.com/sakanaai/shinkaevolve/tree/main/shinka/edit): mutation applier · Turns proposals into executable candidates via diff or full-file edits · `shinka/edit`

### State and selection

Persistent archives, islands, parents, and novelty

- [Experiment DB](https://github.com/sakanaai/shinkaevolve/tree/main/shinka/database): persistent state · Stores archives, parents, inspirations, islands, and prompts · `shinka/database`

### Integrations

LLM providers, embeddings, and launch backends

- [LLM layer](https://github.com/sakanaai/shinkaevolve/tree/main/shinka/llm): provider abstraction · Provider-agnostic model access and routing · `shinka/llm`
- [Launch backends](https://github.com/sakanaai/shinkaevolve/tree/main/shinka/launch): execution launcher · Runs evaluators locally, under SLURM, or in containerized environments · `shinka/launch`
- [Embeddings](https://github.com/sakanaai/shinkaevolve/tree/main/shinka/embed): code similarity · Generates embeddings for novelty and similarity checks · `shinka/embed`

### Presentation

Web UI and offline plotting

- [Web UI](https://github.com/sakanaai/shinkaevolve/tree/main/shinka/webui): inspection UI · Interactive lineage, timing, cost, and comparison views · `shinka/webui`
- [Plots](https://github.com/sakanaai/shinkaevolve/tree/main/shinka/plots): offline visualization · Produces static charts for throughput, Pareto, similarity, and lineage · `shinka/plots`

### Config and examples

Hydra presets, sample tasks, and usage wrappers

- [Configs](https://github.com/sakanaai/shinkaevolve/tree/main/shinka/configs): hydra presets · Task, database, evolution, cluster, and variant presets · `shinka/configs`
- [Examples](https://github.com/sakanaai/shinkaevolve/tree/main/examples): tasks and demos · Sample tasks with seed programs and evaluators · `examples`
- [Skills](https://github.com/sakanaai/shinkaevolve/tree/main/skills): agent wrappers · Thin orchestration wrappers for setup, conversion, run, and inspection · `skills`

## Connections

- Launch CLI → Core loop: configures · Hydra launches the main evolution runner
- Run CLI → Async runner: starts · Task-directory CLI enters the async throughput path
- Visualize CLI → Web UI: serves · Starts the browser-based inspection UI
- Core loop → LLM layer: queries · Requests candidate proposals and prompt variants
- Core loop → Edit apply: mutates · Applies model output to produce candidate programs
- Core loop → Eval wrapper: evaluates · Wraps task-specific scoring and feedback
- Core loop → Experiment DB: persists · Writes archives, lineage, and selection state
- Core loop → Novelty gate: filters · Rejects or gates candidates by novelty
- Core loop → Prompt evo: adapts · Optionally evolves system prompts during the run
- Async runner → Launch backends: dispatches · Schedules out-of-process evaluator jobs
- Async runner → Experiment DB: streams · Decoupled worker writes and recovery handling
- Novelty gate → Embeddings: compares · Uses embeddings for similarity and diversity checks
- Experiment DB → Embeddings: indexes · Stores and samples with similarity-aware metadata
- Experiment DB → Core loop: feeds · Supplies parents, inspirations, and island sampling
- Launch backends → Eval wrapper: executes · Runs evaluators and task programs out-of-process
- Web UI → Experiment DB: reads · Visualizes lineage and state from experiment storage
- Plots → Experiment DB: analyzes · Generates offline summaries from stored runs
- Configs → Launch CLI: binds · Hydra presets assemble runnable experiments
- Configs → Run CLI: binds · Task configs and variants drive the task CLI
- Examples → Eval wrapper: defines · Each task supplies seed program and evaluate.py boundary
- Skills → Run CLI: wraps · Agent skills call into the same CLI and runner flow
