Metadata-Version: 2.5
Name: elution
Version: 0.2.0
Summary: Skills-native timer-bound research loop with BM25 memory for optimization work
Project-URL: Homepage, https://github.com/gdonninelli/elution
Project-URL: Repository, https://github.com/gdonninelli/elution
Author: Elution contributors
License: MIT
License-File: LICENSE
Keywords: agents,optimization,research,skills
Requires-Python: >=3.13
Provides-Extra: mcp
Provides-Extra: web
Description-Content-Type: text/markdown

# Elution — Timer-Bound AI Research Loop for Code Optimization

<p>
  <a href="https://github.com/gdonninelli/elution"><img alt="GitHub stars" src="https://img.shields.io/github/stars/gdonninelli/elution?style=flat-square"></a>
  <a href="https://github.com/gdonninelli/elution/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-green?style=flat-square"></a>
  <a href="https://www.python.org/downloads/"><img alt="Python 3.13" src="https://img.shields.io/badge/python-3.13-blue?style=flat-square&logo=python"></a>
  <img alt="Runtime: stdlib only" src="https://img.shields.io/badge/runtime-stdlib%20only-lightgrey?style=flat-square">
  <img alt="Version 0.2.0" src="https://img.shields.io/badge/version-0.2.0-amber?style=flat-square">
</p>

**Elution is a skills-native, timer-bound AI research loop with BM25 memory for benchmark-driven code optimization.** Type `/elution 120` in OpenCode, Claude Code, or Pi: subagents research → propose → review → implement → measure until the deadline.

Born for the **[Yukon](https://yukon.org) competition**, extensible to any repo with a measure script.

## Yukon result

Record-holder run on `matrices.fast` (sparse elimination ordering): **0.86136× cheapest ordering, rank 01/11.**

![Yukon matrices.fast result — gdonninelli record holder, 0.86136x, standing 01/11](assets/yukon-matrices-fast-result.png)

## Install

```bash
pip install git+https://github.com/gdonninelli/elution.git
# or: uv tool install git+https://github.com/gdonninelli/elution.git
# dev: uv sync --group dev
```

## Update

```bash
pip install -U git+https://github.com/gdonninelli/elution.git
# dev: git pull && uv sync --group dev
```

## Uninstall

```bash
pip uninstall elution
rm -rf .elution  # generated run state only
```

## Usage

```bash
elution init --minutes 120 --baseline 1.0 --direction minimize
elution search "sparse carry path" --top 8
elution add --kind knowledge --text "..." --source "https://..."
elution deadline   # running | expired — timer is the only stop rule
elution best --show
```

In your agent harness:

```text
/elution 120
```

How it works: researchers gather facts → lead proposes ONE change (after `search --top 8`) → reviewer approves/refines/rejects → coder makes the smallest diff → you measure (`yukon run` or your benchmark) → save to memory, repeat. Submit only on **>0.10% gain** over best-so-far, else once at deadline. Details: `skills/elution/SKILL.md`, `docs/features.md`, `examples/yukon-generic.md`.

> **For AI agents:** read [`AGENTS.md`](AGENTS.md) (repo guide) and [`AGENT.md`](AGENT.md) (quick pointer), then `skills/elution/SKILL.md`.

## License

MIT. See [`LICENSE`](LICENSE).
