autoevolve-cli 0.1.0__py3-none-any.whl

autoevolve/scaffold.py

@@ -0,0 +1,88 @@
+from pathlib import Path
+
+from autoevolve.git import find_repo_root
+from autoevolve.harnesses import HARNESS_SPECS, Harness, get_harness_spec
+from autoevolve.models.experiment import PromptFile
+from autoevolve.problem import parse_problem_spec
+from autoevolve.prompt import build_harness_skill_prompt, build_problem_template
+from autoevolve.repository import (
+    EXPERIMENT_FILE,
+    JOURNAL_FILE,
+    PROBLEM_FILE,
+    parse_experiment_document,
+)
+
+
+class Scaffolder:
+    def __init__(self, cwd: str | Path = ".") -> None:
+        self.root = find_repo_root(cwd)
+
+    def apply_init(self, harness: Harness, continue_hook: bool) -> list[str]:
+        spec = get_harness_spec(harness)
+        written: list[str] = []
+        if not (self.root / PROBLEM_FILE).exists():
+            (self.root / PROBLEM_FILE).write_text(build_problem_template(), encoding="utf-8")
+            written.append(PROBLEM_FILE)
+        prompt_path = self.root / spec.prompt_path
+        prompt_path.parent.mkdir(parents=True, exist_ok=True)
+        prompt_path.write_text(build_harness_skill_prompt(harness), encoding="utf-8")
+        written.append(spec.prompt_path)
+        if continue_hook:
+            for file_spec in spec.continue_hook_files:
+                path = self.root / file_spec.path
+                existing = path.read_text(encoding="utf-8") if path.exists() else None
+                path.parent.mkdir(parents=True, exist_ok=True)
+                path.write_text(file_spec.build_contents(existing), encoding="utf-8")
+                written.append(file_spec.path)
+        return written
+
+    def prompt_files(self) -> list[PromptFile]:
+        files: list[PromptFile] = []
+        for harness, spec in HARNESS_SPECS.items():
+            path = self.root / spec.prompt_path
+            if path.exists():
+                files.append(PromptFile(harness=harness.value, path=path))
+        return files
+
+    def update_prompt(self, prompt_file: PromptFile) -> None:
+        harness = Harness(prompt_file.harness)
+        prompt_file.path.parent.mkdir(parents=True, exist_ok=True)
+        prompt_file.path.write_text(build_harness_skill_prompt(harness), encoding="utf-8")
+
+    def validate(self) -> list[str]:
+        problems: list[str] = []
+        problem_path = self.root / PROBLEM_FILE
+        if not problem_path.exists():
+            problems.append(f"Missing {PROBLEM_FILE}. Run autoevolve init first.")
+            problem = None
+        else:
+            try:
+                problem = parse_problem_spec(problem_path.read_text(encoding="utf-8"))
+            except ValueError as error:
+                problems.append(str(error))
+                problem = None
+        if not self.prompt_files():
+            problems.append(
+                "Missing prompt file. Expected PROGRAM.md or a supported harness skill file."
+            )
+        journal_path = self.root / JOURNAL_FILE
+        experiment_path = self.root / EXPERIMENT_FILE
+        if journal_path.exists() or experiment_path.exists():
+            if not journal_path.exists():
+                problems.append(f"Missing {JOURNAL_FILE}.")
+            if not experiment_path.exists():
+                problems.append(f"Missing {EXPERIMENT_FILE}.")
+            if experiment_path.exists():
+                try:
+                    document = parse_experiment_document(
+                        experiment_path.read_text(encoding="utf-8")
+                    )
+                except ValueError as error:
+                    problems.append(str(error))
+                else:
+                    if problem is not None and problem.metric not in document.metrics:
+                        problems.append(
+                            f'{EXPERIMENT_FILE} must record the primary metric "{problem.metric}" '
+                            f"declared in {PROBLEM_FILE} ({problem.raw})."
+                        )
+        return problems

