glitchlings 0.2.1__cp312-cp312-win_amd64.whl

glitchlings/zoo/jargoyle.py

@@ -0,0 +1,275 @@
+import random
+import re
+from collections.abc import Iterable
+from dataclasses import dataclass
+from typing import Any, Literal, cast
+
+import nltk
+from nltk.corpus.reader import WordNetCorpusReader
+from nltk.data import find
+
+from .core import AttackWave, Glitchling
+
+try:  # pragma: no cover - exercised when the namespace package is present
+    from nltk.corpus import wordnet as _WORDNET_MODULE
+except ModuleNotFoundError:  # pragma: no cover - triggered on modern NLTK installs
+    _WORDNET_MODULE = None
+
+_WORDNET_HANDLE: WordNetCorpusReader | Any | None = _WORDNET_MODULE
+
+_wordnet_ready = False
+
+
+def _load_wordnet_reader() -> WordNetCorpusReader:
+    """Return a WordNet corpus reader from the downloaded corpus files."""
+
+    try:
+        root = find("corpora/wordnet")
+    except LookupError:
+        try:
+            zip_root = find("corpora/wordnet.zip")
+        except LookupError as exc:
+            raise RuntimeError(
+                "The NLTK WordNet corpus is not installed; run `nltk.download('wordnet')`."
+            ) from exc
+        root = zip_root.join("wordnet/")
+
+    return WordNetCorpusReader(root, None)
+
+
+def _wordnet(force_refresh: bool = False) -> WordNetCorpusReader | Any:
+    """Retrieve the active WordNet handle, rebuilding it on demand."""
+
+    global _WORDNET_HANDLE
+
+    if force_refresh:
+        _WORDNET_HANDLE = _WORDNET_MODULE
+
+    if _WORDNET_HANDLE is not None:
+        return _WORDNET_HANDLE
+
+    _WORDNET_HANDLE = _load_wordnet_reader()
+    return _WORDNET_HANDLE
+
+
+def ensure_wordnet() -> None:
+    """Ensure the WordNet corpus is available before use."""
+
+    global _wordnet_ready
+    if _wordnet_ready:
+        return
+
+    resource = _wordnet()
+
+    try:
+        resource.ensure_loaded()
+    except LookupError:
+        nltk.download("wordnet", quiet=True)
+        try:
+            resource = _wordnet(force_refresh=True)
+            resource.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
+
+
+# Backwards compatibility for callers relying on the previous private helper name.
+_ensure_wordnet = ensure_wordnet
+
+
+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()
+    wordnet = _wordnet()
+    synonyms: set[str] = set()
+    for pos_tag in parts_of_speech:
+        synsets = wordnet.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()
+    wordnet = _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 wordnet.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", "ensure_wordnet", "jargoyle"]

glitchlings/zoo/mim1c.py

@@ -0,0 +1,89 @@
+from collections.abc import Collection
+import random
+from typing import Literal
+
+from confusable_homoglyphs import confusables
+
+from .core import AttackOrder, AttackWave, Glitchling
+
+
+def swap_homoglyphs(
+    text: str,
+    replacement_rate: float = 0.02,
+    classes: list[str] | Literal["all"] | None = None,
+    banned_characters: Collection[str] | 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.
+    - banned_characters: Characters that must never appear as replacements.
+    - 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)
+    banned_set = set(banned_characters or ())
+    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 banned_set:
+            options = [opt for opt in options if opt not in banned_set]
+        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,
+        banned_characters: Collection[str] | 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,
+            banned_characters=banned_characters,
+        )
+
+
+mim1c = Mim1c()
+
+
+__all__ = ["Mim1c", "mim1c"]

glitchlings/zoo/redactyl.py

