autoevolve-cli 0.1.0__py3-none-any.whl

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/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()

autoevolve/commands/human.py

@@ -0,0 +1,166 @@
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.prompt import Confirm, Prompt
+
+from autoevolve.harnesses import Harness, get_harness_spec
+from autoevolve.repository import PROBLEM_FILE
+from autoevolve.scaffold import Scaffolder
+
+app = typer.Typer()
+console = Console(highlight=False)
+
+
+@app.command(
+    "init",
+    rich_help_panel="Human",
+    short_help="Set up PROBLEM.md and agent instructions.",
+    help=(
+        "Set up PROBLEM.md and agent instructions.\n\n"
+        f"If {PROBLEM_FILE} does not exist, init writes a stub. If it already exists, "
+        "init leaves it unchanged. If no harness is provided, init prompts for one. "
+        "Use --yes to skip confirmation prompts and write files immediately."
+    ),
+)
+def init(
+    harness: Annotated[Harness | None, typer.Option(help="Target agent harness.")] = None,
+    continue_hook: Annotated[
+        bool,
+        typer.Option(help="Install a continue-forever stop hook for supported harnesses."),
+    ] = False,
+    yes: Annotated[bool, typer.Option(help="Skip confirmation prompts.")] = False,
+) -> None:
+    scaffolder = Scaffolder()
+    if harness is None:
+        choice = Prompt.ask(
+            "Harness",
+            choices=[item.value for item in Harness],
+            default=Harness.CLAUDE.value,
+            console=console,
+        )
+        selected = Harness(choice.strip())
+    else:
+        selected = harness
+    spec = get_harness_spec(selected)
+    if continue_hook and not spec.supports_continue_hook:
+        raise RuntimeError(f'Continue hooks are not supported for harness "{selected.value}".')
+    if spec.supports_continue_hook and not continue_hook and not yes:
+        continue_hook = Confirm.ask(
+            f"Install a continue hook for {selected.value}?",
+            default=False,
+            console=console,
+        )
+
+    problem_exists = (scaffolder.root / PROBLEM_FILE).exists()
+    files = [PROBLEM_FILE, spec.prompt_path]
+    if continue_hook:
+        files.extend(item.path for item in spec.continue_hook_files)
+
+    console.print("[bold]Setup[/bold]")
+    console.print(f"[bold]{'Repository':<14}[/bold]{scaffolder.root}", soft_wrap=True)
+    console.print(f"[bold]{'Harness':<14}[/bold]{selected.value}")
+    console.print(
+        f"[bold]{'Problem':<14}[/bold]"
+        f"{'keep existing' if problem_exists else 'write'} {PROBLEM_FILE}"
+    )
+    if continue_hook:
+        console.print(f"[bold]{'Continue hook':<14}[/bold]enabled")
+    console.print()
+    console.print("[bold]Files[/bold]")
+    for path in files:
+        action = "keep" if path == PROBLEM_FILE and problem_exists else "write"
+        console.print(f"[dim]{action:<6}[/dim]{path}", soft_wrap=True)
+    if not yes and not Confirm.ask("Write these files?", default=True, console=console):
+        raise typer.Exit()
+
+    written = scaffolder.apply_init(selected, continue_hook)
+    console.print()
+    console.print("[bold green]autoevolve initialized[/bold green]")
+    if written:
+        console.print(f"[bold]{'Written':<14}[/bold]{written[0]}", soft_wrap=True)
+        for path in written[1:]:
+            console.print(f"{'':14}{path}", soft_wrap=True)
+    _print_next_step(selected, spec.display_name, spec.handoff_prompt)
+
+
+def _print_next_step(harness: Harness, display_name: str, handoff_prompt: str) -> None:
+    console.print()
+    console.print("[bold cyan]Next Step[/bold cyan]")
+    if harness is Harness.OTHER:
+        console.print("Tell your coding agent to:")
+        console.print(f'  "{handoff_prompt}"', soft_wrap=True)
+        return
+    console.print(f"Open {display_name} and type:")
+    console.print(f"  [bold]{handoff_prompt}[/bold]", soft_wrap=True)
+
+
+@app.command(
+    "validate",
+    rich_help_panel="Human",
+    short_help="Check that the repo is ready for autoevolve.",
+    help=(
+        "Check that the repo is ready for autoevolve.\n\n"
+        "validate checks the required autoevolve files and validates the current "
+        "experiment record when one is present."
+    ),
+)
+def validate() -> None:
+    problems = Scaffolder().validate()
+    if problems:
+        raise RuntimeError("\n".join(problems))
+    typer.echo("OK: repository is ready for autoevolve.")
+
+
+@app.command(
+    "update",
+    rich_help_panel="Human",
+    short_help="Update detected prompt files to the latest version.",
+    help=(
+        "Update detected prompt files to the latest version.\n\n"
+        "update refreshes any detected harness prompt files in the current "
+        "repository. It asks before overwriting PROGRAM.md unless --yes is set."
+    ),
+)
+def update(
+    yes: Annotated[bool, typer.Option(help="Skip confirmation prompts.")] = False,
+) -> None:
+    scaffolder = Scaffolder()
+    prompt_files = scaffolder.prompt_files()
+    if not prompt_files:
+        raise RuntimeError("No prompt files found. Run autoevolve init first.")
+
+    updated: list[str] = []
+    skipped: list[str] = []
+    typer.echo("detected prompts:")
+    for prompt_file in prompt_files:
+        relative = prompt_file.path.relative_to(scaffolder.root).as_posix()
+        typer.echo(f"  - {relative} ({prompt_file.harness})")
+        if relative == "PROGRAM.md" and not yes:
+            if not typer.confirm("Overwrite PROGRAM.md?", default=False):
+                skipped.append(relative)
+                continue
+        scaffolder.update_prompt(prompt_file)
+        updated.append(relative)
+
+    typer.echo("")
+    if updated:
+        typer.echo("updated:")
+        for path in updated:
+            typer.echo(f"  - {path}")
+    if skipped:
+        typer.echo("skipped:")
+        for path in skipped:
+            typer.echo(f"  - {path}")
+
+
+@app.command(
+    "dashboard",
+    rich_help_panel="Human",
+    short_help="Open the experiment dashboard.",
+    help="Open the experiment dashboard.\n\nMonitor experiment progress in an interactive TUI.",
+)
+def dashboard() -> None:
+    from autoevolve.dashboard import DashboardApp
+
+    DashboardApp(cwd=".").run()