glitchlings 0.4.5__cp311-cp311-win_amd64.whl

glitchlings/dlc/pytorch_lightning.py

@@ -0,0 +1,209 @@
+"""Integration helpers for PyTorch Lightning data modules."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping, Sequence
+from typing import Any, cast
+
+from ..compat import get_pytorch_lightning_datamodule, require_pytorch_lightning
+from ..util.adapters import coerce_gaggle
+from ..zoo import Gaggle, Glitchling
+from ._shared import corrupt_text_value, normalize_column_spec
+
+
+def _glitch_batch(batch: Any, columns: list[str], gaggle: Gaggle) -> Any:
+    """Apply glitchlings to the configured batch columns."""
+    if not isinstance(batch, Mapping):
+        return batch
+
+    if hasattr(batch, "copy"):
+        mutated = batch.copy()
+    else:
+        mutated = dict(batch)
+
+    missing = [column for column in columns if column not in mutated]
+    if missing:
+        missing_str = ", ".join(sorted(missing))
+        raise ValueError(f"Columns not found in batch: {missing_str}")
+
+    for column in columns:
+        mutated[column] = corrupt_text_value(mutated[column], gaggle)
+
+    return mutated
+
+
+def _wrap_dataloader(dataloader: Any, columns: list[str], gaggle: Gaggle) -> Any:
+    """Wrap a dataloader so yielded batches are corrupted lazily."""
+    if dataloader is None:
+        return None
+
+    if isinstance(dataloader, Mapping):
+        mapping_type = cast(type[Any], dataloader.__class__)
+        return mapping_type(
+            {key: _wrap_dataloader(value, columns, gaggle) for key, value in dataloader.items()}
+        )
+
+    if isinstance(dataloader, list):
+        return [_wrap_dataloader(value, columns, gaggle) for value in dataloader]
+
+    if isinstance(dataloader, tuple):
+        return tuple(_wrap_dataloader(value, columns, gaggle) for value in dataloader)
+
+    if isinstance(dataloader, Sequence) and not isinstance(dataloader, (str, bytes, bytearray)):
+        sequence_type = cast(type[Any], dataloader.__class__)
+        return sequence_type(_wrap_dataloader(value, columns, gaggle) for value in dataloader)
+
+    return _GlitchedDataLoader(dataloader, columns, gaggle)
+
+
+class _GlitchedDataLoader:
+    """Proxy dataloader that glitches batches produced by the wrapped loader."""
+
+    def __init__(self, dataloader: Any, columns: list[str], gaggle: Gaggle) -> None:
+        self._dataloader = dataloader
+        self._columns = columns
+        self._gaggle = gaggle
+
+    def __iter__(self) -> Any:
+        for batch in self._dataloader:
+            yield _glitch_batch(batch, self._columns, self._gaggle)
+
+    def __len__(self) -> int:
+        return len(self._dataloader)
+
+    def __getattr__(self, attribute: str) -> Any:
+        return getattr(self._dataloader, attribute)
+
+
+def _glitch_datamodule(
+    datamodule: Any,
+    glitchlings: Glitchling | Gaggle | str | Iterable[str | Glitchling],
+    column: str | Sequence[str],
+    *,
+    seed: int = 151,
+) -> Any:
+    """Return a proxy that applies glitchlings to batches from the datamodule."""
+
+    columns = normalize_column_spec(column)
+    if columns is None:  # pragma: no cover - defensive
+        raise ValueError("At least one column must be specified")
+    # Lightning datamodules only support string column names (mapping keys)
+    columns_str = cast(list[str], columns)
+    gaggle = coerce_gaggle(glitchlings, seed=seed)
+    return _GlitchedLightningDataModule(datamodule, columns_str, gaggle)
+
+
+class _GlitchedLightningDataModule:
+    """Proxy wrapper around a LightningDataModule applying glitchlings to batches."""
+
+    def __init__(self, base: Any, columns: list[str], gaggle: Gaggle) -> None:
+        object.__setattr__(self, "_glitch_base", base)
+        object.__setattr__(self, "_glitch_columns", columns)
+        object.__setattr__(self, "_glitch_gaggle", gaggle)
+
+    def __getattr__(self, attribute: str) -> Any:
+        return getattr(self._glitch_base, attribute)
+
+    def __setattr__(self, attribute: str, value: Any) -> None:
+        if attribute.startswith("_glitch_"):
+            object.__setattr__(self, attribute, value)
+        else:
+            setattr(self._glitch_base, attribute, value)
+
+    def __delattr__(self, attribute: str) -> None:
+        if attribute.startswith("_glitch_"):
+            object.__delattr__(self, attribute)
+        else:
+            delattr(self._glitch_base, attribute)
+
+    def __dir__(self) -> list[str]:
+        return sorted(set(dir(self.__class__)) | set(dir(self._glitch_base)))
+
+    # LightningDataModule API -------------------------------------------------
+    def prepare_data(self, *args: Any, **kwargs: Any) -> Any:
+        return self._glitch_base.prepare_data(*args, **kwargs)
+
+    def setup(self, *args: Any, **kwargs: Any) -> Any:
+        return self._glitch_base.setup(*args, **kwargs)
+
+    def teardown(self, *args: Any, **kwargs: Any) -> Any:
+        return self._glitch_base.teardown(*args, **kwargs)
+
+    def state_dict(self) -> Mapping[str, Any]:
+        state = self._glitch_base.state_dict()
+        return cast(Mapping[str, Any], state)
+
+    def load_state_dict(self, state_dict: Mapping[str, Any]) -> None:
+        self._glitch_base.load_state_dict(state_dict)
+
+    def transfer_batch_to_device(self, batch: Any, device: Any, dataloader_idx: int) -> Any:
+        return self._glitch_base.transfer_batch_to_device(batch, device, dataloader_idx)
+
+    def on_before_batch_transfer(self, batch: Any, dataloader_idx: int) -> Any:
+        return self._glitch_base.on_before_batch_transfer(batch, dataloader_idx)
+
+    def on_after_batch_transfer(self, batch: Any, dataloader_idx: int) -> Any:
+        return self._glitch_base.on_after_batch_transfer(batch, dataloader_idx)
+
+    def train_dataloader(self, *args: Any, **kwargs: Any) -> Any:
+        loader = self._glitch_base.train_dataloader(*args, **kwargs)
+        return _wrap_dataloader(loader, self._glitch_columns, self._glitch_gaggle)
+
+    def val_dataloader(self, *args: Any, **kwargs: Any) -> Any:
+        loader = self._glitch_base.val_dataloader(*args, **kwargs)
+        return _wrap_dataloader(loader, self._glitch_columns, self._glitch_gaggle)
+
+    def test_dataloader(self, *args: Any, **kwargs: Any) -> Any:
+        loader = self._glitch_base.test_dataloader(*args, **kwargs)
+        return _wrap_dataloader(loader, self._glitch_columns, self._glitch_gaggle)
+
+    def predict_dataloader(self, *args: Any, **kwargs: Any) -> Any:
+        loader = self._glitch_base.predict_dataloader(*args, **kwargs)
+        return _wrap_dataloader(loader, self._glitch_columns, self._glitch_gaggle)
+
+
+def _ensure_datamodule_class() -> Any:
+    """Return the Lightning ``LightningDataModule`` patched with ``.glitch``."""
+
+    datamodule_cls = get_pytorch_lightning_datamodule()
+    if datamodule_cls is None:  # pragma: no cover - dependency is optional
+        module = require_pytorch_lightning("pytorch_lightning is not installed")
+        datamodule_cls = getattr(module, "LightningDataModule", None)
+        if datamodule_cls is None:
+            raise ModuleNotFoundError("pytorch_lightning is not installed")
+
+    if getattr(datamodule_cls, "glitch", None) is None:
+
+        def glitch(
+            self: Any,
+            glitchlings: Glitchling | Gaggle | str | Iterable[str | Glitchling],
+            *,
+            column: str | Sequence[str],
+            seed: int = 151,
+            **_: Any,
+        ) -> Any:
+            return _glitch_datamodule(self, glitchlings, column, seed=seed)
+
+        setattr(datamodule_cls, "glitch", glitch)
+
+    if not issubclass(_GlitchedLightningDataModule, datamodule_cls):
+        _GlitchedLightningDataModule.__bases__ = (datamodule_cls,)
+
+    return datamodule_cls
+
+
+def install() -> None:
+    """Monkeypatch ``LightningDataModule`` with ``.glitch``."""
+
+    _ensure_datamodule_class()
+
+
+LightningDataModule: type[Any] | None
+_LightningDataModuleAlias = get_pytorch_lightning_datamodule()
+if _LightningDataModuleAlias is not None:
+    LightningDataModule = _ensure_datamodule_class()
+else:  # pragma: no cover - optional dependency
+    LightningDataModule = None
+
+
+__all__ = ["LightningDataModule", "install"]

glitchlings/lexicon/__init__.py

@@ -0,0 +1,192 @@
+"""Lexicon abstractions and default backend resolution helpers."""
+
+from __future__ import annotations
+
+import random
+from abc import ABC, abstractmethod
+from hashlib import blake2s
+from pathlib import Path
+from typing import Callable, Iterable
+
+from glitchlings.config import get_config
+
+from ._cache import CacheEntries, CacheSnapshot
+
+
+class Lexicon(ABC):
+    """Abstract interface describing synonym lookup backends.
+
+    Parameters
+    ----------
+    seed:
+        Optional integer used to derive deterministic random number generators
+        for synonym sampling. Identical seeds guarantee reproducible results for
+        the same word/part-of-speech queries.
+
+    """
+
+    def __init__(self, *, seed: int | None = None) -> None:
+        self._seed = seed
+
+    @property
+    def seed(self) -> int | None:
+        """Return the current base seed used for deterministic sampling."""
+        return self._seed
+
+    def reseed(self, seed: int | None) -> None:
+        """Update the base seed driving deterministic synonym sampling."""
+        self._seed = seed
+
+    def _derive_rng(self, word: str, pos: str | None) -> random.Random:
+        """Return an RNG derived from the base seed, word, and POS tag."""
+        seed_material = blake2s(digest_size=8)
+        seed_material.update(word.lower().encode("utf8"))
+        if pos is not None:
+            seed_material.update(pos.lower().encode("utf8"))
+        seed_repr = "None" if self._seed is None else str(self._seed)
+        seed_material.update(seed_repr.encode("utf8"))
+        derived_seed = int.from_bytes(seed_material.digest(), "big", signed=False)
+        return random.Random(derived_seed)
+
+    def _deterministic_sample(
+        self, values: Iterable[str], *, limit: int, word: str, pos: str | None
+    ) -> list[str]:
+        """Return up to ``limit`` values sampled deterministically."""
+        if limit <= 0:
+            return []
+
+        items = list(values)
+        if len(items) <= limit:
+            return items
+
+        rng = self._derive_rng(word, pos)
+        indices = rng.sample(range(len(items)), k=limit)
+        indices.sort()
+        return [items[index] for index in indices]
+
+    @abstractmethod
+    def get_synonyms(self, word: str, pos: str | None = None, n: int = 5) -> list[str]:
+        """Return up to ``n`` synonyms for ``word`` constrained by ``pos``."""
+
+    def supports_pos(self, pos: str | None) -> bool:
+        """Return ``True`` when the backend can service ``pos`` queries."""
+        return True
+
+    def __repr__(self) -> str:  # pragma: no cover - trivial representation
+        return f"{self.__class__.__name__}(seed={self._seed!r})"
+
+
+class LexiconBackend(Lexicon):
+    """Extended lexicon interface that supports cache persistence."""
+
+    Cache = CacheEntries
+
+    @classmethod
+    @abstractmethod
+    def load_cache(cls, path: str | Path) -> CacheSnapshot:
+        """Return a validated cache snapshot loaded from ``path``."""
+
+    @abstractmethod
+    def save_cache(self, path: str | Path | None = None) -> Path | None:
+        """Persist the backend cache to ``path`` and return the destination."""
+
+
+from .metrics import (  # noqa: E402
+    compare_lexicons,
+    coverage_ratio,
+    mean_cosine_similarity,
+    synonym_diversity,
+)
+from .vector import VectorLexicon, build_vector_cache  # noqa: E402
+
+_WordNetLexicon: type[LexiconBackend] | None
+try:  # pragma: no cover - optional dependency
+    from .wordnet import WordNetLexicon as _WordNetLexicon
+except (
+    ImportError,
+    ModuleNotFoundError,
+    AttributeError,
+):  # pragma: no cover - triggered when nltk unavailable
+    _WordNetLexicon = None
+
+WordNetLexicon: type[LexiconBackend] | None = _WordNetLexicon
+
+
+_BACKEND_FACTORIES: dict[str, Callable[[int | None], Lexicon | None]] = {}
+
+
+def register_backend(name: str, factory: Callable[[int | None], Lexicon | None]) -> None:
+    """Register ``factory`` for ``name`` so it can be selected via config."""
+    normalized = name.lower()
+    _BACKEND_FACTORIES[normalized] = factory
+
+
+def unregister_backend(name: str) -> None:
+    """Remove a previously registered backend."""
+    _BACKEND_FACTORIES.pop(name.lower(), None)
+
+
+def available_backends() -> list[str]:
+    """Return the names of registered lexicon factories."""
+    return sorted(_BACKEND_FACTORIES)
+
+
+def _vector_backend(seed: int | None) -> Lexicon | None:
+    config = get_config()
+    cache_path = config.lexicon.vector_cache
+    if cache_path is None:
+        return None
+    if not cache_path.exists():
+        return None
+    return VectorLexicon(cache_path=cache_path, seed=seed)
+
+
+def _wordnet_backend(seed: int | None) -> Lexicon | None:  # pragma: no cover - optional
+    if WordNetLexicon is None:
+        return None
+    try:
+        lexicon = WordNetLexicon(seed=seed)
+    except RuntimeError:
+        return None
+    return lexicon
+
+
+register_backend("vector", _vector_backend)
+register_backend("wordnet", _wordnet_backend)
+
+
+def get_default_lexicon(seed: int | None = None) -> Lexicon:
+    """Return the first available lexicon according to configuration priority."""
+    config = get_config()
+    attempts: list[str] = []
+    for name in config.lexicon.priority:
+        factory = _BACKEND_FACTORIES.get(name.lower())
+        if factory is None:
+            attempts.append(f"{name} (unknown)")
+            continue
+        lexicon = factory(seed)
+        if lexicon is not None:
+            return lexicon
+        attempts.append(f"{name} (unavailable)")
+    attempted = ", ".join(attempts) or "<none>"
+    raise RuntimeError(
+        "No lexicon backends available; configure lexicon.priority with at least one "
+        f"working backend. Attempts: {attempted}."
+    )
+
+
+__all__ = [
+    "Lexicon",
+    "LexiconBackend",
+    "VectorLexicon",
+    "WordNetLexicon",
+    "build_vector_cache",
+    "compare_lexicons",
+    "coverage_ratio",
+    "mean_cosine_similarity",
+    "synonym_diversity",
+    "get_default_lexicon",
+    "register_backend",
+    "unregister_backend",
+    "available_backends",
+]

glitchlings/lexicon/_cache.py

@@ -0,0 +1,108 @@
+"""Shared cache helpers for lexicon backends."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from hashlib import blake2s
+from pathlib import Path
+from typing import Mapping, Sequence, cast
+
+CacheEntries = dict[str, list[str]]
+
+
+@dataclass(frozen=True)
+class CacheSnapshot:
+    """Materialised cache data and its integrity checksum."""
+
+    entries: CacheEntries
+    checksum: str | None = None
+
+
+def _normalize_entries(payload: Mapping[str, object]) -> CacheEntries:
+    """Convert raw cache payloads into canonical mapping form."""
+    entries: CacheEntries = {}
+    for key, values in payload.items():
+        if not isinstance(key, str):
+            raise RuntimeError("Synonym cache keys must be strings.")
+        if not isinstance(values, Sequence):
+            raise RuntimeError("Synonym cache values must be sequences of strings.")
+        entries[key] = [str(value) for value in values]
+    return entries
+
+
+def _canonical_json(entries: Mapping[str, Sequence[str]]) -> str:
+    """Return a deterministic JSON serialisation for ``entries``."""
+    serialisable = {key: list(values) for key, values in sorted(entries.items())}
+    return json.dumps(serialisable, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+
+
+def compute_checksum(entries: Mapping[str, Sequence[str]]) -> str:
+    """Return a BLAKE2s checksum for ``entries``."""
+    digest = blake2s(_canonical_json(entries).encode("utf8"), digest_size=16)
+    return digest.hexdigest()
+
+
+def load_cache(path: Path) -> CacheSnapshot:
+    """Load a cache from ``path`` and verify its checksum if present."""
+    if not path.exists():
+        return CacheSnapshot(entries={}, checksum=None)
+
+    with path.open("r", encoding="utf8") as handle:
+        payload_obj = json.load(handle)
+
+    checksum: str | None = None
+    entries_payload: Mapping[str, object]
+
+    if not isinstance(payload_obj, Mapping):
+        raise RuntimeError("Synonym cache payload must be a mapping of strings to lists.")
+
+    payload = cast(Mapping[str, object], payload_obj)
+
+    if "__meta__" in payload and "entries" in payload:
+        meta_obj = payload["__meta__"]
+        entries_obj = payload["entries"]
+        if not isinstance(entries_obj, Mapping):
+            raise RuntimeError("Synonym cache entries must be stored as a mapping.")
+        entries_payload = cast(Mapping[str, object], entries_obj)
+        if isinstance(meta_obj, Mapping):
+            raw_checksum = meta_obj.get("checksum")
+            if raw_checksum is not None and not isinstance(raw_checksum, str):
+                raise RuntimeError("Synonym cache checksum must be a string when provided.")
+            checksum = raw_checksum if isinstance(raw_checksum, str) else None
+        else:
+            raise RuntimeError("Synonym cache metadata must be a mapping.")
+    else:
+        entries_payload = payload  # legacy format without metadata
+
+    entries = _normalize_entries(entries_payload)
+    if checksum is not None:
+        expected = compute_checksum(entries)
+        if checksum != expected:
+            raise RuntimeError(
+                "Synonym cache checksum mismatch; the cache file appears to be corrupted."
+            )
+
+    return CacheSnapshot(entries=entries, checksum=checksum)
+
+
+def write_cache(path: Path, entries: Mapping[str, Sequence[str]]) -> CacheSnapshot:
+    """Persist ``entries`` to ``path`` with checksum metadata."""
+    serialisable: CacheEntries = {key: list(values) for key, values in sorted(entries.items())}
+    checksum = compute_checksum(serialisable)
+    payload = {
+        "__meta__": {
+            "checksum": checksum,
+            "entries": len(serialisable),
+        },
+        "entries": serialisable,
+    }
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    with path.open("w", encoding="utf8") as handle:
+        json.dump(payload, handle, ensure_ascii=False, indent=2, sort_keys=True)
+
+    return CacheSnapshot(entries=serialisable, checksum=checksum)
+
+
+__all__ = ["CacheEntries", "CacheSnapshot", "compute_checksum", "load_cache", "write_cache"]

glitchlings/lexicon/data/default_vector_cache.json

@@ -0,0 +1,82 @@
+{
+  "alpha": [
+    "beta",
+    "gamma",
+    "delta"
+  ],
+  "beta": [
+    "alpha",
+    "gamma",
+    "delta"
+  ],
+  "delta": [
+    "alpha",
+    "beta",
+    "gamma"
+  ],
+  "fast": [
+    "rapid",
+    "swift",
+    "speedy",
+    "brisk"
+  ],
+  "gamma": [
+    "alpha",
+    "beta",
+    "delta"
+  ],
+  "happy": [
+    "glad",
+    "joyful",
+    "content",
+    "upbeat"
+  ],
+  "quick": [
+    "swift",
+    "rapid",
+    "speedy",
+    "nimble"
+  ],
+  "quickly": [
+    "swiftly",
+    "rapidly",
+    "promptly",
+    "speedily"
+  ],
+  "sing": [
+    "croon",
+    "serenade",
+    "vocalize",
+    "perform"
+  ],
+  "slow": [
+    "sluggish",
+    "leisurely",
+    "unhurried",
+    "gradual"
+  ],
+  "songs": [
+    "tracks",
+    "melodies",
+    "ballads",
+    "tunes"
+  ],
+  "text": [
+    "passage",
+    "copy",
+    "script",
+    "narrative"
+  ],
+  "they": [
+    "those people",
+    "those individuals",
+    "the group",
+    "those folks"
+  ],
+  "words": [
+    "terms",
+    "phrases",
+    "lexicon",
+    "vocabulary"
+  ]
+}