glitchlings 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

{zoo → glitchlings/zoo}/core.py

@@ -1,136 +1,190 @@
-from enum import IntEnum, auto
-from datasets import Dataset
-import random
-from typing import Any, Callable
-
-import functools as ft
-
-
-# Text levels for glitchlings, to enforce a sort order
-# Work from highest level down, because e.g.
-# duplicating a word then adding a typo is potentially different than
-# adding a typo then duplicating a word
-class AttackWave(IntEnum):
-    DOCUMENT = auto()
-    PARAGRAPH = auto()
-    SENTENCE = auto()
-    WORD = auto()
-    CHARACTER = auto()
-
-
-# Modifier for within the same attack wave
-class AttackOrder(IntEnum):
-    FIRST = auto()
-    EARLY = auto()
-    NORMAL = auto()
-    LATE = auto()
-    LAST = auto()
-
-
-class Glitchling:
-    def __init__(
-        self,
-        name: str,
-        corruption_function: Callable,
-        scope: AttackWave,
-        order: AttackOrder = AttackOrder.NORMAL,
-        seed: int | None = None,
-        **kwargs,
-    ):
-        # Each Glitchling maintains its own RNG for deterministic yet isolated behavior.
-        # If no seed is supplied, we fall back to Python's default entropy.
-        self.seed = seed
-        self.rng: random.Random = random.Random(seed)
-        self.name: str = name
-        self.corruption_function: Callable[..., str] = corruption_function
-        self.level: AttackWave = scope
-        self.order: AttackOrder = order
-        self.kwargs: dict[str, Any] = {}
-        for kw, val in kwargs.items():
-            self.set_param(kw, val)
-
-    def set_param(self, key: str, value: Any):
-        setattr(self, key, value)
-        self.kwargs[key] = value
-
-    def __corrupt(self, text, *args, **kwargs):
-        # Pass rng to underlying corruption function if it expects it.
-        if "rng" in self.corruption_function.__code__.co_varnames:
-            corrupted = self.corruption_function(text, *args, rng=self.rng, **kwargs)
-        else:
-            corrupted = self.corruption_function(text, *args, **kwargs)
-        return corrupted
-
-    def corrupt(self, text: str | list[dict]) -> str | list[dict]:
-        if isinstance(text, list):
-            text[-1]["content"] = self.__corrupt(text[-1]["content"], **self.kwargs)
-        else:
-            text = self.__corrupt(text, **self.kwargs)
-
-        return text
-
-    def corrupt_dataset(self, dataset: Dataset, columns: list[str]) -> Dataset:
-        def __corrupt_row(row):
-            for column in columns:
-                row[column] = self.corrupt(row[column])
-            return row
-
-        dataset = dataset.map(__corrupt_row)
-
-        return dataset
-
-    def __call__(self, text: str, *args, **kwds) -> str | list[dict]:
-        return self.corrupt(text, *args, **kwds)
-
-    def reset_rng(self, seed=None):
-        """Reset this glitchling's RNG to its initial seed (if one was provided)."""
-        if seed is not None:
-            self.seed = seed
-        if self.seed is not None:
-            self.rng = random.Random(self.seed)
-
-    def clone(self, seed=None) -> "Glitchling":
-        """Create a copy of this glitchling, optionally with a new seed."""
-        new_glitchling = Glitchling(
-            self.name,
-            self.corruption_function,
-            self.level,
-            self.order,
-            seed=seed if seed is not None else self.seed,
-            **self.kwargs,
-        )
-        return new_glitchling
-
-
-class Gaggle(Glitchling):
-    def __init__(self, glitchlings: list[Glitchling], seed: int = 151):
-        super().__init__("Gaggle", self.corrupt, AttackWave.DOCUMENT, seed=seed)
-        self.glitchlings: dict[AttackWave, list[Glitchling]] = {
-            level: [] for level in AttackWave
-        }
-        self.apply_order: list[Glitchling] = []
-        # Derive deterministic per-glitchling seeds from master seed if provided
-        for idx, g in enumerate(glitchlings):
-            _g = g.clone()
-            derived_seed = Gaggle.derive_seed(seed, _g.name, idx)
-            _g.reset_rng(derived_seed)
-            self.glitchlings[g.level].append(_g)
-        self.sort_glitchlings()
-
-    @staticmethod
-    def derive_seed(master_seed: int, glitchling_name: str, index: int) -> int:
-        """Derive a deterministic seed for a glitchling based on the master seed."""
-        return hash((master_seed, glitchling_name, index)) & 0xFFFFFFFF
-
-    def sort_glitchlings(self):
-        self.apply_order = [
-            g
-            for _, glitchlings in sorted(self.glitchlings.items())
-            for g in sorted(glitchlings, key=lambda x: (x.order, x.name))
-        ]
-
-    def corrupt(self, text: str) -> str:
-        corrupted = text
-        for glitchling in self.apply_order:
-            corrupted = glitchling(corrupted)
-        return corrupted
+"""Core data structures used to model glitchlings and their interactions."""
+
+from enum import IntEnum, auto
+from datasets import Dataset
+import random
+from typing import Any, Protocol
+
+
+class CorruptionCallable(Protocol):
+    """Protocol describing a callable capable of corrupting text."""
+
+    def __call__(self, text: str, *args: Any, **kwargs: Any) -> str: ...
+
+
+# Text levels for glitchlings, to enforce a sort order
+# Work from highest level down, because e.g.
+# duplicating a word then adding a typo is potentially different than
+# adding a typo then duplicating a word
+class AttackWave(IntEnum):
+    """Granularity of text that a glitchling corrupts."""
+
+    DOCUMENT = auto()
+    PARAGRAPH = auto()
+    SENTENCE = auto()
+    WORD = auto()
+    CHARACTER = auto()
+
+
+# Modifier for within the same attack wave
+class AttackOrder(IntEnum):
+    """Relative execution order for glitchlings within the same wave."""
+
+    FIRST = auto()
+    EARLY = auto()
+    NORMAL = auto()
+    LATE = auto()
+    LAST = auto()
+
+
+class Glitchling:
+    """A single text corruption agent with deterministic behaviour."""
+
+    def __init__(
+        self,
+        name: str,
+        corruption_function: CorruptionCallable,
+        scope: AttackWave,
+        order: AttackOrder = AttackOrder.NORMAL,
+        seed: int | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize a glitchling.
+
+        Args:
+            name: Human readable glitchling name.
+            corruption_function: Callable used to transform text.
+            scope: Text granularity on which the glitchling operates.
+            order: Relative ordering within the same scope.
+            seed: Optional seed for deterministic random behaviour.
+            **kwargs: Additional parameters forwarded to the corruption callable.
+        """
+
+        # Each Glitchling maintains its own RNG for deterministic yet isolated behavior.
+        # If no seed is supplied, we fall back to Python's default entropy.
+        self.seed = seed
+        self.rng: random.Random = random.Random(seed)
+        self.name: str = name
+        self.corruption_function: CorruptionCallable = corruption_function
+        self.level: AttackWave = scope
+        self.order: AttackOrder = order
+        self.kwargs: dict[str, Any] = {}
+        for kw, val in kwargs.items():
+            self.set_param(kw, val)
+
+    def set_param(self, key: str, value: Any) -> None:
+        """Persist a parameter for use by the corruption callable."""
+
+        setattr(self, key, value)
+        self.kwargs[key] = value
+
+    def __corrupt(self, text: str, *args: Any, **kwargs: Any) -> str:
+        """Execute the corruption callable, injecting the RNG when required."""
+
+        # Pass rng to underlying corruption function if it expects it.
+        if "rng" in self.corruption_function.__code__.co_varnames:
+            corrupted = self.corruption_function(text, *args, rng=self.rng, **kwargs)
+        else:
+            corrupted = self.corruption_function(text, *args, **kwargs)
+        return corrupted
+
+    def corrupt(self, text: str | list[dict[str, Any]]) -> str | list[dict[str, Any]]:
+        """Apply the corruption function to text or conversational transcripts."""
+
+        if isinstance(text, list):
+            text[-1]["content"] = self.__corrupt(text[-1]["content"], **self.kwargs)
+        else:
+            text = self.__corrupt(text, **self.kwargs)
+
+        return text
+
+    def corrupt_dataset(self, dataset: Dataset, columns: list[str]) -> Dataset:
+        """Apply corruption lazily across dataset columns."""
+
+        def __corrupt_row(row: dict[str, Any]) -> dict[str, Any]:
+            row = dict(row)
+            for column in columns:
+                row[column] = self.corrupt(row[column])
+            return row
+
+        return dataset.with_transform(__corrupt_row)
+
+    def __call__(self, text: str, *args: Any, **kwds: Any) -> str | list[dict[str, Any]]:
+        """Allow a glitchling to be invoked directly like a callable."""
+
+        return self.corrupt(text, *args, **kwds)
+
+    def reset_rng(self, seed: int | None = None) -> None:
+        """Reset the glitchling's RNG to its initial seed."""
+
+        if seed is not None:
+            self.seed = seed
+        if self.seed is not None:
+            self.rng = random.Random(self.seed)
+
+    def clone(self, seed: int | None = None) -> "Glitchling":
+        """Create a copy of this glitchling, optionally with a new seed."""
+
+        cls = self.__class__
+        filtered_kwargs = {k: v for k, v in self.kwargs.items() if k != "seed"}
+        clone_seed = seed if seed is not None else self.seed
+        if clone_seed is not None:
+            filtered_kwargs["seed"] = clone_seed
+
+        if cls is Glitchling:
+            return Glitchling(
+                self.name,
+                self.corruption_function,
+                self.level,
+                self.order,
+                **filtered_kwargs,
+            )
+
+        return cls(**filtered_kwargs)
+
+
+class Gaggle(Glitchling):
+    """A collection of glitchlings executed in a deterministic order."""
+
+    def __init__(self, glitchlings: list[Glitchling], seed: int = 151):
+        """Initialize the gaggle and derive per-glitchling RNG seeds.
+
+        Args:
+            glitchlings: Glitchlings to orchestrate.
+            seed: Master seed used to derive per-glitchling seeds.
+        """
+
+        super().__init__("Gaggle", self.corrupt, AttackWave.DOCUMENT, seed=seed)
+        self.glitchlings: dict[AttackWave, list[Glitchling]] = {
+            level: [] for level in AttackWave
+        }
+        self.apply_order: list[Glitchling] = []
+        # Derive deterministic per-glitchling seeds from master seed if provided
+        for idx, g in enumerate(glitchlings):
+            _g = g.clone()
+            derived_seed = Gaggle.derive_seed(seed, _g.name, idx)
+            _g.reset_rng(derived_seed)
+            self.glitchlings[g.level].append(_g)
+        self.sort_glitchlings()
+
+    @staticmethod
+    def derive_seed(master_seed: int, glitchling_name: str, index: int) -> int:
+        """Derive a deterministic seed for a glitchling based on the master seed."""
+        return hash((master_seed, glitchling_name, index)) & 0xFFFFFFFF
+
+    def sort_glitchlings(self) -> None:
+        """Sort glitchlings by wave then order to produce application order."""
+
+        self.apply_order = [
+            g
+            for _, glitchlings in sorted(self.glitchlings.items())
+            for g in sorted(glitchlings, key=lambda x: (x.order, x.name))
+        ]
+
+    def corrupt(self, text: str) -> str:
+        """Apply each glitchling to the provided text sequentially."""
+
+        corrupted = text
+        for glitchling in self.apply_order:
+            corrupted = glitchling(corrupted)
+        return corrupted

glitchlings/zoo/jargoyle.py

@@ -0,0 +1,225 @@
+import random
+import re
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import Any, Literal, cast
+
+import nltk
+from nltk.corpus import wordnet as wn
+from .core import Glitchling, AttackWave
+
+_wordnet_ready = False
+
+
+def _ensure_wordnet() -> None:
+    """Ensure the WordNet corpus is available before use."""
+
+    global _wordnet_ready
+    if _wordnet_ready:
+        return
+
+    try:
+        wn.ensure_loaded()
+    except LookupError:
+        nltk.download("wordnet", quiet=True)
+        try:
+            wn.ensure_loaded()
+        except LookupError as exc:  # pragma: no cover - only triggered when download fails
+            raise RuntimeError(
+                "Unable to load NLTK WordNet corpus for the jargoyle glitchling."
+            ) from exc
+
+    _wordnet_ready = True
+
+
+PartOfSpeech = Literal["n", "v", "a", "r"]
+PartOfSpeechInput = PartOfSpeech | Iterable[PartOfSpeech] | Literal["any"]
+NormalizedPartsOfSpeech = tuple[PartOfSpeech, ...]
+
+_VALID_POS: tuple[PartOfSpeech, ...] = ("n", "v", "a", "r")
+
+
+def _split_token(token: str) -> tuple[str, str, str]:
+    """Split a token into leading punctuation, core word, and trailing punctuation."""
+
+    match = re.match(r"^(\W*)(.*?)(\W*)$", token)
+    if not match:
+        return "", token, ""
+    prefix, core, suffix = match.groups()
+    return prefix, core, suffix
+
+
+def _normalize_parts_of_speech(part_of_speech: PartOfSpeechInput) -> NormalizedPartsOfSpeech:
+    """Coerce user input into a tuple of valid WordNet POS tags."""
+
+    if isinstance(part_of_speech, str):
+        lowered = part_of_speech.lower()
+        if lowered == "any":
+            return _VALID_POS
+        if lowered not in _VALID_POS:
+            raise ValueError(
+                "part_of_speech must be one of 'n', 'v', 'a', 'r', or 'any'"
+            )
+        return (cast(PartOfSpeech, lowered),)
+
+    normalized: list[PartOfSpeech] = []
+    for pos in part_of_speech:
+        if pos not in _VALID_POS:
+            raise ValueError(
+                "part_of_speech entries must be one of 'n', 'v', 'a', or 'r'"
+            )
+        if pos not in normalized:
+            normalized.append(pos)
+    if not normalized:
+        raise ValueError("part_of_speech iterable may not be empty")
+    return tuple(normalized)
+
+
+@dataclass(frozen=True)
+class CandidateInfo:
+    """Metadata for a candidate token that may be replaced."""
+
+    prefix: str
+    core_word: str
+    suffix: str
+    parts_of_speech: NormalizedPartsOfSpeech
+
+
+def _collect_synonyms(
+    word: str, parts_of_speech: NormalizedPartsOfSpeech
+) -> list[str]:
+    """Gather deterministic synonym candidates for the supplied word."""
+
+    normalized_word = word.lower()
+    synonyms: set[str] = set()
+    for pos_tag in parts_of_speech:
+        synsets = wn.synsets(word, pos=pos_tag)
+        if not synsets:
+            continue
+
+        for synset in synsets:
+            lemmas_list = [lemma.name() for lemma in cast(Any, synset).lemmas()]
+            if not lemmas_list:
+                continue
+
+            filtered = []
+            for lemma_str in lemmas_list:
+                cleaned = lemma_str.replace("_", " ")
+                if cleaned.lower() != normalized_word:
+                    filtered.append(cleaned)
+
+            if filtered:
+                synonyms.update(filtered)
+                break
+
+        if synonyms:
+            break
+
+    return sorted(synonyms)
+
+
+def substitute_random_synonyms(
+    text: str,
+    replacement_rate: float = 0.1,
+    part_of_speech: PartOfSpeechInput = "n",
+    seed: int | None = None,
+    rng: random.Random | None = None,
+) -> str:
+    """Replace words with random WordNet synonyms.
+
+    Parameters
+    - text: Input text.
+    - replacement_rate: Max proportion of candidate words to replace (default 0.1).
+    - part_of_speech: WordNet POS tag(s) to target. Accepts "n", "v", "a", "r",
+      any iterable of those tags, or "any" to include all four.
+    - rng: Optional RNG instance used for deterministic sampling.
+    - seed: Optional seed if `rng` not provided.
+
+    Determinism
+    - Candidates collected in left-to-right order; no set() reordering.
+    - Replacement positions chosen via rng.sample.
+    - Synonyms sorted before rng.choice to fix ordering.
+    - For each POS, the first synset containing alternate lemmas is used for stability.
+    """
+    _ensure_wordnet()
+
+    active_rng: random.Random
+    if rng is not None:
+        active_rng = rng
+    else:
+        active_rng = random.Random(seed)
+
+    target_pos = _normalize_parts_of_speech(part_of_speech)
+
+    # Split but keep whitespace separators so we can rebuild easily
+    tokens = re.split(r"(\s+)", text)
+
+    # Collect indices of candidate tokens (even positions 0,2,.. are words given our split design)
+    candidate_indices: list[int] = []
+    candidate_metadata: dict[int, CandidateInfo] = {}
+    for idx, tok in enumerate(tokens):
+        if idx % 2 == 0 and tok and not tok.isspace():
+            prefix, core_word, suffix = _split_token(tok)
+            if not core_word:
+                continue
+
+            available_pos: NormalizedPartsOfSpeech = tuple(
+                pos for pos in target_pos if wn.synsets(core_word, pos=pos)
+            )
+            if available_pos:
+                candidate_indices.append(idx)
+                candidate_metadata[idx] = CandidateInfo(
+                    prefix=prefix,
+                    core_word=core_word,
+                    suffix=suffix,
+                    parts_of_speech=available_pos,
+                )
+
+    if not candidate_indices:
+        return text
+
+    max_replacements = int(len(candidate_indices) * replacement_rate)
+    if max_replacements <= 0:
+        return text
+
+    # Choose which positions to replace deterministically via rng.sample
+    replace_positions = active_rng.sample(candidate_indices, k=max_replacements)
+    # Process in ascending order to avoid affecting later indices
+    replace_positions.sort()
+
+    for pos in replace_positions:
+        metadata = candidate_metadata[pos]
+        synonyms = _collect_synonyms(metadata.core_word, metadata.parts_of_speech)
+        if not synonyms:
+            continue
+
+        replacement = active_rng.choice(synonyms)
+        tokens[pos] = f"{metadata.prefix}{replacement}{metadata.suffix}"
+
+    return "".join(tokens)
+
+
+class Jargoyle(Glitchling):
+    """Glitchling that swaps words with random WordNet synonyms."""
+
+    def __init__(
+        self,
+        *,
+        replacement_rate: float = 0.1,
+        part_of_speech: PartOfSpeechInput = "n",
+        seed: int | None = None,
+    ) -> None:
+        super().__init__(
+            name="Jargoyle",
+            corruption_function=substitute_random_synonyms,
+            scope=AttackWave.WORD,
+            seed=seed,
+            replacement_rate=replacement_rate,
+            part_of_speech=part_of_speech,
+        )
+
+
+jargoyle = Jargoyle()
+
+
+__all__ = ["Jargoyle", "jargoyle"]