glitchlings 0.1.0__py3-none-any.whl

main.py

@@ -0,0 +1,6 @@
+def main():
+    print("Hello from glitchlings!")
+
+
+if __name__ == "__main__":
+    main()

pyproject.toml

@@ -0,0 +1,74 @@
+[project]
+name = "glitchlings"
+version = "0.1.0"
+description = "Monsters for your language games."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "confusable-homoglyphs>=3.3.1",
+    "datasets>=4.0.0",
+    "jellyfish>=1.2.0",
+    "nltk>=3.9.1",
+]
+
+authors = [
+    { name = "osoleve" }
+]
+keywords = ["nlp", "text", "adversarial", "data", "evaluation", "glitch"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Testing",
+]
+
+[project.license]
+file = "LICENSE"
+
+[project.urls]
+Homepage = "https://github.com/osoleve/glitchlings"
+Repository = "https://github.com/osoleve/glitchlings.git"
+Issues = "https://github.com/osoleve/glitchlings/issues"
+Changelog = "https://github.com/osoleve/glitchlings/releases"
+
+[project.scripts]
+glitchlings = "glitchlings.main:main"
+
+[project.optional-dependencies]
+prime = [
+    "verifiers>=0.1.3.post0",
+]
+dev = [
+    "pytest>=8.0.0",
+]
+
+[build-system]
+requires = ["hatchling>=1.18"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build]
+exclude = [
+    "**/__pycache__/**",
+    ".git/**",
+    ".venv/**",
+]
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+    "**/__pycache__/**",
+    ".git/**",
+    ".venv/**",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["."]
+exclude = [
+    "tests/**",
+    "tests",
+    "**/__pycache__/**",
+]

util/__init__.py

@@ -0,0 +1,73 @@
+import difflib
+
+SAMPLE_TEXT = "One morning, when Gregor Samsa woke from troubled dreams, he found himself transformed in his bed into a horrible vermin. He lay on his armour-like back, and if he lifted his head a little he could see his brown belly, slightly domed and divided by arches into stiff sections. The bedding was hardly able to cover it and seemed ready to slide off any moment. His many legs, pitifully thin compared with the size of the rest of him, waved about helplessly as he looked."
+
+
+def string_diffs(a: str, b: str):
+    """
+    Compare two strings using SequenceMatcher and return
+    grouped adjacent opcodes (excluding 'equal' tags).
+
+    Each element is a tuple: (tag, a_text, b_text).
+    """
+    sm = difflib.SequenceMatcher(None, a, b)
+    ops = []
+    buffer = []
+
+    for tag, i1, i2, j1, j2 in sm.get_opcodes():
+        if tag == "equal":
+            # flush any buffered operations before skipping
+            if buffer:
+                ops.append(buffer)
+                buffer = []
+            continue
+
+        # append operation to buffer
+        buffer.append((tag, a[i1:i2], b[j1:j2]))
+
+    # flush trailing buffer
+    if buffer:
+        ops.append(buffer)
+
+    return ops
+
+
+_KEYNEIGHBORS = {
+    "CURATOR_QWERTY": {
+        "a": [*"qwsz"],
+        "b": [*"vghn  "],
+        "c": [*"xdfv  "],
+        "d": [*"serfcx"],
+        "e": [*"wsdrf34"],
+        "f": [*"drtgvc"],
+        "g": [*"ftyhbv"],
+        "h": [*"gyujnb"],
+        "i": [*"ujko89"],
+        "j": [*"huikmn"],
+        "k": [*"jilom,"],
+        "l": [*"kop;.,"],
+        "m": [*"njk,  "],
+        "n": [*"bhjm  "],
+        "o": [*"iklp90"],
+        "p": [*"o0-[;l"],
+        "q": [*"was 12"],
+        "r": [*"edft45"],
+        "s": [*"awedxz"],
+        "t": [*"r56ygf"],
+        "u": [*"y78ijh"],
+        "v": [*"cfgb  "],
+        "w": [*"q23esa"],
+        "x": [*"zsdc  "],
+        "y": [*"t67uhg"],
+        "z": [*"asx"],
+    }
+}
+
+
+class KeyNeighbors:
+    def __init__(self):
+        for layout_name, layout in _KEYNEIGHBORS.items():
+            setattr(self, layout_name, layout)
+
+
+KEYNEIGHBORS = KeyNeighbors()

zoo/__init__.py

@@ -0,0 +1,50 @@
+from .typogre import typogre
+from .mim1c import mim1c
+from .jargoyle import jargoyle
+from .reduple import reduple
+from .rushmore import rushmore
+from .redactyl import redactyl
+from .scannequin import scannequin
+from .core import Glitchling, Gaggle
+
+__all__ = [
+    "typogre",
+    "mim1c",
+    "jargoyle",
+    "reduple",
+    "rushmore",
+    "redactyl",
+    "scannequin",
+    "Glitchling",
+    "Gaggle",
+    "summon",
+]
+
+
+def summon(glitchlings: list[str | Glitchling], seed: int = 151) -> Gaggle:
+    """Summon glitchlings by name (using defaults) or instance (to change parameters)."""
+    available = {
+        g.name.lower(): g
+        for g in [
+            typogre,
+            mim1c,
+            jargoyle,
+            reduple,
+            rushmore,
+            redactyl,
+            scannequin,
+        ]
+    }
+    summoned = []
+    for entry in glitchlings:
+        if isinstance(entry, Glitchling):
+            summoned.append(entry)
+            continue
+
+        g = available.get(entry.lower())
+        if g:
+            summoned.append(g)
+        else:
+            raise ValueError(f"Glitchling '{entry}' not found.")
+
+    return Gaggle(summoned, seed=seed)

