invarlock 0.2.0__py3-none-any.whl

invarlock/cli/provenance.py

@@ -0,0 +1,66 @@
+"""Adapter-lite provenance extraction utilities.
+
+Provides a tiny, versioned schema describing the adapter family and the
+underlying library versions. This does not perform any edits; it only reads
+environment and import metadata to annotate reports/certificates.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from importlib.metadata import version as pkg_version
+from typing import Any
+
+
+@dataclass
+class AdapterProvenance:
+    family: str
+    library: str
+    version: str | None
+    supported: bool
+    tested: list[str]
+    message: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+_FAMILY_MAP: dict[str, tuple[str, str, list[str]]] = {
+    # name -> (family, library, tested_versions)
+    "hf_gptq": ("gptq", "auto-gptq", []),
+    "hf_awq": ("awq", "autoawq", []),
+    "hf_bnb": ("bnb", "bitsandbytes", []),
+    # ONNX stack (requires extras: invarlock[onnx])
+    "hf_onnx": ("onnx", "onnxruntime", []),
+}
+
+
+def extract_adapter_provenance(adapter_name: str) -> AdapterProvenance:
+    name = (adapter_name or "").strip().lower()
+    family, library, tested = _FAMILY_MAP.get(name, ("hf", "transformers", []))
+
+    ver: str | None
+    try:
+        ver = pkg_version(library)
+        supported = True if (not tested or ver in tested) else False
+        msg = (
+            None
+            if supported
+            else f"Use Compare & Certify (BYOE); {library} version unsupported (tested: {tested})"
+        )
+    except Exception:  # Package not installed or version unknown
+        ver = None
+        supported = False
+        msg = f"{library} not available; prefer Compare & Certify (BYOE) or install extras."
+
+    return AdapterProvenance(
+        family=family,
+        library=library,
+        version=ver,
+        supported=supported,
+        tested=tested,
+        message=msg,
+    )
+
+
+__all__ = ["extract_adapter_provenance", "AdapterProvenance"]

invarlock/cli/utils.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def coerce_option(value: Any, fallback: Any | None = None) -> Any:
+    """Return a Typer option's concrete value.
+
+    - If `value` looks like a Typer OptionInfo, return its `.default`.
+    - Otherwise, return `value` unless it is None, in which case `fallback`.
+    This keeps CLI command functions callable both by Typer and directly in tests.
+    """
+    try:
+        # Typer OptionInfo typically exposes a `.default` attribute
+        default = getattr(value, "default", None)
+        # If it's an OptionInfo-like object, prefer its default
+        if default is not None or value.__class__.__name__ == "OptionInfo":
+            return default if default is not None else fallback
+    except Exception:
+        pass
+    return value if value is not None else fallback
+
+
+def coerce_float(value: Any, default: float) -> float:
+    """Coerce arbitrary input to float, falling back to `default` on error."""
+    try:
+        if value is None:
+            return default
+        return float(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def coerce_int(value: Any, default: int) -> int:
+    """Coerce arbitrary input to int, falling back to `default` on error."""
+    try:
+        if value is None:
+            return default
+        return int(value)
+    except (TypeError, ValueError):
+        return default

invarlock/config.py

@@ -0,0 +1,56 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class Defaults:
+    """
+    Global default parameters for the InvarLock framework. This dataclass
+    centralizes hyperparameters for different lenses, especially for the
+    'auto' calibration modes.
+    """
+
+    # --- Lens 1: FFT Energy ---
+    # In 'auto' mode, keep heads that constitute this percentage of cumulative energy.
+    fft_energy_keep: float = 0.95
+
+    # --- Lens 2: Mutual Information ---
+    # In 'auto' mode, keep neurons whose cumulative MI constitutes this percentage of the total.
+    mi_info_keep: float = 0.90
+
+    # --- Lens 3: Stability (Koopman) ---
+    # Default spectral norm margin when not using auto-calibration.
+    koopman_margin: float = 1.05  # A safe default slightly above 1.0
+
+    # --- Lens 4: RMT Clipping ---
+    # Default alpha for upper spectral edge clipping.
+    mp_alpha: float = 1.5
+    # Default beta for lower spectral edge clipping.
+    # mp_beta: float = 0.10
+
+    # --- Global Compression Target ---
+    # Fraction of original trainable parameters to aim for.
+    # e.g., 0.70 -> aim for ~70% of the baseline parameter count.
+    # This is a high-level objective that the auto-mode translates
+    # into concrete head and neuron pruning ratios.
+    target_param_keep: float = 0.70
+
+    # --- General ---
+    # Default seed for all deterministic operations.
+    seed: int = 42
+
+    # Variance Equalization minimum gain threshold
+    ve_min_gain: float = 0.30
+
+
+# Create a singleton instance for easy import
+CFG = Defaults()
+
+
+def get_default_config():
+    """
+    Get the default configuration for InvarLock.
+
+    Returns:
+        Defaults: A dataclass instance with default configuration values
+    """
+    return Defaults()

invarlock/core/__init__.py

@@ -0,0 +1,62 @@
+"""
+InvarLock Core Module
+=================
+
+Core torch-independent interfaces and coordination logic.
+
+This module provides the foundational abstractions and orchestration
+for the InvarLock framework without requiring heavy dependencies.
+"""
+
+from .abi import INVARLOCK_CORE_ABI
+from .api import Guard, ModelAdapter, ModelEdit, RunConfig, RunReport
+from .checkpoint import CheckpointManager
+from .events import EventLogger
+from .exceptions import InvarlockError
+from .registry import PluginInfo, get_registry
+from .types import (
+    EditInfo,
+    EditType,
+    GuardResult,
+    GuardType,
+    LogLevel,
+    ModelInfo,
+    RunStatus,
+)
+
+__all__ = [
+    # Core interfaces
+    "ModelAdapter",
+    "ModelEdit",
+    "Guard",
+    # ABI contract
+    "INVARLOCK_CORE_ABI",
+    "RunConfig",
+    "RunReport",
+    # Exceptions
+    "InvarlockError",
+    # Types and enums
+    "EditType",
+    "GuardType",
+    "RunStatus",
+    "LogLevel",
+    "ModelInfo",
+    "EditInfo",
+    "GuardResult",
+    # Registry and discovery
+    "get_registry",
+    "PluginInfo",
+    # Supporting services
+    "EventLogger",
+    "CheckpointManager",
+]
+
+
+# Lazy import CoreRunner to avoid importing heavy dependencies (e.g., NumPy)
+# during lightweight operations such as registry inspection or CLI startup.
+def __getattr__(name: str):  # pragma: no cover - simple lazy import shim
+    if name == "CoreRunner":
+        from .runner import CoreRunner as _CoreRunner
+
+        return _CoreRunner
+    raise AttributeError(name)

invarlock/core/abi.py

@@ -0,0 +1,15 @@
+"""
+Core ABI contract for InvarLock plugins.
+
+Third-party plugins may declare a matching `INVARLOCK_CORE_ABI` attribute to signal
+compatibility with this release line. Minor bumps may introduce breaking changes
+in plugin contracts; match exactly for stability.
+"""
+
+from __future__ import annotations
+
+# Plugin ABI for the core interfaces used by adapters/edits/guards.
+# Increment when the plugin-facing contracts change.
+INVARLOCK_CORE_ABI = "0.1"
+
+__all__ = ["INVARLOCK_CORE_ABI"]

invarlock/core/api.py

@@ -0,0 +1,274 @@
+"""
+InvarLock Core API
+==============
+
+Core interfaces and data structures - torch-free abstractions.
+
+This module defines the fundamental abstractions used throughout InvarLock:
+- ModelAdapter: Model-specific operations interface
+- ModelEdit: Edit operation interface
+- Guard: Safety validation interface
+- RunConfig: Pipeline configuration
+- RunReport: Execution results
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+class ModelAdapter(ABC):
+    """
+    Abstract interface for model-specific operations.
+
+    Adapters provide model-agnostic access to different architectures
+    (HuggingFace, custom models, etc.) without requiring torch imports
+    in the core API.
+    """
+
+    name: str
+
+    @abstractmethod
+    def can_handle(self, model: Any) -> bool:
+        """Check if this adapter can handle the given model."""
+        pass
+
+    @abstractmethod
+    def describe(self, model: Any) -> dict[str, Any]:
+        """
+        Get model structure description.
+
+        Returns:
+            Dict with keys: n_layer, heads_per_layer, mlp_dims, tying
+        """
+        pass
+
+    @abstractmethod
+    def snapshot(self, model: Any) -> bytes:
+        """Create serialized snapshot of model state."""
+        pass
+
+    @abstractmethod
+    def restore(self, model: Any, blob: bytes) -> None:
+        """Restore model state from snapshot."""
+        pass
+
+
+class ModelEdit(ABC):
+    """
+    Abstract interface for model editing operations.
+
+    Edits modify model parameters/structure while maintaining
+    the model's interface and basic functionality.
+    """
+
+    name: str
+
+    @abstractmethod
+    def can_edit(self, model_desc: dict[str, Any]) -> bool:
+        """Check if this edit can be applied to the described model."""
+        pass
+
+    @abstractmethod
+    def apply(self, model: Any, adapter: ModelAdapter, **kwargs) -> dict[str, Any]:
+        """
+        Apply the edit to the model.
+
+        Args:
+            model: The model to edit
+            adapter: Adapter for model-specific operations
+            **kwargs: Edit-specific parameters
+
+        Returns:
+            Dict with edit metadata and statistics
+        """
+        pass
+
+
+class Guard(ABC):
+    """
+    Abstract interface for safety guards.
+
+    Guards validate model state and behavior to ensure
+    edits don't cause unacceptable degradation.
+    """
+
+    name: str
+
+    @abstractmethod
+    def validate(
+        self, model: Any, adapter: ModelAdapter, context: dict[str, Any]
+    ) -> dict[str, Any]:
+        """
+        Validate model state/behavior.
+
+        Args:
+            model: The model to validate
+            adapter: Adapter for model operations
+            context: Validation context (baseline metrics, etc.)
+
+        Returns:
+            Dict with validation results and status
+        """
+        pass
+
+
+class GuardChain:
+    """
+    Manages a chain of guards with policy-based execution.
+
+    Provides lifecycle management (prepare, before_edit, after_edit, finalize)
+    and aggregates results across multiple guards.
+    """
+
+    def __init__(self, guards: list[Guard], policy: Any | None = None):
+        """
+        Initialize guard chain.
+
+        Args:
+            guards: List of guard instances
+            policy: Policy configuration for guard execution
+        """
+        self.guards = guards
+        self.policy = policy
+
+    def prepare_all(
+        self,
+        model: Any,
+        adapter: ModelAdapter,
+        calib: Any,
+        policy_config: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Prepare all guards."""
+        results = {}
+        for guard in self.guards:
+            if hasattr(guard, "prepare"):
+                results[guard.name] = guard.prepare(
+                    model, adapter, calib, policy_config
+                )
+            else:
+                results[guard.name] = {"ready": True}
+        return results
+
+    def before_edit_all(self, model: Any) -> list[Any]:
+        """Execute before_edit on all guards."""
+        results = []
+        for guard in self.guards:
+            if hasattr(guard, "before_edit"):
+                result = guard.before_edit(model)
+                if result is not None:
+                    results.append(result)
+        return results
+
+    def after_edit_all(self, model: Any) -> list[Any]:
+        """Execute after_edit on all guards."""
+        results = []
+        for guard in self.guards:
+            if hasattr(guard, "after_edit"):
+                result = guard.after_edit(model)
+                if result is not None:
+                    results.append(result)
+        return results
+
+    def finalize_all(self, model: Any) -> list[Any]:
+        """Finalize all guards and return outcomes."""
+        results = []
+        for guard in self.guards:
+            if hasattr(guard, "finalize"):
+                result = guard.finalize(model)
+                results.append(result)
+        return results
+
+    def all_passed(self, outcomes: list[Any]) -> bool:
+        """Check if all guard outcomes passed."""
+        for outcome in outcomes:
+            if hasattr(outcome, "passed") and not outcome.passed:
+                return False
+        return True
+
+    def get_worst_action(self, outcomes: list[Any]) -> str:
+        """Get the worst action from all outcomes."""
+        actions = []
+        for outcome in outcomes:
+            if hasattr(outcome, "action"):
+                actions.append(outcome.action)
+
+        # Import from types to avoid circular dependency
+        from .types import get_worst_action
+
+        return get_worst_action(actions)
+
+
+# Type alias for calibration data
+CalibrationData = Any
+
+
+@dataclass
+class RunConfig:
+    """
+    Configuration for a InvarLock pipeline run.
+
+    Contains all parameters needed to execute the full pipeline:
+    prepare → edit → guards → eval → finalize/rollback.
+    """
+
+    # Device configuration
+    device: str = "auto"
+
+    # Safety thresholds
+    max_pm_ratio: float = 1.5
+    spike_threshold: float = 2.0  # Catastrophic spike threshold for immediate rollback
+
+    # Output configuration
+    event_path: Path | None = None
+    checkpoint_interval: int = 0  # 0 = disabled
+
+    # Execution flags
+    dry_run: bool = False
+    verbose: bool = False
+
+    # Context for guards/eval
+    context: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class RunReport:
+    """
+    Results from a InvarLock pipeline execution.
+
+    Contains comprehensive information about what was executed
+    and the outcomes, suitable for analysis and certification.
+    """
+
+    # Execution metadata
+    meta: dict[str, Any] = field(default_factory=dict)
+
+    # Edit information
+    edit: dict[str, Any] = field(default_factory=dict)
+
+    # Guard validation results
+    guards: dict[str, dict[str, Any]] = field(default_factory=dict)
+
+    # Evaluation metrics
+    metrics: dict[str, Any] = field(default_factory=dict)
+
+    # Captured evaluation windows and auxiliary data
+    evaluation_windows: dict[str, Any] = field(default_factory=dict)
+
+    # Execution status
+    status: str = "pending"  # pending, success, failed, rollback
+
+    # Error information (if any)
+    error: str | None = None
+
+    # Additional context
+    context: dict[str, Any] = field(default_factory=dict)
+
+
+# Type aliases for common patterns
+ModelType = Any  # Actual model type (torch.nn.Module, etc.)
+DeviceType = str | Any  # Device specification
+MetricsDict = dict[str, float | int | str | bool]