autoevolve/worktree.py

@@ -0,0 +1,186 @@
+import json
+import shutil
+from pathlib import Path
+
+from git.exc import GitCommandError
+
+from autoevolve.git import find_repo_root, list_linked_worktrees, open_repo
+from autoevolve.models.experiment import ExperimentWorktree
+from autoevolve.models.worktree import (
+    CleanedWorktrees,
+    RecordedExperiment,
+    StartedExperiment,
+)
+from autoevolve.repository import (
+    EXPERIMENT_FILE,
+    JOURNAL_FILE,
+    WORKTREE_ROOT,
+    ExperimentRepository,
+    parse_experiment_document,
+)
+
+_REF_PREFIX = "autoevolve/"
+
+
+class ExperimentWorktreeManager:
+    def __init__(self, cwd: str | Path = ".") -> None:
+        self.root = find_repo_root(cwd)
+        self.repo = open_repo(self.root)
+        self.cwd = Path(cwd).resolve()
+
+    def start(self, name: str, summary: str, from_ref: str | None) -> StartedExperiment:
+        name = self._validate_name(name)
+        ref_name = f"{_REF_PREFIX}{name}"
+        try:
+            self.repo.git.check_ref_format(f"refs/heads/{ref_name}")
+        except GitCommandError as error:
+            raise ValueError(
+                f'"{ref_name}" is not a valid managed experiment branch name.'
+            ) from error
+        if any(head.name == ref_name for head in self.repo.heads):
+            raise RuntimeError(f'Branch "{ref_name}" already exists.')
+
+        path = (WORKTREE_ROOT / name).resolve()
+        if path.exists():
+            raise RuntimeError(f"Worktree path already exists: {path}")
+
+        current_branch = self.repo.git.branch("--show-current").strip()
+        base_ref = from_ref or current_branch or "HEAD"
+        path.parent.mkdir(parents=True, exist_ok=True)
+        self.repo.git.worktree("add", "-b", ref_name, str(path), self.repo.commit(base_ref).hexsha)
+        (path / JOURNAL_FILE).write_text(self._journal_stub_text(name), encoding="utf-8")
+        (path / EXPERIMENT_FILE).write_text(
+            json.dumps({"summary": summary, "metrics": {}, "references": []}, indent=2) + "\n",
+            encoding="utf-8",
+        )
+        return StartedExperiment(branch=ref_name, base_ref=base_ref, path=path)
+
+    def record(self) -> RecordedExperiment:
+        current_worktree = next(
+            worktree
+            for worktree in list_linked_worktrees(self.repo, current_path=self.cwd)
+            if worktree.is_current
+        )
+        branch_name = current_worktree.branch
+        if not branch_name:
+            raise RuntimeError("record requires an attached branch.")
+        if not branch_name.startswith(_REF_PREFIX):
+            raise RuntimeError(
+                f"record only works on managed autoevolve experiment branches ({_REF_PREFIX}<name>)."
+            )
+
+        root = current_worktree.path.resolve()
+        managed_root = WORKTREE_ROOT.resolve()
+        if root != managed_root and managed_root not in root.parents:
+            raise RuntimeError(
+                f"record must be run from a managed autoevolve worktree under {managed_root}."
+            )
+
+        worktree_repo = open_repo(root)
+        git_dir = Path(worktree_repo.git.rev_parse("--git-dir").strip())
+        if not git_dir.is_absolute():
+            git_dir = (root / git_dir).resolve()
+        common_git_dir = Path(worktree_repo.git.rev_parse("--git-common-dir").strip())
+        if not common_git_dir.is_absolute():
+            common_git_dir = (root / common_git_dir).resolve()
+        if git_dir == common_git_dir:
+            raise RuntimeError("record refuses to remove the primary worktree.")
+
+        journal_path = root / JOURNAL_FILE
+        experiment_path = root / EXPERIMENT_FILE
+        if not journal_path.exists() or not experiment_path.exists():
+            raise RuntimeError(f"record requires both {JOURNAL_FILE} and {EXPERIMENT_FILE}.")
+
+        experiment_name = branch_name.removeprefix(_REF_PREFIX)
+        journal_text = journal_path.read_text(encoding="utf-8").strip()
+        if journal_text == self._journal_stub_text(experiment_name).strip():
+            raise RuntimeError(f"Replace the {JOURNAL_FILE} stub before committing.")
+
+        document = parse_experiment_document(experiment_path.read_text(encoding="utf-8"))
+        if not worktree_repo.is_dirty(untracked_files=True):
+            raise RuntimeError("No changes to commit.")
+
+        message = next((line.strip() for line in document.summary.splitlines() if line.strip()), "")
+        if not message:
+            raise RuntimeError(f"{EXPERIMENT_FILE} summary must not be empty.")
+
+        worktree_repo.git.add("-A")
+        worktree_repo.git.commit("-m", message)
+        sha = worktree_repo.head.commit.hexsha
+        self.repo.git.worktree("remove", str(root))
+        return RecordedExperiment(branch=branch_name, sha=sha, path=root)
+
+    def clean(self, name: str | None, force: bool) -> CleanedWorktrees:
+        worktrees = ExperimentRepository(self.root).active_worktrees()
+        managed = [
+            worktree for worktree in worktrees if worktree.is_managed and not worktree.is_primary
+        ]
+        experiment_name = ""
+        if name is not None:
+            experiment_name = self._normalize_name(name)
+            target_path = (WORKTREE_ROOT / experiment_name).resolve()
+            target = next(
+                (worktree for worktree in worktrees if worktree.path == target_path), None
+            )
+            if target is None or target.is_primary or not target.is_managed:
+                raise RuntimeError(
+                    f'No managed experiment worktree named "{experiment_name}" found for this repository.'
+                )
+            managed = [target]
+
+        if not managed:
+            return CleanedWorktrees(experiment_name=experiment_name, removed=())
+
+        blocked = [worktree for worktree in managed if worktree.is_missing or worktree.dirty]
+        if blocked and not force:
+            reason = (
+                "Refusing to remove a dirty or missing linked worktree without --force:"
+                if len(blocked) == 1
+                else "Refusing to remove dirty or missing linked worktrees without --force:"
+            )
+            details = "\n".join(
+                f"  {self._describe_worktree_for_removal(worktree)}" for worktree in blocked
+            )
+            raise RuntimeError(f"{reason}\n{details}")
+
+        removed = []
+        for worktree in managed:
+            if worktree.is_missing:
+                shutil.rmtree(worktree.path, ignore_errors=True)
+                self.repo.git.worktree("prune", "--expire", "now")
+            else:
+                args = ["worktree", "remove"]
+                if force or worktree.dirty:
+                    args.append("--force")
+                args.append(str(worktree.path))
+                self.repo.git.execute(["git", *args])
+            if worktree.branch and any(head.name == worktree.branch for head in self.repo.heads):
+                self.repo.git.branch("-D", worktree.branch)
+            removed.append(worktree)
+
+        return CleanedWorktrees(experiment_name=experiment_name, removed=tuple(removed))
+
+    @staticmethod
+    def _normalize_name(name: str) -> str:
+        value = name.strip()
+        if value.startswith(_REF_PREFIX):
+            value = value.removeprefix(_REF_PREFIX)
+        return value
+
+    @staticmethod
+    def _validate_name(name: str) -> str:
+        value = ExperimentWorktreeManager._normalize_name(name)
+        if not value:
+            raise ValueError("Experiment name must not be empty.")
+        if WORKTREE_ROOT.resolve() not in (WORKTREE_ROOT / value).resolve().parents:
+            raise ValueError(f'"{name}" is not a valid experiment name.')
+        return value
+
+    @staticmethod
+    def _journal_stub_text(name: str) -> str:
+        return f"# {name}\n\nTODO: fill this in once you're done with your experiment.\n"
+
+    @staticmethod
+    def _describe_worktree_for_removal(worktree: ExperimentWorktree) -> str:
+        state = "missing" if worktree.is_missing else "dirty" if worktree.dirty else "clean"
+        return f"{worktree.path} ({worktree.branch or '(detached HEAD)'}, {state}, {worktree.head[:7]})"

