agentpack-cli 0.1.0__py3-none-any.whl

agentpack/application/pack_service.py

@@ -0,0 +1,352 @@
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from agentpack.core.config import load_config
+from agentpack.core.ignore import load_spec
+from agentpack.core.scanner import scan
+from agentpack.core.snapshot import build_snapshot, save_snapshot, load_snapshot
+from agentpack.core.diff import diff_snapshots
+from agentpack.core import git
+from agentpack.core.context_pack import select_files, save_pack_metadata
+from agentpack.core.models import ContextPack, DependencyGraph, FileInfo, ScanResult, SelectedFile, Receipt
+from agentpack.core.token_estimator import estimate_tokens
+from agentpack.analysis.ranking import score_files, extract_keywords, enrich_keywords_from_files
+from agentpack.analysis.tests import find_related_tests
+from agentpack.analysis import dependency_graph as dep_graph_mod
+from agentpack.summaries.base import build_all_summaries
+
+
+@dataclass
+class PackRequest:
+    root: Path
+    agent: str
+    task: str
+    mode: str
+    budget: int
+    since: str | None
+    refresh: bool
+    summary_provider: str
+
+
+@dataclass
+class PackResult:
+    pack: ContextPack
+    out_path: Path
+    phase_times: dict[str, float]
+    packed_tokens: int
+    raw_tokens: int
+    saving_pct: float
+    changed_files: list[str]
+    scan_result: ScanResult
+
+
+@dataclass
+class ChangeSet:
+    """Result of change detection: snapshot diff combined with git diff."""
+    all_changed: set[str]
+    git_staged: set[str]
+    recently_modified: list[str]
+    current_snap: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class RankResult:
+    """Result of keyword extraction and file scoring."""
+    keywords: set[str]
+    scored: list[tuple[Any, float, list[str]]]
+
+
+@dataclass
+class PackPlan:
+    """Shared planning output used by both pack and explain."""
+    task: str
+    mode: str
+    budget: int
+    scan_result: ScanResult
+    summaries: dict[str, Any]
+    dep_graph: DependencyGraph
+    all_changed: set[str]
+    git_staged: set[str]
+    recently_modified: list[str]
+    keywords: set[str]
+    scored: list[tuple[Any, float, list[str]]]
+    selected: list[SelectedFile]
+    receipts: list[Receipt]
+    phase_times: dict[str, float]
+    current_snap: dict[str, Any] = field(default_factory=dict)
+
+
+class ChangeDetector:
+    """Combines snapshot diff + git diff → ChangeSet of changed paths."""
+
+    def detect(
+        self,
+        packable: list[FileInfo],
+        root: Path,
+        since: str | None,
+    ) -> ChangeSet:
+        current_snap = build_snapshot(packable)
+        previous_snap = load_snapshot(root)
+        snap_diff = diff_snapshots(previous_snap, current_snap)
+        changed_from_snap: set[str] = set(snap_diff.added + snap_diff.modified)
+
+        git_changed: set[str] = set()
+        git_staged: set[str] = set()
+        recently_modified: list[str] = []
+
+        if git.is_git_repo(root):
+            if since:
+                git_changed = git.changed_files_since(root, since)
+            else:
+                git_changed = git.changed_files(root)
+            git_staged = git_changed
+            recently_modified = git.recently_modified_files(root)
+
+        return ChangeSet(
+            all_changed=changed_from_snap | git_changed,
+            git_staged=git_staged,
+            recently_modified=recently_modified,
+            current_snap=current_snap,
+        )
+
+
+class FileRanker:
+    """Extracts keywords from the task and scores files against them."""
+
+    def rank(
+        self,
+        packable: list[FileInfo],
+        changes: ChangeSet,
+        dep_graph: DependencyGraph,
+        task: str,
+        cfg: Any,
+    ) -> RankResult:
+        keywords = extract_keywords(task)
+        keywords = enrich_keywords_from_files(keywords, changes.all_changed, packable)
+        all_paths = {f.path for f in packable}
+
+        for fi in packable:
+            tests = find_related_tests(fi.path, all_paths)
+            dep_graph.nodes[fi.path].tests = tests
+
+        scored = score_files(
+            packable,
+            changed_paths=changes.all_changed,
+            staged_paths=changes.git_staged,
+            recently_modified=changes.recently_modified,
+            dep_graph=dep_graph,
+            keywords=keywords,
+            include_tests=cfg.context.include_tests,
+            include_configs=cfg.context.include_configs,
+            weights=cfg.scoring,
+        )
+        return RankResult(keywords=keywords, scored=scored)
+
+
+class PackPlanner:
+    """Runs scan → summarize → graph → rank → select; shared by pack and explain."""
+
+    def plan(self, request: PackRequest) -> PackPlan:
+        root = request.root
+        cfg = load_config(root)
+        effective_budget = request.budget if request.budget > 0 else cfg.context.default_budget
+        ignore_spec = load_spec(root / cfg.project.ignore_file)
+        phase_times: dict[str, float] = {}
+
+        t0 = time.perf_counter()
+        scan_result = scan(root, ignore_spec, cfg.context.max_file_tokens)
+        phase_times["scan"] = time.perf_counter() - t0
+
+        packable = scan_result.packable
+
+        t0 = time.perf_counter()
+        summaries_objs = build_all_summaries(packable, root, request.summary_provider)
+        summaries = {p: s.model_dump() for p, s in summaries_objs.items()}
+        phase_times["summarize"] = time.perf_counter() - t0
+
+        t0 = time.perf_counter()
+        dep_graph = dep_graph_mod.build(packable, root, summaries=summaries)
+        phase_times["deps"] = time.perf_counter() - t0
+
+        t0 = time.perf_counter()
+        changes = ChangeDetector().detect(packable, root, request.since)
+        phase_times["changes"] = time.perf_counter() - t0
+
+        t0 = time.perf_counter()
+        rank_result = FileRanker().rank(packable, changes, dep_graph, request.task, cfg)
+        phase_times["rank"] = time.perf_counter() - t0
+
+        t0 = time.perf_counter()
+        selected, receipts = select_files(
+            files=packable,
+            scored=rank_result.scored,
+            changed_paths=changes.all_changed,
+            summaries=summaries,
+            mode=request.mode,  # type: ignore[arg-type]
+            budget=effective_budget,
+            max_file_tokens=cfg.context.max_file_tokens,
+            keywords=rank_result.keywords,
+        )
+        phase_times["select"] = time.perf_counter() - t0
+
+        return PackPlan(
+            task=request.task,
+            mode=request.mode,
+            budget=effective_budget,
+            scan_result=scan_result,
+            summaries=summaries,
+            dep_graph=dep_graph,
+            all_changed=changes.all_changed,
+            git_staged=changes.git_staged,
+            recently_modified=changes.recently_modified,
+            keywords=rank_result.keywords,
+            scored=rank_result.scored,
+            selected=selected,
+            receipts=receipts,
+            phase_times=phase_times,
+            current_snap=changes.current_snap,
+        )
+
+
+class AdapterRegistry:
+    """Maps agent names to adapter instances; extensible without touching PackService."""
+
+    @staticmethod
+    def get(agent: str, cfg: Any) -> Any:
+        from agentpack.adapters.claude import ClaudeAdapter
+        from agentpack.adapters.codex import CodexAdapter
+        from agentpack.adapters.cursor import CursorAdapter
+        from agentpack.adapters.windsurf import WindsurfAdapter
+        from agentpack.adapters.generic import GenericAdapter
+
+        adapters = {
+            "claude": lambda: ClaudeAdapter(cfg.agents.claude.output),
+            "cursor": lambda: CursorAdapter(cfg.agents.generic.output),
+            "windsurf": lambda: WindsurfAdapter(cfg.agents.generic.output),
+            "codex": lambda: CodexAdapter(cfg.agents.generic.output),
+        }
+        return adapters.get(agent, lambda: GenericAdapter(cfg.agents.generic.output))()
+
+
+class PackService:
+    """Materializes a plan from PackPlanner into a written context file."""
+
+    def run(self, request: PackRequest) -> PackResult:
+        root = request.root
+        cfg = load_config(root)
+
+        plan = PackPlanner().plan(request)
+
+        packable = plan.scan_result.packable
+        all_tokens = sum(f.estimated_tokens for f in plan.scan_result.all_files)
+        raw_tokens = sum(f.estimated_tokens for f in packable)
+        packed_tokens = sum(_sf_tokens(sf) for sf in plan.selected)
+        saving_pct = (1 - packed_tokens / all_tokens) * 100 if all_tokens > 0 else 0.0
+
+        all_redaction_warnings = [w for sf in plan.selected for w in sf.redaction_warnings]
+
+        pack_obj = ContextPack(
+            task=request.task,
+            agent=request.agent,
+            mode=request.mode,  # type: ignore[arg-type]
+            budget=plan.budget,
+            token_estimate=packed_tokens,
+            raw_repo_tokens=all_tokens,
+            after_ignore_tokens=raw_tokens,
+            estimated_savings_percent=saving_pct,
+            changed_files=sorted(plan.all_changed),
+            selected_files=plan.selected,
+            receipts=plan.receipts if cfg.context.include_receipts else [],
+            redaction_warnings=all_redaction_warnings,
+            stale=False,
+        )
+
+        adapter = AdapterRegistry.get(request.agent, cfg)
+
+        t0 = time.perf_counter()
+        out_path = adapter.write(pack_obj, root)
+        plan.phase_times["render"] = time.perf_counter() - t0
+
+        save_snapshot(plan.current_snap, root)
+        save_pack_metadata(
+            root,
+            context_path=str(out_path.relative_to(root)),
+            snapshot_root_hash=plan.current_snap["root_hash"],
+            task=request.task,
+            agent=request.agent,
+            mode=request.mode,
+            budget=plan.budget,
+            token_estimate=packed_tokens,
+        )
+        _record_metrics(
+            root,
+            task=request.task,
+            mode=request.mode,
+            phase_times=plan.phase_times,
+            packed_tokens=packed_tokens,
+            raw_tokens=all_tokens,
+            saving_pct=saving_pct,
+            selected_count=len(plan.selected),
+            changed_count=len(plan.all_changed),
+        )
+
+        return PackResult(
+            pack=pack_obj,
+            out_path=out_path,
+            phase_times=plan.phase_times,
+            packed_tokens=packed_tokens,
+            raw_tokens=all_tokens,
+            saving_pct=saving_pct,
+            changed_files=sorted(plan.all_changed),
+            scan_result=plan.scan_result,
+        )
+
+
+def _sf_tokens(sf: SelectedFile) -> int:
+    if sf.content:
+        return estimate_tokens(sf.content)
+    parts: list[str] = []
+    if sf.summary:
+        parts.append(sf.summary)
+    for sym in sf.symbols:
+        if sym.signature:
+            parts.append(sym.signature)
+    return estimate_tokens("\n".join(parts)) if parts else 50
+
+
+def _record_metrics(
+    root: Path,
+    *,
+    task: str,
+    mode: str,
+    phase_times: dict[str, float],
+    packed_tokens: int,
+    raw_tokens: int,
+    saving_pct: float,
+    selected_count: int,
+    changed_count: int,
+) -> None:
+    metrics_path = root / ".agentpack" / "metrics.jsonl"
+    record = {
+        "ts": datetime.now(timezone.utc).isoformat(),
+        "task": task,
+        "mode": mode,
+        "packed_tokens": packed_tokens,
+        "raw_tokens": raw_tokens,
+        "saving_pct": round(saving_pct, 1),
+        "selected_files": selected_count,
+        "changed_files": changed_count,
+        "phases": {k: round(v, 3) for k, v in phase_times.items()},
+        "total_s": round(sum(phase_times.values()), 3),
+    }
+    try:
+        with metrics_path.open("a") as fh:
+            fh.write(json.dumps(record) + "\n")
+    except Exception:
+        pass

