# pi-evolve

Evolutionary self-improvement for Pi. Inspired by **AlphaEvolve** (DeepMind), **Sakana AI's ShinkaEvolve**, and the **Darwin Gödel Machine**.

Mutate → Evaluate → Select → Archive → Repeat.

## Install

```bash
pi install npm:@artale/pi-evolve
```

## What it does

Applies evolutionary algorithms to anything the agent works with:
- **Skills** (SKILL.md files) — compress, restructure, improve
- **Prompts** — evolve system prompts for better output
- **Extensions** — optimize code for size + quality
- **Any text file** — evolutionary improvement of anything

## Commands

```
/evolve <file>                    — quick evolution (3 variants)
/evolve status                    — show evolution state
/evolve archive                   — list all variants with scores
/evolve restore <id>              — restore a variant
/evolve compare <a> <b>           — diff two variants
/mutate <file> [goal]             — single mutation pass (3 strategies)
/darwin <file> [gens] [goal]      — full evolutionary loop
```

## Mutation strategies

| Strategy | What it does |
|----------|-------------|
| **compress** | Reduce size 30-50% while preserving all functionality |
| **quality** | Improve effectiveness at similar length |
| **hybrid** | Both shorter AND better (Pareto optimization) |
| **radical** | Completely reimagine structure (divergent exploration) |

## Darwin mode

Full evolutionary loop with multiple generations:

```
/darwin SKILL.md 10 optimize for token efficiency
```

This runs 10 generations, each producing 3 variants (compress, quality, radical), evaluating fitness, selecting the best, and using it as the parent for the next generation.

## Results (from our GEPA predecessor)

Tested on real Pi skills:
- `canvas-design`: **−69% tokens**, same quality
- `pptx`: **−60% tokens**, same quality
- `xlsx`: **−63% tokens**, same quality

## Tools

- `evolve_archive` — save a variant with fitness score
- `evolve_status` — show archive stats
- `evolve_list` — list all variants
- `evolve_restore` — restore a variant to its file

## Architecture

```
/darwin SKILL.md 5
  │
  ├─ Gen 0: Archive original (baseline fitness 50)
  │
  ├─ Gen 1: Mutate × 3 strategies → Evaluate → Select best
  │           compress: 65/100 (−40% tokens)
  │           quality:  58/100 (better structure)
  │           radical:  42/100 (too divergent)
  │           → Winner: compress (65)
  │
  ├─ Gen 2: Mutate winner × 3 → Evaluate → Select
  │           → Winner: hybrid (72)
  │
  └─ Gen 5: Converged at 78/100, −55% tokens
```

All variants archived with fitness scores, token counts, and lineage tracking.

## Inspired by

- [AlphaEvolve](https://deepmind.google/discover/blog/alphaevolve/) — DeepMind's Gemini-powered evolutionary coding agent
- [ShinkaEvolve](https://github.com/SakanaAI/ShinkaEvolve) — Sakana AI's sample-efficient program evolution
- [Darwin Gödel Machine](https://sakana.ai/dgm/) — Self-improving coding agent via evolution
- [OpenEvolve](https://github.com/codelion/openevolve) — Open-source AlphaEvolve reimplementation

## Zero dependencies

Node.js built-ins only. The LLM itself is the mutation operator.

## License

MIT