easyevolve 0.1.0b2__tar.gz

easyevolve-0.1.0b2/.gitignore

@@ -0,0 +1,12 @@
+.env
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+dist/
+.data/
+*.db
+.DS_Store
+node_modules/

easyevolve-0.1.0b2/PKG-INFO

@@ -0,0 +1,87 @@
+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>

easyevolve-0.1.0b2/README.md

@@ -0,0 +1,72 @@
+# 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>

easyevolve-0.1.0b2/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "easyevolve"
+version = "0.1.0b2"
+description = "Give us an evaluator. We'll evolve the code."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = ["httpx>=0.28,<1", "pydantic>=2.10,<3"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+
+[project.urls]
+Homepage = "https://easyevolve.dev"
+Documentation = "https://easyevolve.dev/docs"
+
+[project.scripts]
+easyevolve = "easyevolve.cli:main"
+
+# The SDK source lives in ../src so the service and SDK stay one tested codebase.
+# Metadata 2.4 is accepted by every current uploader and index.
+[tool.hatch.build.targets.sdist]
+core-metadata-version = "2.4"
+
+[tool.hatch.build.targets.sdist.force-include]
+"../src/easyevolve" = "src/easyevolve"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/easyevolve"]
+core-metadata-version = "2.4"

easyevolve-0.1.0b2/src/easyevolve/__init__.py

@@ -0,0 +1,3 @@
+from .client import EasyEvolve, EasyEvolveError, EvolutionResult
+
+__all__ = ["EasyEvolve", "EasyEvolveError", "EvolutionResult"]

easyevolve-0.1.0b2/src/easyevolve/cli.py

@@ -0,0 +1,58 @@
+import argparse
+import getpass
+import sys
+from pathlib import Path
+
+from .client import EasyEvolve, EasyEvolveError
+
+
+def main():
+    try:
+        run_command()
+    except EasyEvolveError as exc:
+        job = f" (job {exc.result.id})" if exc.result else ""
+        sys.exit(f"Error{job}: {exc}")
+
+
+def run_command():
+    parser = argparse.ArgumentParser(description="EasyEvolve hosted code evolution")
+    parser.add_argument("--api-url")
+    commands = parser.add_subparsers(dest="command", required=True)
+    run = commands.add_parser("run")
+    run.add_argument("evaluator")
+    run.add_argument("--task")
+    run.add_argument("--budget", default="2.00")
+    run.add_argument("--iterations", type=int, default=100)
+    run.add_argument("--level", choices=["low", "middle", "high"], default="middle")
+    run.add_argument("--output", default="best.py")
+    resume = commands.add_parser("resume")
+    resume.add_argument("job_id")
+    resume.add_argument("--output", default="best.py")
+    cancel = commands.add_parser("cancel")
+    cancel.add_argument("job_id")
+    commands.add_parser("balance")
+    commands.add_parser("login", help="Save an invite token (read from stdin or a prompt)")
+    args = parser.parse_args()
+    if args.command == "login":
+        token = sys.stdin.readline() if not sys.stdin.isatty() else getpass.getpass("Token: ")
+        with EasyEvolve(base_url=args.api_url) as client:
+            available = client.login(token)
+        print(f"Saved token. Available credit: ${available}")
+        return
+    with EasyEvolve(
+        getattr(args, "evaluator", None), task=getattr(args, "task", None), base_url=args.api_url
+    ) as client:
+        if args.command == "balance":
+            print(f"Available credit: ${client.balance()}")
+            return
+        if args.command == "cancel":
+            print(client.cancel(args.job_id))
+            return
+        result = (
+            client.run(iterations=args.iterations, level=args.level, budget=args.budget)
+            if args.command == "run"
+            else client.resume(args.job_id)
+        )
+        if result.best_code is not None:
+            Path(args.output).write_text(result.best_code)
+        print(f"{result.status}: best score={result.best_score}, cost=${result.cost}")

easyevolve-0.1.0b2/src/easyevolve/client.py

@@ -0,0 +1,255 @@
+import os
+import secrets
+import time
+import uuid
+import webbrowser
+from collections.abc import Callable
+from decimal import ROUND_CEILING, Decimal
+from pathlib import Path
+from urllib.parse import urlparse
+
+import httpx
+from pydantic import BaseModel
+
+from .credentials import Credentials
+
+TERMINAL = {"COMPLETED", "FAILED", "CANCELLED", "BUDGET_EXHAUSTED"}
+
+
+class EvolutionResult(BaseModel):
+    id: str
+    status: str
+    best_code: str | None
+    best_score: float | None
+    initial_score: float | None
+    cost: Decimal
+    budget: Decimal
+    completed_iterations: int
+    error: str | None = None
+    history: list[dict] = []
+
+
+class EasyEvolveError(RuntimeError):
+    def __init__(
+        self, message: str, status_code: int | None = None, result: EvolutionResult | None = None
+    ):
+        super().__init__(message)
+        self.status_code = status_code
+        self.result = result
+
+
+class EasyEvolve:
+    def __init__(
+        self,
+        evaluator: str | Path | None = None,
+        *,
+        task: str | None = None,
+        initial_code: str | None = None,
+        base_url: str | None = None,
+        token: str | None = None,
+        credentials_path: str | Path | None = None,
+        poll_interval: float = 2.0,
+        client: httpx.Client | None = None,
+    ):
+        self.evaluator = Path(evaluator) if evaluator is not None else None
+        self.task = task
+        self.initial_code = initial_code
+        self.base_url = (
+            base_url or os.environ.get("EASYEVOLVE_API_URL") or "https://api.easyevolve.dev"
+        ).rstrip("/")
+        parsed = urlparse(self.base_url)
+        if parsed.scheme != "https" and not (
+            parsed.scheme == "http" and parsed.hostname in {"localhost", "127.0.0.1", "::1"}
+        ):
+            raise ValueError("Use HTTPS, or HTTP on localhost for development")
+        if poll_interval < 0:
+            raise ValueError("poll_interval must be nonnegative")
+        self.credentials = Credentials(self.base_url, credentials_path)
+        self.token = (
+            token or os.environ.get("EASYEVOLVE_TOKEN") or self.credentials.read().get("token")
+        )
+        self.poll_interval = poll_interval
+        self.client = client or httpx.Client(base_url=self.base_url, timeout=30)
+        self.owns_client = client is None
+        self.job_id: str | None = None
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *_):
+        self.close()
+
+    def close(self):
+        if self.owns_client:
+            self.client.close()
+
+    def request(self, method: str, path: str, **kwargs) -> dict:
+        headers = kwargs.pop("headers", {})
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+        try:
+            response = self.client.request(method, path, headers=headers, **kwargs)
+        except httpx.HTTPError as exc:
+            raise EasyEvolveError(
+                f"API connection failed. Resume job {self.job_id} if one was created."
+            ) from exc
+        if response.is_error:
+            try:
+                detail = response.json().get("detail", "API request failed")
+            except ValueError:
+                detail = "API request failed"
+            raise EasyEvolveError(str(detail), response.status_code)
+        return response.json() if response.content else {}
+
+    def estimate(self, *, iterations: int = 100, level: str = "middle", budget=2.0) -> dict:
+        return self.request(
+            "POST",
+            "/v1/estimate",
+            json={
+                "iterations": iterations,
+                "level": level,
+                "budget": str(budget),
+            },
+        )
+
+    def balance(self) -> Decimal:
+        return Decimal(self.request("GET", "/v1/billing/balance")["available"])
+
+    def purchase_credits(self, amount=5.0, *, open_browser: bool = True, timeout: float = 900):
+        stored = self.credentials.read()
+        pending = stored.get("pending_checkout")
+        if pending is None:
+            pending = self.request("POST", "/v1/auth/checkout", json={"amount": str(amount)})
+            pending["device_token"] = "ee_" + secrets.token_urlsafe(32)
+            self.credentials.write({**stored, "pending_checkout": pending})
+        print(f"Payment required. Complete Stripe Checkout:\n{pending['url']}")
+        if open_browser:
+            webbrowser.open(pending["url"])
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            claimed = self.request(
+                "POST",
+                f"/v1/auth/checkout/{pending['checkout_id']}/claim",
+                json={
+                    "claim_token": pending["claim_token"],
+                    "device_token": pending["device_token"],
+                },
+            )
+            if claimed["status"] == "paid":
+                self.token = claimed["token"]
+                self.credentials.write({"token": self.token})
+                return
+            time.sleep(max(self.poll_interval, 0.1))
+        raise EasyEvolveError(
+            "Checkout timed out. Call purchase_credits again to resume this checkout."
+        )
+
+    def submit(
+        self,
+        *,
+        iterations: int = 100,
+        level: str = "middle",
+        budget=2.0,
+        idempotency_key: str | None = None,
+    ) -> str:
+        if self.evaluator is None:
+            raise ValueError("evaluator is required to submit a new job")
+        body = {
+            "evaluator": self.evaluator.read_text(encoding="utf-8"),
+            "task": self.task,
+            "initial_code": self.initial_code,
+            "iterations": iterations,
+            "level": level,
+            "budget": str(budget),
+        }
+        key = idempotency_key or str(uuid.uuid4())
+        # POST is safe to retry with the same key if the response was lost.
+        for attempt in range(2):
+            try:
+                job = self.request("POST", "/v1/jobs", json=body, headers={"Idempotency-Key": key})
+                self.job_id = job["id"]
+                print(f"Job ID: {self.job_id}")
+                return self.job_id
+            except EasyEvolveError as exc:
+                if exc.status_code is not None or attempt:
+                    raise
+        raise AssertionError("Unreachable")
+
+    def progress(self, job_id: str) -> dict:
+        return self.request("GET", f"/v1/jobs/{job_id}")
+
+    def result(self, job_id: str) -> EvolutionResult:
+        return EvolutionResult.model_validate(self.request("GET", f"/v1/jobs/{job_id}/result"))
+
+    def cancel(self, job_id: str | None = None) -> dict:
+        job_id = job_id or self.job_id
+        if not job_id:
+            raise ValueError("job_id is required")
+        return self.request("POST", f"/v1/jobs/{job_id}/cancel")
+
+    def resume(
+        self,
+        job_id: str,
+        *,
+        timeout: float | None = None,
+        on_progress: Callable[[dict], None] | None = None,
+    ) -> EvolutionResult:
+        self.job_id = job_id
+        start = time.monotonic()
+        last = None
+        while True:
+            job = self.progress(job_id)
+            if job != last and on_progress:
+                on_progress(job)
+            last = job
+            if job["status"] in TERMINAL:
+                result = self.result(job_id)
+                if result.status == "FAILED":
+                    raise EasyEvolveError(result.error or "Evolution failed", result=result)
+                return result
+            if timeout is not None and time.monotonic() - start >= timeout:
+                raise TimeoutError(f"Job {job_id} is still running; reconnect with resume(job_id)")
+            time.sleep(self.poll_interval)
+
+    def run(
+        self,
+        *,
+        iterations: int = 100,
+        level: str = "middle",
+        budget=2.0,
+        auto_checkout: bool = True,
+        timeout: float | None = None,
+        on_progress: Callable[[dict], None] | None = None,
+    ) -> EvolutionResult:
+        estimate = self.estimate(iterations=iterations, level=level, budget=budget)
+        print(f"Estimated cap: ${estimate['estimated_cost']}\nMaximum budget: ${budget}")
+        if auto_checkout and (self.token is None or self.balance() < Decimal(str(budget))):
+            amount = max(Decimal("5"), Decimal(str(budget))).quantize(
+                Decimal("0.01"), rounding=ROUND_CEILING
+            )
+            self.purchase_credits(amount)
+        job_id = self.submit(iterations=iterations, level=level, budget=budget)
+
+        def display(job):
+            print(
+                f"{job['status']} | Iteration {job['completed_iterations']}/{job['iterations']} "
+                f"| Best score: {job['best_score']} | Cost: ${job['cost']}"
+            )
+
+        return self.resume(job_id, timeout=timeout, on_progress=on_progress or display)
+
+    def login(self, token: str) -> Decimal:
+        """Verify an invite token and store it for this API origin."""
+        self.token = token.strip()
+        available = self.balance()
+        self.credentials.write({"token": self.token})
+        return available
+
+    def rotate_token(self):
+        self.token = self.request("POST", "/v1/auth/token/rotate")["token"]
+        self.credentials.write({"token": self.token})
+
+    def revoke_token(self):
+        self.request("POST", "/v1/auth/token/revoke")
+        self.token = None
+        self.credentials.write({})

easyevolve-0.1.0b2/src/easyevolve/credentials.py

@@ -0,0 +1,35 @@
+import json
+import os
+import tempfile
+from pathlib import Path
+
+
+class Credentials:
+    def __init__(self, base_url: str, path: str | Path | None = None):
+        self.url = base_url.rstrip("/")
+        self.path = (
+            Path(path)
+            if path
+            else Path(os.environ.get("XDG_CONFIG_HOME", str(Path.home() / ".config")))
+            / "easyevolve"
+            / "credentials.json"
+        )
+
+    def read(self) -> dict:
+        if not self.path.exists():
+            return {}
+        return json.loads(self.path.read_text()).get(self.url, {})
+
+    def write(self, data: dict):
+        self.path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+        entries = json.loads(self.path.read_text()) if self.path.exists() else {}
+        entries[self.url] = data
+        fd, temporary = tempfile.mkstemp(dir=self.path.parent)
+        try:
+            os.fchmod(fd, 0o600)
+            with os.fdopen(fd, "w") as output:
+                json.dump(entries, output)
+            os.replace(temporary, self.path)
+        finally:
+            if os.path.exists(temporary):
+                os.unlink(temporary)