autoevolve-cli 0.1.0__tar.gz

autoevolve_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  UV_FROZEN: "1"
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Sync dependencies
+        run: make sync
+
+      - name: Run checks
+        run: make check

autoevolve_cli-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/autoevolve-cli
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: make sync
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

autoevolve_cli-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

autoevolve_cli-0.1.0/.python-version

@@ -0,0 +1 @@
+3.10

autoevolve_cli-0.1.0/Makefile

@@ -0,0 +1,31 @@
+.PHONY: sync
+sync:
+	uv sync
+
+.PHONY: format
+format:
+	uv run ruff format .
+	uv run ruff check --fix .
+
+.PHONY: format-check
+format-check:
+	uv run ruff format --check .
+
+.PHONY: lint
+lint:
+	uv run ruff check .
+
+.PHONY: typecheck
+typecheck:
+	uv run mypy src
+
+.PHONY: test
+test:
+	uv run pytest -q
+
+.PHONY: build
+build:
+	uv build
+
+.PHONY: check
+check: format-check lint typecheck test

autoevolve_cli-0.1.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: autoevolve-cli
+Version: 0.1.0
+Summary: Git-backed experiment loops for coding agents
+Requires-Python: >=3.10
+Requires-Dist: gitpython>=3.1.46
+Requires-Dist: rich>=14
+Requires-Dist: textual>=1
+Requires-Dist: typer>=0.24.1
+Description-Content-Type: text/markdown
+
+# autoevolve
+
+![screenshot](./assets/screenshot.png)
+
+`autoevolve` lets coding agents run git-backed experiment loops autonomously. It gives agents a lightweight workflow for branching, recording results, and comparing experiments without needing heavy external dependencies, databases, or services.
+
+Run it inside an existing project, let it set up the files your coding agent needs, and then let the agent iterate through experiments, branch into new research directions, and explore ideas on its own.
+
+## Install
+
+```bash
+pip install autoevolve-cli
+```
+
+## Quickstart
+
+**1. Initialize `autoevolve` in an existing git repo**:
+
+```bash
+autoevolve init
+```
+
+`autoevolve init` walks you through the setup for your coding harness and problem:
+
+- `SKILL.md` or `PROGRAM.md`: the instructions your coding agent reads to use `autoevolve`
+- `PROBLEM.md`: the goal, metric, constraints, and validation setup for your problem
+
+For an example problem to try, see the [circle packing example repo](https://github.com/wiskojo/autoevolve-circle-packing-example).
+
+**2. Tell your agent to read `PROGRAM.md` or activate the skill depending on your setup**:
+
+```
+Read PROGRAM.md, then start working.
+
+# If using skills
+$autoevolve  # Codex
+/autoevolve  # Claude Code
+```
+
+From there, your agent should start working in the repo as usual. Experiment commits will include:
+
+- `EXPERIMENT.json`: the structured record of the experiment, including summary, metrics, and any references to other experiments
+- `JOURNAL.md`: the narrative record of the experiment, which could include the hypothesis, changes made, outcomes, reflections, etc.
+
+**3. Start the TUI to monitor your agent's progress**:
+
+```bash
+autoevolve dashboard
+```
+
+## CLI
+
+Here’s the CLI surface: `Human` commands handle setup and monitoring, `Lifecycle` manages experiments, and `Inspect` and `Analytics` help your agents review the experiment state.
+
+```
+Usage: autoevolve [OPTIONS] COMMAND [ARGS]...
+
+  Git-backed experiment loops for coding agents.
+
+Options:
+  --help  Show this message and exit.
+
+Human:
+  init       Set up PROBLEM.md and agent instructions.
+  validate   Check that the repo is ready for autoevolve.
+  update     Update detected prompt files to the latest version.
+  dashboard  Open the experiment dashboard.
+
+Lifecycle:
+  start      Create a managed experiment branch and worktree.
+  record     Validate, commit, and remove the current managed worktree.
+  clean      Remove stale managed worktrees for this repository.
+
+Inspect:
+  status     Show the current experiment status.
+  log        Show experiment logs.
+  show       Show experiment details.
+  compare    Compare two experiments.
+  lineage    Show experiment lineage around one ref.
+
+Analytics:
+  recent     List the most recent recorded experiments.
+  best       List the top experiments for one metric.
+  pareto     List the Pareto frontier for selected metrics.
+
+Examples:
+  autoevolve start tune-thresholds "Try a tighter threshold sweep" --from 07f1844
+  autoevolve record
+  autoevolve log
+  autoevolve recent --limit 5
+  autoevolve best --max benchmark_score --limit 5
+
+Run "autoevolve <command> --help" for command-specific details.
+```

autoevolve_cli-0.1.0/README.md

@@ -0,0 +1,94 @@
+# autoevolve
+
+![screenshot](./assets/screenshot.png)
+
+`autoevolve` lets coding agents run git-backed experiment loops autonomously. It gives agents a lightweight workflow for branching, recording results, and comparing experiments without needing heavy external dependencies, databases, or services.
+
+Run it inside an existing project, let it set up the files your coding agent needs, and then let the agent iterate through experiments, branch into new research directions, and explore ideas on its own.
+
+## Install
+
+```bash
+pip install autoevolve-cli
+```
+
+## Quickstart
+
+**1. Initialize `autoevolve` in an existing git repo**:
+
+```bash
+autoevolve init
+```
+
+`autoevolve init` walks you through the setup for your coding harness and problem:
+
+- `SKILL.md` or `PROGRAM.md`: the instructions your coding agent reads to use `autoevolve`
+- `PROBLEM.md`: the goal, metric, constraints, and validation setup for your problem
+
+For an example problem to try, see the [circle packing example repo](https://github.com/wiskojo/autoevolve-circle-packing-example).
+
+**2. Tell your agent to read `PROGRAM.md` or activate the skill depending on your setup**:
+
+```
+Read PROGRAM.md, then start working.
+
+# If using skills
+$autoevolve  # Codex
+/autoevolve  # Claude Code
+```
+
+From there, your agent should start working in the repo as usual. Experiment commits will include:
+
+- `EXPERIMENT.json`: the structured record of the experiment, including summary, metrics, and any references to other experiments
+- `JOURNAL.md`: the narrative record of the experiment, which could include the hypothesis, changes made, outcomes, reflections, etc.
+
+**3. Start the TUI to monitor your agent's progress**:
+
+```bash
+autoevolve dashboard
+```
+
+## CLI
+
+Here’s the CLI surface: `Human` commands handle setup and monitoring, `Lifecycle` manages experiments, and `Inspect` and `Analytics` help your agents review the experiment state.
+
+```
+Usage: autoevolve [OPTIONS] COMMAND [ARGS]...
+
+  Git-backed experiment loops for coding agents.
+
+Options:
+  --help  Show this message and exit.
+
+Human:
+  init       Set up PROBLEM.md and agent instructions.
+  validate   Check that the repo is ready for autoevolve.
+  update     Update detected prompt files to the latest version.
+  dashboard  Open the experiment dashboard.
+
+Lifecycle:
+  start      Create a managed experiment branch and worktree.
+  record     Validate, commit, and remove the current managed worktree.
+  clean      Remove stale managed worktrees for this repository.
+
+Inspect:
+  status     Show the current experiment status.
+  log        Show experiment logs.
+  show       Show experiment details.
+  compare    Compare two experiments.
+  lineage    Show experiment lineage around one ref.
+
+Analytics:
+  recent     List the most recent recorded experiments.
+  best       List the top experiments for one metric.
+  pareto     List the Pareto frontier for selected metrics.
+
+Examples:
+  autoevolve start tune-thresholds "Try a tighter threshold sweep" --from 07f1844
+  autoevolve record
+  autoevolve log
+  autoevolve recent --limit 5
+  autoevolve best --max benchmark_score --limit 5
+
+Run "autoevolve <command> --help" for command-specific details.
+```

autoevolve_cli-0.1.0/pyproject.toml

@@ -0,0 +1,57 @@
+[project]
+name = "autoevolve-cli"
+dynamic = ["version"]
+description = "Git-backed experiment loops for coding agents"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "gitpython>=3.1.46",
+    "rich>=14",
+    "textual>=1",
+    "typer>=0.24.1",
+]
+
+[dependency-groups]
+dev = [
+    "inline-snapshot>=0.32.5",
+    "mypy>=1.19.1",
+    "pytest>=9.0.2",
+    "ruff>=0.15.7",
+]
+
+[project.scripts]
+autoevolve = "autoevolve.app:main"
+
+[build-system]
+requires = ["hatchling>=1.27", "hatch-vcs>=0.4"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "vcs"
+tag-pattern = "^v(?P<version>.*)$"
+fallback-version = "0.1.0"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/autoevolve"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+extend-exclude = ["tests/fixtures"]
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "B", "C4", "UP"]
+ignore = ["E501"]
+
+[tool.mypy]
+strict = true
+warn_return_any = true
+no_implicit_optional = true
+strict_equality = true
+warn_unreachable = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.inline-snapshot]
+format-command = "ruff format --stdin-filename {filename} -"

