Metadata-Version: 2.4
Name: easyevolve
Version: 0.1.0b2
Summary: Give us an evaluator. We'll evolve the code.
Project-URL: Homepage, https://easyevolve.dev
Project-URL: Documentation, https://easyevolve.dev/docs
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: httpx<1,>=0.28
Requires-Dist: pydantic<3,>=2.10
Description-Content-Type: text/markdown

# EasyEvolve

**Give us an evaluator. We'll evolve the code.**

EasyEvolve is a hosted API that improves Python code with LLM-driven evolutionary search.
You write a function that scores a candidate program; the service generates, mutates and
evaluates candidates in isolated sandboxes and returns the best one.

> **Invite-only beta.** You need an invite token from the EasyEvolve team.
> The API, pricing and limits may change, and data may be reset during the beta.

## Install

```sh
pip install --pre easyevolve
```

Python 3.11 or later.

## Sign in with your invite token

```sh
easyevolve login
```

Paste the token when prompted. It is stored at `~/.config/easyevolve/credentials.json`
with owner-only permissions. You can also set `EASYEVOLVE_TOKEN` instead.

## Write an evaluator

Expose `evaluate(candidate_path: str) -> dict` returning a finite `score` (higher is better).
Use the Python standard library only.

```python
# eval.py
"""Candidate contract: solve(values: list[int]) -> list[int], sorted ascending."""
import importlib.util


def evaluate(candidate_path: str) -> dict:
    spec = importlib.util.spec_from_file_location("candidate", candidate_path)
    candidate = importlib.util.module_from_spec(spec)
    spec.loader.exec_module(candidate)
    cases = [[], [1], [3, 1, 2], [5, -1, 5, 0], list(range(30, 0, -1))]
    passed = sum(candidate.solve(values.copy()) == sorted(values) for values in cases)
    return {"score": passed / len(cases)}
```

## Run

```python
from easyevolve import EasyEvolve

with EasyEvolve(evaluator="eval.py") as client:
    print(client.estimate(iterations=5, level="low", budget=0.5))
    result = client.run(iterations=5, level="low", budget=0.5)
    print(result.best_score, result.cost)
    print(result.best_code)
```

Or from the terminal:

```sh
easyevolve balance
easyevolve run eval.py --iterations 5 --level low --budget 0.5
```

`budget` (USD) is a hard cap: the run stops before it would exceed it, and unused budget
returns to your balance. A client timeout does not stop the job; use
`client.resume(job_id)` to reconnect or `easyevolve cancel <job_id>` to stop it.

Documentation: <https://easyevolve.dev/docs>
