invarlock 0.2.0__py3-none-any.whl

invarlock/eval/providers/base.py

@@ -0,0 +1,67 @@
+"""
+EvaluationProvider base Protocol (Phase 1 scaffold).
+
+Providers encapsulate dataset/task specifics (pairing, masking, transforms),
+exposing a stable schedule and a reproducibility digest so metrics can be
+computed in a task-agnostic way.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any, Protocol
+
+
+def deterministic_worker_init_fn(worker_id: int, *, base_seed: int = 0) -> None:
+    """Best-effort deterministic worker initializer.
+
+    Sets RNG seeds for `random`, `numpy`, and `torch` (if available) using a
+    stable derivation from `base_seed` and `worker_id`.
+    """
+    try:
+        import random
+
+        random.seed((base_seed ^ (worker_id + 17)) & 0x7FFFFFFF)
+    except Exception:
+        pass
+    try:
+        import numpy as _np
+
+        _np.random.seed(((base_seed + 97) ^ (worker_id * 131)) & 0x7FFFFFFF)
+    except Exception:
+        pass
+    try:  # pragma: no cover - torch may be unavailable in CI
+        import torch as _torch
+
+        _torch.manual_seed((base_seed * 1009 + worker_id * 7919) & 0x7FFFFFFF)
+        if hasattr(_torch.cuda, "manual_seed_all"):
+            _torch.cuda.manual_seed_all(
+                (base_seed * 1013 + worker_id * 7951) & 0x7FFFFFFF
+            )
+    except Exception:
+        pass
+
+
+def deterministic_shards(n: int, *, num_workers: int) -> list[list[int]]:
+    """Return a deterministic partition of `range(n)` across `num_workers` workers.
+
+    Uses simple modulo-based assignment to ensure stable sharding independent of
+    process scheduling. `num_workers <= 1` yields a single shard with all items.
+    """
+    if num_workers is None or num_workers <= 1:
+        return [list(range(n))]
+    shards: list[list[int]] = [[] for _ in range(int(num_workers))]
+    for i in range(int(n)):
+        shards[i % int(num_workers)].append(i)
+    return shards
+
+
+class EvaluationProvider(Protocol):
+    def pairing_schedule(self) -> list[str]:
+        """Return a stable, sorted list of example IDs used for pairing."""
+
+    def digest(self) -> dict[str, Any]:
+        """Return a reproducibility digest (tokenizer/masking/transform hashes)."""
+
+    def batches(self, *, seed: int, batch_size: int) -> Iterable[dict[str, Any]]:
+        """Yield task-appropriate batches (input tensors/labels/masks)."""

invarlock/eval/providers/seq2seq.py

@@ -0,0 +1,111 @@
+"""
+Seq2Seq provider (Phase 2 scaffold).
+
+Future implementation will stream paired (encoder_inputs, decoder_labels) with
+stable example IDs and a digest of tokenization/EOS policies.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+from .base import EvaluationProvider
+
+
+class Seq2SeqProvider(EvaluationProvider):
+    """Deterministic synthetic seq2seq provider for tests and smokes.
+
+    Args (kwargs):
+        n: number of examples (default: 12)
+        src_len: source length (default: 6)
+        tgt_len: target length (default: 7)
+        pad_id: pad token id (default: 0)
+        bos_id: BOS id (default: 1)
+        eos_id: EOS id (default: 2)
+    """
+
+    def __init__(self, **kwargs: Any) -> None:
+        self._n = int(kwargs.get("n", 12))
+        self._src_len = int(kwargs.get("src_len", 6))
+        self._tgt_len = int(kwargs.get("tgt_len", 7))
+        self._pad_id = int(kwargs.get("pad_id", 0))
+        self._bos_id = int(kwargs.get("bos_id", 1))
+        self._eos_id = int(kwargs.get("eos_id", 2))
+        self._ids: list[str] = []
+
+    def pairing_schedule(self) -> list[str]:
+        return (
+            sorted(self._ids) if self._ids else [f"ex{i:04d}" for i in range(self._n)]
+        )
+
+    def digest(self) -> dict[str, Any]:
+        return {
+            "provider": "seq2seq",
+            "version": 1,
+            "pad_id": self._pad_id,
+            "eos_id": self._eos_id,
+            "bos_id": self._bos_id,
+        }
+
+    def _gen_example(self, idx: int, *, seed: int) -> dict[str, Any]:
+        import random
+
+        rng = random.Random((seed + 17) ^ (idx * 97))
+        # Source: BOS + tokens + PAD
+        src_real = max(3, self._src_len - (idx % 2))
+        src_ids = (
+            [self._bos_id]
+            + [1 + rng.randint(0, 19) for _ in range(src_real - 2)]
+            + [self._eos_id]
+        )
+        if src_real < self._src_len:
+            src_ids += [self._pad_id] * (self._src_len - src_real)
+        src_mask = [1 if t != self._pad_id else 0 for t in src_ids]
+
+        # Target: tokens ending with EOS and padding
+        tgt_real = max(3, self._tgt_len - (idx % 3))
+        tgt_ids = [1 + rng.randint(0, 19) for _ in range(tgt_real - 1)] + [self._eos_id]
+        if tgt_real < self._tgt_len:
+            tgt_ids += [self._pad_id] * (self._tgt_len - tgt_real)
+        tgt_mask = [1 if t != self._pad_id else 0 for t in tgt_ids]
+
+        ex_id = f"ex{idx:04d}"
+        weights = sum(1 for t, m in zip(tgt_ids, tgt_mask, strict=False) if m)
+        return {
+            "ids": ex_id,
+            "src_ids": src_ids,
+            "src_mask": src_mask,
+            "tgt_ids": tgt_ids,
+            "tgt_mask": tgt_mask,
+            "weights": int(weights),
+        }
+
+    def batches(self, *, seed: int, batch_size: int) -> Iterable[dict[str, Any]]:
+        assert batch_size > 0
+        batch = {
+            "ids": [],
+            "src_ids": [],
+            "src_mask": [],
+            "tgt_ids": [],
+            "tgt_mask": [],
+            "weights": [],
+        }
+        self._ids = []
+        for i in range(self._n):
+            ex = self._gen_example(i, seed=seed)
+            self._ids.append(ex["ids"])
+            for k in ("ids", "src_ids", "src_mask", "tgt_ids", "tgt_mask", "weights"):
+                batch[k].append(ex[k])
+            if len(batch["ids"]) >= batch_size:
+                yield batch
+                batch = {
+                    "ids": [],
+                    "src_ids": [],
+                    "src_mask": [],
+                    "tgt_ids": [],
+                    "tgt_mask": [],
+                    "weights": [],
+                }
+        if batch["ids"]:
+            yield batch