@@ -0,0 +1,128 @@
+import re
+import random
+
+from .core import Glitchling, AttackWave
+
+FULL_BLOCK = "█"
+
+
+try:
+    from glitchlings._zoo_rust import redact_words as _redact_words_rust
+except ImportError:  # pragma: no cover - compiled extension not present
+    _redact_words_rust = None
+
+
+def _python_redact_words(
+    text: str,
+    *,
+    replacement_char: str,
+    redaction_rate: float,
+    merge_adjacent: bool,
+    rng: random.Random,
+) -> str:
+    """Redact random words by replacing their characters.
+
+    Parameters
+    - text: Input text.
+    - replacement_char: The character to use for redaction (default FULL_BLOCK).
+    - redaction_rate: Max proportion of words to redact (default 0.05).
+    - merge_adjacent: If True, merges adjacent redactions across intervening non-word chars.
+    - seed: Seed used if `rng` not provided (default 151).
+    - rng: Optional RNG; overrides seed.
+    """
+    # Preserve exact spacing and punctuation by using regex
+    tokens = re.split(r"(\s+)", text)
+    word_indices = [i for i, token in enumerate(tokens) if i % 2 == 0 and token.strip()]
+    if not word_indices:
+        raise ValueError("Cannot redact words because the input text contains no redactable words.")
+    num_to_redact = max(1, int(len(word_indices) * redaction_rate))
+
+    # Sample from the indices of actual words
+    indices_to_redact = rng.sample(word_indices, k=num_to_redact)
+    indices_to_redact.sort()
+
+    for i in indices_to_redact:
+        if i >= len(tokens):
+            break
+
+        word = tokens[i]
+        if not word or word.isspace():  # Skip empty or whitespace
+            continue
+
+        # Check if word has trailing punctuation
+        match = re.match(r"^(\W*)(.*?)(\W*)$", word)
+        if match:
+            prefix, core, suffix = match.groups()
+            tokens[i] = f"{prefix}{replacement_char * len(core)}{suffix}"
+        else:
+            tokens[i] = f"{replacement_char * len(word)}"
+
+    text = "".join(tokens)
+
+    if merge_adjacent:
+        text = re.sub(
+            rf"{replacement_char}\W+{replacement_char}",
+            lambda m: replacement_char * (len(m.group(0)) - 1),
+            text,
+        )
+
+    return text
+
+
+def redact_words(
+    text: str,
+    replacement_char: str = FULL_BLOCK,
+    redaction_rate: float = 0.05,
+    merge_adjacent: bool = False,
+    seed: int = 151,
+    rng: random.Random | None = None,
+) -> str:
+    """Redact random words by replacing their characters."""
+
+    if rng is None:
+        rng = random.Random(seed)
+
+    if _redact_words_rust is not None:
+        return _redact_words_rust(
+            text,
+            replacement_char,
+            redaction_rate,
+            merge_adjacent,
+            rng,
+        )
+
+    return _python_redact_words(
+        text,
+        replacement_char=replacement_char,
+        redaction_rate=redaction_rate,
+        merge_adjacent=merge_adjacent,
+        rng=rng,
+    )
+
+
+class Redactyl(Glitchling):
+    """Glitchling that redacts words with block characters."""
+
+    def __init__(
+        self,
+        *,
+        replacement_char: str = FULL_BLOCK,
+        redaction_rate: float = 0.05,
+        merge_adjacent: bool = False,
+        seed: int = 151,
+    ) -> None:
+        super().__init__(
+            name="Redactyl",
+            corruption_function=redact_words,
+            scope=AttackWave.WORD,
+            seed=seed,
+            replacement_char=replacement_char,
+            redaction_rate=redaction_rate,
+            merge_adjacent=merge_adjacent,
+        )
+
+
+redactyl = Redactyl()
+
+
+__all__ = ["Redactyl", "redactyl"]

glitchlings/zoo/reduple.py

