glitchlings 1.0.0__cp313-cp313-win_amd64.whl

glitchlings/zoo/pedant/core.py

@@ -0,0 +1,99 @@
+"""Core classes for the pedant evolution chain backed by the Rust pipeline."""
+
+from __future__ import annotations
+
+from typing import Dict, Type
+
+from glitchlings.internal.rust_ffi import apply_grammar_rule_rust
+
+from ..core import Gaggle
+from .stones import PedantStone
+
+
+def apply_pedant(
+    text: str,
+    *,
+    stone: PedantStone,
+    seed: int,
+) -> str:
+    """Apply a pedant transformation via the Rust extension."""
+
+    return apply_grammar_rule_rust(
+        text,
+        stone=stone.label,
+        seed=int(seed),
+    )
+
+
+class PedantEvolution:
+    """Concrete pedant form that delegates to the Rust implementation."""
+
+    stone: PedantStone
+
+    def __init__(
+        self,
+        seed: int,
+        *,
+        stone: PedantStone | None = None,
+    ) -> None:
+        resolved_stone = stone or getattr(self, "stone", None)
+        if resolved_stone is None:  # pragma: no cover - defensive guard
+            raise ValueError("PedantEvolution requires a PedantStone")
+        self.seed = int(seed)
+        self.stone = resolved_stone
+
+    def move(self, text: str) -> str:
+        result = apply_pedant(text, stone=self.stone, seed=self.seed)
+        return result
+
+
+class PedantBase:
+    """Base pedant capable of evolving into specialised grammar forms."""
+
+    name: str = "Pedant"
+    type: str = "Normal"
+    flavor: str = "A novice grammarian waiting to evolve."
+
+    def __init__(self, seed: int, *, root_seed: int | None = None) -> None:
+        self.seed = int(seed)
+        self.root_seed = int(seed if root_seed is None else root_seed)
+
+    def evolve(self, stone: PedantStone | str) -> PedantEvolution:
+        pedant_stone = PedantStone.from_value(stone)
+        form_cls = EVOLUTIONS.get(pedant_stone)
+        if form_cls is None:  # pragma: no cover - sanity guard
+            raise KeyError(f"Unknown stone: {stone}")
+        derived_seed = Gaggle.derive_seed(self.root_seed, pedant_stone.label, 0)
+        return form_cls(seed=int(derived_seed))
+
+    def move(self, text: str) -> str:
+        return text
+
+    def __repr__(self) -> str:  # pragma: no cover - debugging helper
+        return f"<{self.__class__.__name__} seed={self.seed} type={self.type}>"
+
+
+EVOLUTIONS: Dict[PedantStone, Type[PedantEvolution]] = {}
+
+
+try:  # pragma: no cover - import resolution occurs at runtime
+    from .forms import (
+        Aetheria,
+        Andi,
+        Apostrofae,
+        Commama,
+        Infinitoad,
+    )
+except ImportError:  # pragma: no cover - partial imports during type checking
+    pass
+else:
+    EVOLUTIONS = {
+        PedantStone.HYPERCORRECTITE: Andi,
+        PedantStone.UNSPLITTIUM: Infinitoad,
+        PedantStone.COEURITE: Aetheria,
+        PedantStone.CURLITE: Apostrofae,
+        PedantStone.OXFORDIUM: Commama,
+    }
+
+
+__all__ = ["PedantBase", "PedantEvolution", "EVOLUTIONS", "apply_pedant"]

glitchlings/zoo/pedant/forms.py

@@ -0,0 +1,50 @@
+"""Pedant evolution forms delegating to the Rust-backed core."""
+
+from __future__ import annotations
+
+from .core import PedantEvolution
+from .stones import PedantStone
+
+
+class Andi(PedantEvolution):
+    stone = PedantStone.HYPERCORRECTITE
+    name = "Andi"
+    type = "Ghost"
+    flavor = "Learned that 'me' is wrong and now overcorrects everywhere."
+
+
+class Infinitoad(PedantEvolution):
+    stone = PedantStone.UNSPLITTIUM
+    name = "Infinitoad"
+    type = "Steel"
+    flavor = "To never split what was never whole."
+
+
+class Aetheria(PedantEvolution):
+    stone = PedantStone.COEURITE
+    name = "Aetheria"
+    type = "Psychic"
+    flavor = "Resurrects archaic ligatures and diacritics."
+
+
+class Apostrofae(PedantEvolution):
+    stone = PedantStone.CURLITE
+    name = "Apostrofae"
+    type = "Fairy"
+    flavor = "Curves quotes into typeset perfection."
+
+
+class Commama(PedantEvolution):
+    stone = PedantStone.OXFORDIUM
+    name = "Commama"
+    type = "Steel"
+    flavor = "Oxonian hero of the list."
+
+
+__all__ = [
+    "Andi",
+    "Infinitoad",
+    "Aetheria",
+    "Apostrofae",
+    "Commama",
+]

