glitchlings 0.4.5__cp311-cp311-win_amd64.whl

glitchlings/zoo/redactyl.py

@@ -0,0 +1,193 @@
+import random
+import re
+from typing import Any, cast
+
+from ._rate import resolve_rate
+from ._rust_extensions import get_rust_operation
+from ._sampling import weighted_sample_without_replacement
+from ._text_utils import (
+    WordToken,
+    collect_word_tokens,
+    split_preserving_whitespace,
+)
+from .core import AttackWave, Glitchling
+
+FULL_BLOCK = "█"
+
+# Load Rust-accelerated operation if available
+_redact_words_rust = get_rust_operation("redact_words")
+
+
+def _python_redact_words(
+    text: str,
+    *,
+    replacement_char: str,
+    rate: float,
+    merge_adjacent: bool,
+    rng: random.Random,
+    unweighted: bool = False,
+) -> str:
+    """Redact random words by replacing their characters.
+
+    Parameters
+    ----------
+    - text: Input text.
+    - replacement_char: The character to use for redaction (default FULL_BLOCK).
+    - rate: Max proportion of words to redact (default 0.05).
+    - merge_adjacent: If True, merges adjacent redactions across intervening non-word chars.
+    - rng: RNG used for sampling decisions.
+    - unweighted: When True, sample words uniformly instead of by length.
+
+    """
+    tokens = split_preserving_whitespace(text)
+    word_tokens = collect_word_tokens(tokens)
+    if not word_tokens:
+        raise ValueError("Cannot redact words because the input text contains no redactable words.")
+
+    population = [token.index for token in word_tokens]
+    weights = [1.0 if unweighted else float(token.core_length) for token in word_tokens]
+
+    clamped_rate = max(0.0, min(rate, 1.0))
+    raw_quota = len(population) * clamped_rate
+    num_to_redact = int(raw_quota)
+    if clamped_rate > 0.0:
+        num_to_redact = max(1, num_to_redact)
+    num_to_redact = min(num_to_redact, len(population))
+    if num_to_redact <= 0:
+        return "".join(tokens)
+
+    indices_to_redact = weighted_sample_without_replacement(
+        population,
+        weights,
+        k=num_to_redact,
+        rng=rng,
+    )
+    indices_to_redact.sort()
+
+    token_by_index: dict[int, WordToken] = {token.index: token for token in word_tokens}
+
+    for i in indices_to_redact:
+        if i >= len(tokens):
+            break
+
+        token = token_by_index.get(i)
+        if token is None:
+            continue
+
+        prefix, core, suffix = token.prefix, token.core, token.suffix
+        tokens[i] = f"{prefix}{replacement_char * len(core)}{suffix}"
+
+    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,
+    rate: float | None = None,
+    merge_adjacent: bool = False,
+    seed: int = 151,
+    rng: random.Random | None = None,
+    *,
+    redaction_rate: float | None = None,
+    unweighted: bool = False,
+) -> str:
+    """Redact random words by replacing their characters."""
+    effective_rate = resolve_rate(
+        rate=rate,
+        legacy_value=redaction_rate,
+        default=0.025,
+        legacy_name="redaction_rate",
+    )
+
+    if rng is None:
+        rng = random.Random(seed)
+
+    clamped_rate = max(0.0, min(effective_rate, 1.0))
+    unweighted_flag = bool(unweighted)
+
+    use_rust = _redact_words_rust is not None and isinstance(merge_adjacent, bool)
+
+    if use_rust:
+        assert _redact_words_rust is not None  # Type narrowing for mypy
+        return cast(
+            str,
+            _redact_words_rust(
+                text,
+                replacement_char,
+                clamped_rate,
+                merge_adjacent,
+                unweighted_flag,
+                rng,
+            ),
+        )
+
+    return _python_redact_words(
+        text,
+        replacement_char=replacement_char,
+        rate=clamped_rate,
+        merge_adjacent=merge_adjacent,
+        rng=rng,
+        unweighted=unweighted_flag,
+    )
+
+
+class Redactyl(Glitchling):
+    """Glitchling that redacts words with block characters."""
+
+    def __init__(
+        self,
+        *,
+        replacement_char: str = FULL_BLOCK,
+        rate: float | None = None,
+        redaction_rate: float | None = None,
+        merge_adjacent: bool = False,
+        seed: int = 151,
+        unweighted: bool = False,
+    ) -> None:
+        self._param_aliases = {"redaction_rate": "rate"}
+        effective_rate = resolve_rate(
+            rate=rate,
+            legacy_value=redaction_rate,
+            default=0.025,
+            legacy_name="redaction_rate",
+        )
+        super().__init__(
+            name="Redactyl",
+            corruption_function=redact_words,
+            scope=AttackWave.WORD,
+            seed=seed,
+            replacement_char=replacement_char,
+            rate=effective_rate,
+            merge_adjacent=merge_adjacent,
+            unweighted=unweighted,
+        )
+
+    def pipeline_operation(self) -> dict[str, Any] | None:
+        replacement_char = self.kwargs.get("replacement_char")
+        rate = self.kwargs.get("rate")
+        merge_adjacent = self.kwargs.get("merge_adjacent")
+        if replacement_char is None or rate is None or merge_adjacent is None:
+            return None
+        unweighted = bool(self.kwargs.get("unweighted", False))
+        return {
+            "type": "redact",
+            "replacement_char": str(replacement_char),
+            "redaction_rate": float(rate),
+            "merge_adjacent": bool(merge_adjacent),
+            "unweighted": unweighted,
+        }
+
+
+redactyl = Redactyl()
+
+
+__all__ = ["Redactyl", "redactyl"]

