context-router-cli 0.2.0__py3-none-any.whl

cli/__init__.py

@@ -0,0 +1,3 @@
+"""context-router CLI application."""
+
+from __future__ import annotations

cli/commands/__init__.py

@@ -0,0 +1,3 @@
+"""CLI command modules for context-router."""
+
+from __future__ import annotations

cli/commands/benchmark.py

@@ -0,0 +1,153 @@
+"""context-router benchmark command — runs the benchmark harness."""
+
+from __future__ import annotations
+
+import json
+from datetime import date
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+benchmark_app = typer.Typer(help="Run the context-router benchmark harness.")
+
+
+def _root_path(root: str) -> Path:
+    return Path(root).resolve() if root else Path.cwd()
+
+
+# ---------------------------------------------------------------------------
+# benchmark run
+# ---------------------------------------------------------------------------
+
+@benchmark_app.command("run")
+def benchmark_run(
+    project_root: Annotated[
+        str,
+        typer.Option("--project-root", help="Project root. Auto-detected when omitted."),
+    ] = "",
+    output: Annotated[
+        str,
+        typer.Option("--output", "-o", help="Output JSON path. Auto-named when omitted."),
+    ] = "",
+    naive: Annotated[
+        bool,
+        typer.Option("--naive/--no-naive", help="Include naive baseline token count."),
+    ] = True,
+    keyword: Annotated[
+        bool,
+        typer.Option("--keyword/--no-keyword", help="Include keyword baseline token count."),
+    ] = True,
+    json_output: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """Run the 20-task benchmark suite and produce a JSON + Markdown report.
+
+    Exit codes:
+      0 — success
+      1 — project not initialised (no DB)
+    """
+    from benchmark import BenchmarkRunner, to_json, to_markdown
+    from benchmark.baselines import naive_tokens, keyword_tokens
+
+    root = _root_path(project_root)
+    db_path = root / ".context-router" / "context-router.db"
+    if not db_path.exists():
+        typer.echo(
+            "No index found. Run 'context-router init' and 'context-router index' first.",
+            err=True,
+        )
+        raise typer.Exit(1)
+
+    if not json_output:
+        typer.echo("Running 20-task benchmark suite...")
+    runner = BenchmarkRunner(project_root=root)
+    report = runner.run_suite()
+
+    naive_tok = naive_tokens(root) if naive else 0
+    keyword_tok = 0
+    if keyword:
+        # Use an implement-mode query as a representative sample
+        keyword_tok = keyword_tokens(root, "implement feature endpoint handler")
+
+    # Save JSON report
+    cr_dir = root / ".context-router"
+    cr_dir.mkdir(exist_ok=True)
+    today = date.today().strftime("%Y%m%d")
+    json_path = Path(output) if output else cr_dir / f"benchmark-{today}.json"
+    json_path.write_text(to_json(report))
+
+    # Save Markdown report alongside JSON
+    md_path = json_path.with_suffix(".md")
+    md_path.write_text(to_markdown(report, naive_tok=naive_tok, keyword_tok=keyword_tok))
+
+    if json_output:
+        typer.echo(to_json(report))
+        return
+
+    s = report.summary
+    typer.echo(f"\n{'=' * 60}")
+    typer.echo(f"Benchmark complete — run {report.run_id}")
+    typer.echo(f"{'=' * 60}")
+    typer.echo(f"  Tasks:           {s.get('total_tasks', 0)}")
+    typer.echo(f"  Success rate:    {s.get('success_rate', 0):.1f}%")
+    typer.echo(f"  Avg reduction:   {s.get('avg_reduction_pct', 0):.1f}%")
+    typer.echo(f"  Avg tokens:      {s.get('avg_est_tokens', 0):,}")
+    typer.echo(f"  Avg latency:     {s.get('avg_latency_ms', 0):.0f} ms")
+    if naive_tok:
+        router_tok = s.get("avg_est_tokens", 1) or 1
+        vs_naive = round((naive_tok - router_tok) / naive_tok * 100, 1)
+        typer.echo(f"  vs Naive:        -{vs_naive:.0f}% ({naive_tok:,} → {router_tok:,} tokens)")
+    typer.echo(f"\nJSON report: {json_path}")
+    typer.echo(f"Markdown:    {md_path}")
+
+
+# ---------------------------------------------------------------------------
+# benchmark report
+# ---------------------------------------------------------------------------
+
+@benchmark_app.command("report")
+def benchmark_report(
+    input_file: Annotated[
+        str,
+        typer.Option("--input", "-i", help="Path to benchmark JSON report file."),
+    ] = "",
+    project_root: Annotated[
+        str,
+        typer.Option("--project-root", help="Project root to auto-find latest report."),
+    ] = "",
+    json_output: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """Print a Markdown summary of a saved benchmark JSON report.
+
+    If --input is omitted, finds the most recent benchmark JSON in
+    .context-router/.
+
+    Exit codes:
+      0 — success
+      1 — no report found
+    """
+    from benchmark import to_json, to_markdown
+    from benchmark.models import BenchmarkReport
+
+    # Resolve report path
+    if input_file:
+        report_path = Path(input_file)
+    else:
+        root = _root_path(project_root)
+        cr_dir = root / ".context-router"
+        candidates = sorted(cr_dir.glob("benchmark-*.json"), reverse=True)
+        if not candidates:
+            typer.echo("No benchmark report found. Run 'context-router benchmark run' first.", err=True)
+            raise typer.Exit(1)
+        report_path = candidates[0]
+
+    if not report_path.exists():
+        typer.echo(f"Report not found: {report_path}", err=True)
+        raise typer.Exit(1)
+
+    report = BenchmarkReport.model_validate_json(report_path.read_text())
+
+    if json_output:
+        typer.echo(to_json(report))
+    else:
+        typer.echo(to_markdown(report))

cli/commands/decisions.py

@@ -0,0 +1,169 @@
+"""context-router decisions command — manages architectural decision records."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+decisions_app = typer.Typer(help="Manage architectural decision records (ADRs).")
+
+
+def _open_store(project_root: str) -> tuple["DecisionStore", "Database"]:
+    """Open the database and return (DecisionStore, Database).
+
+    Caller must close the Database.
+    """
+    from core.orchestrator import _find_project_root
+    from memory.store import DecisionStore
+    from storage_sqlite.database import Database
+
+    root = Path(project_root) if project_root else _find_project_root(Path.cwd())
+    db_path = root / ".context-router" / "context-router.db"
+    if not db_path.exists():
+        typer.echo(
+            "No index found. Run 'context-router init' and 'context-router index' first.",
+            err=True,
+        )
+        raise typer.Exit(1)
+    db = Database(db_path)
+    db.initialize()
+    return DecisionStore(db), db
+
+
+@decisions_app.command("add")
+def add(
+    title: Annotated[str, typer.Argument(help="Short title for the decision.")],
+    context: Annotated[
+        str,
+        typer.Option("--context", "-c", help="Background context for the decision."),
+    ] = "",
+    decision: Annotated[
+        str,
+        typer.Option("--decision", "-d", help="The decision that was made."),
+    ] = "",
+    consequences: Annotated[
+        str,
+        typer.Option("--consequences", help="Consequences and trade-offs."),
+    ] = "",
+    tags: Annotated[
+        str,
+        typer.Option("--tags", help="Comma-separated tags (e.g. storage,performance)."),
+    ] = "",
+    status: Annotated[
+        str,
+        typer.Option("--status", help="proposed|accepted|deprecated|superseded"),
+    ] = "accepted",
+    project_root: Annotated[
+        str,
+        typer.Option("--project-root", help="Project root. Auto-detected when omitted."),
+    ] = "",
+    json_output: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """Add a new architectural decision record.
+
+    Exit codes:
+      0 — success
+      1 — database not initialised
+      2 — invalid status value
+    """
+    valid_statuses = ("proposed", "accepted", "deprecated", "superseded")
+    if status not in valid_statuses:
+        typer.echo(f"Error: --status must be one of: {', '.join(valid_statuses)}", err=True)
+        raise typer.Exit(2)
+
+    from contracts.models import Decision
+
+    tag_list = [t.strip() for t in tags.split(",") if t.strip()] if tags else []
+    dec = Decision(
+        title=title,
+        status=status,  # type: ignore[arg-type]
+        context=context,
+        decision=decision,
+        consequences=consequences,
+        tags=tag_list,
+    )
+
+    store, db = _open_store(project_root)
+    try:
+        dec_id = store.add(dec)
+    finally:
+        db.close()
+
+    if json_output:
+        import json
+        typer.echo(json.dumps({"id": dec_id, "title": title}))
+    else:
+        typer.echo(f"Decision added: {dec_id[:8]}  {title}")
+
+
+@decisions_app.command("search")
+def search(
+    query: Annotated[str, typer.Argument(help="Search query.")],
+    project_root: Annotated[
+        str,
+        typer.Option("--project-root", help="Project root. Auto-detected when omitted."),
+    ] = "",
+    json_output: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """Search stored architectural decisions by keyword.
+
+    Exit codes:
+      0 — success (even if no results)
+      1 — database not initialised
+    """
+    store, db = _open_store(project_root)
+    try:
+        results = store.search(query)
+    finally:
+        db.close()
+
+    if json_output:
+        import json
+        typer.echo(json.dumps([r.model_dump(mode="json") for r in results], indent=2))
+        return
+
+    if not results:
+        typer.echo("No decisions found.")
+        return
+
+    for dec in results:
+        typer.echo(f"  [{dec.status}] {dec.title}")
+        if dec.decision:
+            typer.echo(f"    {dec.decision[:120]}")
+        if dec.tags:
+            typer.echo(f"    tags: {', '.join(dec.tags)}")
+
+
+@decisions_app.command("list")
+def list_decisions(
+    project_root: Annotated[
+        str,
+        typer.Option("--project-root", help="Project root. Auto-detected when omitted."),
+    ] = "",
+    json_output: Annotated[bool, typer.Option("--json")] = False,
+) -> None:
+    """List all stored architectural decisions.
+
+    Exit codes:
+      0 — success
+      1 — database not initialised
+    """
+    store, db = _open_store(project_root)
+    try:
+        all_decs = store.get_all()
+    finally:
+        db.close()
+
+    if json_output:
+        import json
+        typer.echo(json.dumps([d.model_dump(mode="json") for d in all_decs], indent=2))
+        return
+
+    if not all_decs:
+        typer.echo("No decisions stored yet.")
+        return
+
+    for dec in all_decs:
+        typer.echo(f"  [{dec.status}] {dec.title}")

cli/commands/explain.py

@@ -0,0 +1,46 @@
+"""context-router explain command — explains the last generated context pack."""
+
+from __future__ import annotations
+
+import typer
+
+explain_app = typer.Typer(help="Explain context selection decisions.")
+
+
+@explain_app.command("last-pack")
+def last_pack(
+    json_output: bool = typer.Option(False, "--json", help="Output result as JSON."),
+) -> None:
+    """Print a human-readable rationale for the last generated context pack.
+
+    Each selected item is shown with a one-sentence explanation of why it was
+    included.  Run 'context-router pack' first to generate a pack.
+
+    Exit codes:
+      0 — success
+      1 — no pack found (run 'context-router pack' first)
+    """
+    from core.orchestrator import Orchestrator  # local import — keeps CLI startup fast
+
+    result = Orchestrator().last_pack()
+
+    if result is None:
+        typer.echo(
+            "No context pack found. Run 'context-router pack --mode <mode>' first.",
+            err=True,
+        )
+        raise typer.Exit(code=1)
+
+    if json_output:
+        typer.echo(result.model_dump_json(indent=2))
+        return
+
+    typer.echo(
+        f"Last pack  mode={result.mode}  items={len(result.selected_items)}  "
+        f"tokens={result.total_est_tokens:,}"
+    )
+    typer.echo("")
+
+    for item in result.selected_items:
+        typer.echo(f"  [{item.source_type}] {item.title}")
+        typer.echo(f"    {item.reason}")