glitchlings 1.0.0__cp313-cp313-win_amd64.whl

glitchlings/constants.py

@@ -0,0 +1,139 @@
+"""Centralized defaults and shared configuration constants."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+# Global configuration defaults
+DEFAULT_ATTACK_SEED = 151
+DEFAULT_CONFIG_PATH = Path(__file__).with_name("config.toml")
+
+# Character-level glitchling default rates
+DEFAULT_TYPOGRE_RATE = 0.02
+DEFAULT_TYPOGRE_KEYBOARD = "CURATOR_QWERTY"
+DEFAULT_TYPOGRE_MOTOR_WEIGHTING = "uniform"
+DEFAULT_MIM1C_RATE = 0.02
+DEFAULT_ZEEDUB_RATE = 0.02
+
+# Scannequin OCR simulation defaults
+# Base rate for character-level OCR confusions
+DEFAULT_SCANNEQUIN_RATE = 0.02
+# Burst model parameters (Kanungo et al., 1994)
+DEFAULT_SCANNEQUIN_BURST_ENTER = 0.0  # Disabled by default
+DEFAULT_SCANNEQUIN_BURST_EXIT = 0.3
+DEFAULT_SCANNEQUIN_BURST_MULTIPLIER = 3.0
+# Document-level bias parameters (UNLV-ISRI, 1995)
+DEFAULT_SCANNEQUIN_BIAS_K = 0  # Disabled by default
+DEFAULT_SCANNEQUIN_BIAS_BETA = 2.0
+# Whitespace error parameters (Smith, 2007)
+DEFAULT_SCANNEQUIN_SPACE_DROP_RATE = 0.0  # Disabled by default
+DEFAULT_SCANNEQUIN_SPACE_INSERT_RATE = 0.0  # Disabled by default
+
+# Scannequin quality presets based on UNLV-ISRI test regimes (Rice et al., 1995)
+# Each preset maps to (rate, burst_enter, burst_exit, burst_multiplier, bias_k, bias_beta,
+#                      space_drop_rate, space_insert_rate)
+SCANNEQUIN_PRESETS: dict[str, tuple[float, float, float, float, int, float, float, float]] = {
+    # Clean 300dpi scan - minimal errors, good quality baseline
+    "clean_300dpi": (0.01, 0.0, 0.3, 3.0, 0, 2.0, 0.0, 0.0),
+    # Newspaper scan - moderate errors, some burst, stroke-loss bias
+    "newspaper": (0.03, 0.05, 0.3, 2.5, 3, 2.0, 0.005, 0.002),
+    # Fax quality - high errors, strong burst, heavy l/1/I confusion bias
+    "fax": (0.06, 0.1, 0.2, 3.5, 5, 3.0, 0.02, 0.01),
+    # Third-generation photocopy - very degraded, long burst runs
+    "photocopy_3rd_gen": (0.08, 0.15, 0.15, 4.0, 5, 3.5, 0.03, 0.015),
+}
+
+# Word-level glitchling default rates
+DEFAULT_WHEREWOLF_RATE = 0.02
+DEFAULT_WHEREWOLF_WEIGHTING = "flat"
+DEFAULT_JARGOYLE_RATE = 0.01
+DEFAULT_REDACTYL_RATE = 0.025
+DEFAULT_REDACTYL_CHAR = "\u2588"  # █ FULL BLOCK
+
+# Rushmore default rates per mode
+RUSHMORE_DEFAULT_RATES = {
+    "delete": 0.01,
+    "duplicate": 0.01,
+    "swap": 0.5,
+}
+
+# Mim1c Unicode script class defaults
+MIM1C_DEFAULT_CLASSES: tuple[str, ...] = ("LATIN", "GREEK", "CYRILLIC", "COMMON")
+
+# Mim1c homoglyph mode defaults
+# Available modes: "single_script", "mixed_script", "compatibility", "aggressive"
+DEFAULT_MIM1C_MODE = "mixed_script"
+DEFAULT_MIM1C_MAX_CONSECUTIVE = 3
+
+# Zeedub zero-width character palettes by visibility mode
+ZEEDUB_DEFAULT_ZERO_WIDTHS: tuple[str, ...] = (
+    "\u200b",  # ZERO WIDTH SPACE
+    "\u200c",  # ZERO WIDTH NON-JOINER
+    "\u200d",  # ZERO WIDTH JOINER
+    "\ufeff",  # BYTE ORDER MARK (zero-width no-break space)
+)
+
+# Glyphless mode palette (true invisibles only)
+ZEEDUB_GLYPHLESS_PALETTE: tuple[str, ...] = (
+    "\u200b",  # ZERO WIDTH SPACE
+    "\u200c",  # ZERO WIDTH NON-JOINER
+    "\u200d",  # ZERO WIDTH JOINER
+    "\ufeff",  # BYTE ORDER MARK
+    "\u2060",  # WORD JOINER
+    "\u034f",  # COMBINING GRAPHEME JOINER
+)
+
+# With joiners palette (includes variation selectors VS1-VS16)
+ZEEDUB_WITH_JOINERS_PALETTE: tuple[str, ...] = ZEEDUB_GLYPHLESS_PALETTE + tuple(
+    chr(c)
+    for c in range(0xFE00, 0xFE10)  # VS1-VS16
+)
+
+# Semi-visible palette (includes thin spaces)
+ZEEDUB_SEMI_VISIBLE_PALETTE: tuple[str, ...] = ZEEDUB_WITH_JOINERS_PALETTE + (
+    "\u200a",  # HAIR SPACE
+    "\u2009",  # THIN SPACE
+    "\u202f",  # NARROW NO-BREAK SPACE
+)
+
+# Zeedub defaults
+DEFAULT_ZEEDUB_VISIBILITY = "glyphless"
+DEFAULT_ZEEDUB_PLACEMENT = "random"
+DEFAULT_ZEEDUB_MAX_CONSECUTIVE = 4
+
+__all__ = [
+    "DEFAULT_ATTACK_SEED",
+    "DEFAULT_CONFIG_PATH",
+    "DEFAULT_WHEREWOLF_RATE",
+    "DEFAULT_WHEREWOLF_WEIGHTING",
+    "DEFAULT_JARGOYLE_RATE",
+    "DEFAULT_MIM1C_RATE",
+    "DEFAULT_REDACTYL_CHAR",
+    "DEFAULT_REDACTYL_RATE",
+    # Scannequin defaults
+    "DEFAULT_SCANNEQUIN_RATE",
+    "DEFAULT_SCANNEQUIN_BURST_ENTER",
+    "DEFAULT_SCANNEQUIN_BURST_EXIT",
+    "DEFAULT_SCANNEQUIN_BURST_MULTIPLIER",
+    "DEFAULT_SCANNEQUIN_BIAS_K",
+    "DEFAULT_SCANNEQUIN_BIAS_BETA",
+    "DEFAULT_SCANNEQUIN_SPACE_DROP_RATE",
+    "DEFAULT_SCANNEQUIN_SPACE_INSERT_RATE",
+    "SCANNEQUIN_PRESETS",
+    # Typogre defaults
+    "DEFAULT_TYPOGRE_KEYBOARD",
+    "DEFAULT_TYPOGRE_MOTOR_WEIGHTING",
+    "DEFAULT_TYPOGRE_RATE",
+    "DEFAULT_ZEEDUB_RATE",
+    "DEFAULT_ZEEDUB_VISIBILITY",
+    "DEFAULT_ZEEDUB_PLACEMENT",
+    "DEFAULT_ZEEDUB_MAX_CONSECUTIVE",
+    "MIM1C_DEFAULT_CLASSES",
+    "DEFAULT_MIM1C_MODE",
+    "DEFAULT_MIM1C_MAX_CONSECUTIVE",
+    "RUSHMORE_DEFAULT_RATES",
+    "ZEEDUB_DEFAULT_ZERO_WIDTHS",
+    "ZEEDUB_GLYPHLESS_PALETTE",
+    "ZEEDUB_WITH_JOINERS_PALETTE",
+    "ZEEDUB_SEMI_VISIBLE_PALETTE",
+]

glitchlings/dev/__init__.py

@@ -0,0 +1,3 @@
+"""Developer-facing utilities for maintaining the Glitchlings repository."""
+
+__all__ = []

glitchlings/dev/docs.py

@@ -0,0 +1,45 @@
+"""Developer helpers for refreshing generated documentation assets."""
+
+from __future__ import annotations
+
+import runpy
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[3]
+DOCS_DIR = REPO_ROOT / "docs"
+
+
+def _run_script(path: Path) -> None:
+    if not path.exists():
+        raise FileNotFoundError(f"Documentation helper not found: {path}")
+    runpy.run_path(str(path))
+
+
+def refresh_cli_reference() -> None:
+    """Regenerate the CLI reference docs page."""
+    _run_script(DOCS_DIR / "build_cli_reference.py")
+
+
+def refresh_monster_manual() -> None:
+    """Regenerate the Monster Manual."""
+    _run_script(DOCS_DIR / "build_monster_manual.py")
+
+
+def refresh_gallery() -> None:
+    """Regenerate the glitchling gallery page."""
+    _run_script(DOCS_DIR / "build_glitchling_gallery.py")
+
+
+def refresh_all() -> None:
+    """Regenerate CLI reference, Monster Manual, and gallery docs in one call."""
+    refresh_cli_reference()
+    refresh_monster_manual()
+    refresh_gallery()
+
+
+def main() -> None:
+    refresh_all()
+
+
+if __name__ == "__main__":
+    main()

glitchlings/dlc/__init__.py

@@ -0,0 +1,21 @@
+"""Optional DLC integrations for Glitchlings.
+
+This module provides explicit wrapper classes for integrating glitchlings
+with popular ML frameworks:
+
+- :class:`~glitchlings.dlc.huggingface.GlitchedDataset`: Wrap Hugging Face datasets
+- :class:`~glitchlings.dlc.pytorch.GlitchedDataLoader`: Wrap PyTorch data loaders
+- :class:`~glitchlings.dlc.pytorch_lightning.GlitchedLightningDataModule`: Wrap
+  Lightning data modules
+- :class:`~glitchlings.dlc.gutenberg.GlitchenbergAPI`: Wrap Project Gutenberg API
+- :class:`~glitchlings.dlc.langchain.GlitchedRunnable`: Wrap LangChain runnables
+- :class:`~glitchlings.dlc.nemo.GlitchlingColumnGenerator`: NeMo DataDesigner plugin
+
+Example:
+    >>> from glitchlings.dlc.huggingface import GlitchedDataset
+    >>> from datasets import Dataset
+    >>> dataset = Dataset.from_dict({"text": ["hello", "world"]})
+    >>> corrupted = GlitchedDataset(dataset, "typogre", column="text")
+"""
+
+__all__: list[str] = []

glitchlings/dlc/_shared.py

@@ -0,0 +1,300 @@
+"""Shared utilities for DLC integrations."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any, cast
+
+from ..util.transcripts import is_transcript
+from ..zoo.core import Gaggle
+
+
+def resolve_columns(dataset: Any, columns: Sequence[str] | None) -> list[str]:
+    """Identify which dataset columns should be corrupted."""
+    available = set(getattr(dataset, "column_names", ()))
+
+    if columns is not None:
+        missing = sorted(set(columns) - available)
+        if missing:
+            missing_str = ", ".join(missing)
+            raise ValueError(f"Columns not found in dataset: {missing_str}")
+        return list(columns)
+
+    for candidate in ("prompt", "question"):
+        if candidate in available:
+            return [candidate]
+
+    try:
+        dataset_length = len(dataset)
+    except TypeError:
+        preview_rows: list[dict[str, Any]]
+        take_fn = getattr(dataset, "take", None)
+        if callable(take_fn):
+            preview_rows = list(take_fn(1))
+        else:
+            iterator = iter(dataset)
+            try:
+                first_row = next(iterator)
+            except StopIteration:
+                preview_rows = []
+            else:
+                preview_rows = [first_row]
+        sample = dict(preview_rows[0]) if preview_rows else {}
+    else:
+        sample = dataset[0] if dataset_length else {}
+    inferred = [
+        name for name in getattr(dataset, "column_names", ()) if isinstance(sample.get(name), str)
+    ]
+
+    if inferred:
+        return inferred
+
+    raise ValueError("Unable to determine which dataset columns to corrupt.")
+
+
+def normalize_column_spec(
+    columns: str | int | Sequence[str | int] | None,
+) -> list[str | int] | None:
+    """Normalize a column specification into a list of keys or indices.
+
+    Args:
+        columns: Column specification as a single value, sequence of values, or None.
+
+    Returns:
+        A list of column identifiers, or None if input was None.
+
+    Raises:
+        ValueError: If an empty sequence is provided.
+    """
+    if columns is None:
+        return None
+
+    if isinstance(columns, (str, int)):
+        return [columns]
+
+    normalized = list(columns)
+    if not normalized:
+        raise ValueError("At least one column must be specified")
+    return normalized
+
+
+def is_textual_candidate(value: Any) -> bool:
+    """Return ``True`` when ``value`` looks like text that glitchlings can corrupt.
+
+    Args:
+        value: The value to check for textual content.
+
+    Returns:
+        True if the value appears to be textual content.
+    """
+    if isinstance(value, str):
+        return True
+
+    if is_transcript(value, allow_empty=False, require_all_content=True):
+        return True
+
+    if isinstance(value, Sequence) and not isinstance(value, (bytes, bytearray, str)):
+        if not value:
+            return False
+        if all(isinstance(item, str) for item in value):
+            return True
+        if is_transcript(list(value), allow_empty=False, require_all_content=True):
+            return True
+
+    return False
+
+
+def corrupt_text_value(value: Any, gaggle: Gaggle) -> Any:
+    """Return ``value`` with glitchlings applied when possible.
+
+    Uses parallel Rust pipeline execution for lists of strings when all
+    glitchlings support the Rust pipeline, providing significant speedups
+    for large batches.
+
+    Args:
+        value: The value to corrupt (string, transcript, or sequence of strings).
+        gaggle: The gaggle of glitchlings to apply.
+
+    Returns:
+        The corrupted value, preserving the original type where possible.
+    """
+    if isinstance(value, str):
+        return gaggle.corrupt(value)
+
+    if is_transcript(value, allow_empty=True):
+        return gaggle.corrupt(value)
+
+    if isinstance(value, list) and value and all(isinstance(item, str) for item in value):
+        return gaggle.corrupt_batch(value)
+
+    if isinstance(value, tuple) and value and all(isinstance(item, str) for item in value):
+        return tuple(gaggle.corrupt_batch(list(value)))
+
+    return value
+
+
+def infer_batch_targets(batch: Any) -> list[str | int] | None:
+    """Infer which fields should be glitched from a representative batch.
+
+    Args:
+        batch: A batch from a DataLoader (mapping, sequence, or textual value).
+
+    Returns:
+        A list of column keys (strings) or indices (ints), or None if the batch
+        itself is textual content.
+
+    Raises:
+        ValueError: If unable to infer textual columns/indices.
+        TypeError: If the batch type is unsupported.
+    """
+    if isinstance(batch, Mapping):
+        inferred = [key for key, value in batch.items() if is_textual_candidate(value)]
+        if inferred:
+            return inferred
+        raise ValueError("Unable to infer which mapping columns contain text")
+
+    if isinstance(batch, Sequence) and not isinstance(batch, (bytes, bytearray, str)):
+        inferred_indices: list[str | int] = [
+            idx for idx, value in enumerate(batch) if is_textual_candidate(value)
+        ]
+        if inferred_indices:
+            return inferred_indices
+        raise ValueError("Unable to infer which sequence indices contain text")
+
+    if is_textual_candidate(batch):
+        return None
+
+    raise TypeError("Unsupported DataLoader batch type for glitching")
+
+
+def corrupt_batch(batch: Any, targets: list[str | int] | None, gaggle: Gaggle) -> Any:
+    """Return batch with glitchlings applied to the specified targets.
+
+    Args:
+        batch: The batch to corrupt (mapping, sequence, or textual value).
+        targets: List of column keys (strings) or indices (ints), or None to
+                 corrupt the entire batch as textual content.
+        gaggle: The gaggle of glitchlings to apply.
+
+    Returns:
+        The corrupted batch, preserving the original type.
+
+    Raises:
+        TypeError: If batch type is unsupported or targets are incompatible.
+        ValueError: If a specified target is not found in the batch.
+    """
+    if targets is None:
+        return corrupt_text_value(batch, gaggle)
+
+    if isinstance(batch, Mapping):
+        # Use copy() if available, otherwise dict()
+        if hasattr(batch, "copy"):
+            mutated = batch.copy()
+        else:
+            mutated = dict(batch)
+
+        for key in targets:
+            if not isinstance(key, str):
+                raise TypeError("Mapping batches require string column names")
+            if key not in mutated:
+                raise ValueError(f"Column '{key}' not found in DataLoader batch")
+            mutated[key] = corrupt_text_value(mutated[key], gaggle)
+        return mutated
+
+    if isinstance(batch, Sequence) and not isinstance(batch, (bytes, bytearray, str)):
+        mutated_sequence = list(batch)
+        for index in targets:
+            if not isinstance(index, int):
+                raise TypeError("Sequence batches require integer column indices")
+            try:
+                mutated_sequence[index] = corrupt_text_value(mutated_sequence[index], gaggle)
+            except IndexError as exc:  # pragma: no cover - defensive
+                raise IndexError("Column index out of range for DataLoader batch") from exc
+        if isinstance(batch, tuple):
+            return tuple(mutated_sequence)
+        return mutated_sequence
+
+    raise TypeError("Unsupported DataLoader batch type for glitching")
+
+
+class BaseGlitchedDataLoader:
+    """Proxy dataloader that glitches batches produced by the wrapped loader.
+
+    This class wraps a dataloader and applies glitchlings to specified columns
+    in each batch as it's yielded. It supports both mapping-based batches (dict-like)
+    and sequence-based batches (list/tuple-like).
+    """
+
+    def __init__(self, dataloader: Any, columns: list[str | int], gaggle: Gaggle) -> None:
+        """Initialize the glitched dataloader.
+
+        Args:
+            dataloader: The underlying dataloader to wrap.
+            columns: List of column names (strings) or indices (ints) to corrupt.
+            gaggle: The gaggle of glitchlings to apply.
+        """
+        self._dataloader = dataloader
+        self._columns = columns
+        self._gaggle = gaggle
+
+    def __iter__(self) -> Any:
+        """Yield corrupted batches from the underlying dataloader."""
+        for batch in self._dataloader:
+            yield corrupt_batch(batch, self._columns, self._gaggle)
+
+    def __len__(self) -> int:
+        """Return the number of batches in the dataloader."""
+        return len(self._dataloader)
+
+    def __getattr__(self, attribute: str) -> Any:
+        """Proxy attribute access to the underlying dataloader."""
+        return getattr(self._dataloader, attribute)
+
+
+def wrap_dataloader(dataloader: Any, columns: list[str | int], gaggle: Gaggle) -> Any:
+    """Wrap a dataloader (or nested structure) to apply glitchlings lazily.
+
+    This function recursively wraps dataloaders in nested structures (mappings,
+    lists, tuples, etc.) so that all dataloaders in the structure will yield
+    corrupted batches.
+
+    Args:
+        dataloader: The dataloader or nested structure to wrap.
+        columns: List of column names (strings) or indices (ints) to corrupt.
+        gaggle: The gaggle of glitchlings to apply.
+
+    Returns:
+        The wrapped dataloader or structure, with the same type as the input.
+    """
+    if dataloader is None:
+        return None
+
+    if isinstance(dataloader, Mapping):
+        mapping_type = cast(type[Any], dataloader.__class__)
+        return mapping_type(
+            {key: wrap_dataloader(value, columns, gaggle) for key, value in dataloader.items()}
+        )
+
+    if isinstance(dataloader, list):
+        return [wrap_dataloader(value, columns, gaggle) for value in dataloader]
+
+    if isinstance(dataloader, tuple):
+        return tuple(wrap_dataloader(value, columns, gaggle) for value in dataloader)
+
+    if isinstance(dataloader, Sequence) and not isinstance(dataloader, (str, bytes, bytearray)):
+        sequence_type = cast(type[Any], dataloader.__class__)
+        return sequence_type(wrap_dataloader(value, columns, gaggle) for value in dataloader)
+
+    return BaseGlitchedDataLoader(dataloader, columns, gaggle)
+
+
+__all__ = [
+    "BaseGlitchedDataLoader",
+    "corrupt_batch",
+    "corrupt_text_value",
+    "infer_batch_targets",
+    "is_textual_candidate",
+    "normalize_column_spec",
+    "resolve_columns",
+    "wrap_dataloader",
+]