agentinputlab 0.1.0a1__py3-none-any.whl

agentinputlab/cli/main.py

@@ -0,0 +1,933 @@
+"""Dependency-free AgentInputLab command line interface."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any
+
+from agentinputlab.contracts.enums import ReleaseTier, SemanticFamily, SupportStatus
+from agentinputlab.contracts.errors import AgentInputLabError, RegistryError
+from agentinputlab.contracts.serialization import to_jsonable
+from agentinputlab.registry import (
+    AlgorithmCard,
+    AlgorithmRegistry,
+    find_repository_registry,
+    load_packaged_registry,
+    load_registry_file,
+    validate_snapshot_sync,
+)
+
+
+def _cmd_smoke(args: argparse.Namespace) -> int:
+    """Run the dependency-free Query2doc to BM25 reference loop."""
+
+    from agentinputlab import FrozenAgentState, InterventionContext
+    from agentinputlab.algorithms.reformulate.query2doc import (
+        OfficialQuery2DocRow,
+        Query2DocCache,
+        Query2DocFixtureCached,
+    )
+    from agentinputlab.backends.retrieval import Document, InMemoryBM25Retriever
+    from agentinputlab.runner import InterventionRunner
+
+    state = FrozenAgentState(task_id="tiny-q1", query="capital france")
+    cache = Query2DocCache(
+        (
+            OfficialQuery2DocRow(
+                query_id="tiny-q1",
+                query=state.query,
+                pseudo_doc="Paris is the capital of France.",
+                split="tiny",
+            ),
+        )
+    )
+    algorithm = Query2DocFixtureCached(cache, split="tiny")
+    record = InterventionRunner().run(
+        algorithm,
+        state,
+        InterventionContext(seed=0),
+    )
+    transformed = record.patch.apply(state)
+    retriever = InMemoryBM25Retriever(
+        (
+            Document(
+                doc_id="fr",
+                text="Paris is the capital of France.",
+                corpus_revision="synthetic-v1",
+            ),
+            Document(
+                doc_id="de",
+                text="Berlin is the capital of Germany.",
+                corpus_revision="synthetic-v1",
+            ),
+        )
+    )
+    results = retriever.retrieve(transformed.query, top_k=2)
+    payload = {
+        "ok": bool(results and results[0].document.doc_id == "fr"),
+        "offline": True,
+        "profile_kind": record.patch.profile_kind,
+        "release_id": algorithm.release_id,
+        "input_state_hash": record.input_state_hash,
+        "patch_hash": record.patch.patch_hash,
+        "top_document_id": results[0].document.doc_id if results else None,
+    }
+    if args.json:
+        _json_dump(payload)
+    else:
+        print(
+            "offline smoke: "
+            f"{'OK' if payload['ok'] else 'FAILED'} - "
+            f"{payload['release_id']} -> {payload['top_document_id']}"
+        )
+    return 0 if payload["ok"] else 1
+
+
+def _json_dump(value: Any) -> None:
+    print(json.dumps(value, ensure_ascii=False, indent=2, sort_keys=True))
+
+
+def _table(headers: Sequence[str], rows: Sequence[Sequence[str]]) -> str:
+    widths = [len(header) for header in headers]
+    for row in rows:
+        for index, cell in enumerate(row):
+            widths[index] = max(widths[index], len(cell))
+    lines = [
+        "  ".join(header.ljust(widths[index]) for index, header in enumerate(headers)),
+        "  ".join("-" * width for width in widths),
+    ]
+    lines.extend(
+        "  ".join(cell.ljust(widths[index]) for index, cell in enumerate(row)) for row in rows
+    )
+    return "\n".join(lines)
+
+
+def _registry_from_argument(path: str | None) -> AlgorithmRegistry:
+    document = load_registry_file(path) if path else load_packaged_registry()
+    return AlgorithmRegistry(document)
+
+
+def _cmd_list(args: argparse.Namespace) -> int:
+    registry = _registry_from_argument(args.registry)
+    if args.releases:
+        records = registry.list_releases(
+            family=args.family,
+            tier=args.tier,
+            status=args.status,
+            delivery_tier=args.delivery_tier,
+        )
+        if args.json:
+            _json_dump(
+                [
+                    {
+                        "method_id": method.method_id,
+                        "display_name": method.display_name,
+                        "semantic_family": method.semantic_family.value,
+                        "release_tier": method.release_tier.value,
+                        **release.to_dict(),
+                        "entrypoint_available": release.entrypoint_available,
+                        "runnable": release.runnable,
+                        "availability": release.availability,
+                        "blocker": release.blocker,
+                    }
+                    for method, release in records
+                ]
+            )
+            return 0
+        rows = [
+            (
+                release.id,
+                method.display_name,
+                method.semantic_family.value,
+                release.status.value,
+                release.delivery_tier,
+                "yes" if release.entrypoint_available else "no",
+                "yes" if release.runnable else "no",
+                release.availability,
+                release.blocker,
+            )
+            for method, release in records
+        ]
+        print(
+            _table(
+                (
+                    "RELEASE",
+                    "METHOD",
+                    "FAMILY",
+                    "STATUS",
+                    "DELIVERY",
+                    "ENTRYPOINT",
+                    "RUNNABLE",
+                    "AVAILABILITY",
+                    "BLOCKER",
+                ),
+                rows,
+            )
+        )
+        return 0
+
+    methods = registry.list_methods(family=args.family, tier=args.tier, status=args.status)
+    if args.json:
+        _json_dump([method.to_dict() for method in methods])
+        return 0
+    rows = [
+        (
+            method.method_id,
+            method.display_name,
+            method.semantic_family.value,
+            method.release_tier.value,
+            method.status.value,
+            str(len(method.releases)),
+        )
+        for method in methods
+    ]
+    print(_table(("METHOD", "NAME", "FAMILY", "TIER", "STATUS", "RELEASES"), rows))
+    return 0
+
+
+def _cmd_show(args: argparse.Namespace) -> int:
+    registry = _registry_from_argument(args.registry)
+    result = registry.get(args.identity)
+    if isinstance(result, AlgorithmCard):
+        payload = result.to_dict()
+    else:
+        method, release = result
+        payload = {"method": method.to_dict(), "release": release.to_dict()}
+    _json_dump(payload)
+    return 0
+
+
+def _cmd_validate_registry(args: argparse.Namespace) -> int:
+    if args.path:
+        document = load_registry_file(args.path)
+        source = Path(args.path).expanduser().resolve()
+    else:
+        repository_source = find_repository_registry()
+        if repository_source is None:
+            document = load_packaged_registry()
+            source = Path("agentinputlab.registry/data/algorithms.json")
+        else:
+            document = load_registry_file(repository_source)
+            source = repository_source
+    if args.check_snapshot and source.is_file():
+        validate_snapshot_sync(source)
+    registry = AlgorithmRegistry(document)
+    report = registry.doctor()
+    payload = {
+        "valid": report.ok,
+        "source": str(source),
+        **report.to_dict(),
+    }
+    if args.json:
+        _json_dump(payload)
+    else:
+        print(
+            f"registry valid: {source} "
+            f"({report.method_count} methods, {report.release_count} releases, "
+            f"{report.must_ship_count} must-ship, {report.entrypoint_count} entrypoints, "
+            f"{report.locked_count} locked)"
+        )
+    return 0 if report.ok else 1
+
+
+def _cmd_doctor(args: argparse.Namespace) -> int:
+    registry = _registry_from_argument(args.registry)
+    report = registry.doctor()
+    source_path = Path(args.source).expanduser().resolve() if args.source else None
+    if source_path is None:
+        source_path = find_repository_registry()
+
+    sync_ok: bool | None = None
+    errors = list(report.errors)
+    if source_path is not None:
+        try:
+            validate_snapshot_sync(source_path)
+            sync_ok = True
+        except RegistryError as exc:
+            sync_ok = False
+            errors.append(str(exc))
+
+    ok = report.ok and sync_ok is not False
+    payload = {
+        **report.to_dict(),
+        "ok": ok,
+        "offline": bool(args.offline),
+        "source_registry": str(source_path) if source_path else None,
+        "snapshot_synchronized": sync_ok,
+        "errors": errors,
+    }
+    if args.json:
+        _json_dump(payload)
+    else:
+        state = "OK" if ok else "FAILED"
+        print(
+            f"registry doctor: {state} — {report.method_count} methods, "
+            f"{report.release_count} releases, {report.must_ship_count} must-ship, "
+            f"{report.entrypoint_count} entrypoints, {report.locked_count} locked"
+        )
+        if sync_ok is True:
+            print("source snapshot: synchronized")
+        elif sync_ok is False:
+            print("source snapshot: OUT OF SYNC")
+        elif source_path is None:
+            print("source snapshot: not checked (installed-package mode)")
+        for warning in report.warnings:
+            print(f"warning: {warning}")
+        for error in errors:
+            print(f"error: {error}", file=sys.stderr)
+    return 0 if ok else 1
+
+
+def _cmd_selector_list(args: argparse.Namespace) -> int:
+    from agentinputlab.selectors import list_selector_cards
+
+    cards = list_selector_cards()
+    payload = [
+        {
+            "selector_id": card.selector_id,
+            "display_name": card.display_name,
+            "kind": card.kind.value,
+            "requires_fit": card.requires_fit,
+            "optional_dependency": card.optional_dependency or None,
+        }
+        for card in cards
+    ]
+    if args.json:
+        _json_dump(payload)
+    else:
+        print(
+            _table(
+                ("SELECTOR", "NAME", "KIND", "REQUIRES_FIT", "OPTIONAL_DEPENDENCY"),
+                [
+                    (
+                        item["selector_id"],
+                        item["display_name"],
+                        item["kind"],
+                        "yes" if item["requires_fit"] else "no",
+                        item["optional_dependency"] or "-",
+                    )
+                    for item in payload
+                ],
+            )
+        )
+    return 0
+
+
+def _cmd_selector_features(args: argparse.Namespace) -> int:
+    from agentinputlab.contracts import FrozenAgentState
+    from agentinputlab.selectors import VisibleStateFeatureExtractor
+
+    state = FrozenAgentState(
+        query=args.query,
+        instruction=args.instruction,
+        tool_names=tuple(args.tool_name),
+    )
+    observation = VisibleStateFeatureExtractor().extract(state)
+    _json_dump(
+        {
+            "state_hash": state.state_hash,
+            "feature_hash": observation.feature_hash,
+            "features": to_jsonable(observation.features),
+            "extractor": {
+                "id": observation.extractor_id,
+                "revision": observation.extractor_revision,
+            },
+            "access_domains": [item.value for item in observation.access_domains],
+            "provenance": to_jsonable(observation.provenance),
+            "raw_text_persisted": False,
+        }
+    )
+    return 0
+
+
+def _cmd_selector_inspect(args: argparse.Namespace) -> int:
+    from agentinputlab.selectors import (
+        SelectorArtifactIdentity,
+        SelectorArtifactStore,
+    )
+
+    identity = SelectorArtifactIdentity(
+        selector_id=args.selector_id,
+        revision=args.revision,
+        sha256=args.sha256,
+    )
+    _selector, bundle = SelectorArtifactStore(args.store).load(identity)
+    _json_dump(
+        {
+            "identity": to_jsonable(identity),
+            "stage": bundle.stage.value,
+            "bundle_hash": bundle.bundle_hash,
+            "model_hash": bundle.model_hash,
+            "extractor": {
+                "id": bundle.extractor_id,
+                "revision": bundle.extractor_revision,
+                "sha256": bundle.extractor_hash,
+            },
+            "feature_schema": {
+                "id": bundle.feature_schema_id,
+                "sha256": bundle.feature_schema_hash,
+            },
+            "representative_by_family": {
+                family.value: release_id
+                for family, release_id in bundle.representative_by_family.items()
+            },
+            "training_table_sha256": bundle.training_table_sha256,
+            "split_provenance_hash": bundle.split_provenance_hash,
+            "comparison_profile_hash": bundle.comparison_profile_hash,
+        }
+    )
+    return 0
+
+
+def _cmd_dataset_prepare(args: argparse.Namespace) -> int:
+    from agentinputlab.benchmarks import prepare_benchmark
+
+    _json_dump(
+        prepare_benchmark(
+            args.cell_id,
+            cache_dir=args.cache_dir,
+            offline=args.offline,
+            accept_license_review=args.accept_license_review,
+            max_download_bytes=args.max_download_mib * 1024 * 1024,
+            max_prepared_bytes=args.max_prepared_mib * 1024 * 1024,
+        )
+    )
+    return 0
+
+
+def _cmd_trec_sample(args: argparse.Namespace) -> int:
+    from agentinputlab.data import prepare_trec_dl_sample
+
+    _json_dump(
+        prepare_trec_dl_sample(
+            args.root,
+            year=args.year,
+            query_count=args.query_count,
+            query_offset=args.query_offset,
+            offline=args.offline,
+            accept_license_review=args.accept_license_review,
+            max_download_bytes=args.max_download_mib * 1024 * 1024,
+            expected_corpus_revision=args.corpus_revision,
+            source_sample_root=args.source_sample_root,
+            source_manifest_sha256=args.source_manifest_sha256,
+        )
+    )
+    return 0
+
+
+def _cmd_campaign_doctor(args: argparse.Namespace) -> int:
+    from agentinputlab.campaign import campaign_doctor
+
+    readiness = args.readiness
+    if readiness is None:
+        candidate = Path("configs/parity/adapter_readiness.json")
+        readiness = candidate if candidate.is_file() else None
+    report = campaign_doctor(
+        args.prepared,
+        readiness_path=readiness,
+    )
+    _json_dump(to_jsonable(report))
+    target_ready = (
+        report["static_data_ready"] if args.target == "static" else report["full_campaign_ready"]
+    )
+    return 0 if target_ready else 2
+
+
+def _cmd_campaign_prepare(args: argparse.Namespace) -> int:
+    from agentinputlab.benchmarks import (
+        BenchmarkSmokeAssetRegistry,
+        materialize_benchmark_asset,
+    )
+    from agentinputlab.campaign import existing_campaign_assets
+
+    registry = BenchmarkSmokeAssetRegistry.default()
+    reports: list[dict[str, Any]] = []
+    blocked: list[dict[str, str]] = []
+    for asset_id in existing_campaign_assets():
+        asset = registry.get(asset_id)
+        if asset.status == "license_review_required" and not args.accept_license_review:
+            blocked.append(
+                {
+                    "asset_id": asset_id,
+                    "reason": (
+                        "license review is required; rerun with "
+                        "--accept-license-review after reviewing the source terms"
+                    ),
+                }
+            )
+            continue
+        reports.append(
+            materialize_benchmark_asset(
+                asset_id,
+                store_root=args.store,
+                prepared_root=args.prepared,
+                allow_network=args.allow_network,
+                accept_license_review=args.accept_license_review,
+            )
+        )
+    _json_dump(
+        {
+            "schema_version": 1,
+            "protocol": "agentinputlab.campaign-prepare.v1",
+            "scope": "existing-data-main",
+            "assets": reports,
+            "blocked": blocked,
+            "inventory_only_cells_touched": 0,
+            "experiment_executed": False,
+        }
+    )
+    return 0 if not blocked else 2
+
+
+def _cmd_campaign_bootstrap(args: argparse.Namespace) -> int:
+    from agentinputlab.runtime_bootstrap import bootstrap_runtime_sources
+
+    report = bootstrap_runtime_sources(
+        args.root,
+        method_ids=args.method or None,
+        include_arenas=not args.no_arenas,
+        allow_network=args.allow_network,
+    )
+    _json_dump(to_jsonable(report))
+    return 0 if report["ready_count"] == report["source_count"] else 2
+
+
+def _cmd_campaign_smoke(args: argparse.Namespace) -> int:
+    from agentinputlab.campaign import campaign_data_smoke
+
+    _json_dump(to_jsonable(campaign_data_smoke(args.prepared)))
+    return 0
+
+
+def _cmd_campaign_methods(args: argparse.Namespace) -> int:
+    from agentinputlab.campaign import campaign_method_matrix
+
+    report = campaign_method_matrix(args.catalog, args.readiness)
+    _json_dump(to_jsonable(report))
+    return 0 if report["adapter_ready"] == report["method_count"] else 2
+
+
+def _cmd_campaign_run(args: argparse.Namespace) -> int:
+    from agentinputlab.experiments.cli import main as experiment_main
+
+    arguments = ["run", str(args.manifest)]
+    if args.driver:
+        arguments.extend(("--driver", args.driver))
+    if args.no_resolve_units:
+        arguments.append("--no-resolve-units")
+    if args.shard_count is not None:
+        arguments.extend(("--shard-count", str(args.shard_count)))
+        arguments.extend(("--shard-index", str(args.shard_index)))
+    if args.execute:
+        arguments.append("--execute")
+    arguments.extend(("--output-root", str(args.output_root)))
+    if args.resume:
+        arguments.append("--resume")
+    if args.fail_fast:
+        arguments.append("--fail-fast")
+    return experiment_main(arguments)
+
+
+def _cmd_campaign_verify(args: argparse.Namespace) -> int:
+    from agentinputlab.campaign import campaign_verify_run
+
+    _json_dump(
+        to_jsonable(
+            campaign_verify_run(
+                args.run_dir,
+                allow_incomplete=args.allow_incomplete,
+            )
+        )
+    )
+    return 0
+
+
+def _cmd_campaign_analyze(args: argparse.Namespace) -> int:
+    from agentinputlab.experiments import analyze_confirmatory_protocol
+
+    result = analyze_confirmatory_protocol(
+        tuple(str(path) for path in args.run_dir),
+        protocol=args.protocol,
+        metric=args.metric,
+        algorithm_failure_value=args.algorithm_failure_value,
+        bootstrap_samples=args.bootstrap_samples,
+        permutation_samples=args.permutation_samples,
+        random_seed=args.random_seed,
+    )
+    _json_dump(to_jsonable(result))
+    return 0
+
+
+def _cmd_campaign_run_all(args: argparse.Namespace) -> int:
+    from agentinputlab.campaign_runner import (
+        load_one_click_campaign,
+        run_one_click_campaign,
+    )
+
+    campaign = load_one_click_campaign(args.config)
+    result = run_one_click_campaign(campaign, execute=args.execute)
+    _json_dump(to_jsonable(result))
+    if not args.execute:
+        return 0 if result["ready"] else 2
+    if result.get("execution_blocked") is True:
+        return 2
+    return 0 if result["all_succeeded"] else 3
+
+
+def _cmd_campaign_run_production(args: argparse.Namespace) -> int:
+    from agentinputlab.production_campaign import (
+        load_production_campaign,
+        run_production_campaign,
+    )
+
+    campaign = load_production_campaign(args.config)
+    result = run_production_campaign(campaign, execute=args.execute)
+    _json_dump(to_jsonable(result))
+    if not args.execute:
+        return 0 if result["ready"] else 2
+    if result.get("execution_blocked") is True:
+        return 2
+    return 0 if result["all_succeeded"] else 3
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="agentinputlab",
+        description="Inspect and validate the AgentInputLab algorithm registry.",
+    )
+    parser.add_argument(
+        "--registry",
+        help="Use a source registry instead of the packaged snapshot.",
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    data_parser = subparsers.add_parser(
+        "datasets", help="Prepare source-locked datasets with bounded automatic downloads."
+    )
+    data_commands = data_parser.add_subparsers(dest="dataset_command", required=True)
+    data_prepare = data_commands.add_parser(
+        "prepare", help="Reuse a cache or download missing pinned source files."
+    )
+    data_prepare.add_argument("cell_id")
+    data_prepare.add_argument("--cache-dir", type=Path)
+    data_prepare.add_argument("--offline", action="store_true")
+    data_prepare.add_argument("--accept-license-review", action="store_true")
+    data_prepare.add_argument(
+        "--max-download-mib",
+        type=int,
+        default=512,
+        help="Total missing source-file limit; default 512 MiB. No full multi-GB download by default.",
+    )
+    data_prepare.set_defaults(func=_cmd_dataset_prepare)
+    data_prepare.add_argument(
+        "--max-prepared-mib",
+        type=int,
+        default=512,
+        help="Per-asset normalized-output limit; default 512 MiB. Keeps a further 1 GiB free.",
+    )
+    trec = data_commands.add_parser(
+        "prepare-trec-sample", help="Prepare a bounded official-source TREC compatibility sample."
+    )
+    trec.add_argument("root", type=Path)
+    trec.add_argument("--year", required=True, type=int, choices=(2019, 2020))
+    trec.add_argument("--query-count", type=int, default=2)
+    trec.add_argument("--query-offset", type=int, default=0)
+    trec.add_argument("--offline", action="store_true")
+    trec.add_argument("--accept-license-review", action="store_true")
+    trec.add_argument("--max-download-mib", type=int, default=16)
+    trec.add_argument("--corpus-revision")
+    trec.add_argument("--source-sample-root", type=Path)
+    trec.add_argument("--source-manifest-sha256")
+    trec.set_defaults(func=_cmd_trec_sample)
+
+    list_parser = subparsers.add_parser("list", help="List methods or release profiles.")
+    list_parser.add_argument(
+        "--family", choices=[item.value for item in SemanticFamily], help="Filter by family."
+    )
+    list_parser.add_argument(
+        "--tier", choices=[item.value for item in ReleaseTier], help="Filter by release tier."
+    )
+    list_parser.add_argument(
+        "--status", choices=[item.value for item in SupportStatus], help="Filter by status."
+    )
+    list_parser.add_argument(
+        "--delivery-tier",
+        choices=["must_ship", "stretch", "blocked_or_post_v1"],
+        help="Filter release profiles by engineering delivery tier.",
+    )
+    list_parser.add_argument(
+        "--releases", action="store_true", help="List release profiles instead of methods."
+    )
+    list_parser.add_argument("--json", action="store_true", help="Emit JSON.")
+    list_parser.set_defaults(func=_cmd_list)
+
+    show_parser = subparsers.add_parser("show", help="Show one method or release profile.")
+    show_parser.add_argument("identity", help="Canonical method ID or exact release ID.")
+    show_parser.set_defaults(func=_cmd_show)
+
+    doctor_parser = subparsers.add_parser("doctor", help="Run registry integrity diagnostics.")
+    doctor_parser.add_argument("--source", help="Source registry to compare with the snapshot.")
+    doctor_parser.add_argument(
+        "--offline",
+        action="store_true",
+        help="Assert that diagnostics must not contact external services.",
+    )
+    doctor_parser.add_argument("--json", action="store_true", help="Emit JSON.")
+    doctor_parser.set_defaults(func=_cmd_doctor)
+
+    validate_parser = subparsers.add_parser(
+        "validate-registry", help="Validate a source or packaged registry."
+    )
+    validate_parser.add_argument(
+        "path", nargs="?", help="Registry path; defaults to checkout source."
+    )
+    validate_parser.add_argument(
+        "--check-snapshot",
+        action="store_true",
+        help="Also require equality with the packaged snapshot.",
+    )
+    validate_parser.add_argument("--json", action="store_true", help="Emit JSON.")
+    validate_parser.set_defaults(func=_cmd_validate_registry)
+
+    smoke_parser = subparsers.add_parser(
+        "smoke",
+        help="Run the dependency-free Query2doc and BM25 reference loop.",
+    )
+    smoke_parser.add_argument("--json", action="store_true", help="Emit JSON.")
+    smoke_parser.set_defaults(func=_cmd_smoke)
+
+    selector_parser = subparsers.add_parser(
+        "selector",
+        help="Inspect selector catalog, visible features, and exact frozen artifacts.",
+    )
+    selector_subparsers = selector_parser.add_subparsers(
+        dest="selector_command",
+        required=True,
+    )
+    selector_list = selector_subparsers.add_parser("list", help="List selector cards.")
+    selector_list.add_argument("--json", action="store_true", help="Emit JSON.")
+    selector_list.set_defaults(func=_cmd_selector_list)
+
+    selector_features = selector_subparsers.add_parser(
+        "features",
+        help="Extract evaluator-blind visible-state features.",
+    )
+    selector_features.add_argument("--query", default="")
+    selector_features.add_argument("--instruction", default="")
+    selector_features.add_argument("--tool-name", action="append", default=[])
+    selector_features.set_defaults(func=_cmd_selector_features)
+
+    selector_inspect = selector_subparsers.add_parser(
+        "inspect",
+        help="Inspect one exact content-addressed selector artifact.",
+    )
+    selector_inspect.add_argument("--store", type=Path, required=True)
+    selector_inspect.add_argument("--selector-id", required=True)
+    selector_inspect.add_argument("--revision", required=True)
+    selector_inspect.add_argument("--sha256", required=True)
+    selector_inspect.set_defaults(func=_cmd_selector_inspect)
+
+    campaign_parser = subparsers.add_parser(
+        "campaign",
+        help=(
+            "Prepare, diagnose, smoke, run, verify, and analyze the frozen existing-data campaign."
+        ),
+    )
+    campaign_subparsers = campaign_parser.add_subparsers(
+        dest="campaign_command",
+        required=True,
+    )
+
+    campaign_doctor_parser = campaign_subparsers.add_parser(
+        "doctor",
+        help="Inspect real prepared data, method surfaces, and stateful-runtime blockers.",
+    )
+    campaign_doctor_parser.add_argument(
+        "--prepared",
+        type=Path,
+        default=Path("data/normalized"),
+    )
+    campaign_doctor_parser.add_argument(
+        "--readiness",
+        type=Path,
+        help="Adapter readiness matrix; defaults to the checkout catalog when present.",
+    )
+    campaign_doctor_parser.add_argument(
+        "--target",
+        choices=("static", "full"),
+        default="full",
+        help="Choose whether missing stateful runtime bridges are fatal.",
+    )
+    campaign_doctor_parser.set_defaults(func=_cmd_campaign_doctor)
+
+    campaign_prepare_parser = campaign_subparsers.add_parser(
+        "prepare",
+        help="Acquire and preprocess accepted sources only; never touches D0 inventory cells.",
+    )
+    campaign_prepare_parser.add_argument(
+        "--store",
+        type=Path,
+        default=Path("data/raw"),
+    )
+    campaign_prepare_parser.add_argument(
+        "--prepared",
+        type=Path,
+        default=Path("data/normalized"),
+    )
+    campaign_prepare_parser.add_argument("--allow-network", action="store_true")
+    campaign_prepare_parser.add_argument(
+        "--accept-license-review",
+        action="store_true",
+        help="Process ClariQ locally only after reviewing its source terms.",
+    )
+    campaign_prepare_parser.set_defaults(func=_cmd_campaign_prepare)
+
+    campaign_bootstrap_parser = campaign_subparsers.add_parser(
+        "bootstrap",
+        help=(
+            "Verify or fetch exact public method/arena source checkouts; "
+            "does not install packages, download weights, or run experiments."
+        ),
+    )
+    campaign_bootstrap_parser.add_argument(
+        "--root",
+        type=Path,
+        default=Path("operator/checkouts"),
+    )
+    campaign_bootstrap_parser.add_argument(
+        "--method",
+        action="append",
+        help="Limit bootstrap to one method ID; repeat for multiple methods.",
+    )
+    campaign_bootstrap_parser.add_argument(
+        "--no-arenas",
+        action="store_true",
+        help="Do not include the four official common-support source checkouts.",
+    )
+    campaign_bootstrap_parser.add_argument(
+        "--allow-network",
+        action="store_true",
+        help="Fetch absent or mismatched public checkouts at their exact pinned commits.",
+    )
+    campaign_bootstrap_parser.set_defaults(func=_cmd_campaign_bootstrap)
+
+    campaign_smoke_parser = campaign_subparsers.add_parser(
+        "smoke",
+        help="Load and score one real prepared example from all seven static D2 cells.",
+    )
+    campaign_smoke_parser.add_argument(
+        "--prepared",
+        type=Path,
+        default=Path("data/normalized"),
+    )
+    campaign_smoke_parser.set_defaults(func=_cmd_campaign_smoke)
+
+    campaign_methods_parser = campaign_subparsers.add_parser(
+        "methods",
+        help="List exact launch commands and reviewed adapter gates for all 27 methods.",
+    )
+    campaign_methods_parser.add_argument(
+        "--catalog",
+        type=Path,
+        default=Path("configs/parity/methods.json"),
+    )
+    campaign_methods_parser.add_argument(
+        "--readiness",
+        type=Path,
+        default=Path("configs/parity/adapter_readiness.json"),
+    )
+    campaign_methods_parser.set_defaults(func=_cmd_campaign_methods)
+
+    campaign_run_parser = campaign_subparsers.add_parser(
+        "run",
+        help="Preflight a frozen manifest by default; execute only with --execute.",
+    )
+    campaign_run_parser.add_argument("manifest", type=Path)
+    campaign_run_parser.add_argument("--driver")
+    campaign_run_parser.add_argument("--no-resolve-units", action="store_true")
+    campaign_run_parser.add_argument("--shard-count", type=int)
+    campaign_run_parser.add_argument("--shard-index", type=int, default=0)
+    campaign_run_parser.add_argument("--execute", action="store_true")
+    campaign_run_parser.add_argument("--output-root", type=Path, default=Path("results"))
+    campaign_run_parser.add_argument("--resume", action="store_true")
+    campaign_run_parser.add_argument("--fail-fast", action="store_true")
+    campaign_run_parser.set_defaults(func=_cmd_campaign_run)
+
+    campaign_verify_parser = campaign_subparsers.add_parser(
+        "verify",
+        help="Verify manifest, plan, driver identity, and cell checksums.",
+    )
+    campaign_verify_parser.add_argument("run_dir", type=Path)
+    campaign_verify_parser.add_argument("--allow-incomplete", action="store_true")
+    campaign_verify_parser.set_defaults(func=_cmd_campaign_verify)
+
+    campaign_analyze_parser = campaign_subparsers.add_parser(
+        "analyze",
+        help="Run the strict confirmatory analyzer over verified run directories.",
+    )
+    campaign_analyze_parser.add_argument("run_dir", type=Path, nargs="+")
+    campaign_analyze_parser.add_argument("--protocol", default="auto")
+    campaign_analyze_parser.add_argument("--metric", default="valid_success")
+    campaign_analyze_parser.add_argument("--bootstrap-samples", type=int, default=2_000)
+    campaign_analyze_parser.add_argument("--permutation-samples", type=int, default=2_000)
+    campaign_analyze_parser.add_argument("--random-seed", type=int, default=2027)
+    campaign_analyze_parser.add_argument("--algorithm-failure-value", type=float)
+    campaign_analyze_parser.set_defaults(func=_cmd_campaign_analyze)
+
+    campaign_run_all_parser = campaign_subparsers.add_parser(
+        "run-all",
+        help=(
+            "Preflight all 27 methods and ten accepted-source cells, then execute "
+            "every frozen job with one explicit --execute."
+        ),
+    )
+    campaign_run_all_parser.add_argument(
+        "config",
+        type=Path,
+        help="Strict self-hashed one-click campaign bundle.",
+    )
+    campaign_run_all_parser.add_argument(
+        "--execute",
+        action="store_true",
+        help="Start model/external-runtime calls only after every job preflight is ready.",
+    )
+    campaign_run_all_parser.set_defaults(func=_cmd_campaign_run_all)
+
+    campaign_run_production_parser = campaign_subparsers.add_parser(
+        "run-production",
+        help=(
+            "Preflight or start the complete ordered production DAG: data, "
+            "27-method library parity/discovery, confirmations, selector, robustness, "
+            "stateful replications, and paper export."
+        ),
+    )
+    campaign_run_production_parser.add_argument(
+        "config",
+        type=Path,
+        help="Strict self-hashed production campaign DAG.",
+    )
+    campaign_run_production_parser.add_argument(
+        "--execute",
+        action="store_true",
+        help="Start the complete DAG only after every initial prerequisite passes.",
+    )
+    campaign_run_production_parser.set_defaults(func=_cmd_campaign_run_production)
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return int(args.func(args))
+    except AgentInputLabError as exc:
+        print(f"agentinputlab: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())