invarlock 0.2.0__py3-none-any.whl

invarlock/__init__.py

@@ -0,0 +1,33 @@
+"""
+InvarLock: Edit‑agnostic robustness certificates for weight edits
+=============================================================
+
+Core runtime package — torch-independent utilities, configuration, and interfaces.
+
+This package provides the foundation for the InvarLock GuardChain without heavy dependencies.
+For torch-dependent functionality, see subpackages under `invarlock.*`:
+- `invarlock.adapters`: Model adapters (HF GPT-2/BERT/LLaMA, auto)
+- `invarlock.guards`: Safety mechanisms (invariants, spectral, RMT, variance)
+- `invarlock.edits`: Built-in quantization and edit interfaces
+- `invarlock.eval`: Metrics, guard-overhead checks, and certification
+"""
+
+__version__ = "0.2.0"
+
+# Core exports - torch-independent
+from .config import CFG, Defaults, get_default_config
+
+__all__ = ["__version__", "get_default_config", "Defaults", "CFG"]
+
+
+def __getattr__(name: str):  # pragma: no cover - thin lazy loader
+    """Lazily expose selected subpackages without importing heavy deps at init.
+
+    This keeps `import invarlock` torch-free while allowing patterns like
+    monkeypatching `invarlock.eval.*` in tests.
+    """
+    if name == "eval":
+        import importlib
+
+        return importlib.import_module(".eval", __name__)
+    raise AttributeError(name)

invarlock/__main__.py

