glitchlings 0.2.5__cp312-cp312-win_amd64.whl → 0.9.3__cp312-cp312-win_amd64.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/ekkokin.py

@@ -0,0 +1,118 @@
+"""Homophone substitution glitchling implementation."""
+
+from __future__ import annotations
+
+import math
+import random
+from typing import TYPE_CHECKING, Any, Iterable, Mapping, Sequence
+
+from glitchlings.assets import load_homophone_groups
+from glitchlings.constants import DEFAULT_EKKOKIN_RATE, DEFAULT_EKKOKIN_WEIGHTING
+from glitchlings.internal.rust_ffi import ekkokin_homophones_rust, resolve_seed
+
+from .core import AttackOrder, AttackWave
+from .core import Glitchling as _GlitchlingRuntime
+
+_homophone_groups: tuple[tuple[str, ...], ...] = load_homophone_groups()
+
+
+def _normalise_group(group: Sequence[str]) -> tuple[str, ...]:
+    """Return a tuple of lowercase homophones preserving original order."""
+
+    # Use dict.fromkeys to preserve the original ordering while de-duplicating.
+    return tuple(dict.fromkeys(word.lower() for word in group if word))
+
+
+def _build_lookup(groups: Iterable[Sequence[str]]) -> Mapping[str, tuple[str, ...]]:
+    """Return a mapping from word -> homophone group."""
+
+    lookup: dict[str, tuple[str, ...]] = {}
+    for group in groups:
+        normalised = _normalise_group(group)
+        if len(normalised) < 2:
+            continue
+        for word in normalised:
+            lookup[word] = normalised
+    return lookup
+
+
+_homophone_lookup = _build_lookup(_homophone_groups)
+
+
+class _GlitchlingProtocol:
+    kwargs: dict[str, Any]
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None: ...
+
+    def reset_rng(self, seed: int | None = None) -> None: ...
+
+    def pipeline_operation(self) -> dict[str, object] | None: ...
+
+
+if TYPE_CHECKING:
+    from .core import Glitchling as _GlitchlingBase
+else:
+    _GlitchlingBase = _GlitchlingRuntime
+
+
+def substitute_homophones(
+    text: str,
+    rate: float | None = None,
+    seed: int | None = None,
+    rng: random.Random | None = None,
+) -> str:
+    """Replace words in ``text`` with curated homophones."""
+
+    effective_rate = DEFAULT_EKKOKIN_RATE if rate is None else rate
+
+    clamped_rate = 0.0 if math.isnan(effective_rate) else max(0.0, min(1.0, effective_rate))
+
+    return ekkokin_homophones_rust(
+        text,
+        clamped_rate,
+        DEFAULT_EKKOKIN_WEIGHTING,
+        resolve_seed(seed, rng),
+    )
+
+
+class Ekkokin(_GlitchlingBase):
+    """Glitchling that swaps words for curated homophones."""
+
+    flavor = "Homophonic idiolectician. There leased favourite flavour? Orange."
+
+    def __init__(
+        self,
+        *,
+        rate: float | None = None,
+        seed: int | None = None,
+    ) -> None:
+        effective_rate = DEFAULT_EKKOKIN_RATE if rate is None else rate
+        super().__init__(
+            name="Ekkokin",
+            corruption_function=substitute_homophones,
+            scope=AttackWave.WORD,
+            order=AttackOrder.EARLY,
+            seed=seed,
+            pipeline_operation=_build_pipeline_descriptor,
+            rate=effective_rate,
+        )
+
+
+def _build_pipeline_descriptor(glitch: _GlitchlingBase) -> dict[str, object]:
+    rate_value = glitch.kwargs.get("rate")
+    rate = DEFAULT_EKKOKIN_RATE if rate_value is None else float(rate_value)
+    return {
+        "type": "ekkokin",
+        "rate": rate,
+        "weighting": DEFAULT_EKKOKIN_WEIGHTING,
+    }
+
+
+ekkokin = Ekkokin()
+
+
+__all__ = [
+    "Ekkokin",
+    "ekkokin",
+    "substitute_homophones",
+]

glitchlings/zoo/hokey.py

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