autoevolve_cli-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,25 @@
+autoevolve/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+autoevolve/app.py,sha256=cpTr6_6mltOqsHqeJdrM_cWR9NdLX0SDIJ8UuCvFDl4,3138
+autoevolve/dashboard.py,sha256=M3awNBIJ_Ls75Sv1iI7fA5K7ZUl7k9BabWLofBTasf8,70002
+autoevolve/git.py,sha256=p4cDwdWYUrSvxB73WtD9LsceIWQpJUHkQeWhI-QDCXM,6074
+autoevolve/harnesses.py,sha256=2yfOimWwYiNMKDjpKxfraIbOHJy0UfHkYjPdJrjIUQE,5148
+autoevolve/problem.py,sha256=FZxikK1_yThXGmSVHovPtGQCxnR3WK7WJrdNgTz8ZJI,1700
+autoevolve/prompt.py,sha256=cDRdKUzvsbdC1WkhlLkCyeoGohvL7I5qlHTBIkvG0Cg,10446
+autoevolve/repository.py,sha256=GN_jTGDXn33O-hYSRf9Ra44TSXFAZBJ2cMDstFBKXBM,17576
+autoevolve/scaffold.py,sha256=T_7rIvfCDq7lAKl9366JZeLEwzl5VCFi6hQGIlYKaJA,3886
+autoevolve/worktree.py,sha256=v6GH_tZN8Zqfx7S4zR8r-We5ypmW6FFFdqYgYCo2VxI,8055
+autoevolve/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+autoevolve/commands/analytics.py,sha256=W0NWnV--ppjali7bCwEMkDQ4H7mKzxyZjnKQZe9lOA8,5590
+autoevolve/commands/human.py,sha256=KtZXy-B2MaB0RmaufBgaDWbaDWp77vdGgpXzXiMZfn4,5981
+autoevolve/commands/inspect.py,sha256=4r9lXn_gDEBDsVeBj8dK13k-pZSnzBofC_Oa9UO0Z34,16855
+autoevolve/commands/lifecycle.py,sha256=nP2dzvKfChp3xaiLprL7Q_7r1VrfMMnF6uSRhI5yQMw,2694
+autoevolve/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+autoevolve/models/experiment.py,sha256=vtEFvNdPMHbn-7Lgc5C8JMvKdbyXoaPiTU4R5JOXp-c,1084
+autoevolve/models/git.py,sha256=3OjAbDwfwbc6AVyRHEkaJVRWgGEoogo6D9R-Q38H438,533
+autoevolve/models/lineage.py,sha256=RdN7IW68uu53zpP46e-YcOr3pHLUKzE69Rd108X79rE,359
+autoevolve/models/types.py,sha256=l0Q0WJluBOqWdGUM0CFZni5eGTo2Djc-yuA2_e0TasI,404
+autoevolve/models/worktree.py,sha256=LFsU9s7IM-wPA5Fcl9P7bXw_fuqRGWPbTJpSpip86EM,435
+autoevolve_cli-0.1.0.dist-info/METADATA,sha256=ziyxO9BYaGxXf93tI5b-YFKFP5RiXYlEx6KGCN7Va20,3465
+autoevolve_cli-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+autoevolve_cli-0.1.0.dist-info/entry_points.txt,sha256=z2i3w3IUGOocuocPfKRknQrF3tczuNtRcVcEuSqYL7c,51
+autoevolve_cli-0.1.0.dist-info/RECORD,,

autoevolve_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

autoevolve_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+autoevolve = autoevolve.app:main