invarlock 0.3.8__tar.gz → 0.3.9__tar.gz

{invarlock-0.3.8/src/invarlock.egg-info → invarlock-0.3.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: invarlock
-Version: 0.3.8
+Version: 0.3.9
 Summary: Edit‑agnostic robustness evaluation reports for weight edits (InvarLock framework)
 Author-email: InvarLock Team <oss@invarlock.dev>
 Maintainer-email: InvarLock Maintainers <support@invarlock.dev>
@@ -106,31 +106,44 @@ Requires-Dist: twine>=4.0.0; extra == "dev"
 Dynamic: license-file
 
 <p align="center">
-  <img
-    src="docs/assets/invarlock-logo.svg"
-    alt="InvarLock"
-    width="420"
-  />
+  <picture>
+    <source
+      media="(prefers-color-scheme: dark)"
+      srcset="docs/assets/invarlock-logo-dark.svg"
+    />
+    <img src="docs/assets/invarlock-logo.svg" alt="InvarLock" />
+  </picture>
 </p>
 
-# InvarLock — Edit‑agnostic robustness reports for weight edits
+<p align="center"><em>Edit‑agnostic robustness reports for weight edits</em></p>
 
-[![CI](https://img.shields.io/github/actions/workflow/status/invarlock/invarlock/ci.yml?branch=main&logo=github&label=CI)](https://github.com/invarlock/invarlock/actions/workflows/ci.yml)
-[![PyPI](https://badge.fury.io/py/invarlock.svg)](https://pypi.org/project/invarlock/)
-[![Docs](https://img.shields.io/badge/docs-quickstart-blue.svg)](https://github.com/invarlock/invarlock/blob/main/docs/user-guide/quickstart.md)
-[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
-[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/release/python-3120/)
+<p align="center">
+  <a href="https://github.com/invarlock/invarlock/actions/workflows/ci.yml">
+    <img alt="CI" src="https://img.shields.io/github/actions/workflow/status/invarlock/invarlock/ci.yml?branch=main&logo=github&label=CI" />
+  </a>
+  <a href="https://pypi.org/project/invarlock/">
+    <img alt="PyPI" src="https://badge.fury.io/py/invarlock.svg" />
+  </a>
+  <a href="https://github.com/invarlock/invarlock/blob/main/docs/user-guide/quickstart.md">
+    <img alt="Docs" src="https://img.shields.io/badge/docs-quickstart-blue.svg" />
+  </a>
+  <a href="LICENSE">
+    <img alt="License: Apache-2.0" src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" />
+  </a>
+  <a href="https://www.python.org/downloads/release/python-3120/">
+    <img alt="Python 3.12+" src="https://img.shields.io/badge/python-3.12+-blue.svg" />
+  </a>
+</p>
+
+<p align="center">
+  <strong>Catch silent quality regressions from quantization, pruning, and weight edits before they ship.</strong>
+</p>
 
 Quantizing, pruning, or otherwise editing a model’s weights can silently degrade quality.
 InvarLock compares an edited **subject** checkpoint against a fixed **baseline** with paired
 evaluation windows, enforces a guard pipeline (invariants → spectral → RMT → variance), and
 produces a machine‑readable Evaluation Report you can gate in CI.
 
-> Status: pre‑1.0. Until 1.0, minor releases may be breaking. See `CHANGELOG.md`.
-
-For guidance on where to ask questions, how to report bugs, and what to expect in terms of response times, see
-[SUPPORT.md](https://github.com/invarlock/invarlock/blob/main/SUPPORT.md).
-
 ## Why InvarLock?
 
 - **Quality gates for weight edits**: catch regressions before deployment.
@@ -270,6 +283,13 @@ If you use InvarLock in scientific work, please cite it (canonical metadata is i
 | CPU                    | ✅ Fallback      | Slower but functional                     |
 <!-- markdownlint-enable MD060 -->
 
+## Project status
+
+InvarLock is pre‑1.0. Until 1.0, minor releases may include breaking changes. See [`CHANGELOG.md`](CHANGELOG.md).
+
+For guidance on where to ask questions, how to report bugs, and what to expect in terms of response times, see
+[`SUPPORT.md`](SUPPORT.md).
+
 ## Contributing
 
 - Contributing guide: <https://github.com/invarlock/invarlock/blob/main/CONTRIBUTING.md>

{invarlock-0.3.8 → invarlock-0.3.9}/README.md

@@ -1,29 +1,42 @@
 <p align="center">
-  <img
-    src="docs/assets/invarlock-logo.svg"
-    alt="InvarLock"
-    width="420"
-  />
+  <picture>
+    <source
+      media="(prefers-color-scheme: dark)"
+      srcset="docs/assets/invarlock-logo-dark.svg"
+    />
+    <img src="docs/assets/invarlock-logo.svg" alt="InvarLock" />
+  </picture>
 </p>
 
-# InvarLock — Edit‑agnostic robustness reports for weight edits
+<p align="center"><em>Edit‑agnostic robustness reports for weight edits</em></p>
 
-[![CI](https://img.shields.io/github/actions/workflow/status/invarlock/invarlock/ci.yml?branch=main&logo=github&label=CI)](https://github.com/invarlock/invarlock/actions/workflows/ci.yml)
-[![PyPI](https://badge.fury.io/py/invarlock.svg)](https://pypi.org/project/invarlock/)
-[![Docs](https://img.shields.io/badge/docs-quickstart-blue.svg)](https://github.com/invarlock/invarlock/blob/main/docs/user-guide/quickstart.md)
-[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
-[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/release/python-3120/)
+<p align="center">
+  <a href="https://github.com/invarlock/invarlock/actions/workflows/ci.yml">
+    <img alt="CI" src="https://img.shields.io/github/actions/workflow/status/invarlock/invarlock/ci.yml?branch=main&logo=github&label=CI" />
+  </a>
+  <a href="https://pypi.org/project/invarlock/">
+    <img alt="PyPI" src="https://badge.fury.io/py/invarlock.svg" />
+  </a>
+  <a href="https://github.com/invarlock/invarlock/blob/main/docs/user-guide/quickstart.md">
+    <img alt="Docs" src="https://img.shields.io/badge/docs-quickstart-blue.svg" />
+  </a>
+  <a href="LICENSE">
+    <img alt="License: Apache-2.0" src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" />
+  </a>
+  <a href="https://www.python.org/downloads/release/python-3120/">
+    <img alt="Python 3.12+" src="https://img.shields.io/badge/python-3.12+-blue.svg" />
+  </a>
+</p>
+
+<p align="center">
+  <strong>Catch silent quality regressions from quantization, pruning, and weight edits before they ship.</strong>
+</p>
 
 Quantizing, pruning, or otherwise editing a model’s weights can silently degrade quality.
 InvarLock compares an edited **subject** checkpoint against a fixed **baseline** with paired
 evaluation windows, enforces a guard pipeline (invariants → spectral → RMT → variance), and
 produces a machine‑readable Evaluation Report you can gate in CI.
 
-> Status: pre‑1.0. Until 1.0, minor releases may be breaking. See `CHANGELOG.md`.
-
-For guidance on where to ask questions, how to report bugs, and what to expect in terms of response times, see
-[SUPPORT.md](https://github.com/invarlock/invarlock/blob/main/SUPPORT.md).
-
 ## Why InvarLock?
 
 - **Quality gates for weight edits**: catch regressions before deployment.
@@ -163,6 +176,13 @@ If you use InvarLock in scientific work, please cite it (canonical metadata is i
 | CPU                    | ✅ Fallback      | Slower but functional                     |
 <!-- markdownlint-enable MD060 -->
 
+## Project status
+
+InvarLock is pre‑1.0. Until 1.0, minor releases may include breaking changes. See [`CHANGELOG.md`](CHANGELOG.md).
+
+For guidance on where to ask questions, how to report bugs, and what to expect in terms of response times, see
+[`SUPPORT.md`](SUPPORT.md).
+
 ## Contributing
 
 - Contributing guide: <https://github.com/invarlock/invarlock/blob/main/CONTRIBUTING.md>

{invarlock-0.3.8 → invarlock-0.3.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "invarlock"
-version = "0.3.8"
+version = "0.3.9"
 description = "Edit‑agnostic robustness evaluation reports for weight edits (InvarLock framework)"
 authors = [{ name = "InvarLock Team", email = "oss@invarlock.dev" }]
 maintainers = [{ name = "InvarLock Maintainers", email = "support@invarlock.dev" }]

{invarlock-0.3.8 → invarlock-0.3.9}/src/invarlock/__init__.py

@@ -12,7 +12,7 @@ For torch-dependent functionality, see subpackages under `invarlock.*`:
 - `invarlock.eval`: Metrics, guard-overhead checks, and evaluation reporting
 """
 
-__version__ = "0.3.8"
+__version__ = "0.3.9"
 
 # Core exports - torch-independent
 from .config import CFG, Defaults, get_default_config

{invarlock-0.3.8 → invarlock-0.3.9}/src/invarlock/calibration/spectral_null.py

@@ -35,7 +35,7 @@ def _bh_reject_families(
 
     order = sorted(
         range(n),
-        key=lambda idx: (float("inf") if not _finite01(pvals[idx]) else pvals[idx]),
+        key=lambda idx: float("inf") if not _finite01(pvals[idx]) else pvals[idx],
     )
     max_k = 0
     for rank, idx in enumerate(order, start=1):

{invarlock-0.3.8 → invarlock-0.3.9}/src/invarlock/cli/commands/explain_gates.py

@@ -1,13 +1,17 @@
 from __future__ import annotations
 
 import json
+import math
 from pathlib import Path
 
 import typer
 from rich.console import Console
 
 from invarlock.core.auto_tuning import get_tier_policies
-from invarlock.reporting.report_builder import make_report
+from invarlock.reporting.report_builder import (
+    PM_DRIFT_BAND_DEFAULT,
+    make_report,
+)
 
 console = Console()
 
@@ -47,12 +51,8 @@ def explain_gates_command(
     tier = str(
         (evaluation_report.get("auto", {}) or {}).get("tier", "balanced")
     ).lower()
-    tier_thresholds = {
-        "conservative": 1.05,
-        "balanced": 1.10,
-        "aggressive": 1.20,
-        "none": 1.10,
-    }
+    tier_policies = get_tier_policies()
+    tier_defaults = tier_policies.get(tier, tier_policies.get("balanced", {}))
     resolved_policy = (
         evaluation_report.get("resolved_policy", {})
         if isinstance(evaluation_report.get("resolved_policy"), dict)
@@ -64,8 +64,6 @@ def explain_gates_command(
         else {}
     )
     if not metrics_policy:
-        tier_policies = get_tier_policies()
-        tier_defaults = tier_policies.get(tier, tier_policies.get("balanced", {}))
         metrics_policy = (
             tier_defaults.get("metrics", {}) if isinstance(tier_defaults, dict) else {}
         )
@@ -79,13 +77,31 @@ def explain_gates_command(
     hysteresis_ratio = float(pm_policy.get("hysteresis_ratio", 0.0))
     min_tokens = int(pm_policy.get("min_tokens", 0))
     try:
-        limit_base = float(
-            pm_policy.get("ratio_limit_base", tier_thresholds.get(tier, 1.10))
-            or tier_thresholds.get(tier, 1.10)
-        )
+        limit_base = float(pm_policy.get("ratio_limit_base"))
     except Exception:
-        limit_base = tier_thresholds.get(tier, 1.10)
-    limit_with_hyst = limit_base + max(0.0, hysteresis_ratio)
+        limit_base = None
+    if limit_base is None or not isinstance(limit_base, int | float):
+        limit_base = None
+    elif not float("-inf") < float(limit_base) < float("inf"):
+        limit_base = None
+    if limit_base is None:
+        try:
+            fallback = (
+                tier_defaults.get("metrics", {})
+                if isinstance(tier_defaults, dict)
+                else {}
+            )
+            fallback_pm = (
+                fallback.get("pm_ratio", {}) if isinstance(fallback, dict) else {}
+            )
+            limit_base = float(fallback_pm.get("ratio_limit_base"))
+        except Exception:
+            limit_base = None
+    limit_with_hyst = (
+        float(limit_base) + max(0.0, hysteresis_ratio)
+        if isinstance(limit_base, int | float)
+        else None
+    )
     tokens_ok = True
     telem = (
         evaluation_report.get("telemetry", {})
@@ -118,16 +134,21 @@ def explain_gates_command(
             )
         else:
             console.print(f"  observed: {ratio:.3f}x")
-    console.print(
-        f"  threshold: ≤ {limit_base:.2f}x{(f' (+hysteresis {hysteresis_ratio:.3f})' if hysteresis_ratio else '')}"
-    )
+    if isinstance(limit_base, int | float):
+        hyst_suffix = (
+            f" (+hysteresis {hysteresis_ratio:.3f})" if hysteresis_ratio else ""
+        )
+        console.print(f"  threshold: ≤ {float(limit_base):.2f}x{hyst_suffix}")
+    else:
+        console.print("  threshold: unavailable")
     console.print(
         f"  tokens: {'ok' if tokens_ok else 'below floor'} (token floors: min_tokens={min_tokens or 0}, total={int(telem.get('preview_total_tokens', 0)) + int(telem.get('final_total_tokens', 0)) if telem else 0})"
     )
     if hysteresis_applied:
-        console.print(
-            f"  note: hysteresis applied → effective threshold = {limit_with_hyst:.3f}x"
-        )
+        if isinstance(limit_with_hyst, int | float):
+            console.print(
+                f"  note: hysteresis applied → effective threshold = {float(limit_with_hyst):.3f}x"
+            )
 
     # Tail gate explanation (warn/fail; based on per-window Δlog-loss vs baseline)
     pm_tail = (
@@ -199,11 +220,18 @@ def explain_gates_command(
     except Exception:
         pass
 
-    # Drift gate explanation
+    # Drift gate explanation (ppl-like kinds only)
     drift = None
-    drift_ci = None
-    if isinstance(evaluation_report.get("primary_metric"), dict):
-        pm = evaluation_report.get("primary_metric", {})
+    drift_status = (
+        "PASS" if bool(validation.get("preview_final_drift_acceptable")) else "FAIL"
+    )
+    pm = (
+        evaluation_report.get("primary_metric", {})
+        if isinstance(evaluation_report.get("primary_metric"), dict)
+        else {}
+    )
+    kind = str(pm.get("kind", "") or "").lower()
+    if kind.startswith("ppl"):
         preview = pm.get("preview")
         final = pm.get("final")
         if isinstance(preview, int | float) and isinstance(final, int | float):
@@ -212,19 +240,26 @@ def explain_gates_command(
                     drift = float(final) / float(preview)
             except Exception:
                 drift = None
-    drift_status = (
-        "PASS" if bool(validation.get("preview_final_drift_acceptable")) else "FAIL"
-    )
-    console.print("\n[bold]Gate: Drift (final/preview)[/bold]")
-    if isinstance(drift, int | float):
-        if isinstance(drift_ci, tuple | list) and len(drift_ci) == 2:
-            console.print(
-                f"  observed: {drift:.3f} (CI {drift_ci[0]:.3f}-{drift_ci[1]:.3f})"
-            )
-        else:
+
+        console.print("\n[bold]Gate: Drift (final/preview)[/bold]")
+        if isinstance(drift, int | float):
             console.print(f"  observed: {drift:.3f}")
-    console.print("  threshold: 0.95-1.05")
-    console.print(f"  status: {drift_status}")
+        drift_band = (
+            pm.get("drift_band") if isinstance(pm.get("drift_band"), dict) else {}
+        )
+        drift_min = drift_band.get("min")
+        drift_max = drift_band.get("max")
+        if not (
+            isinstance(drift_min, int | float)
+            and isinstance(drift_max, int | float)
+            and math.isfinite(float(drift_min))
+            and math.isfinite(float(drift_max))
+            and float(drift_min) > 0.0
+            and float(drift_min) < float(drift_max)
+        ):
+            drift_min, drift_max = PM_DRIFT_BAND_DEFAULT
+        console.print(f"  threshold: {float(drift_min):.3f}-{float(drift_max):.3f}")
+        console.print(f"  status: {drift_status}")
 
     # Guard Overhead explanation (if present)
     overhead = (

{invarlock-0.3.8 → invarlock-0.3.9}/src/invarlock/cli/commands/report.py

@@ -337,9 +337,13 @@ def _generate_reports(
 
                 console.print("  ARTIFACTS")
                 entries = _artifact_entries(saved_files, str(output_dir))
+                artifact_label_width = max(
+                    ARTIFACT_LABEL_WIDTH,
+                    max((len(label) for label, _ in entries), default=0),
+                )
                 for idx, (label, value) in enumerate(entries):
                     branch = "└─" if idx == len(entries) - 1 else "├─"
-                    console.print(f"  {branch} {label:<{ARTIFACT_LABEL_WIDTH}} {value}")
+                    console.print(f"  {branch} {label:<{artifact_label_width}} {value}")
                 console.print("═" * SECTION_WIDTH)
 
                 # In CLI report flow, do not hard-exit on validation failure; just display status.

{invarlock-0.3.8 → invarlock-0.3.9}/src/invarlock/guards/spectral.py

@@ -61,7 +61,7 @@ def _bh_reject_families(
 
     order = sorted(
         range(n),
-        key=lambda idx: (float("inf") if not _finite01(pvals[idx]) else pvals[idx]),
+        key=lambda idx: float("inf") if not _finite01(pvals[idx]) else pvals[idx],
     )
     max_k = 0
     for rank, idx in enumerate(order, start=1):

{invarlock-0.3.8 → invarlock-0.3.9}/src/invarlock/guards_ref/spectral_ref.py

@@ -20,7 +20,7 @@ def bh_select(pvals: list[float], alpha: float) -> list[bool]:
 
     # Sort by p-value ascending while remembering original indices
     order = sorted(
-        range(n), key=lambda i: (float("inf") if not _finite01(pvals[i]) else pvals[i])
+        range(n), key=lambda i: float("inf") if not _finite01(pvals[i]) else pvals[i]
     )
     rejs_sorted = [False] * n
     max_k = 0

{invarlock-0.3.8 → invarlock-0.3.9}/src/invarlock/observability/health.py

@@ -3,6 +3,7 @@ Health checking and status monitoring.
 """
 
 import logging
+import os
 import time
 import traceback
 from collections.abc import Callable
@@ -177,8 +178,12 @@ class HealthChecker:
 
         def check_cpu():
             """Check CPU usage."""
+            cpu_details: dict[str, Any] = {"percent": None, "core_count": None}
+            warnings: list[str] = []
+
             try:
                 cpu_percent = psutil.cpu_percent(interval=1)
+                cpu_details["percent"] = cpu_percent
 
                 if cpu_percent > 95:
                     status = HealthStatus.CRITICAL
@@ -189,28 +194,41 @@ class HealthChecker:
                 else:
                     status = HealthStatus.HEALTHY
                     message = f"CPU usage normal: {cpu_percent:.1f}%"
+            except Exception as e:
+                status = HealthStatus.CRITICAL
+                message = f"Failed to measure CPU usage: {e}"
+                cpu_details["error"] = str(e)
 
-                return ComponentHealth(
-                    name="cpu",
-                    status=status,
-                    message=message,
-                    details={
-                        "percent": cpu_percent,
-                        "core_count": psutil.cpu_count(),
-                        "load_avg": psutil.getloadavg()
-                        if hasattr(psutil, "getloadavg")
-                        else None,
-                    },
-                    timestamp=time.time(),
-                )
+            try:
+                core_count = psutil.cpu_count()
+                if core_count is None:
+                    core_count = os.cpu_count()
+                cpu_details["core_count"] = core_count
             except Exception as e:
-                return ComponentHealth(
-                    name="cpu",
-                    status=HealthStatus.CRITICAL,
-                    message=f"Failed to check CPU: {e}",
-                    details={"error": str(e)},
-                    timestamp=time.time(),
-                )
+                cpu_details["core_count"] = os.cpu_count()
+                warnings.append(f"cpu_count_unavailable: {e}")
+
+            try:
+                load_avg: Any | None = None
+                if hasattr(psutil, "getloadavg"):
+                    load_avg = psutil.getloadavg()
+                elif hasattr(os, "getloadavg"):
+                    load_avg = os.getloadavg()  # type: ignore[attr-defined]
+                cpu_details["load_avg"] = load_avg
+            except Exception as e:
+                cpu_details["load_avg"] = None
+                warnings.append(f"load_avg_unavailable: {e}")
+
+            if warnings:
+                cpu_details["warnings"] = warnings
+
+            return ComponentHealth(
+                name="cpu",
+                status=status,
+                message=message,
+                details=cpu_details,
+                timestamp=time.time(),
+            )
 
         def check_disk():
             """Check disk space."""

{invarlock-0.3.8 → invarlock-0.3.9}/src/invarlock/reporting/report_builder.py

@@ -80,6 +80,9 @@ TIER_RATIO_LIMITS: dict[str, float] = {
     "none": 1.10,
 }
 
+# Canonical preview→final drift band used when not explicitly configured.
+PM_DRIFT_BAND_DEFAULT: tuple[float, float] = (0.95, 1.05)
+
 
 def _is_ppl_kind(name: Any) -> bool:
     """Return True if a primary_metric kind denotes a ppl-like metric.
@@ -3263,8 +3266,7 @@ def _resolve_pm_drift_band_from_report(
 ) -> dict[str, float]:
     """Resolve preview→final drift band from report context/meta/env."""
 
-    base_min = 0.95
-    base_max = 1.05
+    base_min, base_max = PM_DRIFT_BAND_DEFAULT
 
     def _safe_float(val: Any) -> float | None:
         try:
@@ -3436,8 +3438,7 @@ def _compute_validation_flags(
     # Canonical Gates
     # 1. Drift gate: by default 0.95 ≤ final/preview ≤ 1.05 (configurable)
     drift_ratio = ppl.get("preview_final_ratio", 1.0)
-    drift_min = 0.95
-    drift_max = 1.05
+    drift_min, drift_max = PM_DRIFT_BAND_DEFAULT
     if isinstance(pm_drift_band, dict):
         try:
             cand_min = pm_drift_band.get("min")

{invarlock-0.3.8 → invarlock-0.3.9/src/invarlock.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: invarlock
-Version: 0.3.8
+Version: 0.3.9
 Summary: Edit‑agnostic robustness evaluation reports for weight edits (InvarLock framework)
 Author-email: InvarLock Team <oss@invarlock.dev>
 Maintainer-email: InvarLock Maintainers <support@invarlock.dev>
@@ -106,31 +106,44 @@ Requires-Dist: twine>=4.0.0; extra == "dev"
 Dynamic: license-file
 
 <p align="center">
-  <img
-    src="docs/assets/invarlock-logo.svg"
-    alt="InvarLock"
-    width="420"
-  />
+  <picture>
+    <source
+      media="(prefers-color-scheme: dark)"
+      srcset="docs/assets/invarlock-logo-dark.svg"
+    />
+    <img src="docs/assets/invarlock-logo.svg" alt="InvarLock" />
+  </picture>
 </p>
 
-# InvarLock — Edit‑agnostic robustness reports for weight edits
+<p align="center"><em>Edit‑agnostic robustness reports for weight edits</em></p>
 
-[![CI](https://img.shields.io/github/actions/workflow/status/invarlock/invarlock/ci.yml?branch=main&logo=github&label=CI)](https://github.com/invarlock/invarlock/actions/workflows/ci.yml)
-[![PyPI](https://badge.fury.io/py/invarlock.svg)](https://pypi.org/project/invarlock/)
-[![Docs](https://img.shields.io/badge/docs-quickstart-blue.svg)](https://github.com/invarlock/invarlock/blob/main/docs/user-guide/quickstart.md)
-[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
-[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/release/python-3120/)
+<p align="center">
+  <a href="https://github.com/invarlock/invarlock/actions/workflows/ci.yml">
+    <img alt="CI" src="https://img.shields.io/github/actions/workflow/status/invarlock/invarlock/ci.yml?branch=main&logo=github&label=CI" />
+  </a>
+  <a href="https://pypi.org/project/invarlock/">
+    <img alt="PyPI" src="https://badge.fury.io/py/invarlock.svg" />
+  </a>
+  <a href="https://github.com/invarlock/invarlock/blob/main/docs/user-guide/quickstart.md">
+    <img alt="Docs" src="https://img.shields.io/badge/docs-quickstart-blue.svg" />
+  </a>
+  <a href="LICENSE">
+    <img alt="License: Apache-2.0" src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" />
+  </a>
+  <a href="https://www.python.org/downloads/release/python-3120/">
+    <img alt="Python 3.12+" src="https://img.shields.io/badge/python-3.12+-blue.svg" />
+  </a>
+</p>
+
+<p align="center">
+  <strong>Catch silent quality regressions from quantization, pruning, and weight edits before they ship.</strong>
+</p>
 
 Quantizing, pruning, or otherwise editing a model’s weights can silently degrade quality.
 InvarLock compares an edited **subject** checkpoint against a fixed **baseline** with paired
 evaluation windows, enforces a guard pipeline (invariants → spectral → RMT → variance), and
 produces a machine‑readable Evaluation Report you can gate in CI.
 
-> Status: pre‑1.0. Until 1.0, minor releases may be breaking. See `CHANGELOG.md`.
-
-For guidance on where to ask questions, how to report bugs, and what to expect in terms of response times, see
-[SUPPORT.md](https://github.com/invarlock/invarlock/blob/main/SUPPORT.md).
-
 ## Why InvarLock?
 
 - **Quality gates for weight edits**: catch regressions before deployment.
@@ -270,6 +283,13 @@ If you use InvarLock in scientific work, please cite it (canonical metadata is i
 | CPU                    | ✅ Fallback      | Slower but functional                     |
 <!-- markdownlint-enable MD060 -->
 
+## Project status
+
+InvarLock is pre‑1.0. Until 1.0, minor releases may include breaking changes. See [`CHANGELOG.md`](CHANGELOG.md).
+
+For guidance on where to ask questions, how to report bugs, and what to expect in terms of response times, see
+[`SUPPORT.md`](SUPPORT.md).
+
 ## Contributing
 
 - Contributing guide: <https://github.com/invarlock/invarlock/blob/main/CONTRIBUTING.md>