evo-anything 0.1.0

package/README_EN.md

@@ -0,0 +1,321 @@
+# Evo-anything Plugin — Git-Based Evolutionary Code Optimizer
+
+Evo-anything is the engineering implementation of **"From Understanding to Excelling: Template-Free Algorithm Design through Structural-Functional Co-Evolution"** (arXiv:2503.10721). It applies LLM-driven **structural-functional co-evolution** to automatically optimize code in any git repository toward better benchmark performance.
+
+> **Paper:** Zhe Zhao, Haibin Wen, Pengkun Wang, Ye Wei, Zaixi Zhang, Xi Lin, Fei Liu, Bo An, Hui Xiong, Yang Wang, Qingfu Zhang. *From Understanding to Excelling: Template-Free Algorithm Design through Structural-Functional Co-Evolution.* arXiv:2503.10721 [cs.SE], 2025.
+
+## Installation
+
+### Prerequisites
+
+- Python >= 3.11
+- Git
+- GitHub CLI (`gh`) — required for `/hunt` to search repositories
+
+### Option 1: npm (recommended)
+
+```bash
+npm install -g evo-anything
+```
+
+This automatically installs the Python MCP server via `pip` during the npm postinstall step.
+
+After installation, configure your AI IDE:
+
+```bash
+# Configure all supported platforms (Claude Code, Cursor, Windsurf, OpenClaw)
+npx evo-anything setup
+
+# Or configure a specific platform
+npx evo-anything setup --platform claude
+npx evo-anything setup --platform cursor
+npx evo-anything setup --platform windsurf
+npx evo-anything setup --platform openclaw
+```
+
+---
+
+### Option 2: Manual
+
+#### Step 1: Install evo-engine (required for all platforms)
+
+```bash
+git clone https://github.com/DataLab-atom/Evo-anything.git
+cd Evo-anything/plugin/evo-engine
+pip install .
+```
+
+---
+
+### OpenClaw
+
+<details>
+<summary>CLI one-liner (recommended)</summary>
+
+```bash
+openclaw plugins install openclaw-evo
+openclaw gateway restart
+openclaw plugins doctor   # verify
+```
+
+</details>
+
+<details>
+<summary>Local development mode</summary>
+
+```bash
+openclaw plugins install -l ./plugin
+openclaw gateway restart
+```
+
+</details>
+
+<details>
+<summary>Manual install</summary>
+
+Copy the plugin to the extensions directory and register it in `~/.openclaw/openclaw.json`:
+
+```bash
+cp -r plugin/ ~/.openclaw/extensions/openclaw-evo/
+```
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "openclaw-evo": {
+        "enabled": true,
+        "config": {}
+      }
+    }
+  },
+  "mcpServers": {
+    "evo-engine": {
+      "command": "evo-engine",
+      "args": [],
+      "env": {}
+    }
+  }
+}
+```
+
+```bash
+openclaw gateway restart
+```
+
+</details>
+
+**Verify:** Type `/status` in a conversation. Seeing "Evolution not initialized" means the install succeeded.
+
+---
+
+### Claude Code
+
+Add the MCP server to your project root or global `.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "evo-engine": {
+      "command": "evo-engine",
+      "type": "stdio"
+    }
+  }
+}
+```
+
+Link skills to Claude Code:
+
+```bash
+ln -s $(pwd)/plugin/skills/* ~/.claude/skills/
+```
+
+Restart Claude Code and you're ready.
+
+---
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "evo-engine": {
+      "command": "evo-engine",
+      "type": "stdio"
+    }
+  }
+}
+```
+
+Cursor will auto-discover MCP tools (`evo_init`, `evo_next_batch`, etc.). Import skills as Cursor Rules manually:
+
+```bash
+cp plugin/AGENTS.md .cursor/rules/evo-agents.md
+```
+
+---
+
+### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "evo-engine": {
+      "command": "evo-engine",
+      "type": "stdio"
+    }
+  }
+}
+```
+
+---
+
+### Any Other MCP-Compatible Client
+
+Evo-anything's core is a standard [MCP](https://modelcontextprotocol.io) server. Any client that supports MCP stdio transport can connect:
+
+```bash
+# Start the server directly (stdio mode)
+evo-engine
+
+# Or run as a Python module
+python -m plugin.evo-engine.server
+```
+
+Available MCP tools: `evo_init`, `evo_register_targets`, `evo_next_batch`, `evo_report_fitness`, `evo_select_survivors`, `evo_get_status`, `evo_get_lineage`, `evo_freeze_target`, `evo_boost_target`, `evo_record_synergy`, `evo_check_cache`.
+
+---
+
+### Optional Configuration
+
+Evolution state is stored in `~/.openclaw/evo-state/` by default. Override with an environment variable (`U2E` stands for *Understanding to Excelling*, the paper's acronym):
+
+```bash
+export U2E_STATE_DIR=/path/to/your/state
+```
+
+Or configure via `openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "openclaw-evo": {
+        "enabled": true,
+        "config": {
+          "statePath": "/path/to/your/state"
+        }
+      }
+    }
+  }
+}
+```
+
+## Quick Start
+
+```
+You send: I want SOTA on CIFAR-100-LT
+         ↓
+  /hunt triggers automatically
+         ↓
+  Searches GitHub → finds 3 candidates → asks which one
+         ↓
+  You say: use #1
+         ↓
+  clone → pip install → download data → run baseline to confirm it works
+         ↓
+  Automatically calls /evolve → evolution loop begins
+         ↓
+  Progress report after each generation
+         ↓
+  Pushes best branch + sends final report when done
+```
+
+## How It Works
+
+Evo-anything implements the **U2E (Understanding to Excelling) protocol** proposed in the paper — a template-free, two-dimensional co-evolution framework. Unlike EoH and FunSearch, which rely on predefined templates and optimize only local key functions, U2E performs global joint optimization across both the **functional dimension** (algorithm logic) and the **structural dimension** (code architecture).
+
+Every experiment is tracked as a git branch. The evolution loop has six stages:
+
+1. **Analysis** — automatically identify key algorithm modules worth optimizing
+2. **Planning** — decide mutation/crossover strategy and variant counts; adaptively allocate budget by temperature per target
+3. **Generation** — LLM generates code variants (mutation: single-parent refinement; crossover: two-parent combination)
+4. **Evaluation** — run benchmarks in isolated git worktrees
+5. **Selection** — keep the best, discard the rest; run cross-target Synergy checks every N generations
+6. **Reflection** — extract lessons into structured memory to guide future evolution
+
+The best result of each generation is tagged (`best-gen-{N}`), and the final `best-overall` branch is pushed.
+
+### Comparison with Prior Work
+
+| Method | Template Required | Optimization Scope | Structural Evolution |
+|--------|------------------|--------------------|----------------------|
+| EoH / FunSearch | Yes (predefined) | Local functions | No |
+| **Evo-anything (U2E)** | **No** | **Global multi-target** | **Functional + Structural co-evolution** |
+
+## Skills
+
+| Command | Description |
+|---------|-------------|
+| `/hunt <task description>` | Search GitHub for a suitable repo, auto clone/install/baseline, then start evolution |
+| `/evolve <repo> <benchmark_cmd>` | Start an evolutionary optimization loop on a given repo |
+| `/status` | Check current evolution progress |
+| `/report` | Generate a full evolution report |
+| `/boost <target_id>` | Increase the priority of an optimization target |
+| `/freeze <target_id>` | Freeze a target, stopping evolution on it |
+
+## Repository Structure
+
+```
+Evo-anythin/
+├── LICENSE
+├── README.md
+├── README_EN.md
+└── plugin/
+    ├── openclaw.plugin.json   # plugin definition
+    ├── AGENTS.md              # evolution protocol (core loop)
+    ├── SOUL.md                # agent persona
+    ├── TOOLS.md               # tool usage conventions
+    ├── evo-engine/            # evolution engine (MCP server)
+    │   ├── server.py          # MCP tool interface
+    │   ├── models.py          # data models
+    │   └── selection.py       # selection algorithms
+    └── skills/                # user-invocable skills
+        ├── hunt/              # search and deploy a codebase
+        ├── evolve/            # start evolution loop
+        ├── status/            # check progress
+        ├── report/            # generate report
+        ├── boost/             # boost target priority
+        └── freeze/            # freeze a target
+```
+
+## Evolution Memory
+
+Evo-anything maintains structured memory in the target repository to avoid repeating failed attempts:
+
+```
+memory/
+├── global/long_term.md           — cross-target lessons
+├── targets/{id}/
+│   ├── short_term/gen_{N}.md     — per-generation reflection
+│   ├── long_term.md              — accumulated wisdom for this target
+│   └── failures.md               — what NOT to try again
+└── synergy/records.md            — cross-function combination results
+```
+
+## Branch Naming
+
+```
+gen-{N}/{target_id}/{op}-{V}             # single-target variant
+gen-{N}/synergy/{targetA}+{targetB}-{V}  # cross-target combination
+```
+
+Tags: `seed-baseline`, `best-gen-{N}`, `best-overall`
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "evo-anything",
+  "version": "0.1.0",
+  "description": "Git-based evolutionary algorithm design engine. Evolves code via LLM-driven mutation, crossover, and reflection on any git repository.",
+  "keywords": [
+    "ai",
+    "evolutionary-algorithm",
+    "mcp",
+    "llm",
+    "code-optimization",
+    "openclaw",
+    "claude"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DataLab-atom/Evo-anything.git"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "bin": {
+    "evo-anything": "scripts/cli.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "files": [
+    "plugin/",
+    "scripts/",
+    "README.md",
+    "README_EN.md"
+  ]
+}

package/plugin/AGENTS.md

@@ -0,0 +1,89 @@
+# U2E Evolution Protocol
+
+You are the orchestrator of a git-based evolutionary algorithm design engine.
+
+## Overview
+
+You evolve code in a target git repository by running generations of:
+1. **Analysis** — identify which functions to optimize (MapAgent role)
+2. **Planning** — decide operation types and variant counts per target (PlanAgent role)
+3. **Generation** — create code variants via mutation or crossover (CodeGenAgent role)
+4. **Evaluation** — run benchmarks in isolated git worktrees (DevAgent role)
+5. **Selection** — keep the best, eliminate the rest
+6. **Reflection** — extract lessons, update memory (ReflectAgent role)
+
+## Core Loop
+
+```
+Call evo_init → set up evolution state
+Call evo_register_targets → define what to optimize
+
+WHILE evo_get_status shows budget remaining:
+  1. Call evo_next_batch → get [{branch, op, target, parents}]
+  2. For each operation:
+     a. git checkout -b <branch> from parent
+     b. Read target function code
+     c. Read memory/ for this target (long_term + failures)
+     d. Generate variant (mutate or crossover via LLM)
+     e. Write code change, git commit
+  3. For each branch to evaluate:
+     a. git worktree add <path> <branch>
+     b. Run benchmark command in worktree
+     c. Parse fitness from output
+     d. Call evo_report_fitness with result
+     e. git worktree remove <path>
+  4. Call evo_select_survivors → get keep/eliminate lists
+  5. Delete eliminated branches
+  6. Tag best: git tag best-gen-{N}
+  7. Reflect:
+     a. git diff best..second_best → short-term reflection
+     b. Write to memory/targets/{id}/short_term/gen_{N}.md
+     c. Synthesize long_term.md from accumulated short_term
+     d. Record failures to memory/targets/{id}/failures.md
+  8. Every 3 generations: synergy check
+     a. Cherry-pick best of each target into one branch
+     b. Evaluate combined fitness
+     c. Record synergy results
+```
+
+## Memory Layout
+
+```
+memory/
+├── global/long_term.md           — cross-target lessons
+├── targets/{id}/
+│   ├── short_term/gen_{N}.md     — per-generation reflection
+│   ├── long_term.md              — accumulated wisdom for this target
+│   └── failures.md               — what NOT to try again
+└── synergy/records.md            — cross-function combination results
+```
+
+Write memory as Markdown. Be specific: include generation numbers, fitness values, and what changed.
+
+## Branch Naming
+
+```
+gen-{N}/{target_id}/{op}-{V}
+gen-{N}/synergy/{targetA}+{targetB}-{V}
+```
+
+Tags: `seed-baseline`, `best-gen-{N}`, `best-overall`
+
+## Evaluation Protocol
+
+1. **Static check** — read generated code, fix obvious issues (missing imports, syntax errors). Do NOT fix algorithm logic.
+2. **Quick eval** — if quick_cmd is configured, run it first to filter obvious failures.
+3. **Full eval** — run full benchmark only on candidates that pass quick eval.
+
+If a variant crashes:
+- Read the traceback
+- If it's a trivial fix (missing import, typo, type mismatch): fix it, re-commit, re-evaluate
+- If it's an algorithm logic error: mark as failed, record in failures.md
+
+## Constraints
+
+- NEVER modify the benchmark command or evaluation script
+- NEVER change function signatures — only change function bodies
+- NEVER edit files outside the declared optimization targets
+- Always commit before evaluating (so the branch captures the exact code)
+- Always clean up worktrees after evaluation

package/plugin/SOUL.md

@@ -0,0 +1,7 @@
+You are an expert algorithm engineer running an evolutionary code optimization engine.
+
+You operate on git repositories. You evolve code by iterating through generations of mutation, crossover, and reflection — all tracked as git branches.
+
+You are methodical, data-driven, and never guess. You read code before changing it. You check fitness before claiming improvement. You record every experiment.
+
+When speaking to the user, be concise and direct. Report numbers, not feelings.

package/plugin/TOOLS.md

@@ -0,0 +1,32 @@
+# Tool Usage Conventions
+
+## evo-engine MCP tools
+
+All deterministic evolution bookkeeping goes through the `evo_*` MCP tools.
+Never manually track population state — always call the tool.
+
+- `evo_init` — call once at the start to initialize evolution state
+- `evo_register_targets` — register optimization targets identified by code analysis
+- `evo_next_batch` — get the next set of branch operations to execute
+- `evo_report_fitness` — report benchmark results back after evaluation
+- `evo_select_survivors` — run selection algorithm, get keep/eliminate lists
+- `evo_get_status` — check current evolution progress
+- `evo_get_lineage` — trace how a branch evolved
+- `evo_freeze_target` / `evo_boost_target` — manual priority control
+
+## Git operations
+
+Use `exec` to run git commands directly. Key patterns:
+- `git worktree add <path> <branch>` — create isolated evaluation directory
+- `git worktree remove <path>` — clean up after evaluation
+- `git checkout -b <branch>` — create variant branch
+- `git diff <a>..<b>` — compare two variants (feed to reflection)
+- `git cherry-pick` — combine best parts from different branches
+
+## Code operations
+
+Use `read` / `edit` / `write` for code changes. Never blindly generate — always read the target function first, understand its context, then modify.
+
+## Benchmark
+
+Use `exec` to run the user's benchmark command inside a worktree. Always capture both stdout and stderr.

package/plugin/evo-engine/models.py

@@ -0,0 +1,103 @@
+"""Data models for evolution state."""
+
+from __future__ import annotations
+from enum import Enum
+from pydantic import BaseModel, Field
+from typing import Optional
+import time
+
+
+class Objective(str, Enum):
+    MIN = "min"
+    MAX = "max"
+
+
+class Operation(str, Enum):
+    MUTATE = "mutate"
+    CROSSOVER = "crossover"
+    SYNERGY = "synergy"
+
+
+class TargetStatus(str, Enum):
+    ACTIVE = "active"
+    FROZEN = "frozen"
+
+
+class Target(BaseModel):
+    """An optimization target (a function to evolve)."""
+    id: str
+    file: str
+    function: str
+    lines: str = ""
+    impact: str = "medium"
+    description: str = ""
+    status: TargetStatus = TargetStatus.ACTIVE
+    temperature: float = 1.0  # explore/exploit control
+    current_best_obj: Optional[float] = None
+    current_best_branch: Optional[str] = None
+    stagnation_count: int = 0  # generations without improvement
+
+
+class Individual(BaseModel):
+    """A single code variant living on a git branch."""
+    branch: str
+    generation: int
+    target_id: str
+    operation: Operation
+    parent_branches: list[str] = Field(default_factory=list)
+    fitness: Optional[float] = None
+    success: bool = False
+    code_hash: Optional[str] = None
+    raw_output: Optional[str] = None
+    timestamp: float = Field(default_factory=time.time)
+
+
+class BatchItem(BaseModel):
+    """A single operation to execute in the next batch."""
+    branch: str
+    operation: Operation
+    target_id: str
+    parent_branches: list[str]
+    target_file: str
+    target_function: str
+
+
+class SurvivorResult(BaseModel):
+    """Result of selection: who lives, who dies."""
+    keep: list[str]
+    eliminate: list[str]
+    best_branch: str
+    best_obj: float
+
+
+class EvolutionConfig(BaseModel):
+    """Configuration for an evolution run."""
+    repo_path: str
+    benchmark_cmd: str
+    objective: Objective = Objective.MIN
+    max_fe: int = 500
+    pop_size: int = 8
+    mutation_rate: float = 0.5
+    synergy_interval: int = 3
+    top_k_survive: int = 5
+    quick_cmd: Optional[str] = None
+
+
+class EvolutionState(BaseModel):
+    """Full state of an evolution run, persisted to disk."""
+    config: EvolutionConfig
+    generation: int = 0
+    total_evals: int = 0
+    seed_obj: Optional[float] = None
+    seed_branch: str = "seed-baseline"
+    best_obj_overall: Optional[float] = None
+    best_branch_overall: Optional[str] = None
+    targets: dict[str, Target] = Field(default_factory=dict)
+    # All individuals ever created, keyed by branch name
+    individuals: dict[str, Individual] = Field(default_factory=dict)
+    # Active branches per target (alive in current population)
+    active_branches: dict[str, list[str]] = Field(default_factory=dict)
+    # Fitness cache: code_hash -> fitness
+    fitness_cache: dict[str, float] = Field(default_factory=dict)
+    # Synergy records
+    synergy_records: list[dict] = Field(default_factory=list)

package/plugin/evo-engine/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "openclaw-evo-engine"
+version = "0.1.0"
+description = "MCP server for Evo-anything evolutionary algorithm bookkeeping"
+requires-python = ">=3.11"
+dependencies = [
+    "mcp>=1.0",
+    "pydantic>=2.0",
+]
+
+[project.scripts]
+evo-engine = "server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"