@@ -0,0 +1,100 @@
+import re
+import random
+
+from .core import Glitchling, AttackWave
+
+try:
+    from glitchlings._zoo_rust import reduplicate_words as _reduplicate_words_rust
+except ImportError:  # pragma: no cover - compiled extension not present
+    _reduplicate_words_rust = None
+
+
+def _python_reduplicate_words(
+    text: str,
+    *,
+    reduplication_rate: float,
+    rng: random.Random,
+) -> str:
+    """Randomly reduplicate words in the text.
+
+    Parameters
+    - text: Input text.
+    - reduplication_rate: Max proportion of words to reduplicate (default 0.05).
+    - seed: Optional seed if `rng` not provided.
+    - rng: Optional RNG; overrides seed.
+
+    Notes
+    - Preserves spacing and punctuation by tokenizing with separators.
+    - Deterministic when run with a fixed seed or via Gaggle.
+    """
+    # Preserve exact spacing and punctuation by using regex
+    tokens = re.split(r"(\s+)", text)  # Split but keep separators
+
+    for i in range(0, len(tokens), 2):  # Every other token is a word
+        if i >= len(tokens):
+            break
+
+        word = tokens[i]
+        if not word or word.isspace():  # Skip empty or whitespace
+            continue
+
+        # Only consider actual words for reduplication
+        if rng.random() < reduplication_rate:
+            # Check if word has trailing punctuation
+            match = re.match(r"^(\W*)(.*?)(\W*)$", word)
+            if match:
+                prefix, core, suffix = match.groups()
+                # Reduplicate with a space: "word" -> "word word"
+                tokens[i] = f"{prefix}{core} {core}{suffix}"
+            else:
+                tokens[i] = f"{word} {word}"
+    return "".join(tokens)
+
+
+def reduplicate_words(
+    text: str,
+    reduplication_rate: float = 0.05,
+    seed: int | None = None,
+    rng: random.Random | None = None,
+) -> str:
+    """Randomly reduplicate words in the text.
+
+    Falls back to the Python implementation when the optional Rust
+    extension is unavailable.
+    """
+
+    if rng is None:
+        rng = random.Random(seed)
+
+    if _reduplicate_words_rust is not None:
+        return _reduplicate_words_rust(text, reduplication_rate, rng)
+
+    return _python_reduplicate_words(
+        text,
+        reduplication_rate=reduplication_rate,
+        rng=rng,
+    )
+
+
+class Reduple(Glitchling):
+    """Glitchling that repeats words to simulate stuttering speech."""
+
+    def __init__(
+        self,
+        *,
+        reduplication_rate: float = 0.05,
+        seed: int | None = None,
+    ) -> None:
+        super().__init__(
+            name="Reduple",
+            corruption_function=reduplicate_words,
+            scope=AttackWave.WORD,
+            seed=seed,
+            reduplication_rate=reduplication_rate,
+        )
+
+
+reduple = Reduple()
+
+
+__all__ = ["Reduple", "reduple"]

glitchlings/zoo/rushmore.py

@@ -0,0 +1,104 @@
+import math
+import random
+import re
+
+from .core import Glitchling, AttackWave
+
+try:
+    from glitchlings._zoo_rust import delete_random_words as _delete_random_words_rust
+except ImportError:  # pragma: no cover - compiled extension not present
+    _delete_random_words_rust = None
+
+
+def _python_delete_random_words(
+    text: str,
+    *,
+    max_deletion_rate: float,
+    rng: random.Random,
+) -> str:
+    """Delete random words from the input text while preserving whitespace."""
+
+    tokens = re.split(r"(\s+)", text)  # Split but keep separators for later rejoin
+
+    candidate_indices: list[int] = []
+    for i in range(2, len(tokens), 2):  # Every other token is a word, skip the first word
+        word = tokens[i]
+        if not word or word.isspace():
+            continue
+
+        candidate_indices.append(i)
+
+    allowed_deletions = min(
+        len(candidate_indices), math.floor(len(candidate_indices) * max_deletion_rate)
+    )
+    if allowed_deletions <= 0:
+        return text
+
+    deletions = 0
+    for i in candidate_indices:
+        if rng.random() < max_deletion_rate:
+            word = tokens[i]
+            match = re.match(r"^(\W*)(.*?)(\W*)$", word)
+            if match:
+                prefix, _, suffix = match.groups()
+                tokens[i] = f"{prefix.strip()}{suffix.strip()}"
+            else:
+                tokens[i] = ""
+
+            deletions += 1
+            if deletions >= allowed_deletions:
+                break
+
+    text = "".join(tokens)
+    text = re.sub(r"\s+([.,;:])", r"\1", text)
+    text = re.sub(r"\s{2,}", " ", text).strip()
+
+    return text
+
+
+def delete_random_words(
+    text: str,
+    max_deletion_rate: float = 0.01,
+    seed: int | None = None,
+    rng: random.Random | None = None,
+) -> str:
+    """Delete random words from the input text.
+
+    Uses the optional Rust implementation when available.
+    """
+
+    if rng is None:
+        rng = random.Random(seed)
+
+    if _delete_random_words_rust is not None:
+        return _delete_random_words_rust(text, max_deletion_rate, rng)
+
+    return _python_delete_random_words(
+        text,
+        max_deletion_rate=max_deletion_rate,
+        rng=rng,
+    )
+
+
+class Rushmore(Glitchling):
+    """Glitchling that deletes words to simulate missing information."""
+
+    def __init__(
+        self,
+        *,
+        max_deletion_rate: float = 0.01,
+        seed: int | None = None,
+    ) -> None:
+        super().__init__(
+            name="Rushmore",
+            corruption_function=delete_random_words,
+            scope=AttackWave.WORD,
+            seed=seed,
+            max_deletion_rate=max_deletion_rate,
+        )
+
+
+rushmore = Rushmore()
+
+
+__all__ = ["Rushmore", "rushmore"]