agentpack/cli.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import typer
+from agentpack.commands import init, scan, diff, status, stats, summarize, pack, install, monitor, explain, doctor, session, watch, claude_cmd, benchmark
+from agentpack import __version__
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(__version__)
+        raise typer.Exit()
+
+
+app = typer.Typer(help="AgentPack — token-aware context packing for AI coding agents.")
+
+
+@app.callback()
+def _main(
+    version: bool = typer.Option(False, "--version", "-v", callback=_version_callback, is_eager=True, help="Show version and exit."),
+) -> None:
+    pass
+
+
+for mod in [init, scan, diff, status, stats, summarize, pack, install, monitor, explain, doctor, session, watch, claude_cmd, benchmark]:
+    mod.register(app)
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

agentpack/commands/_shared.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from rich.console import Console
+
+console = Console()
+
+_ROOT = Path(".")
+
+
+def _root() -> Path:
+    return _ROOT

agentpack/commands/benchmark.py

@@ -0,0 +1,302 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.table import Table
+from rich import box
+
+from agentpack.commands._shared import console, _root
+from agentpack.commands.pack import _resolve_task
+
+
+@dataclass
+class BenchmarkCase:
+    task: str
+    mode: str = "balanced"
+    expected_files: list[str] = field(default_factory=list)
+
+
+@dataclass
+class CaseResult:
+    case: BenchmarkCase
+    packed_tokens: int
+    raw_tokens: int
+    saving_pct: float
+    selected_paths: list[str]
+    changed_covered: int      # # changed files that were selected
+    changed_total: int        # total changed files detected
+    total_s: float
+    phase_times: dict[str, float]
+
+
+def _load_cases(path: Path) -> list[BenchmarkCase]:
+    try:
+        import tomllib
+    except ImportError:
+        import tomli as tomllib  # type: ignore[no-redef]
+
+    data = tomllib.loads(path.read_text(encoding="utf-8"))
+    cases: list[BenchmarkCase] = []
+    for raw in data.get("cases", []):
+        cases.append(BenchmarkCase(
+            task=raw["task"],
+            mode=raw.get("mode", "balanced"),
+            expected_files=raw.get("expected_files", []),
+        ))
+    return cases
+
+
+def _scaffold_cases(root: Path) -> Path:
+    out = root / ".agentpack" / "benchmark.toml"
+    if out.exists():
+        return out
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(
+        '# AgentPack benchmark cases\n'
+        '# Each case runs a pack and measures token savings, speed, and\n'
+        '# selection quality. Add expected_files for precision/recall scoring.\n\n'
+        '[[cases]]\n'
+        'task = "fix auth token expiry"\n'
+        'mode = "balanced"\n'
+        '# expected_files = [\n'
+        '#   "src/auth/token.py",\n'
+        '#   "src/auth/session.py",\n'
+        '# ]\n\n'
+        '[[cases]]\n'
+        'task = "add rate limiting to API endpoints"\n'
+        'mode = "balanced"\n',
+        encoding="utf-8",
+    )
+    return out
+
+
+def _run_case(root: Path, case: BenchmarkCase) -> CaseResult:
+    from agentpack.application.pack_service import PackPlanner, PackRequest, _sf_tokens
+    from agentpack.core.token_estimator import estimate_tokens
+
+    request = PackRequest(
+        root=root,
+        agent="generic",
+        task=case.task,
+        mode=case.mode,
+        budget=0,
+        since=None,
+        refresh=False,
+        summary_provider="offline",
+    )
+
+    t0 = time.perf_counter()
+    plan = PackPlanner().plan(request)
+    total_s = time.perf_counter() - t0
+
+    packed_tokens = sum(_sf_tokens(sf) for sf in plan.selected)
+    raw_tokens = sum(f.estimated_tokens for f in plan.scan_result.all_files)
+    saving_pct = (1 - packed_tokens / raw_tokens) * 100 if raw_tokens > 0 else 0.0
+
+    selected_paths = [sf.path for sf in plan.selected]
+    selected_set = set(selected_paths)
+
+    changed_covered = len(plan.all_changed & selected_set)
+    changed_total = len(plan.all_changed)
+
+    return CaseResult(
+        case=case,
+        packed_tokens=packed_tokens,
+        raw_tokens=raw_tokens,
+        saving_pct=saving_pct,
+        selected_paths=selected_paths,
+        changed_covered=changed_covered,
+        changed_total=changed_total,
+        total_s=total_s,
+        phase_times=plan.phase_times,
+    )
+
+
+def _precision_recall(result: CaseResult) -> tuple[float, float, float]:
+    """Returns (precision, recall, f1). Requires expected_files on the case."""
+    expected = set(result.case.expected_files)
+    if not expected:
+        return 0.0, 0.0, 0.0
+    selected = set(result.selected_paths)
+    tp = len(selected & expected)
+    p = tp / len(selected) if selected else 0.0
+    r = tp / len(expected)
+    f1 = 2 * p * r / (p + r) if (p + r) > 0 else 0.0
+    return p, r, f1
+
+
+def _print_case_detail(result: CaseResult) -> None:
+    has_gt = bool(result.case.expected_files)
+    p, r, f1 = _precision_recall(result) if has_gt else (0.0, 0.0, 0.0)
+
+    console.print(f"\n[bold cyan]{result.case.task}[/]  [dim]mode={result.case.mode}[/]")
+
+    tbl = Table(box=box.SIMPLE, show_header=False, padding=(0, 2))
+    tbl.add_column(style="dim")
+    tbl.add_column(justify="right", style="bold")
+    tbl.add_row("packed tokens", f"{result.packed_tokens:,}")
+    tbl.add_row("raw tokens", f"{result.raw_tokens:,}")
+    tbl.add_row("saving", f"[green]{result.saving_pct:.1f}%[/]")
+    tbl.add_row("files selected", str(len(result.selected_paths)))
+    if result.changed_total > 0:
+        cov_pct = result.changed_covered / result.changed_total * 100
+        tbl.add_row("changed files covered", f"{result.changed_covered}/{result.changed_total}  ({cov_pct:.0f}%)")
+    tbl.add_row("total time", f"{result.total_s:.2f}s")
+    console.print(tbl)
+
+    if result.phase_times:
+        phases = Table(box=box.SIMPLE, show_header=True, padding=(0, 2))
+        phases.add_column("phase", style="dim")
+        phases.add_column("time", justify="right")
+        for phase, t in result.phase_times.items():
+            phases.add_row(phase, f"{t:.3f}s")
+        console.print(phases)
+
+    if has_gt:
+        console.print(
+            f"  precision [bold]{p:.1%}[/]  "
+            f"recall [bold]{r:.1%}[/]  "
+            f"F1 [bold]{f1:.1%}[/]"
+        )
+        expected_set = set(result.case.expected_files)
+        selected_set = set(result.selected_paths)
+        hits = expected_set & selected_set
+        misses = expected_set - selected_set
+        if hits:
+            console.print(f"  [green]hit:[/]  " + ", ".join(sorted(hits)))
+        if misses:
+            console.print(f"  [red]miss:[/] " + ", ".join(sorted(misses)))
+
+    console.print(f"  [dim]top files:[/] " + ", ".join(result.selected_paths[:5]))
+
+
+def _print_summary_table(results: list[CaseResult]) -> None:
+    has_gt = any(r.case.expected_files for r in results)
+
+    tbl = Table(box=box.SIMPLE, show_header=True, padding=(0, 1))
+    tbl.add_column("task", max_width=40)
+    tbl.add_column("mode", width=9)
+    tbl.add_column("tokens", justify="right")
+    tbl.add_column("saving", justify="right")
+    tbl.add_column("files", justify="right")
+    tbl.add_column("time", justify="right")
+    if has_gt:
+        tbl.add_column("P", justify="right")
+        tbl.add_column("R", justify="right")
+        tbl.add_column("F1", justify="right")
+
+    for r in results:
+        p, rec, f1 = _precision_recall(r) if r.case.expected_files else (0.0, 0.0, 0.0)
+        row = [
+            r.case.task[:38],
+            r.case.mode,
+            f"{r.packed_tokens:,}",
+            f"{r.saving_pct:.1f}%",
+            str(len(r.selected_paths)),
+            f"{r.total_s:.2f}s",
+        ]
+        if has_gt:
+            row += [
+                f"{p:.1%}" if r.case.expected_files else "—",
+                f"{rec:.1%}" if r.case.expected_files else "—",
+                f"{f1:.1%}" if r.case.expected_files else "—",
+            ]
+        tbl.add_row(*row)
+
+    console.print()
+    console.print(tbl)
+
+
+def _print_compare_table(task: str, results: list[CaseResult]) -> None:
+    """Side-by-side mode comparison for a single task."""
+    console.print(f"\n[bold]Mode comparison:[/] [cyan]{task}[/]\n")
+
+    tbl = Table(box=box.SIMPLE, show_header=True, padding=(0, 2))
+    tbl.add_column("mode", width=10)
+    tbl.add_column("tokens", justify="right")
+    tbl.add_column("saving", justify="right")
+    tbl.add_column("files", justify="right")
+    tbl.add_column("time", justify="right")
+
+    for r in results:
+        tbl.add_row(
+            r.case.mode,
+            f"{r.packed_tokens:,}",
+            f"{r.saving_pct:.1f}%",
+            str(len(r.selected_paths)),
+            f"{r.total_s:.2f}s",
+        )
+    console.print(tbl)
+
+
+def register(app: typer.Typer) -> None:
+    @app.command()
+    def benchmark(
+        task: str = typer.Option("", "--task", help="Single task to benchmark (skips cases file)."),
+        mode: str = typer.Option("balanced", "--mode", help="Mode for single-task run (minimal|balanced|deep)."),
+        cases: str = typer.Option("", "--cases", help="Path to TOML cases file (default: .agentpack/benchmark.toml)."),
+        compare: bool = typer.Option(False, "--compare", is_flag=True, help="Compare minimal/balanced/deep for each task."),
+        init: bool = typer.Option(False, "--init", is_flag=True, help="Scaffold a benchmark.toml and exit."),
+    ) -> None:
+        """Benchmark file selection quality and token efficiency across tasks."""
+        root = _root()
+
+        if init:
+            out = _scaffold_cases(root)
+            console.print(f"[green]✓[/] Created [bold]{out}[/]")
+            console.print("  Edit the file to add your tasks and expected files, then run [bold]agentpack benchmark[/].")
+            return
+
+        # Build case list
+        if task:
+            resolved = _resolve_task(task) if task == "auto" else task
+            bench_cases = [BenchmarkCase(task=resolved, mode=mode)]
+        else:
+            cases_path = Path(cases) if cases else root / ".agentpack" / "benchmark.toml"
+            if not cases_path.exists():
+                console.print(f"[yellow]No cases file found at {cases_path}[/]")
+                console.print("  Run [bold]agentpack benchmark --init[/] to scaffold one, or use [bold]--task \"...\"[/]")
+                raise typer.Exit(1)
+            bench_cases = _load_cases(cases_path)
+            if not bench_cases:
+                console.print("[yellow]No cases defined in benchmark file.[/]")
+                raise typer.Exit(1)
+
+        # Expand for compare mode
+        if compare:
+            expanded: list[BenchmarkCase] = []
+            for c in bench_cases:
+                for m in ("minimal", "balanced", "deep"):
+                    expanded.append(BenchmarkCase(task=c.task, mode=m, expected_files=c.expected_files))
+            bench_cases = expanded
+
+        console.print(f"\n[bold]Running {len(bench_cases)} benchmark case(s)...[/]\n")
+
+        results: list[CaseResult] = []
+        for i, c in enumerate(bench_cases, 1):
+            label = f"[{i}/{len(bench_cases)}] {c.task[:50]}  mode={c.mode}"
+            with console.status(f"[dim]{label}[/]"):
+                try:
+                    r = _run_case(root, c)
+                    results.append(r)
+                except Exception as e:
+                    console.print(f"[red]Error on case '{c.task}': {e}[/]")
+
+        if not results:
+            raise typer.Exit(1)
+
+        # Output
+        if compare and len(set(r.case.task for r in results)) == 1:
+            _print_compare_table(results[0].case.task, results)
+        elif len(results) == 1:
+            _print_case_detail(results[0])
+        else:
+            if not compare:
+                for r in results:
+                    _print_case_detail(r)
+            console.print("\n[bold]Summary[/]")
+            _print_summary_table(results)