autoevolve_cli-0.1.0/src/autoevolve/app.py

@@ -0,0 +1,100 @@
+from collections.abc import Sequence
+
+import click
+import typer
+from typer.core import TyperGroup
+from typer.main import get_command
+
+from autoevolve.commands.analytics import app as analytics_app
+from autoevolve.commands.human import app as human_app
+from autoevolve.commands.inspect import app as inspect_app
+from autoevolve.commands.lifecycle import app as lifecycle_app
+
+
+class AutoevolveGroup(TyperGroup):
+    def format_commands(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        command_names = self.list_commands(ctx)
+        sections: dict[str, list[tuple[str, str]]] = {
+            title: [] for title in ("Human", "Lifecycle", "Inspect", "Analytics")
+        }
+        command_width = max((len(name) for name in command_names), default=0)
+
+        for command_name in command_names:
+            command = self.get_command(ctx, command_name)
+            if command is None or command.hidden:
+                continue
+            section = getattr(command, "rich_help_panel", None) or "Other"
+            sections.setdefault(section, []).append(
+                (
+                    command_name.ljust(command_width),
+                    command.get_short_help_str(formatter.width),
+                )
+            )
+
+        for title, rows in sections.items():
+            if not rows:
+                continue
+            with formatter.section(title):
+                formatter.write_dl(rows)
+
+    def format_epilog(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
+        if self.epilog is None:
+            return
+        formatter.write_paragraph()
+        formatter.write(f"{self.epilog}\n")
+
+
+app = typer.Typer(
+    cls=AutoevolveGroup,
+    help="Git-backed experiment loops for coding agents.",
+    epilog="""Examples:
+  autoevolve start tune-thresholds "Try a tighter threshold sweep" --from 07f1844
+  autoevolve record
+  autoevolve log
+  autoevolve recent --limit 5
+  autoevolve best --max benchmark_score --limit 5
+
+Run "autoevolve <command> --help" for command-specific details.""",
+    invoke_without_command=True,
+    add_completion=False,
+    rich_markup_mode=None,
+    pretty_exceptions_enable=False,
+)
+
+app.add_typer(human_app)
+app.add_typer(lifecycle_app)
+app.add_typer(inspect_app)
+app.add_typer(analytics_app)
+
+
+@app.callback()
+def main_callback(ctx: typer.Context) -> None:
+    if ctx.invoked_subcommand is None and not ctx.resilient_parsing:
+        typer.echo(ctx.get_help())
+        raise typer.Exit()
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    command = get_command(app)
+    try:
+        command.main(
+            args=list(argv) if argv is not None else None,
+            prog_name="autoevolve",
+            standalone_mode=False,
+        )
+        return 0
+    except click.ClickException as error:
+        error.show()
+        return error.exit_code
+    except typer.Abort:
+        typer.echo("Aborted!", err=True)
+        return 1
+    except typer.Exit as error:
+        return error.exit_code
+    except Exception as error:
+        typer.echo(str(error), err=True)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

autoevolve_cli-0.1.0/src/autoevolve/commands/analytics.py

@@ -0,0 +1,163 @@
+import json
+from typing import Annotated
+
+import typer
+
+from autoevolve.models.experiment import ExperimentIndexEntry, Objective
+from autoevolve.models.types import SetOutputFormat
+from autoevolve.repository import ExperimentRepository
+
+app = typer.Typer()
+
+
+@app.command(
+    "recent",
+    rich_help_panel="Analytics",
+    short_help="List the most recent recorded experiments.",
+    help=(
+        "List the most recent recorded experiments.\n\n"
+        "recent emits recent experiments in TSV or JSONL format for scripting "
+        "and analysis."
+    ),
+)
+def recent(
+    limit: Annotated[int, typer.Option(min=1, help="Number of experiments to show.")] = 10,
+    output_format: Annotated[
+        SetOutputFormat,
+        typer.Option("--format", help="Output format."),
+    ] = SetOutputFormat.TSV,
+) -> None:
+    _print_records(ExperimentRepository().recent_index(limit), output_format)
+
+
+@app.command(
+    "best",
+    rich_help_panel="Analytics",
+    short_help="List the top experiments for one metric.",
+    help=(
+        "List the top experiments for one metric.\n\n"
+        "best ranks recorded experiments by one metric. If no metric is "
+        "provided, it defaults to the primary metric from PROBLEM.md."
+    ),
+)
+def best(
+    max_metric: Annotated[str | None, typer.Option("--max", help="Metric to maximize.")] = None,
+    min_metric: Annotated[str | None, typer.Option("--min", help="Metric to minimize.")] = None,
+    limit: Annotated[int, typer.Option(min=1, help="Number of experiments to show.")] = 5,
+    output_format: Annotated[
+        SetOutputFormat,
+        typer.Option("--format", help="Output format."),
+    ] = SetOutputFormat.TSV,
+) -> None:
+    if max_metric and min_metric:
+        raise typer.BadParameter("Use either --max <metric> or --min <metric>, not both.")
+
+    objective = None
+    if max_metric is not None:
+        objective = Objective(direction="max", metric=max_metric)
+    if min_metric is not None:
+        objective = Objective(direction="min", metric=min_metric)
+
+    repository = ExperimentRepository()
+    if objective is None:
+        try:
+            problem = repository.problem()
+        except (FileNotFoundError, ValueError) as error:
+            raise RuntimeError(
+                "best requires an explicit objective, or a valid PROBLEM.md primary metric."
+            ) from error
+        resolved = Objective(direction=problem.direction, metric=problem.metric)
+    else:
+        resolved = objective
+    records = repository.best_records(resolved, limit)
+    if not records:
+        typer.echo(f'No experiments found with a numeric "{resolved.metric}" metric.')
+        return
+    _print_records(records, output_format)
+
+
+@app.command(
+    "pareto",
+    rich_help_panel="Analytics",
+    short_help="List the Pareto frontier for selected metrics.",
+    help=(
+        "List the Pareto frontier for selected metrics.\n\n"
+        "pareto returns the non-dominated recorded experiments for the selected "
+        "metrics in TSV or JSONL format."
+    ),
+)
+def pareto(
+    max_metrics: Annotated[
+        list[str] | None,
+        typer.Option("--max", help="Metric to maximize. Repeat as needed."),
+    ] = None,
+    min_metrics: Annotated[
+        list[str] | None,
+        typer.Option("--min", help="Metric to minimize. Repeat as needed."),
+    ] = None,
+    limit: Annotated[int | None, typer.Option(min=1, help="Number of experiments to show.")] = None,
+    output_format: Annotated[
+        SetOutputFormat,
+        typer.Option("--format", help="Output format."),
+    ] = SetOutputFormat.TSV,
+) -> None:
+    objectives = [Objective(direction="max", metric=metric) for metric in max_metrics or ()]
+    objectives.extend(Objective(direction="min", metric=metric) for metric in min_metrics or ())
+    if not objectives:
+        raise typer.BadParameter(
+            "pareto requires at least one metric, for example: --max primary_metric --min runtime_sec"
+        )
+
+    records = ExperimentRepository().pareto_records(objectives, limit)
+    if not records:
+        typer.echo("No experiments found with numeric metrics for the requested Pareto objectives.")
+        return
+    _print_records(records, output_format)
+
+
+def _print_records(records: list[ExperimentIndexEntry], output_format: SetOutputFormat) -> None:
+    if not records:
+        typer.echo("No experiments found.")
+        return
+    if output_format is SetOutputFormat.TSV:
+        typer.echo("sha\tdate\tmetrics\tsummary")
+        for record in records:
+            typer.echo(_tsv_row(record))
+        return
+    for record in records:
+        typer.echo(json.dumps(_json_record(record)))
+
+
+def _tsv_row(record: ExperimentIndexEntry) -> str:
+    return "\t".join(
+        [
+            record.sha[:7],
+            record.date,
+            _clean(_metric_pairs(record)),
+            _clean(record.document.summary),
+        ]
+    )
+
+
+def _json_record(record: ExperimentIndexEntry) -> dict[str, object]:
+    return {
+        "sha": record.sha,
+        "short_sha": record.sha[:7],
+        "date": record.date,
+        "summary": record.document.summary,
+        "metrics": record.document.metrics,
+        "references": [
+            {"commit": reference.commit, "why": reference.why}
+            for reference in record.document.references
+        ],
+    }
+
+
+def _metric_pairs(record: ExperimentIndexEntry) -> str:
+    return ", ".join(
+        f"{name}={json.dumps(value)}" for name, value in record.document.metrics.items()
+    )
+
+
+def _clean(value: str) -> str:
+    return value.replace("\t", " ").replace("\r", " ").replace("\n", " ").strip()