glitchlings/zoo/reduple.py

@@ -0,0 +1,148 @@
+import random
+from typing import Any, cast
+
+from ._rate import resolve_rate
+from ._rust_extensions import get_rust_operation
+from ._text_utils import WordToken, collect_word_tokens, split_preserving_whitespace
+from .core import AttackWave, Glitchling
+
+# Load Rust-accelerated operation if available
+_reduplicate_words_rust = get_rust_operation("reduplicate_words")
+
+
+def _python_reduplicate_words(
+    text: str,
+    *,
+    rate: float,
+    rng: random.Random,
+    unweighted: bool = False,
+) -> str:
+    """Randomly reduplicate words in the text.
+
+    Parameters
+    ----------
+    - text: Input text.
+    - rate: Max proportion of words to reduplicate (default 0.05).
+    - rng: RNG used for sampling decisions.
+    - unweighted: When True, sample words uniformly instead of length-weighted.
+
+    Notes
+    -----
+    - Preserves spacing and punctuation by tokenizing with separators.
+    - Deterministic when run with a fixed seed or via Gaggle.
+
+    """
+    tokens = split_preserving_whitespace(text)
+    word_tokens = collect_word_tokens(tokens)
+
+    weighted_tokens: list[tuple[int, float, WordToken]] = []
+    for token in word_tokens:
+        weight = 1.0 if unweighted else 1.0 / float(token.core_length)
+        weighted_tokens.append((token.index, weight, token))
+
+    if not weighted_tokens:
+        return "".join(tokens)
+
+    effective_rate = max(rate, 0.0)
+    if effective_rate <= 0.0:
+        return "".join(tokens)
+
+    mean_weight = sum(weight for _, weight, _ in weighted_tokens) / len(weighted_tokens)
+
+    for index, weight, token in weighted_tokens:
+        if effective_rate >= 1.0:
+            probability = 1.0
+        else:
+            if mean_weight <= 0.0:
+                probability = effective_rate
+            else:
+                probability = min(1.0, effective_rate * (weight / mean_weight))
+        if rng.random() >= probability:
+            continue
+
+        prefix, core, suffix = token.prefix, token.core, token.suffix
+        tokens[index] = f"{prefix}{core} {core}{suffix}"
+    return "".join(tokens)
+
+
+def reduplicate_words(
+    text: str,
+    rate: float | None = None,
+    seed: int | None = None,
+    rng: random.Random | None = None,
+    *,
+    reduplication_rate: float | None = None,
+    unweighted: bool = False,
+) -> str:
+    """Randomly reduplicate words in the text.
+
+    Falls back to the Python implementation when the optional Rust
+    extension is unavailable.
+    """
+    effective_rate = resolve_rate(
+        rate=rate,
+        legacy_value=reduplication_rate,
+        default=0.01,
+        legacy_name="reduplication_rate",
+    )
+
+    if rng is None:
+        rng = random.Random(seed)
+
+    clamped_rate = max(0.0, effective_rate)
+    unweighted_flag = bool(unweighted)
+
+    if _reduplicate_words_rust is not None:
+        return cast(str, _reduplicate_words_rust(text, clamped_rate, unweighted_flag, rng))
+
+    return _python_reduplicate_words(
+        text,
+        rate=clamped_rate,
+        rng=rng,
+        unweighted=unweighted_flag,
+    )
+
+
+class Reduple(Glitchling):
+    """Glitchling that repeats words to simulate stuttering speech."""
+
+    def __init__(
+        self,
+        *,
+        rate: float | None = None,
+        reduplication_rate: float | None = None,
+        seed: int | None = None,
+        unweighted: bool = False,
+    ) -> None:
+        self._param_aliases = {"reduplication_rate": "rate"}
+        effective_rate = resolve_rate(
+            rate=rate,
+            legacy_value=reduplication_rate,
+            default=0.01,
+            legacy_name="reduplication_rate",
+        )
+        super().__init__(
+            name="Reduple",
+            corruption_function=reduplicate_words,
+            scope=AttackWave.WORD,
+            seed=seed,
+            rate=effective_rate,
+            unweighted=unweighted,
+        )
+
+    def pipeline_operation(self) -> dict[str, Any] | None:
+        rate = self.kwargs.get("rate")
+        if rate is None:
+            return None
+        unweighted = bool(self.kwargs.get("unweighted", False))
+        return {
+            "type": "reduplicate",
+            "reduplication_rate": float(rate),
+            "unweighted": unweighted,
+        }
+
+
+reduple = Reduple()
+
+
+__all__ = ["Reduple", "reduple"]