zoo/core.py

@@ -0,0 +1,136 @@
+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

zoo/jargoyle.py

@@ -0,0 +1,89 @@
+import random
+from typing import Literal, Any, cast
+import nltk
+import re
+from nltk.corpus import wordnet as wn
+from .core import Glitchling, AttackWave
+
+nltk.download("wordnet", quiet=True)
+
+
+def substitute_random_synonyms(
+    text: str,
+    replacement_rate: float = 0.1,
+    part_of_speech: Literal["n", "v", "a", "r"] = wn.NOUN,
+    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 to target. One of wn.NOUN (default), wn.VERB, wn.ADJ, wn.ADV.
+    - 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.
+    - Only first synset is used for stability.
+    """
+    if rng is None and seed is not None:
+        rng = random.Random(seed)
+    elif rng is None:
+        rng = random.Random()
+
+    # 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] = []
+    for idx, tok in enumerate(tokens):
+        if idx % 2 == 0 and tok and not tok.isspace():
+            if wn.synsets(tok, pos=part_of_speech):
+                candidate_indices.append(idx)
+
+    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 = rng.sample(candidate_indices, k=max_replacements)
+    # Process in ascending order to avoid affecting later indices
+    replace_positions.sort()
+
+    for pos in replace_positions:
+        word = tokens[pos]
+        synsets = wn.synsets(word, pos=part_of_speech)
+        if not synsets:
+            continue
+        synset0: Any = synsets[0]
+        lemmas_list = [lemma.name() for lemma in cast(Any, synset0).lemmas()]
+        if not lemmas_list:
+            continue
+        # Normalize & dedupe deterministically
+        synonyms = sorted(
+            {
+                lemma_str.replace("_", " ")
+                for lemma_str in lemmas_list
+                if lemma_str.lower() != word.lower()
+            }
+        )
+        if not synonyms:
+            continue
+        replacement = rng.choice(synonyms)
+        tokens[pos] = replacement
+
+    return "".join(tokens)
+
+
+jargoyle = Glitchling(
+    name="Jargoyle",
+    corruption_function=substitute_random_synonyms,
+    scope=AttackWave.WORD,
+)

zoo/mim1c.py

@@ -0,0 +1,62 @@
+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"],
+)

zoo/redactyl.py

@@ -0,0 +1,73 @@
+import re
+import random
+from .core import Glitchling, AttackWave
+
+FULL_BLOCK = "█"
+
+
+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.
+
+    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.
+    """
+    if rng is None:
+        rng = random.Random(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()]
+    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
+
+
+redactyl = Glitchling(
+    name="Redactyl",
+    corruption_function=redact_words,
+    replacement_char=FULL_BLOCK,
+    redaction_rate=0.05,
+    scope=AttackWave.WORD,
+    seed=151,
+)

zoo/reduple.py

@@ -0,0 +1,54 @@
+import re
+import random
+from .core import Glitchling, AttackWave
+
+
+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.
+
+    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.
+    """
+    if rng is None:
+        rng = random.Random(seed)
+
+    # 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)
+
+
+reduple = Glitchling(
+    name="Reduple", corruption_function=reduplicate_words, scope=AttackWave.WORD
+)

zoo/rushmore.py

@@ -0,0 +1,53 @@
+import random
+import re
+from .core import Glitchling, AttackWave
+
+
+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.
+
+    Parameters
+    - text: The input text.
+    - max_deletion_rate: The maximum proportion of words to delete (default 0.01).
+    - seed: Optional seed if `rng` not provided.
+    - rng: Optional RNG; overrides seed.
+    """
+    if rng is None:
+        rng = random.Random(seed)
+
+    # Preserve exact spacing and punctuation by using regex
+    tokens = re.split(r"(\s+)", text)  # Split but keep separators
+
+    for i in range(
+        2, len(tokens), 2
+    ):  # Every other token is a word, but skip the first 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 deletion
+    if rng.random() < max_deletion_rate:
+        # Check if word has trailing punctuation
+        match = re.match(r"^(\W*)(.*?)(\W*)$", word)
+        if match:
+            prefix, _, suffix = match.groups()
+            tokens[i] = f"{prefix.strip()}{suffix.strip()}"
+        else:
+            tokens[i] = ""
+
+    text = "".join(tokens)
+    text = re.sub(r"\s+([.,;:])", r"\1", text)
+    text = re.sub(r"\s{2,}", " ", text).strip()
+
+    return text
+
+
+rushmore = Glitchling("rushmore", delete_random_words, scope=AttackWave.WORD)