glitchlings 0.1.1__py3-none-any.whl → 0.1.3__py3-none-any.whl

glitchlings/zoo/core.py

@@ -0,0 +1,230 @@
+"""Core data structures used to model glitchlings and their interactions."""
+
+import inspect
+import random
+from enum import IntEnum, auto
+from hashlib import blake2s
+from typing import Any, Protocol
+
+from datasets import Dataset
+
+
+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
+        if key == "seed":
+            self.reset_rng(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.
+        try:
+            signature = inspect.signature(self.corruption_function)
+        except (TypeError, ValueError):
+            signature = None
+
+        expects_rng = False
+        if signature is not None:
+            expects_rng = "rng" in signature.parameters
+
+        if expects_rng:
+            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:
+                value = row[column]
+                if isinstance(value, list):
+                    row[column] = [self.corrupt(item) for item in value]
+                else:
+                    row[column] = self.corrupt(value)
+            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."""
+        def _int_to_bytes(value: int) -> bytes:
+            if value == 0:
+                return b"\x00"
+
+            abs_value = abs(value)
+            length = max(1, (abs_value.bit_length() + 7) // 8)
+
+            if value < 0:
+                while True:
+                    try:
+                        return value.to_bytes(length, "big", signed=True)
+                    except OverflowError:
+                        length += 1
+
+            return abs_value.to_bytes(length, "big", signed=False)
+
+        hasher = blake2s(digest_size=8)
+        hasher.update(_int_to_bytes(master_seed))
+        hasher.update(b"\x00")
+        hasher.update(glitchling_name.encode("utf-8"))
+        hasher.update(b"\x00")
+        hasher.update(_int_to_bytes(index))
+        return int.from_bytes(hasher.digest(), "big")
+
+    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"]

{zoo → glitchlings/zoo}/mim1c.py

@@ -1,62 +1,79 @@
-from typing import Literal
-from .core import Glitchling, AttackWave, AttackOrder
-import random
-from confusable_homoglyphs import confusables
-
-
-def swap_homoglyphs(
-    text: str,
-    replacement_rate: float = 0.02,
-    classes: list[str] | Literal["all"] | None = None,
-    seed: int | None = None,
-    rng: random.Random | None = None,
-) -> str:
-    """Replace characters with visually confusable homoglyphs.
-
-    Parameters
-    - text: Input text.
-    - replacement_rate: Max proportion of eligible characters to replace (default 0.02).
-    - classes: Restrict replacements to these Unicode script classes (default ["LATIN","GREEK","CYRILLIC"]). Use "all" to allow any.
-    - seed: Optional seed if `rng` not provided.
-    - rng: Optional RNG; overrides seed.
-
-    Notes
-    - Only replaces characters present in confusables.confusables_data with single-codepoint alternatives.
-    - Maintains determinism by shuffling candidates and sampling via the provided RNG.
-    """
-    if rng is None:
-        rng = random.Random(seed)
-
-    if classes is None:
-        classes = ["LATIN", "GREEK", "CYRILLIC"]
-
-    target_chars = [char for char in text if char.isalnum()]
-    confusable_chars = [
-        char for char in target_chars if char in confusables.confusables_data
-    ]
-    num_replacements = int(len(confusable_chars) * replacement_rate)
-    done = 0
-    rng.shuffle(confusable_chars)
-    for char in confusable_chars:
-        if done >= num_replacements:
-            break
-        options = [
-            o["c"] for o in confusables.confusables_data[char] if len(o["c"]) == 1
-        ]
-        if classes != "all":
-            options = [opt for opt in options if confusables.alias(opt) in classes]
-        if not options:
-            continue
-        text = text.replace(char, rng.choice(options), 1)
-        done += 1
-    return text
-
-
-mim1c = Glitchling(
-    name="Mim1c",
-    corruption_function=swap_homoglyphs,
-    scope=AttackWave.CHARACTER,
-    order=AttackOrder.LAST,
-    replacement_rate=0.02,
-    classes=["LATIN", "GREEK", "CYRILLIC"],
-)
+from typing import Literal
+from .core import Glitchling, AttackWave, AttackOrder
+import random
+from confusable_homoglyphs import confusables
+
+
+def swap_homoglyphs(
+    text: str,
+    replacement_rate: float = 0.02,
+    classes: list[str] | Literal["all"] | None = None,
+    seed: int | None = None,
+    rng: random.Random | None = None,
+) -> str:
+    """Replace characters with visually confusable homoglyphs.
+
+    Parameters
+    - text: Input text.
+    - replacement_rate: Max proportion of eligible characters to replace (default 0.02).
+    - classes: Restrict replacements to these Unicode script classes (default ["LATIN","GREEK","CYRILLIC"]). Use "all" to allow any.
+    - seed: Optional seed if `rng` not provided.
+    - rng: Optional RNG; overrides seed.
+
+    Notes
+    - Only replaces characters present in confusables.confusables_data with single-codepoint alternatives.
+    - Maintains determinism by shuffling candidates and sampling via the provided RNG.
+    """
+    if rng is None:
+        rng = random.Random(seed)
+
+    if classes is None:
+        classes = ["LATIN", "GREEK", "CYRILLIC"]
+
+    target_chars = [char for char in text if char.isalnum()]
+    confusable_chars = [
+        char for char in target_chars if char in confusables.confusables_data
+    ]
+    num_replacements = int(len(confusable_chars) * replacement_rate)
+    done = 0
+    rng.shuffle(confusable_chars)
+    for char in confusable_chars:
+        if done >= num_replacements:
+            break
+        options = [
+            o["c"] for o in confusables.confusables_data[char] if len(o["c"]) == 1
+        ]
+        if classes != "all":
+            options = [opt for opt in options if confusables.alias(opt) in classes]
+        if not options:
+            continue
+        text = text.replace(char, rng.choice(options), 1)
+        done += 1
+    return text
+
+
+class Mim1c(Glitchling):
+    """Glitchling that swaps characters for visually similar homoglyphs."""
+
+    def __init__(
+        self,
+        *,
+        replacement_rate: float = 0.02,
+        classes: list[str] | Literal["all"] | None = None,
+        seed: int | None = None,
+    ) -> None:
+        super().__init__(
+            name="Mim1c",
+            corruption_function=swap_homoglyphs,
+            scope=AttackWave.CHARACTER,
+            order=AttackOrder.LAST,
+            seed=seed,
+            replacement_rate=replacement_rate,
+            classes=classes,
+        )
+
+
+mim1c = Mim1c()
+
+
+__all__ = ["Mim1c", "mim1c"]