glitchlings/zoo/rushmore.py

@@ -0,0 +1,153 @@
+import math
+import random
+import re
+from typing import Any, cast
+
+from ._rate import resolve_rate
+from ._rust_extensions import get_rust_operation
+from ._text_utils import WordToken, collect_word_tokens, split_preserving_whitespace
+from .core import AttackWave, Glitchling
+
+# Load Rust-accelerated operation if available
+_delete_random_words_rust = get_rust_operation("delete_random_words")
+
+
+def _python_delete_random_words(
+    text: str,
+    *,
+    rate: float,
+    rng: random.Random,
+    unweighted: bool = False,
+) -> str:
+    """Delete random words from the input text while preserving whitespace."""
+    effective_rate = max(rate, 0.0)
+    if effective_rate <= 0.0:
+        return text
+
+    tokens = split_preserving_whitespace(text)
+    word_tokens = collect_word_tokens(tokens, skip_first_word=True)
+
+    weighted_tokens: list[tuple[int, float, WordToken]] = []
+    for token in word_tokens:
+        weight = 1.0 if unweighted else 1.0 / float(token.core_length)
+        weighted_tokens.append((token.index, weight, token))
+
+    if not weighted_tokens:
+        return text
+
+    allowed_deletions = min(len(weighted_tokens), math.floor(len(weighted_tokens) * effective_rate))
+    if allowed_deletions <= 0:
+        return text
+
+    mean_weight = sum(weight for _, weight, _ in weighted_tokens) / len(weighted_tokens)
+
+    deletions = 0
+    for index, weight, token in weighted_tokens:
+        if deletions >= allowed_deletions:
+            break
+
+        if effective_rate >= 1.0:
+            probability = 1.0
+        else:
+            if mean_weight <= 0.0:
+                probability = effective_rate
+            else:
+                probability = min(1.0, effective_rate * (weight / mean_weight))
+        if rng.random() >= probability:
+            continue
+
+        prefix = token.prefix.strip()
+        suffix = token.suffix.strip()
+        tokens[index] = f"{prefix}{suffix}"
+
+        deletions += 1
+
+    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,
+    rate: float | None = None,
+    seed: int | None = None,
+    rng: random.Random | None = None,
+    *,
+    max_deletion_rate: float | None = None,
+    unweighted: bool = False,
+) -> str:
+    """Delete random words from the input text.
+
+    Uses the optional Rust implementation when available.
+    """
+    effective_rate = resolve_rate(
+        rate=rate,
+        legacy_value=max_deletion_rate,
+        default=0.01,
+        legacy_name="max_deletion_rate",
+    )
+
+    if rng is None:
+        rng = random.Random(seed)
+
+    clamped_rate = max(0.0, effective_rate)
+    unweighted_flag = bool(unweighted)
+
+    if _delete_random_words_rust is not None:
+        return cast(str, _delete_random_words_rust(text, clamped_rate, unweighted_flag, rng))
+
+    return _python_delete_random_words(
+        text,
+        rate=clamped_rate,
+        rng=rng,
+        unweighted=unweighted_flag,
+    )
+
+
+class Rushmore(Glitchling):
+    """Glitchling that deletes words to simulate missing information."""
+
+    def __init__(
+        self,
+        *,
+        rate: float | None = None,
+        max_deletion_rate: float | None = None,
+        seed: int | None = None,
+        unweighted: bool = False,
+    ) -> None:
+        self._param_aliases = {"max_deletion_rate": "rate"}
+        effective_rate = resolve_rate(
+            rate=rate,
+            legacy_value=max_deletion_rate,
+            default=0.01,
+            legacy_name="max_deletion_rate",
+        )
+        super().__init__(
+            name="Rushmore",
+            corruption_function=delete_random_words,
+            scope=AttackWave.WORD,
+            seed=seed,
+            rate=effective_rate,
+            unweighted=unweighted,
+        )
+
+    def pipeline_operation(self) -> dict[str, Any] | None:
+        rate = self.kwargs.get("rate")
+        if rate is None:
+            rate = self.kwargs.get("max_deletion_rate")
+        if rate is None:
+            return None
+        unweighted = bool(self.kwargs.get("unweighted", False))
+        return {
+            "type": "delete",
+            "max_deletion_rate": float(rate),
+            "unweighted": unweighted,
+        }
+
+
+rushmore = Rushmore()
+
+
+__all__ = ["Rushmore", "rushmore"]

