glitchlings 0.10.2__cp312-cp312-macosx_11_0_universal2.whl

glitchlings/zoo/corrupt_dispatch.py

@@ -0,0 +1,295 @@
+"""Pure dispatch logic for Glitchling corruption operations.
+
+This module contains the deterministic, side-effect-free logic for building
+corruption plans. It separates the "what to corrupt" decision from the
+"how to corrupt" execution.
+
+**Design Philosophy:**
+
+All functions in this module are *pure* - they perform dispatch analysis
+based solely on their inputs, without side effects. They do not:
+- Invoke corruption functions
+- Modify state
+- Perform I/O
+
+The separation allows:
+- Corruption dispatch to be tested without actual corruption
+- Clear boundaries between planning and execution
+- Reasoning about what will be corrupted before execution
+
+See AGENTS.md "Functional Purity Architecture" for full details.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from ..util.transcripts import (
+    Transcript,
+    TranscriptTarget,
+    TranscriptTurn,
+    is_transcript,
+    resolve_transcript_indices,
+)
+
+# ---------------------------------------------------------------------------
+# Type Definitions
+# ---------------------------------------------------------------------------
+
+
+@dataclass(slots=True, frozen=True)
+class StringCorruptionTarget:
+    """Target specification for corrupting a plain string.
+
+    Attributes:
+        text: The string to corrupt.
+    """
+
+    text: str
+    kind: Literal["string"] = "string"
+
+
+@dataclass(slots=True, frozen=True)
+class TranscriptTurnTarget:
+    """Target specification for a single turn within a transcript.
+
+    Attributes:
+        index: Position of the turn in the transcript.
+        content: The text content to corrupt.
+    """
+
+    index: int
+    content: str
+
+
+@dataclass(slots=True, frozen=True)
+class TranscriptCorruptionTarget:
+    """Target specification for corrupting transcript turns.
+
+    Attributes:
+        turns: List of turn targets with their indices and content.
+        original_transcript: The original transcript for result assembly.
+    """
+
+    turns: tuple[TranscriptTurnTarget, ...]
+    original_transcript: Transcript
+    kind: Literal["transcript"] = "transcript"
+
+
+# Union type for corruption targets
+CorruptionTarget = StringCorruptionTarget | TranscriptCorruptionTarget
+
+
+# ---------------------------------------------------------------------------
+# Dispatch Functions
+# ---------------------------------------------------------------------------
+
+
+def resolve_corruption_target(
+    text: str | Transcript,
+    transcript_target: TranscriptTarget,
+) -> CorruptionTarget:
+    """Determine what needs to be corrupted from the input.
+
+    This is a pure function that analyzes the input and returns a structured
+    target specification. It does not perform any corruption.
+
+    Args:
+        text: Input text or transcript to analyze.
+        transcript_target: Specification for which transcript turns to target.
+
+    Returns:
+        CorruptionTarget describing what should be corrupted.
+
+    Note:
+        For backwards compatibility, lists that are not valid transcripts
+        (e.g., lists of strings) are treated as strings. The original corrupt()
+        implementation would cast such inputs to str and pass them to the
+        corruption function. This behavior is preserved to maintain compatibility
+        with dataset column transformations.
+    """
+    # Handle plain strings
+    if isinstance(text, str):
+        return StringCorruptionTarget(text=text)
+
+    # Handle transcripts (lists of dicts with "content" keys)
+    if is_transcript(text):
+        indices = resolve_transcript_indices(text, transcript_target)
+        turn_targets: list[TranscriptTurnTarget] = []
+
+        for idx in indices:
+            turn = text[idx]
+            content = turn.get("content")
+            if isinstance(content, str):
+                turn_targets.append(TranscriptTurnTarget(index=idx, content=content))
+
+        return TranscriptCorruptionTarget(
+            turns=tuple(turn_targets),
+            original_transcript=text,
+        )
+
+    # For backwards compatibility: treat other types (including lists of strings)
+    # as strings by casting. This preserves the original behavior where
+    # non-transcript lists were passed to corruption functions after casting.
+    # This handles cases like dataset column transformations where HuggingFace
+    # may batch values as lists.
+    return StringCorruptionTarget(text=str(text))
+
+
+def count_corruption_targets(target: CorruptionTarget) -> int:
+    """Count how many text segments will be corrupted.
+
+    Args:
+        target: The corruption target specification.
+
+    Returns:
+        Number of text segments that will be processed.
+    """
+    if isinstance(target, StringCorruptionTarget):
+        return 1
+    return len(target.turns)
+
+
+def extract_texts_to_corrupt(target: CorruptionTarget) -> list[str]:
+    """Extract all text strings that need to be corrupted.
+
+    This is useful for batch processing or analysis.
+
+    Args:
+        target: The corruption target specification.
+
+    Returns:
+        List of text strings to corrupt.
+    """
+    if isinstance(target, StringCorruptionTarget):
+        return [target.text]
+    return [turn.content for turn in target.turns]
+
+
+# ---------------------------------------------------------------------------
+# Result Assembly Functions
+# ---------------------------------------------------------------------------
+
+
+def assemble_string_result(
+    _target: StringCorruptionTarget,
+    corrupted: str,
+) -> str:
+    """Assemble the result for a string corruption.
+
+    Args:
+        _target: The original target (unused, included for symmetry).
+        corrupted: The corrupted text.
+
+    Returns:
+        The corrupted string.
+    """
+    return corrupted
+
+
+def assemble_transcript_result(
+    target: TranscriptCorruptionTarget,
+    corrupted_contents: dict[int, str],
+) -> Transcript:
+    """Assemble the result for a transcript corruption.
+
+    Creates a copy of the original transcript with specified turns updated.
+
+    Args:
+        target: The original target specification.
+        corrupted_contents: Mapping of turn indices to corrupted content.
+
+    Returns:
+        New transcript with corrupted turns.
+    """
+    # Create a deep copy of the transcript
+    result: list[TranscriptTurn] = [dict(turn) for turn in target.original_transcript]
+
+    # Apply corrupted content to targeted turns
+    for idx, content in corrupted_contents.items():
+        if 0 <= idx < len(result):
+            result[idx]["content"] = content
+
+    return result
+
+
+def assemble_corruption_result(
+    target: CorruptionTarget,
+    corrupted: str | dict[int, str],
+) -> str | Transcript:
+    """Assemble the final result based on target type.
+
+    This is a pure function that combines the original target structure
+    with the corrupted content.
+
+    Args:
+        target: The original corruption target.
+        corrupted: Either a single corrupted string (for StringCorruptionTarget)
+            or a mapping of indices to corrupted content (for TranscriptCorruptionTarget).
+
+    Returns:
+        The assembled result matching the input type.
+
+    Raises:
+        TypeError: If corrupted value type doesn't match target type.
+    """
+    if isinstance(target, StringCorruptionTarget):
+        if not isinstance(corrupted, str):
+            message = "String target requires corrupted string result"
+            raise TypeError(message)
+        return assemble_string_result(target, corrupted)
+
+    if isinstance(target, TranscriptCorruptionTarget):
+        if not isinstance(corrupted, dict):
+            message = "Transcript target requires corrupted content mapping"
+            raise TypeError(message)
+        return assemble_transcript_result(target, corrupted)
+
+    # Should be unreachable due to typing, but be explicit
+    message = f"Unknown target type: {type(target).__name__}"
+    raise TypeError(message)
+
+
+# ---------------------------------------------------------------------------
+# Validation Helpers
+# ---------------------------------------------------------------------------
+
+
+def validate_text_input(text: Any) -> str | Transcript:
+    """Validate that input is a supported text type.
+
+    Args:
+        text: Input to validate.
+
+    Returns:
+        The validated input.
+
+    Raises:
+        TypeError: If input is not a string or transcript.
+    """
+    if isinstance(text, str):
+        return text
+    if is_transcript(text):
+        return text
+    message = f"Expected string or transcript, got {type(text).__name__}"
+    raise TypeError(message)
+
+
+__all__ = [
+    # Target types
+    "StringCorruptionTarget",
+    "TranscriptTurnTarget",
+    "TranscriptCorruptionTarget",
+    "CorruptionTarget",
+    # Dispatch functions
+    "resolve_corruption_target",
+    "count_corruption_targets",
+    "extract_texts_to_corrupt",
+    # Result assembly
+    "assemble_string_result",
+    "assemble_transcript_result",
+    "assemble_corruption_result",
+    # Validation
+    "validate_text_input",
+]

glitchlings/zoo/hokey.py

@@ -0,0 +1,139 @@
+"""Hokey glitchling that performs expressive lengthening."""
+
+from __future__ import annotations
+
+import random
+from typing import Any, cast
+
+from glitchlings.internal.rust_ffi import hokey_rust, resolve_seed
+
+from .core import AttackOrder, AttackWave, Gaggle, PipelineOperationPayload
+from .core import Glitchling as GlitchlingBase
+
+
+def extend_vowels(
+    text: str,
+    rate: float = 0.3,
+    extension_min: int = 2,
+    extension_max: int = 5,
+    word_length_threshold: int = 6,
+    seed: int | None = None,
+    rng: random.Random | None = None,
+    base_p: float | None = None,
+) -> str:
+    """Extend expressive segments of words for emphasis.
+
+    Parameters
+    ----------
+    text : str
+        Input text to transform.
+    rate : float, optional
+        Global selection rate for candidate words.
+    extension_min : int, optional
+        Minimum number of extra repetitions for the stretch unit.
+    extension_max : int, optional
+        Maximum number of extra repetitions for the stretch unit.
+    word_length_threshold : int, optional
+        Preferred maximum alphabetic length; longer words are de-emphasised but not
+        excluded.
+    seed : int, optional
+        Deterministic seed when ``rng`` is not supplied.
+    rng : random.Random, optional
+        Random number generator to drive sampling.
+    base_p : float, optional
+        Base probability for the negative-binomial sampler (heavier tails for smaller
+        values). Defaults to ``0.45``.
+    """
+    if not text:
+        return text
+
+    base_probability = base_p if base_p is not None else 0.45
+
+    seed_value = resolve_seed(seed, rng)
+    return hokey_rust(
+        text,
+        rate,
+        extension_min,
+        extension_max,
+        word_length_threshold,
+        base_probability,
+        seed_value,
+    )
+
+
+class Hokey(GlitchlingBase):
+    """Glitchling that stretches words using linguistic heuristics."""
+
+    flavor = "Sooooo excited to meet you! We reeeeeally missed you last week."
+
+    seed: int | None
+
+    def __init__(
+        self,
+        *,
+        rate: float = 0.3,
+        extension_min: int = 2,
+        extension_max: int = 5,
+        word_length_threshold: int = 6,
+        base_p: float = 0.45,
+        seed: int | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self._master_seed: int | None = seed
+
+        def _corruption_wrapper(text: str, **kwargs: Any) -> str:
+            return extend_vowels(text, **kwargs)
+
+        super().__init__(
+            name="Hokey",
+            corruption_function=_corruption_wrapper,
+            scope=AttackWave.CHARACTER,
+            order=AttackOrder.FIRST,
+            seed=seed,
+            rate=rate,
+            extension_min=extension_min,
+            extension_max=extension_max,
+            word_length_threshold=word_length_threshold,
+            base_p=base_p,
+            **kwargs,
+        )
+
+    def pipeline_operation(self) -> PipelineOperationPayload:
+        kwargs = self.kwargs
+        rate = kwargs.get("rate")
+        extension_min = kwargs.get("extension_min")
+        extension_max = kwargs.get("extension_max")
+        word_length_threshold = kwargs.get("word_length_threshold")
+        base_p = kwargs.get("base_p")
+        return cast(
+            PipelineOperationPayload,
+            {
+                "type": "hokey",
+                "rate": 0.3 if rate is None else float(rate),
+                "extension_min": 2 if extension_min is None else int(extension_min),
+                "extension_max": 5 if extension_max is None else int(extension_max),
+                "word_length_threshold": 6
+                if word_length_threshold is None
+                else int(word_length_threshold),
+                "base_p": 0.45 if base_p is None else float(base_p),
+            },
+        )
+
+    def reset_rng(self, seed: int | None = None) -> None:
+        if seed is not None:
+            self._master_seed = seed
+            super().reset_rng(seed)
+            if self.seed is None:
+                return
+            derived = Gaggle.derive_seed(int(seed), self.name, 0)
+            self.seed = int(derived)
+            self.rng = random.Random(self.seed)
+            self.kwargs["seed"] = self.seed
+        else:
+            super().reset_rng(None)
+
+
+hokey = Hokey()
+
+
+__all__ = ["Hokey", "hokey", "extend_vowels"]

glitchlings/zoo/jargoyle.py

@@ -0,0 +1,243 @@
+"""Jargoyle glitchling: Dictionary-based word drift.
+
+Jargoyle swaps words with alternatives from bundled lexeme dictionaries.
+Multiple dictionaries are supported:
+- "colors": Color term swapping
+- "synonyms": General synonym substitution
+- "corporate": Business jargon alternatives
+- "academic": Scholarly word substitutions
+- "cyberpunk": Neon cyberpunk slang and gadgetry
+- "lovecraftian": Cosmic horror terminology
+You can also drop additional dictionaries into ``assets/lexemes`` to make
+them available without modifying the code. The backend discovers any
+``*.json`` file in that directory at runtime.
+
+Two modes are available:
+- "literal": First entry in each word's alternatives (deterministic mapping)
+- "drift": Random selection from alternatives (probabilistic)
+"""
+
+from __future__ import annotations
+
+import os
+from importlib import resources
+from pathlib import Path
+from typing import Any, Literal, cast
+
+from glitchlings.constants import DEFAULT_JARGOYLE_RATE
+from glitchlings.internal.rust_ffi import (
+    jargoyle_drift_rust,
+    list_lexeme_dictionaries_rust,
+    resolve_seed,
+)
+
+from .core import AttackOrder, AttackWave, Glitchling, PipelineOperationPayload
+
+_LEXEME_ENV_VAR = "GLITCHLINGS_LEXEME_DIR"
+
+
+def _configure_lexeme_directory() -> Path | None:
+    """Expose the bundled lexeme directory to the Rust backend via an env var."""
+
+    try:
+        lexeme_root = resources.files("glitchlings.assets.lexemes")
+    except (ModuleNotFoundError, AttributeError):
+        return None
+
+    try:
+        with resources.as_file(lexeme_root) as resolved:
+            path = Path(resolved)
+    except FileNotFoundError:
+        return None
+
+    if not path.is_dir():
+        return None
+
+    os.environ.setdefault(_LEXEME_ENV_VAR, str(path))
+    return path
+
+
+_configure_lexeme_directory()
+
+DEFAULT_LEXEMES = "synonyms"
+
+# Valid modes
+JargoyleMode = Literal["literal", "drift"]
+VALID_MODES = ("literal", "drift")
+DEFAULT_MODE: JargoyleMode = "drift"
+
+
+def _available_lexemes() -> list[str]:
+    return sorted({name.lower() for name in list_lexeme_dictionaries_rust()})
+
+
+def _validate_lexemes(name: str) -> str:
+    normalized = name.lower()
+    available = _available_lexemes()
+    if normalized not in available:
+        raise ValueError(f"Invalid lexemes '{name}'. Must be one of: {', '.join(available)}")
+    return normalized
+
+
+def _validate_mode(mode: JargoyleMode | str) -> JargoyleMode:
+    normalized = mode.lower()
+    if normalized not in VALID_MODES:
+        raise ValueError(f"Invalid mode '{mode}'. Must be one of: {', '.join(VALID_MODES)}")
+    return cast(JargoyleMode, normalized)
+
+
+VALID_LEXEMES = tuple(_available_lexemes())
+
+
+def list_lexeme_dictionaries() -> list[str]:
+    """Return the list of available lexeme dictionaries.
+
+    Returns:
+        List of dictionary names that can be used with Jargoyle.
+    """
+    return _available_lexemes()
+
+
+def jargoyle_drift(
+    text: str,
+    *,
+    lexemes: str = DEFAULT_LEXEMES,
+    mode: JargoyleMode = DEFAULT_MODE,
+    rate: float | None = None,
+    seed: int | None = None,
+) -> str:
+    """Apply dictionary-based word drift to text.
+
+    Args:
+        text: Input text to transform.
+        lexemes: Name of the dictionary to use.
+        mode: "literal" for deterministic first-entry swaps,
+              "drift" for random selection from alternatives.
+        rate: Probability of transforming each matching word (0.0 to 1.0).
+        seed: Seed for deterministic randomness (only used in "drift" mode).
+
+    Returns:
+        Text with word substitutions applied.
+
+    Raises:
+        ValueError: If lexemes or mode is invalid.
+    """
+    normalized_lexemes = _validate_lexemes(lexemes)
+    normalized_mode = _validate_mode(mode)
+
+    effective_rate = DEFAULT_JARGOYLE_RATE if rate is None else float(rate)
+    resolved_seed = resolve_seed(seed, None) if normalized_mode == "drift" else None
+
+    return jargoyle_drift_rust(
+        text,
+        normalized_lexemes,
+        normalized_mode,
+        effective_rate,
+        resolved_seed,
+    )
+
+
+class Jargoyle(Glitchling):
+    """Glitchling that swaps words using bundled lexeme dictionaries.
+
+    Jargoyle replaces words with alternatives from one of several dictionaries:
+
+    - **colors**: Swap color terms (e.g., "red" -> "blue").
+    - **synonyms**: General synonym substitution (e.g., "fast" -> "rapid").
+    - **corporate**: Business jargon alternatives.
+    - **academic**: Scholarly word substitutions.
+    - **cyberpunk**: Neon cyberpunk slang and gadgetry.
+    - **lovecraftian**: Cosmic horror terminology.
+    - **custom**: Any ``*.json`` dictionary placed in ``assets/lexemes``.
+
+    Two modes are supported:
+
+    - **literal**: Use the first (canonical) entry for each word.
+    - **drift**: Randomly select from available alternatives.
+
+    Example:
+        >>> from glitchlings import Jargoyle
+        >>> jargoyle = Jargoyle(lexemes="colors", mode="literal")
+        >>> jargoyle("The red balloon floated away.")
+        'The blue balloon floated away.'
+
+        >>> jargoyle = Jargoyle(lexemes="synonyms", mode="drift", rate=0.5, seed=42)
+        >>> jargoyle("The quick fox jumps fast.")
+        'The swift fox jumps rapid.'
+    """
+
+    flavor = "Oh no... The worst person you know just bought a thesaurus..."
+
+    def __init__(
+        self,
+        *,
+        lexemes: str = DEFAULT_LEXEMES,
+        mode: JargoyleMode = DEFAULT_MODE,
+        rate: float | None = None,
+        seed: int | None = None,
+        **kwargs: Any,
+    ) -> None:
+        """Initialize Jargoyle with the specified dictionary and mode.
+
+        Args:
+            lexemes: Name of the dictionary to use. See ``list_lexeme_dictionaries()``
+                for the full, dynamic list (including any custom ``*.json`` files).
+            mode: Transformation mode. "literal" for deterministic swaps,
+                "drift" for random selection.
+            rate: Probability of transforming each matching word (0.0 to 1.0).
+                Defaults to 0.01.
+            seed: Seed for deterministic randomness.
+        """
+        # Validate inputs
+        normalized_lexemes = _validate_lexemes(lexemes)
+        normalized_mode = _validate_mode(mode)
+
+        effective_rate = DEFAULT_JARGOYLE_RATE if rate is None else rate
+
+        super().__init__(
+            name="Jargoyle",
+            corruption_function=jargoyle_drift,
+            scope=AttackWave.WORD,
+            order=AttackOrder.NORMAL,
+            seed=seed,
+            lexemes=normalized_lexemes,
+            mode=normalized_mode,
+            rate=effective_rate,
+            **kwargs,
+            # Pass seed explicitly to kwargs so corruption_function receives it
+            # (seed is stored separately in base class but needed by jargoyle_drift)
+        )
+        # Ensure seed is in kwargs for the corruption function
+        self.kwargs["seed"] = seed
+
+    def pipeline_operation(self) -> PipelineOperationPayload:
+        """Return the pipeline descriptor for the Rust backend."""
+        lexemes = self.kwargs.get("lexemes", DEFAULT_LEXEMES)
+        mode = self.kwargs.get("mode", DEFAULT_MODE)
+        rate = self.kwargs.get("rate", DEFAULT_JARGOYLE_RATE)
+        return cast(
+            PipelineOperationPayload,
+            {
+                "type": "jargoyle",
+                "lexemes": str(lexemes),
+                "mode": str(mode),
+                "rate": float(rate),
+            },
+        )
+
+
+# Module-level singleton for convenience
+jargoyle = Jargoyle()
+
+
+__all__ = [
+    "DEFAULT_LEXEMES",
+    "DEFAULT_MODE",
+    "Jargoyle",
+    "JargoyleMode",
+    "VALID_LEXEMES",
+    "VALID_MODES",
+    "jargoyle",
+    "jargoyle_drift",
+    "list_lexeme_dictionaries",
+]