@@ -0,0 +1,10 @@
+from .cli.app import app
+
+
+def main() -> None:
+    """Entry point for `python -m invarlock`."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

invarlock/_data/runtime/profiles/ci_cpu.yaml

@@ -0,0 +1,15 @@
+# CPU-only CI profile for telemetry/edge validation runs.
+#
+# Forces CPU execution and trims window counts slightly so telemetry runs
+# finish quickly on developer machines while still exercising guards.
+
+model:
+  device: "cpu"
+
+dataset:
+  preview_n: 120
+  final_n: 120
+  stride: 512
+
+context:
+  telemetry_profile: "ci_cpu"

invarlock/_data/runtime/profiles/release.yaml

@@ -0,0 +1,23 @@
+# Release profile overrides for certification workflows.
+#
+# Applies denser evaluation coverage, longer bootstrap runs, and embeds
+# policy snapshot metadata so artifacts can be audited after publication.
+
+dataset:
+  preview_n: 400
+  final_n: 400
+
+guards:
+  variance:
+    max_calib: 320
+
+eval:
+  bootstrap:
+    replicates: 3200
+    alpha: 0.05
+    method: bca_paired_delta_log
+
+context:
+  policy_snapshot:
+    tiers_file: src/invarlock/_data/runtime/tiers.yaml
+    profile: release

invarlock/_data/runtime/tiers.yaml

@@ -0,0 +1,76 @@
+# Tier guard policy knobs for variance correction (balanced vs conservative)
+#
+# These values mirror the settings validated during the December 2025
+# calibration runs. They should be kept in sync with the policy digest
+# embedded in certificates and referenced by automation documentation.
+
+balanced:
+  variance_guard:
+    deadband: 0.02
+    min_abs_adjust: 0.012
+    max_scale_step: 0.03
+    min_effect_lognll: 0.0009
+    predictive_one_sided: true
+    topk_backstop: 1
+    max_adjusted_modules: 1
+    tap: "transformer.h.*.mlp.c_proj"
+    predictive_gate: true
+  spectral_guard:
+    sigma_quantile: 0.95
+    deadband: 0.10
+    scope: all
+    max_caps: 5
+    max_spectral_norm: null
+    family_caps:
+      ffn: 3.834
+      attn: 3.423
+      embed: 3.1
+      other: 3.1
+    multiple_testing:
+      method: bh
+      alpha: 0.05
+      m: 4
+  rmt_guard:
+    deadband: 0.10
+    margin: 1.5
+    epsilon_default: 0.10
+    epsilon_by_family:
+      ffn: 0.10
+      attn: 0.08
+      embed: 0.12
+      other: 0.12
+
+conservative:
+  variance_guard:
+    deadband: 0.03
+    min_abs_adjust: 0.02
+    max_scale_step: 0.015
+    min_effect_lognll: 0.0018
+    predictive_one_sided: false
+    topk_backstop: 0
+    max_adjusted_modules: 0
+    tap: "transformer.h.*.mlp.c_proj"
+    predictive_gate: true
+  spectral_guard:
+    sigma_quantile: 0.90
+    deadband: 0.05
+    scope: ffn
+    max_caps: 3
+    family_caps:
+      ffn: 2.3
+      attn: 2.6
+      embed: 2.8
+      other: 2.8
+    multiple_testing:
+      method: bonferroni
+      alpha: 0.02
+      m: 4
+  rmt_guard:
+    deadband: 0.05
+    margin: 1.3
+    epsilon_default: 0.06
+    epsilon_by_family:
+      ffn: 0.06
+      attn: 0.05
+      embed: 0.07
+      other: 0.07

invarlock/adapters/__init__.py

@@ -0,0 +1,102 @@
+"""Adapter namespace (`invarlock.adapters`) exposing built-in adapters.
+
+Provides lazy import of heavy submodules to avoid importing Transformers
+stacks unless needed. Accessing adapter classes triggers on-demand import.
+"""
+
+from __future__ import annotations
+
+import importlib as _importlib
+from typing import Any as _Any
+
+from invarlock.core.abi import INVARLOCK_CORE_ABI as INVARLOCK_CORE_ABI
+
+from .base import (
+    AdapterConfig,
+    AdapterInterface,
+    BaseAdapter,
+    DeviceManager,
+)
+from .base import (
+    PerformanceMetrics as BasePerformanceMetrics,
+)
+
+_LAZY_MAP = {
+    "HF_BERT_Adapter": ".hf_bert",
+    "HF_GPT2_Adapter": ".hf_gpt2",
+    "HF_LLaMA_Adapter": ".hf_llama",
+    "HF_T5_Adapter": ".hf_t5",
+    "HF_ORT_CausalLM_Adapter": ".hf_onnx",
+    "HF_Causal_Auto_Adapter": ".auto",
+    "HF_MLM_Auto_Adapter": ".auto",
+}
+
+
+def __getattr__(name: str) -> _Any:  # pragma: no cover - simple lazy import
+    mod_name = _LAZY_MAP.get(name)
+    if not mod_name:
+        raise AttributeError(name)
+    module = _importlib.import_module(mod_name, __name__)
+    try:
+        return getattr(module, name)
+    except AttributeError as exc:  # re-raise with module context
+        raise AttributeError(f"{name} not found in {mod_name}") from exc
+
+
+# Simple quality label helper used by tests
+def quality_label(ratio: float) -> str:
+    if ratio <= 1.10:
+        return "Excellent"
+    if ratio <= 1.25:
+        return "Good"
+    if ratio <= 1.40:
+        return "Fair"
+    return "Degraded"
+
+
+class _RemovedComponent:
+    def __init__(self, name: str, replacement: str | None = None):
+        self._name = name
+        self._replacement = replacement
+
+    def __call__(self, *args, **kwargs):
+        raise NotImplementedError(
+            f"{self._name} is not available in InvarLock 1.0."
+            + (f" Use: {self._replacement}" if self._replacement else "")
+        )
+
+    def __getattr__(self, _):  # pragma: no cover - simple passthrough
+        return _RemovedComponent(self._name, self._replacement)
+
+
+# Placeholders for removed/legacy utilities referenced in tests
+HF_Pythia_Adapter = _RemovedComponent("HF_Pythia_Adapter")
+auto_tune_pruning_budget = _RemovedComponent("auto_tune_pruning_budget")
+run_auto_invarlock = _RemovedComponent("run_auto_invarlock")
+InvarLockPipeline = _RemovedComponent("InvarLockPipeline", "invarlock.cli.app:main")
+InvarLockConfig = _RemovedComponent(
+    "InvarLockConfig", "invarlock.cli.config:InvarLockConfig"
+)
+run_invarlock_pipeline = _RemovedComponent(
+    "run_invarlock_pipeline", "invarlock.cli.run"
+)
+run_invarlock = _RemovedComponent("run_invarlock", "invarlock.cli.run")
+quick_prune_gpt2 = _RemovedComponent("quick_prune_gpt2")
+
+__all__ = [
+    "HF_GPT2_Adapter",
+    "HF_BERT_Adapter",
+    "HF_LLaMA_Adapter",
+    "HF_T5_Adapter",
+    "HF_ORT_CausalLM_Adapter",
+    "HF_Causal_Auto_Adapter",
+    "HF_MLM_Auto_Adapter",
+    "BaseAdapter",
+    "AdapterConfig",
+    "AdapterInterface",
+    "DeviceManager",
+    "BasePerformanceMetrics",
+    "quality_label",
+    "_RemovedComponent",
+    "INVARLOCK_CORE_ABI",
+]

invarlock/adapters/_capabilities.py

@@ -0,0 +1,45 @@
+"""
+Model capability probes (lightweight, no heavy imports).
+
+Currently supports a simple MoE probe that scans module names to infer whether
+the model likely contains mixture-of-experts structures (router/gating and
+expert FFNs).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def probe_moe_capabilities(model: Any) -> dict[str, Any]:
+    """Detect MoE-related modules in a model by name heuristics.
+
+    Returns:
+        {
+          'moe': bool,
+          'families': set[str],           # e.g., {'router','expert_ffn'}
+          'counts': dict[str,int],        # occurrences per family
+        }
+    """
+    families: set[str] = set()
+    counts: dict[str, int] = {}
+    try:
+        for name, _module in model.named_modules():
+            lname = str(name).lower()
+            # Router/gating indicators
+            if any(
+                tok in lname
+                for tok in ("router", "routing", "gate", "gating", "dispatch", "switch")
+            ):
+                families.add("router")
+                counts["router"] = counts.get("router", 0) + 1
+            # Expert FFN indicators
+            if any(
+                tok in lname
+                for tok in ("experts", "expert", "moe", "mixture_of_experts")
+            ):
+                families.add("expert_ffn")
+                counts["expert_ffn"] = counts.get("expert_ffn", 0) + 1
+    except Exception:
+        pass
+    return {"moe": bool(families), "families": families, "counts": counts}