glitchlings/zoo/scannequin.py

@@ -0,0 +1,171 @@
+import random
+import re
+from typing import Any, cast
+
+from ._ocr_confusions import load_confusion_table
+from ._rate import resolve_rate
+from ._rust_extensions import get_rust_operation
+from .core import AttackOrder, AttackWave, Glitchling
+
+# Load Rust-accelerated operation if available
+_ocr_artifacts_rust = get_rust_operation("ocr_artifacts")
+
+
+def _python_ocr_artifacts(
+    text: str,
+    *,
+    rate: float,
+    rng: random.Random,
+) -> str:
+    """Introduce OCR-like artifacts into text.
+
+    Parameters
+    ----------
+    - text: Input text to corrupt.
+    - rate: Max proportion of eligible confusion matches to replace (default 0.02).
+    - seed: Optional seed if `rng` not provided.
+    - rng: Optional RNG; overrides seed.
+
+    Notes
+    -----
+    - Uses a curated set of common OCR confusions (rn↔m, cl↔d, O↔0, l/I/1, etc.).
+    - Collects all non-overlapping candidate spans in reading order, then samples
+      a subset deterministically with the provided RNG.
+    - Replacements can change length (e.g., m→rn), so edits are applied from left
+      to right using precomputed spans to avoid index drift.
+
+    """
+    if not text:
+        return text
+
+    # Keep the confusion definitions in a shared data file so both the Python
+    # and Rust implementations stay in sync.
+    confusion_table = load_confusion_table()
+
+    # Build candidate matches as (start, end, choices)
+    candidates: list[tuple[int, int, list[str]]] = []
+
+    # To avoid double-counting overlapping patterns (like 'l' inside 'li'),
+    # we will scan longer patterns first by sorting by len(src) desc.
+    for src, choices in sorted(confusion_table, key=lambda p: -len(p[0])):
+        pattern = re.escape(src)
+        for m in re.finditer(pattern, text):
+            start, end = m.span()
+            candidates.append((start, end, choices))
+
+    if not candidates:
+        return text
+
+    # Decide how many to replace
+    k = int(len(candidates) * rate)
+    if k <= 0:
+        return text
+
+    # Shuffle deterministically and select non-overlapping k spans
+    rng.shuffle(candidates)
+    chosen: list[tuple[int, int, str]] = []
+    occupied: list[tuple[int, int]] = []
+
+    def overlaps(a: tuple[int, int], b: tuple[int, int]) -> bool:
+        return not (a[1] <= b[0] or b[1] <= a[0])
+
+    for start, end, choices in candidates:
+        if len(chosen) >= k:
+            break
+        span = (start, end)
+        if any(overlaps(span, occ) for occ in occupied):
+            continue
+        replacement = rng.choice(choices)
+        chosen.append((start, end, replacement))
+        occupied.append(span)
+
+    if not chosen:
+        return text
+
+    # Apply edits from left to right
+    chosen.sort(key=lambda t: t[0])
+    out_parts = []
+    cursor = 0
+    for start, end, rep in chosen:
+        if cursor < start:
+            out_parts.append(text[cursor:start])
+        out_parts.append(rep)
+        cursor = end
+    if cursor < len(text):
+        out_parts.append(text[cursor:])
+
+    return "".join(out_parts)
+
+
+def ocr_artifacts(
+    text: str,
+    rate: float | None = None,
+    seed: int | None = None,
+    rng: random.Random | None = None,
+    *,
+    error_rate: float | None = None,
+) -> str:
+    """Introduce OCR-like artifacts into text.
+
+    Prefers the Rust implementation when available.
+    """
+    if not text:
+        return text
+
+    effective_rate = resolve_rate(
+        rate=rate,
+        legacy_value=error_rate,
+        default=0.02,
+        legacy_name="error_rate",
+    )
+
+    if rng is None:
+        rng = random.Random(seed)
+
+    clamped_rate = max(0.0, effective_rate)
+
+    if _ocr_artifacts_rust is not None:
+        return cast(str, _ocr_artifacts_rust(text, clamped_rate, rng))
+
+    return _python_ocr_artifacts(text, rate=clamped_rate, rng=rng)
+
+
+class Scannequin(Glitchling):
+    """Glitchling that simulates OCR artifacts using common confusions."""
+
+    def __init__(
+        self,
+        *,
+        rate: float | None = None,
+        error_rate: float | None = None,
+        seed: int | None = None,
+    ) -> None:
+        self._param_aliases = {"error_rate": "rate"}
+        effective_rate = resolve_rate(
+            rate=rate,
+            legacy_value=error_rate,
+            default=0.02,
+            legacy_name="error_rate",
+        )
+        super().__init__(
+            name="Scannequin",
+            corruption_function=ocr_artifacts,
+            scope=AttackWave.CHARACTER,
+            order=AttackOrder.LATE,
+            seed=seed,
+            rate=effective_rate,
+        )
+
+    def pipeline_operation(self) -> dict[str, Any] | None:
+        rate = self.kwargs.get("rate")
+        if rate is None:
+            rate = self.kwargs.get("error_rate")
+        if rate is None:
+            return None
+        return {"type": "ocr", "error_rate": float(rate)}
+
+
+scannequin = Scannequin()
+
+
+__all__ = ["Scannequin", "scannequin"]