glitchlings/zoo/pedant/stones.py

@@ -0,0 +1,83 @@
+"""Evolution stones recognised by the pedant."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+@dataclass(frozen=True)
+class Stone:
+    """Descriptor for an evolution stone."""
+
+    name: str
+    type: str
+    effect: str
+
+
+class PedantStone(Enum):
+    """Enumeration of evolution stones available to the pedant."""
+
+    HYPERCORRECTITE = Stone(
+        "Hypercorrectite",
+        "Ghost",
+        "Induces prestigious-sounding pronoun errors in coordinate structures.",
+    )
+    UNSPLITTIUM = Stone(
+        "Unsplittium",
+        "Steel",
+        "Unsplits infinitives that were never meant to be joined.",
+    )
+    COEURITE = Stone(
+        "Coeurite",
+        "Psychic",
+        "Restores archaic ligatures to modern words.",
+    )
+    CURLITE = Stone(
+        "Curlite",
+        "Fairy",
+        "Coaches punctuation to embrace typographic curls.",
+    )
+    OXFORDIUM = Stone("Oxfordium", "Steel", "Polishes serial comma usage.")
+
+    @property
+    def descriptor(self) -> Stone:
+        """Return the metadata describing this stone."""
+
+        return self.value
+
+    @property
+    def label(self) -> str:
+        """Return the display name for this stone."""
+
+        return self.value.name
+
+    def __str__(self) -> str:  # pragma: no cover - convenience for reprs/CLI echo
+        return self.label
+
+    @classmethod
+    def from_value(cls, value: object) -> "PedantStone":
+        """Normalise ``value`` into a :class:`PedantStone` member."""
+
+        if isinstance(value, cls):
+            return value
+        if isinstance(value, Stone):
+            for member in cls:
+                if member.value == value:
+                    return member
+            msg = f"Unknown pedant stone descriptor: {value!r}"
+            raise ValueError(msg)
+
+        try:
+            return _STONE_BY_NAME[str(value)]
+        except KeyError as exc:
+            raise ValueError(f"Unknown pedant stone: {value!r}") from exc
+
+
+_STONE_BY_NAME: dict[str, PedantStone] = {stone.value.name: stone for stone in PedantStone}
+
+
+STONES: dict[str, Stone] = {stone.label: stone.descriptor for stone in PedantStone}
+
+
+__all__ = ["Stone", "PedantStone", "STONES"]

glitchlings/zoo/redactyl.py

@@ -0,0 +1,94 @@
+import random
+from typing import Any, cast
+
+from glitchlings.constants import DEFAULT_REDACTYL_CHAR, DEFAULT_REDACTYL_RATE
+from glitchlings.internal.rust_ffi import redact_words_rust, resolve_seed
+
+from .core import AttackWave, Glitchling, PipelineOperationPayload
+
+
+def redact_words(
+    text: str,
+    replacement_char: str | None = DEFAULT_REDACTYL_CHAR,
+    rate: float | None = None,
+    merge_adjacent: bool | None = False,
+    seed: int = 151,
+    rng: random.Random | None = None,
+    *,
+    unweighted: bool = False,
+) -> str:
+    """Redact random words by replacing their characters."""
+    effective_rate = DEFAULT_REDACTYL_RATE if rate is None else rate
+
+    replacement = DEFAULT_REDACTYL_CHAR if replacement_char is None else str(replacement_char)
+    merge = False if merge_adjacent is None else bool(merge_adjacent)
+
+    clamped_rate = max(0.0, min(effective_rate, 1.0))
+    unweighted_flag = bool(unweighted)
+
+    return redact_words_rust(
+        text,
+        replacement,
+        clamped_rate,
+        merge,
+        unweighted_flag,
+        resolve_seed(seed, rng),
+    )
+
+
+class Redactyl(Glitchling):
+    """Glitchling that redacts words with block characters."""
+
+    flavor = "Some things are better left ████████."
+
+    def __init__(
+        self,
+        *,
+        replacement_char: str = DEFAULT_REDACTYL_CHAR,
+        rate: float | None = None,
+        merge_adjacent: bool = False,
+        seed: int = 151,
+        unweighted: bool = False,
+        **kwargs: Any,
+    ) -> None:
+        effective_rate = DEFAULT_REDACTYL_RATE if rate is None else 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,
+            **kwargs,
+        )
+
+    def pipeline_operation(self) -> PipelineOperationPayload:
+        replacement_char_value = self.kwargs.get("replacement_char", DEFAULT_REDACTYL_CHAR)
+        rate_value = self.kwargs.get("rate", DEFAULT_REDACTYL_RATE)
+        merge_value = self.kwargs.get("merge_adjacent", False)
+
+        replacement_char = str(
+            DEFAULT_REDACTYL_CHAR if replacement_char_value is None else replacement_char_value
+        )
+        rate = float(DEFAULT_REDACTYL_RATE if rate_value is None else rate_value)
+        merge_adjacent = bool(merge_value)
+        unweighted = bool(self.kwargs.get("unweighted", False))
+
+        return cast(
+            PipelineOperationPayload,
+            {
+                "type": "redact",
+                "replacement_char": replacement_char,
+                "rate": rate,
+                "merge_adjacent": merge_adjacent,
+                "unweighted": unweighted,
+            },
+        )
+
+
+redactyl = Redactyl()
+
+
+__all__ = ["Redactyl", "redactyl", "redact_words"]

glitchlings/zoo/rng.py

@@ -0,0 +1,280 @@
+"""RNG boundary layer for seed resolution.
+
+This module provides the interface between RNG state and concrete random values.
+All randomness in the glitchlings library flows through these functions.
+
+Design Philosophy
+-----------------
+RNG management is an *impure* operation - it involves stateful objects
+(random.Random) and non-deterministic behavior when no seed is provided.
+This module provides the boundary layer that converts RNG state into
+concrete values that can be passed to pure functions.
+
+The pattern is:
+    1. User provides `seed: int | None` and/or `rng: random.Random | None`
+    2. Boundary layer resolves to a concrete `int` via `resolve_seed()`
+    3. Pure/Rust functions receive the concrete seed value
+
+This separation means:
+    - Pure transformation code never touches RNG objects
+    - Tests can provide explicit seed values for reproducibility
+    - RNG state management is isolated to the boundary
+
+See AGENTS.md "Functional Purity Architecture" for full details.
+"""
+
+from __future__ import annotations
+
+import random
+from typing import Protocol, runtime_checkable
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+# Bit width for seed values (64-bit for compatibility with Rust u64)
+SEED_BIT_WIDTH = 64
+SEED_MASK = (1 << SEED_BIT_WIDTH) - 1  # 0xFFFFFFFFFFFFFFFF
+
+# FNV-1a constants for 64-bit hashing (fast, simple string hashing)
+_FNV_OFFSET_BASIS = 0xCBF29CE484222325
+_FNV_PRIME = 0x100000001B3
+
+# SplitMix64 constants (standard PRNG seed mixer)
+_SPLITMIX_GAMMA = 0x9E3779B97F4A7C15
+_SPLITMIX_MIX1 = 0xBF58476D1CE4E5B9
+_SPLITMIX_MIX2 = 0x94D049BB133111EB
+
+
+# ---------------------------------------------------------------------------
+# Protocols
+# ---------------------------------------------------------------------------
+
+
+@runtime_checkable
+class RandomBitsSource(Protocol):
+    """Protocol for objects that can provide random bits."""
+
+    def getrandbits(self, k: int) -> int:
+        """Return a non-negative integer with k random bits."""
+        ...
+
+
+# ---------------------------------------------------------------------------
+# Core Boundary Functions
+# ---------------------------------------------------------------------------
+
+
+def resolve_seed(
+    seed: int | None,
+    rng: random.Random | None,
+) -> int:
+    """Resolve a seed from optional explicit seed or RNG state.
+
+    This is the primary boundary function for RNG resolution. Call this
+    once at the boundary layer, then pass the resulting int to all
+    downstream pure/Rust functions.
+
+    Args:
+        seed: Explicit seed value. If provided, takes precedence over rng.
+        rng: Random generator to sample from if seed is None.
+
+    Returns:
+        A 64-bit unsigned integer suitable for Rust FFI.
+
+    Note:
+        If both seed and rng are None, uses module-level random state.
+        This is non-deterministic and should only happen at top-level CLI usage.
+
+    Examples:
+        >>> resolve_seed(42, None)  # explicit seed
+        42
+        >>> rng = random.Random(123)
+        >>> resolve_seed(None, rng)  # sample from RNG
+        14522756016584210807
+    """
+    if seed is not None:
+        return int(seed) & SEED_MASK
+    if rng is not None:
+        return rng.getrandbits(SEED_BIT_WIDTH)
+    return random.getrandbits(SEED_BIT_WIDTH)
+
+
+def resolve_seed_deterministic(
+    seed: int | None,
+    rng: random.Random | None,
+) -> int:
+    """Resolve a seed, requiring explicit seed or RNG.
+
+    Like resolve_seed(), but raises ValueError if both seed and rng are None.
+    Use this when non-deterministic behavior would be a bug.
+
+    Args:
+        seed: Explicit seed value.
+        rng: Random generator to sample from.
+
+    Returns:
+        A 64-bit unsigned integer.
+
+    Raises:
+        ValueError: If both seed and rng are None.
+    """
+    if seed is not None:
+        return int(seed) & SEED_MASK
+    if rng is not None:
+        return rng.getrandbits(SEED_BIT_WIDTH)
+    raise ValueError("Either seed or rng must be provided for deterministic behavior")
+
+
+# ---------------------------------------------------------------------------
+# Seed Derivation (Deterministic)
+# ---------------------------------------------------------------------------
+
+
+def _fnv1a_hash(data: bytes) -> int:
+    """FNV-1a 64-bit hash of bytes.
+
+    Fast, simple string hashing with good distribution.
+    No cryptographic properties needed for seed derivation.
+    """
+    h = _FNV_OFFSET_BASIS
+    for byte in data:
+        h ^= byte
+        h = (h * _FNV_PRIME) & SEED_MASK
+    return h
+
+
+def _splitmix64(state: int) -> int:
+    """SplitMix64 mixing function.
+
+    Standard PRNG seed mixer used by Java's SplittableRandom
+    and Rust's rand crate. Provides excellent avalanche properties.
+    """
+    state = (state + _SPLITMIX_GAMMA) & SEED_MASK
+    state = ((state ^ (state >> 30)) * _SPLITMIX_MIX1) & SEED_MASK
+    state = ((state ^ (state >> 27)) * _SPLITMIX_MIX2) & SEED_MASK
+    return (state ^ (state >> 31)) & SEED_MASK
+
+
+def derive_seed(base_seed: int, *components: int | str) -> int:
+    """Derive a new seed from a base seed and components.
+
+    This is a pure function for hierarchical seed derivation.
+    Used by Gaggle to give each glitchling a unique but reproducible seed.
+
+    Uses FNV-1a for string hashing and SplitMix64 for mixing. This provides
+    stable, deterministic derivation across interpreter runs without the
+    overhead of cryptographic hashing.
+
+    Args:
+        base_seed: The parent seed.
+        *components: Additional components to mix in (integers or strings).
+
+    Returns:
+        A derived 64-bit seed.
+
+    Examples:
+        >>> derive_seed(12345, 0)  # first child
+        2454886589211414944
+        >>> derive_seed(12345, 1)  # second child
+        18133564086679993456
+        >>> derive_seed(12345, "typogre")  # named child
+        1187037253482581891
+    """
+    state = base_seed & SEED_MASK
+
+    for component in components:
+        if isinstance(component, str):
+            # Hash string to u64 via FNV-1a, then XOR into state
+            state ^= _fnv1a_hash(component.encode("utf-8"))
+        else:
+            # XOR integer directly (masked to 64 bits)
+            state ^= abs(component) & SEED_MASK
+
+        # Mix with SplitMix64 after each component
+        state = _splitmix64(state)
+
+    return state
+
+
+# ---------------------------------------------------------------------------
+# Random Value Generation (Impure)
+# ---------------------------------------------------------------------------
+
+
+def create_rng(seed: int) -> random.Random:
+    """Create a new Random instance from a seed.
+
+    Use this when you need to create child RNG states for parallel operations.
+    Prefer passing concrete seed values to functions when possible.
+
+    Args:
+        seed: The seed for the new RNG.
+
+    Returns:
+        A new random.Random instance.
+    """
+    return random.Random(seed)
+
+
+def sample_random_float(rng: random.Random) -> float:
+    """Sample a random float in [0.0, 1.0) from an RNG.
+
+    Args:
+        rng: The random generator.
+
+    Returns:
+        Float in range [0.0, 1.0).
+    """
+    return rng.random()
+
+
+def sample_random_int(rng: random.Random, *, low: int, high: int) -> int:
+    """Sample a random integer in [low, high] inclusive.
+
+    Args:
+        rng: The random generator.
+        low: Minimum value (inclusive).
+        high: Maximum value (inclusive).
+
+    Returns:
+        Random integer in range [low, high].
+    """
+    return rng.randint(low, high)
+
+
+def sample_random_index(rng: random.Random, length: int) -> int:
+    """Sample a random index for a sequence of given length.
+
+    Args:
+        rng: The random generator.
+        length: The sequence length.
+
+    Returns:
+        Random index in range [0, length).
+
+    Raises:
+        ValueError: If length <= 0.
+    """
+    if length <= 0:
+        raise ValueError("Cannot sample index from empty sequence")
+    return rng.randrange(length)
+
+
+__all__ = [
+    # Constants
+    "SEED_BIT_WIDTH",
+    "SEED_MASK",
+    # Protocols
+    "RandomBitsSource",
+    # Boundary functions
+    "resolve_seed",
+    "resolve_seed_deterministic",
+    # Derivation
+    "derive_seed",
+    # RNG operations (impure)
+    "create_rng",
+    "sample_random_float",
+    "sample_random_int",
+    "sample_random_index",
+]