invarlock/adapters/auto.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+import importlib as _importlib
+from typing import Any
+
+from invarlock.core.api import ModelAdapter
+
+from ..cli.adapter_auto import resolve_auto_adapter
+
+
+class _DelegatingAdapter(ModelAdapter):
+    name = "auto_adapter"
+
+    def __init__(self) -> None:
+        self._delegate: ModelAdapter | None = None
+
+    def _ensure_delegate_from_id(self, model_id: str) -> ModelAdapter:
+        if self._delegate is not None:
+            return self._delegate
+        resolved = resolve_auto_adapter(model_id)
+        if resolved == "hf_llama":
+            HF_LLaMA_Adapter = _importlib.import_module(
+                ".hf_llama", __package__
+            ).HF_LLaMA_Adapter
+            self._delegate = HF_LLaMA_Adapter()
+        elif resolved == "hf_bert":
+            HF_BERT_Adapter = _importlib.import_module(
+                ".hf_bert", __package__
+            ).HF_BERT_Adapter
+            self._delegate = HF_BERT_Adapter()
+        else:
+            HF_GPT2_Adapter = _importlib.import_module(
+                ".hf_gpt2", __package__
+            ).HF_GPT2_Adapter
+            self._delegate = HF_GPT2_Adapter()
+        return self._delegate
+
+    def _ensure_delegate_from_model(self, model: Any) -> ModelAdapter:
+        # Best-effort: inspect class name
+        cls_name = getattr(model, "__class__", type(model)).__name__.lower()
+        if any(k in cls_name for k in ["llama", "mistral", "qwen", "yi"]):
+            HF_LLaMA_Adapter = _importlib.import_module(
+                ".hf_llama", __package__
+            ).HF_LLaMA_Adapter
+            self._delegate = HF_LLaMA_Adapter()
+        elif any(k in cls_name for k in ["bert", "roberta", "albert", "deberta"]):
+            HF_BERT_Adapter = _importlib.import_module(
+                ".hf_bert", __package__
+            ).HF_BERT_Adapter
+            self._delegate = HF_BERT_Adapter()
+        else:
+            HF_GPT2_Adapter = _importlib.import_module(
+                ".hf_gpt2", __package__
+            ).HF_GPT2_Adapter
+            self._delegate = HF_GPT2_Adapter()
+        return self._delegate
+
+    def can_handle(self, model: Any) -> bool:  # pragma: no cover - trivial
+        return True
+
+    def describe(self, model: Any) -> dict[str, Any]:
+        delegate = self._delegate or self._ensure_delegate_from_model(model)
+        return delegate.describe(model)
+
+    def snapshot(self, model: Any) -> bytes:
+        delegate = self._delegate or self._ensure_delegate_from_model(model)
+        return delegate.snapshot(model)
+
+    def restore(self, model: Any, blob: bytes) -> None:
+        delegate = self._delegate or self._ensure_delegate_from_model(model)
+        return delegate.restore(model, blob)
+
+    def __getattr__(self, item: str):  # pragma: no cover - passthrough
+        if item == "_delegate":
+            raise AttributeError(item)
+        delegate = self._delegate
+        if delegate is not None and hasattr(delegate, item):
+            return getattr(delegate, item)
+        raise AttributeError(item)
+
+
+class HF_Causal_Auto_Adapter(_DelegatingAdapter):
+    name = "hf_causal_auto"
+
+    def load_model(self, model_id: str, device: str = "auto") -> Any:
+        delegate = self._ensure_delegate_from_id(model_id)
+        return delegate.load_model(model_id, device=device)
+
+
+class HF_MLM_Auto_Adapter(_DelegatingAdapter):
+    name = "hf_mlm_auto"
+
+    def load_model(self, model_id: str, device: str = "auto") -> Any:
+        # Force BERT-like adapter for MLM families
+        HF_BERT_Adapter = _importlib.import_module(
+            ".hf_bert", __package__
+        ).HF_BERT_Adapter
+        self._delegate = HF_BERT_Adapter()
+        return self._delegate.load_model(model_id, device=device)