invarlock 0.2.0__py3-none-any.whl

invarlock/cli/__main__.py

@@ -0,0 +1,8 @@
+"""Module entry so you can `python -m invarlock.cli`."""
+
+from __future__ import annotations
+
+from .app import main
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

invarlock/cli/_evidence.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+
+def maybe_dump_guard_evidence(target_dir: str | Path, payload: dict[str, Any]) -> None:
+    """Dump a small JSON blob of guard decision inputs when INVARLOCK_EVIDENCE_DEBUG=1.
+
+    Keeps payload tiny; callers should pre-filter arrays and redact large fields.
+    """
+    if os.getenv("INVARLOCK_EVIDENCE_DEBUG", "0") != "1":
+        return
+    try:
+        path = Path(target_dir)
+        path.mkdir(parents=True, exist_ok=True)
+        out = path / "guards_evidence.json"
+        out.write_text(
+            json.dumps(payload, indent=2, ensure_ascii=False), encoding="utf-8"
+        )
+    except Exception:
+        # Never raise in evidence hook
+        pass

invarlock/cli/_json.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, is_dataclass
+from datetime import UTC, datetime
+from typing import Any
+
+import typer
+
+try:
+    from invarlock.core.exceptions import InvarlockError
+except Exception:  # pragma: no cover - optional in minimal environments
+    InvarlockError = None  # type: ignore[assignment]
+
+
+def _ts() -> str:
+    return datetime.now(UTC).isoformat()
+
+
+def emit(payload: Any, exit_code: int) -> None:
+    """Emit a JSON payload with a stable envelope and exit.
+
+    - Adds `ts` (UTC ISO) and `component=cli` if absent
+    - Accepts dicts or dataclasses
+    - Exits with provided code via Typer
+    """
+    if is_dataclass(payload):
+        payload = asdict(payload)  # type: ignore[assignment]
+    if isinstance(payload, dict):
+        payload.setdefault("ts", _ts())
+        payload.setdefault("component", "cli")
+    typer.echo(json.dumps(payload, sort_keys=True))
+    raise typer.Exit(exit_code)
+
+
+def encode_error(exc: Exception) -> dict[str, Any]:
+    """Encode an exception as a structured error object for JSON envelopes.
+
+    Fields:
+      - code: error code if available (InvarlockError), else a generic tag
+      - category: exception class name
+      - recoverable: bool when available, else False
+      - context: attached details when available, else {}
+    """
+    try:
+        category = type(exc).__name__
+    except Exception:
+        category = "Exception"
+
+    # Default shape
+    out: dict[str, Any] = {
+        "code": "E_GENERIC",
+        "category": category,
+        "recoverable": False,
+        "context": {},
+    }
+
+    # InvarlockError dataclass provides code/details/recoverable
+    try:
+        if InvarlockError is not None and isinstance(exc, InvarlockError):
+            out["code"] = getattr(exc, "code", out["code"]) or out["code"]
+            out["recoverable"] = bool(getattr(exc, "recoverable", False))
+            details = getattr(exc, "details", None)
+            if isinstance(details, dict):
+                out["context"] = details
+            return out
+    except Exception:
+        # Fall back to generic encoding when anything unexpected happens
+        pass
+
+    # Heuristic: common schema/validation categories → generic schema code
+    if category in {"ValidationError", "ConfigError", "DataError"}:
+        out["code"] = "E_SCHEMA"
+
+    return out

invarlock/cli/adapter_auto.py