invarlock/eval/providers/text_lm.py

@@ -0,0 +1,113 @@
+"""
+Text LM provider (Phase 2 scaffold).
+
+This module will house a provider that encapsulates dataset/tokenizer logic for
+language modeling tasks. For now, it serves as a placeholder aligning with the
+EvaluationProvider protocol.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+from .base import EvaluationProvider
+
+
+class TextLMProvider(EvaluationProvider):
+    """Deterministic synthetic text LM provider for tests and smokes.
+
+    Args (kwargs):
+        task: 'causal' or 'mlm' (default: 'causal')
+        n: number of examples (default: 16)
+        seq_len: length of each sequence (default: 8)
+        mask_prob: MLM mask probability (default: 0.15)
+        pad_id: padding token id (default: 0)
+        eos_id: end-of-sequence id (default: 2)
+    """
+
+    def __init__(self, **kwargs: Any) -> None:
+        self._task = str(kwargs.get("task", "causal")).lower()
+        self._n = int(kwargs.get("n", 16))
+        self._seq_len = int(kwargs.get("seq_len", 8))
+        self._mask_prob = float(kwargs.get("mask_prob", 0.15))
+        self._pad_id = int(kwargs.get("pad_id", 0))
+        self._eos_id = int(kwargs.get("eos_id", 2))
+        self._ids: list[str] = []
+
+    def pairing_schedule(self) -> list[str]:
+        return (
+            sorted(self._ids) if self._ids else [f"ex{i:04d}" for i in range(self._n)]
+        )
+
+    def digest(self) -> dict[str, Any]:
+        return {"provider": "text_lm", "version": 1, "task": self._task}
+
+    def _gen_example(self, idx: int, *, seed: int) -> dict[str, Any]:
+        import random
+
+        rng = random.Random((seed + 31) ^ (idx * 131))
+        # Generate a simple pattern with EOS at end and some pads
+        real_len = max(3, self._seq_len - (idx % 3))
+        ids = [1 + (rng.randint(0, 19)) for _ in range(real_len - 1)] + [self._eos_id]
+        if real_len < self._seq_len:
+            ids = ids + [self._pad_id] * (self._seq_len - real_len)
+        attn = [1 if t != self._pad_id else 0 for t in ids]
+        ex_id = f"ex{idx:04d}"
+
+        labels: list[int] | None = None
+        weights = sum(attn)
+        if self._task == "mlm":
+            labels = [-100] * len(ids)
+            masked = 0
+            for pos, (tok, m) in enumerate(zip(ids, attn, strict=False)):
+                if not m or tok in (self._pad_id, self._eos_id):
+                    continue
+                # Deterministic mask using rng per-position
+                rng2 = random.Random((seed + idx * 17 + pos * 13) & 0x7FFFFFFF)
+                if rng2.random() < self._mask_prob:
+                    labels[pos] = tok
+                    masked += 1
+            if masked == 0:
+                # Ensure at least one label to avoid degenerate windows
+                for pos, (tok, m) in enumerate(zip(ids, attn, strict=False)):
+                    if m and tok not in (self._pad_id, self._eos_id):
+                        labels[pos] = tok
+                        masked = 1
+                        break
+            weights = masked
+
+        return {
+            "ids": ex_id,
+            "input_ids": ids,
+            "attention_mask": attn,
+            "labels": labels if labels is not None else [],
+            "weights": int(weights),
+        }
+
+    def batches(self, *, seed: int, batch_size: int) -> Iterable[dict[str, Any]]:
+        assert batch_size > 0
+        batch: dict[str, Any] = {
+            "ids": [],
+            "input_ids": [],
+            "attention_mask": [],
+            "labels": [],
+            "weights": [],
+        }
+        self._ids = []
+        for i in range(self._n):
+            ex = self._gen_example(i, seed=seed)
+            self._ids.append(ex["ids"])
+            for k in ("ids", "input_ids", "attention_mask", "labels", "weights"):
+                batch[k].append(ex[k])
+            if len(batch["ids"]) >= batch_size:
+                yield batch
+                batch = {
+                    "ids": [],
+                    "input_ids": [],
+                    "attention_mask": [],
+                    "labels": [],
+                    "weights": [],
+                }
+        if batch["ids"]:
+            yield batch

invarlock/eval/providers/vision_text.py

@@ -0,0 +1,93 @@
+"""
+Vision-Text provider (Phase 4): deterministic pairing and reproducibility digest.
+
+This lightweight provider focuses on stable IDs and a reproducibility digest for
+multimodal (image+text) tasks such as image captioning and VQA. It does not
+perform actual batching or transforms; those belong to adapters/inference.
+"""
+
+from __future__ import annotations
+
+import hashlib
+from collections.abc import Iterable, Sequence
+from typing import Any
+
+from .base import EvaluationProvider
+
+
+def _sha256_hex(data: bytes) -> str:
+    h = hashlib.sha256()
+    h.update(data)
+    return h.hexdigest()
+
+
+class VisionTextProvider(EvaluationProvider):
+    """
+    Minimal provider that exposes:
+    - a stable pairing schedule (sorted example IDs), and
+    - a digest with ids and image hashes plus transform pipeline string.
+
+    Args:
+        items: sequence of records with at least keys {"id": str, "image_bytes": bytes}
+        transform_pipeline: human-readable transform pipeline description
+        seed: integer seed recorded for determinism breadcrumbs
+    """
+
+    def __init__(
+        self,
+        *,
+        items: Sequence[dict[str, Any]],
+        transform_pipeline: str = "",
+        seed: int | None = None,
+    ) -> None:
+        self._items = list(items)
+        self._transform_pipeline = str(transform_pipeline)
+        self._seed = int(seed) if seed is not None else None
+
+        # Build sorted schedule once
+        try:
+            self._schedule: list[str] = sorted(str(x["id"]) for x in self._items)
+        except Exception:  # pragma: no cover - defensive
+            self._schedule = []
+
+        # Precompute digest components
+        ids_concat = "".join(self._schedule).encode()
+        self._ids_sha256 = _sha256_hex(ids_concat)
+        # Compute per-image hashes in schedule order; missing bytes treated as empty
+        per_img_hashes = []
+        for rec_id in self._schedule:
+            # find the record with matching id (first match)
+            img_bytes = b""
+            for rec in self._items:
+                if str(rec.get("id")) == rec_id:
+                    ib = rec.get("image_bytes")
+                    if isinstance(ib, bytes | bytearray):
+                        img_bytes = bytes(ib)
+                    break
+            per_img_hashes.append(_sha256_hex(img_bytes).encode())
+        self._images_sha256 = _sha256_hex(b"".join(per_img_hashes))
+
+    def pairing_schedule(self) -> list[str]:
+        return list(self._schedule)
+
+    def digest(self) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "provider": "vision_text",
+            "version": 1,
+            "ids_sha256": self._ids_sha256,
+            "images_sha256": self._images_sha256,
+            "transform_pipeline": self._transform_pipeline,
+        }
+        if self._seed is not None:
+            d["seed"] = int(self._seed)
+        return d
+
+    def batches(
+        self, *, seed: int, batch_size: int
+    ) -> Iterable[dict[str, Any]]:  # pragma: no cover - not used in Phase 4 tests
+        raise NotImplementedError(
+            "VisionTextProvider batches are adapter/task-specific and not implemented here"
+        )
+
+
+__all__ = ["VisionTextProvider"]

invarlock/eval/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561 type hints

invarlock/guards/__init__.py

@@ -0,0 +1,18 @@
+"""Guard namespace (`invarlock.guards`) re-exporting built-in guards."""
+
+from __future__ import annotations
+
+from invarlock.core.abi import INVARLOCK_CORE_ABI as INVARLOCK_CORE_ABI
+
+from .invariants import InvariantsGuard
+from .rmt import RMTGuard
+from .spectral import SpectralGuard
+from .variance import VarianceGuard
+
+__all__ = [
+    "InvariantsGuard",
+    "SpectralGuard",
+    "VarianceGuard",
+    "RMTGuard",
+    "INVARLOCK_CORE_ABI",
+]

invarlock/guards/_contracts.py

@@ -0,0 +1,9 @@
+from __future__ import annotations
+
+import os
+
+
+def guard_assert(cond: bool, msg: str) -> None:
+    """Enable lightweight runtime contracts when INVARLOCK_ASSERT_GUARDS=1."""
+    if os.getenv("INVARLOCK_ASSERT_GUARDS", "0") == "1":
+        assert bool(cond), msg