@@ -0,0 +1,162 @@
+"""
+Auto adapter resolution utilities.
+
+These helpers map a model identifier (HF directory or Hub ID) to a
+concrete built-in adapter name (hf_gpt2, hf_llama, hf_bert) without
+adding a hard dependency on Transformers.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+
+def _read_local_hf_config(model_id: str | os.PathLike[str]) -> dict[str, Any] | None:
+    """Read config.json from a local HF directory if present."""
+    try:
+        p = Path(model_id)
+    except Exception:
+        return None
+    cfg_path = p / "config.json"
+    if not cfg_path.exists():
+        return None
+    try:
+        with cfg_path.open("r", encoding="utf-8") as fh:
+            data = json.load(fh)
+        if isinstance(data, dict):
+            return data
+    except Exception:
+        return None
+    return None
+
+
+def _detect_quant_family_from_cfg(cfg: dict[str, Any]) -> str | None:
+    """Detect quantization family from a HF config dict.
+
+    Returns one of: 'hf_gptq', 'hf_awq', 'hf_bnb' or None if not detected.
+    """
+    try:
+        q = cfg.get("quantization_config") or {}
+        if isinstance(q, dict):
+            method = str(q.get("quant_method", q.get("quant_method_full", ""))).lower()
+            if any(tok in method for tok in ("gptq",)):
+                return "hf_gptq"
+            if any(tok in method for tok in ("awq",)):
+                return "hf_awq"
+            # BitsAndBytes style
+            if any(
+                str(q.get(k, "")).lower() in {"true", "1"}
+                for k in ("load_in_4bit", "load_in_8bit")
+            ) or any("bitsandbytes" in str(v).lower() for v in q.values()):
+                return "hf_bnb"
+    except Exception:
+        return None
+    return None
+
+
+def resolve_auto_adapter(
+    model_id: str | os.PathLike[str], default: str = "hf_gpt2"
+) -> str:
+    """Resolve an appropriate built-in adapter name for a model.
+
+    Heuristics:
+      - Prefer local config.json (no network). Inspect `model_type` and
+        `architectures` to classify LLaMA/Mistral vs BERT vs GPT-like.
+      - Fallback to simple name heuristics on the model_id string.
+      - Default to `hf_gpt2` when unsure.
+    """
+    cfg = _read_local_hf_config(model_id)
+    model_id_str = str(model_id)
+
+    def _from_cfg(c: dict[str, Any]) -> str | None:
+        # Prefer explicit quantization families first
+        fam = _detect_quant_family_from_cfg(c)
+        if fam:
+            return fam
+        mt = str(c.get("model_type", "")).lower()
+        archs = [str(a) for a in c.get("architectures", []) if isinstance(a, str)]
+        arch_blob = " ".join(archs)
+        if (
+            mt in {"llama", "mistral", "qwen", "yi"}
+            or "Llama" in arch_blob
+            or "Mistral" in arch_blob
+        ):
+            return "hf_llama"
+        # Treat masked-LM families as BERT-like
+        if (
+            mt in {"bert", "roberta", "distilbert", "albert", "deberta", "deberta-v2"}
+            or "MaskedLM" in arch_blob
+        ):
+            return "hf_bert"
+        # Generic causal LM
+        if "CausalLM" in arch_blob or mt in {
+            "gpt2",
+            "gpt_neox",
+            "opt",
+            "gptj",
+            "gptj8bit",
+        }:
+            return "hf_gpt2"
+        return None
+
+    # If local directory contains ONNX model files, prefer hf_onnx
+    try:
+        p = Path(model_id)
+        if p.exists() and p.is_dir():
+            # Common Optimum export names
+            onnx_files = [
+                "model.onnx",
+                "decoder_model.onnx",
+                "decoder_with_past_model.onnx",
+                "encoder_model.onnx",
+            ]
+            if any((p / fname).exists() for fname in onnx_files):
+                return "hf_onnx"
+    except Exception:
+        pass
+
+    if isinstance(cfg, dict):
+        resolved = _from_cfg(cfg)
+        if resolved:
+            return resolved
+
+    # String heuristics as last resort
+    lower_id = model_id_str.lower()
+    # Quantized repo heuristics
+    if any(k in lower_id for k in ["gptq", "-gptq", "_gptq"]):
+        return "hf_gptq"
+    if any(k in lower_id for k in ["awq", "-awq", "_awq"]):
+        return "hf_awq"
+    if any(
+        k in lower_id for k in ["bnb", "bitsandbytes", "-4bit", "-8bit", "4bit", "8bit"]
+    ):
+        return "hf_bnb"
+    if any(k in lower_id for k in ["llama", "mistral", "qwen", "yi"]):
+        return "hf_llama"
+    if any(k in lower_id for k in ["bert", "roberta", "albert", "deberta"]):
+        return "hf_bert"
+    return default
+
+
+def apply_auto_adapter_if_needed(cfg: Any) -> Any:
+    """Mutate/clone a InvarLockConfig to resolve adapter:auto → concrete adapter.
+
+    Returns the same config object if no change is needed.
+    """
+    try:
+        adapter = str(getattr(cfg.model, "adapter", ""))
+        if adapter.strip().lower() not in {"auto", "hf_auto", "auto_hf"}:
+            return cfg
+        model_id = str(getattr(cfg.model, "id", ""))
+        resolved = resolve_auto_adapter(model_id)
+        data = cfg.model_dump()
+        data.setdefault("model", {})["adapter"] = resolved
+        return cfg.__class__(data)  # re-wrap as InvarLockConfig
+    except Exception:
+        return cfg
+
+
+__all__ = ["resolve_auto_adapter", "apply_auto_adapter_if_needed"]

invarlock/cli/app.py

@@ -0,0 +1,287 @@
+"""
+InvarLock CLI Main Entry Point (unified namespace)
+=============================================
+
+Modern CLI with clean command interface using modular command structure.
+
+Import guard: set `INVARLOCK_LIGHT_IMPORT=1` to avoid heavy plugin discovery and
+third‑party imports during docs/tests. This keeps `import invarlock.cli.app` safe in
+minimal environments.
+"""
+
+from __future__ import annotations
+
+import os
+
+import typer
+from rich.console import Console
+from typer.core import TyperGroup
+
+from invarlock.security import enforce_default_security
+
+# Lightweight import mode disables heavy side effects in some modules, but we no
+# longer force plugin discovery off globally here; individual commands may gate
+# discovery based on their own flags.
+LIGHT_IMPORT = os.getenv("INVARLOCK_LIGHT_IMPORT", "").strip().lower() in {
+    "1",
+    "true",
+    "yes",
+}
+
+
+# Deterministic help ordering
+class OrderedGroup(TyperGroup):
+    def list_commands(self, ctx):  # type: ignore[override]
+        return [
+            "certify",
+            "report",
+            "verify",
+            "run",
+            "plugins",
+            "doctor",
+            "version",
+        ]
+
+
+# Initialize CLI app
+app = typer.Typer(
+    name="invarlock",
+    help=(
+        "InvarLock — certify model changes with deterministic pairing and safety gates.\n"
+        "Quick path: invarlock certify --baseline <MODEL> --subject <MODEL>\n"
+        "Hint: use --edit-config to run the built-in quant_rtn demo.\n"
+        "Tip: enable downloads with INVARLOCK_ALLOW_NETWORK=1 when fetching.\n"
+        "Exit codes:\n"
+        "  0=success\n"
+        "  1=generic failure\n"
+        "  2=schema invalid\n"
+        "  3=hard abort ([INVARLOCK:EXXX])."
+    ),
+    no_args_is_help=True,
+    cls=OrderedGroup,
+)
+
+console = Console()
+
+
+@app.command()
+def version():
+    """Show InvarLock version."""
+    # Prefer package metadata when available so CLI reflects wheel truth
+    try:
+        from importlib.metadata import version as _pkg_version
+
+        schema = None
+        try:
+            from invarlock.reporting.certificate import (
+                CERTIFICATE_SCHEMA_VERSION as _SCHEMA,
+            )
+
+            schema = _SCHEMA
+        except Exception:
+            schema = None
+        msg = f"InvarLock {_pkg_version('invarlock')}"
+        if schema:
+            msg += f" · schema={schema}"
+        console.print(msg)
+        return
+    except Exception:
+        pass
+    try:
+        from invarlock import __version__
+
+        console.print(f"InvarLock {__version__}")
+    except Exception:
+        console.print("InvarLock version unknown")
+
+
+"""Register command modules and groups in the desired help order.
+
+Order: certify → report → run → plugins → doctor → version
+"""
+
+
+@app.command(
+    name="certify",
+    help=(
+        "Certify a subject model against a baseline and generate a safety certificate. "
+        "Use when you have two model snapshots and want pass/fail gating."
+    ),
+)
+def _certify_lazy(
+    source: str = typer.Option(
+        ..., "--source", "--baseline", help="Baseline model dir or Hub ID"
+    ),
+    edited: str = typer.Option(
+        ..., "--edited", "--subject", help="Subject model dir or Hub ID"
+    ),
+    adapter: str = typer.Option(
+        "auto", "--adapter", help="Adapter name or 'auto' to resolve"
+    ),
+    device: str | None = typer.Option(
+        None, "--device", help="Device override for runs (auto|cuda|mps|cpu)"
+    ),
+    profile: str = typer.Option("ci", "--profile", help="Profile (ci|release)"),
+    tier: str = typer.Option("balanced", "--tier", help="Tier label for context"),
+    preset: str | None = typer.Option(
+        None,
+        "--preset",
+        help=(
+            "Universal preset path to use (defaults to causal or masked preset "
+            "based on adapter)"
+        ),
+    ),
+    out: str = typer.Option("runs", "--out", help="Base output directory"),
+    cert_out: str = typer.Option(
+        "reports/cert", "--cert-out", help="Certificate output directory"
+    ),
+    edit_config: str | None = typer.Option(
+        None, "--edit-config", help="Edit preset to apply a demo edit (quant_rtn)"
+    ),
+):
+    from .commands.certify import certify_command as _cert
+
+    return _cert(
+        source=source,
+        edited=edited,
+        adapter=adapter,
+        device=device,
+        profile=profile,
+        tier=tier,
+        preset=preset,
+        out=out,
+        cert_out=cert_out,
+        edit_config=edit_config,
+    )
+
+
+def _register_subapps() -> None:
+    # Import sub-apps lazily to keep module import light and satisfy E402
+    from .commands.doctor import doctor_command as _doctor_cmd
+    from .commands.plugins import plugins_app as _plugins_app
+    from .commands.report import report_app as _report_app
+
+    app.add_typer(_report_app, name="report")
+    app.add_typer(_plugins_app, name="plugins")
+    app.command(name="doctor")(_doctor_cmd)
+
+
+@app.command(
+    name="verify",
+    help=(
+        "Verify certificate JSON(s) against schema, pairing math, and gates. "
+        "Use --json for a single-line machine-readable envelope."
+    ),
+)
+def _verify_typed(
+    certificates: list[str] = typer.Argument(
+        ..., help="One or more certificate JSON files to verify."
+    ),
+    baseline: str | None = typer.Option(
+        None,
+        "--baseline",
+        help="Optional baseline certificate/report JSON to enforce provider parity.",
+    ),
+    tolerance: float = typer.Option(
+        1e-9, "--tolerance", help="Tolerance for analysis-basis comparisons."
+    ),
+    profile: str | None = typer.Option(
+        "dev",
+        "--profile",
+        help="Execution profile affecting parity enforcement and exit codes (dev|ci|release).",
+    ),
+    json_out: bool = typer.Option(
+        False,
+        "--json",
+        help="Emit machine-readable JSON (suppresses human-readable output)",
+    ),
+):
+    from pathlib import Path as _Path
+
+    from .commands.verify import verify_command as _verify
+
+    cert_paths = [_Path(c) for c in certificates]
+    baseline_path = _Path(baseline) if isinstance(baseline, str) else None
+    return _verify(
+        certificates=cert_paths,
+        baseline=baseline_path,
+        tolerance=tolerance,
+        profile=profile,
+        json_out=json_out,
+    )
+
+
+@app.command(
+    name="run",
+    help=(
+        "Execute an end-to-end run from a YAML config (edit + guards + reports). "
+        "Writes run artifacts and optionally a safety certificate."
+    ),
+)
+def _run_typed(
+    config: str = typer.Option(
+        ..., "--config", "-c", help="Path to YAML configuration file"
+    ),
+    device: str | None = typer.Option(
+        None, "--device", help="Device override (auto|cuda|mps|cpu)"
+    ),
+    profile: str | None = typer.Option(
+        None, "--profile", help="Profile to apply (ci|release)"
+    ),
+    out: str | None = typer.Option(None, "--out", help="Output directory override"),
+    edit: str | None = typer.Option(None, "--edit", help="Edit kind (quant|mixed)"),
+    tier: str | None = typer.Option(
+        None,
+        "--tier",
+        help="Auto-tuning tier override (conservative|balanced|aggressive)",
+    ),
+    probes: int | None = typer.Option(
+        None, "--probes", help="Number of micro-probes (0=deterministic, >0=adaptive)"
+    ),
+    until_pass: bool = typer.Option(
+        False, "--until-pass", help="Retry until certificate passes (max 3 attempts)"
+    ),
+    max_attempts: int = typer.Option(
+        3, "--max-attempts", help="Maximum retry attempts for --until-pass mode"
+    ),
+    timeout: int | None = typer.Option(
+        None, "--timeout", help="Timeout in seconds for --until-pass mode"
+    ),
+    baseline: str | None = typer.Option(
+        None,
+        "--baseline",
+        help="Path to baseline report.json for certificate validation",
+    ),
+    no_cleanup: bool = typer.Option(
+        False, "--no-cleanup", help="Skip cleanup of temporary artifacts"
+    ),
+):
+    from .commands.run import run_command as _run
+
+    return _run(
+        config=config,
+        device=device,
+        profile=profile,
+        out=out,
+        edit=edit,
+        tier=tier,
+        probes=probes,
+        until_pass=until_pass,
+        max_attempts=max_attempts,
+        timeout=timeout,
+        baseline=baseline,
+        no_cleanup=no_cleanup,
+    )
+
+
+_register_subapps()
+
+
+def main() -> None:
+    """Main entry point for the InvarLock CLI."""
+    enforce_default_security()
+    app()
+
+
+if __name__ == "__main__":
+    main()

invarlock/cli/commands/__init__.py

@@ -0,0 +1,26 @@
+"""CLI command package.
+
+Lightweight namespace re-exports for programmatic access in tests and tooling.
+Import-time work is minimal; subcommands themselves may perform heavier imports
+only when invoked.
+"""
+
+from .certify import certify_command
+from .doctor import doctor_command
+from .explain_gates import explain_gates_command
+from .export_html import export_html_command
+from .plugins import plugins_command
+from .report import report_command
+from .run import run_command
+from .verify import verify_command
+
+__all__ = [
+    "certify_command",
+    "doctor_command",
+    "explain_gates_command",
+    "export_html_command",
+    "plugins_command",
+    "run_command",
+    "verify_command",
+    "report_command",
+]