glitchlings 1.0.0__cp313-cp313-win_amd64.whl

glitchlings/zoo/jargoyle.py

@@ -0,0 +1,301 @@
+"""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
+import random
+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 (
+    is_bundled_lexeme_rust,
+    list_bundled_lexeme_dictionaries_rust,
+    list_lexeme_dictionaries_rust,
+    resolve_seed,
+    substitute_lexeme_rust,
+)
+
+from .core import AttackOrder, AttackWave, Glitchling, PipelineOperationPayload
+
+_LEXEME_ENV_VAR = "GLITCHLINGS_LEXEME_DIR"
+_lexeme_directory_configured = False
+
+
+def _configure_lexeme_directory() -> Path | None:
+    """Expose the bundled lexeme directory to the Rust backend via an env var.
+
+    This is only needed for discovering custom lexeme files at runtime.
+    Built-in lexemes (synonyms, colors, corporate, academic, cyberpunk, lovecraftian)
+    are embedded directly in the Rust binary and require no file I/O.
+    """
+    global _lexeme_directory_configured
+    if _lexeme_directory_configured:
+        return None
+
+    try:
+        lexeme_root = resources.files("glitchlings.assets.lexemes")
+    except (ModuleNotFoundError, AttributeError):
+        _lexeme_directory_configured = True
+        return None
+
+    try:
+        with resources.as_file(lexeme_root) as resolved:
+            path = Path(resolved)
+    except FileNotFoundError:
+        _lexeme_directory_configured = True
+        return None
+
+    if not path.is_dir():
+        _lexeme_directory_configured = True
+        return None
+
+    os.environ.setdefault(_LEXEME_ENV_VAR, str(path))
+    _lexeme_directory_configured = True
+    return path
+
+
+# NOTE: We intentionally do NOT call _configure_lexeme_directory() at module load.
+# Built-in lexemes are embedded in the Rust binary and require no file I/O.
+# The directory configuration is only needed for custom lexeme discovery.
+
+DEFAULT_LEXEMES = "synonyms"
+
+# Valid modes
+JargoyleMode = Literal["literal", "drift"]
+VALID_MODES = ("literal", "drift")
+DEFAULT_MODE: JargoyleMode = "drift"
+
+
+def _bundled_lexemes() -> list[str]:
+    """Return the list of bundled (embedded) lexeme dictionaries."""
+    return sorted({name.lower() for name in list_bundled_lexeme_dictionaries_rust()})
+
+
+def _available_lexemes() -> list[str]:
+    """Return all available lexeme dictionaries (bundled + custom)."""
+    return sorted({name.lower() for name in list_lexeme_dictionaries_rust()})
+
+
+def _validate_lexemes(name: str) -> str:
+    """Validate and normalize a lexeme dictionary name.
+
+    For built-in lexemes (bundled in the Rust binary), no file I/O is performed.
+    For custom lexemes, the lexeme directory is configured on-demand to discover them.
+    """
+    normalized = name.lower()
+
+    # Fast path: check if it's a bundled lexeme (no file I/O needed)
+    if is_bundled_lexeme_rust(normalized):
+        return normalized
+
+    # Slow path: configure directory to discover custom lexemes
+    _configure_lexeme_directory()
+
+    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(_bundled_lexemes())
+
+
+def list_lexeme_dictionaries() -> list[str]:
+    """Return the list of available lexeme dictionaries.
+
+    This includes both built-in dictionaries (embedded in the binary) and any
+    custom dictionaries found in the lexeme directory.
+
+    Returns:
+        List of dictionary names that can be used with Jargoyle.
+    """
+    # Configure directory to discover any custom lexemes
+    _configure_lexeme_directory()
+    return _available_lexemes()
+
+
+def list_bundled_lexeme_dictionaries() -> list[str]:
+    """Return the list of bundled (built-in) lexeme dictionaries.
+
+    These dictionaries are embedded directly in the Rust binary and require
+    no file I/O to access.
+
+    Returns:
+        List of built-in dictionary names: academic, colors, corporate,
+        cyberpunk, lovecraftian, synonyms.
+    """
+    return _bundled_lexemes()
+
+
+def jargoyle_drift(
+    text: str,
+    *,
+    lexemes: str = DEFAULT_LEXEMES,
+    mode: JargoyleMode = DEFAULT_MODE,
+    rate: float | None = None,
+    seed: int | None = None,
+    rng: random.Random | 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).
+        rng: Random number generator (alternative to seed).
+
+    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, rng) if normalized_mode == "drift" else None
+
+    return substitute_lexeme_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_bundled_lexeme_dictionaries",
+    "list_lexeme_dictionaries",
+]

glitchlings/zoo/mim1c.py

@@ -0,0 +1,269 @@
+"""Rust-backed Mim1c glitchling that swaps characters for homoglyphs.
+
+The Mim1c glitchling replaces characters with visually similar confusable
+characters (homoglyphs) based on Unicode Technical Standard #39.
+
+## Modes
+
+- **single_script** (safest): Only substitute within the same script
+  (Latin→Latin variants). Minimal visual disruption.
+- **mixed_script** (default): Allow visually similar cross-script substitutions
+  (Latin↔Cyrillic↔Greek). Maximum visual similarity with some mixed scripts.
+- **compatibility**: Include Unicode compatibility variants
+  (fullwidth, math alphanumerics). Wider range of substitutions.
+- **aggressive**: All of the above combined. Most aggressive substitution.
+
+## Locality Control
+
+`max_consecutive` limits how many adjacent characters can be substituted,
+preventing the "ransom note" effect where every character is from a different
+script. Default is 3.
+
+## Data Source
+
+Confusable mappings derived from Unicode Technical Standard #39 (confusables.txt).
+
+## References
+
+- **Unicode Technical Standard #39**: Unicode Security Mechanisms
+  - https://www.unicode.org/reports/tr39/
+- **confusables.txt**: Official confusable character mappings
+  - https://www.unicode.org/Public/security/latest/confusables.txt
+"""
+
+from __future__ import annotations
+
+import random
+from collections.abc import Collection, Iterable
+from typing import Any, Literal, cast
+
+from glitchlings.constants import (
+    DEFAULT_MIM1C_MAX_CONSECUTIVE,
+    DEFAULT_MIM1C_MODE,
+    DEFAULT_MIM1C_RATE,
+    MIM1C_DEFAULT_CLASSES,
+)
+from glitchlings.internal.rust_ffi import resolve_seed, swap_homoglyphs_rust
+
+from .core import AttackOrder, AttackWave, Glitchling, PipelineOperationPayload
+from .validation import normalize_mim1c_max_consecutive, normalize_mim1c_mode
+
+
+def _normalise_classes(
+    value: object,
+) -> tuple[str, ...] | Literal["all"] | None:
+    if value is None:
+        return None
+    if isinstance(value, str):
+        if value.lower() == "all":
+            return "all"
+        return (value,)
+    if isinstance(value, Iterable):
+        return tuple(str(item) for item in value)
+    raise TypeError("classes must be an iterable of strings or 'all'")
+
+
+def _normalise_banned(value: object) -> tuple[str, ...] | None:
+    if value is None:
+        return None
+    if isinstance(value, str):
+        return tuple(value)
+    if isinstance(value, Iterable):
+        return tuple(str(item) for item in value)
+    raise TypeError("banned_characters must be an iterable of strings")
+
+
+def _serialise_classes(
+    value: tuple[str, ...] | Literal["all"] | None,
+) -> list[str] | Literal["all"] | None:
+    if value is None:
+        return None
+    if value == "all":
+        return "all"
+    return list(value)
+
+
+def _serialise_banned(value: tuple[str, ...] | None) -> list[str] | None:
+    if value is None:
+        return None
+    return list(value)
+
+
+HomoglyphMode = Literal["single_script", "mixed_script", "compatibility", "aggressive"]
+
+
+def swap_homoglyphs(
+    text: str,
+    rate: float | None = None,
+    classes: list[str] | Literal["all"] | None = None,
+    banned_characters: Collection[str] | None = None,
+    seed: int | None = None,
+    rng: random.Random | None = None,
+    mode: HomoglyphMode | None = None,
+    max_consecutive: int | None = None,
+) -> str:
+    """Replace characters with visually confusable homoglyphs via the Rust engine.
+
+    Args:
+        text: The input text to transform.
+        rate: Probability of substituting each eligible character. Default 0.02.
+        classes: Unicode script classes to include.
+            Default ["LATIN", "GREEK", "CYRILLIC", "COMMON"].
+        banned_characters: Characters to never use as substitutes.
+        seed: Random seed for deterministic behavior.
+        rng: Optional random.Random instance (alternative to seed).
+        mode: Substitution mode controlling confusable types:
+            - "single_script": Only same-script substitutions (safest).
+            - "mixed_script": Allow cross-script like Latin↔Cyrillic↔Greek (default).
+            - "compatibility": Include fullwidth, math alphanumerics.
+            - "aggressive": All confusable types.
+        max_consecutive: Maximum consecutive characters to substitute. Default 3.
+            Set to 0 for unlimited.
+
+    Returns:
+        Text with some characters replaced by visually similar confusables.
+    """
+    effective_rate = DEFAULT_MIM1C_RATE if rate is None else rate
+    effective_mode = normalize_mim1c_mode(mode, DEFAULT_MIM1C_MODE)
+    effective_max_consecutive = normalize_mim1c_max_consecutive(
+        max_consecutive, DEFAULT_MIM1C_MAX_CONSECUTIVE
+    )
+
+    normalised_classes = _normalise_classes(classes)
+    normalised_banned = _normalise_banned(banned_characters)
+
+    if normalised_classes is None:
+        payload_classes: list[str] | Literal["all"] | None = list(MIM1C_DEFAULT_CLASSES)
+    else:
+        payload_classes = _serialise_classes(normalised_classes)
+    payload_banned = _serialise_banned(normalised_banned)
+
+    return swap_homoglyphs_rust(
+        text,
+        effective_rate,
+        payload_classes,
+        payload_banned,
+        resolve_seed(seed, rng),
+        effective_mode,
+        effective_max_consecutive,
+    )
+
+
+class Mim1c(Glitchling):
+    """Glitchling that swaps characters for visually similar homoglyphs.
+
+    Mim1c replaces characters with visually similar confusable characters
+    (homoglyphs) based on Unicode Technical Standard #39.
+
+    ## Modes
+
+    - **single_script** (safest): Only substitute within the same script
+      (Latin→Latin variants). Minimal visual disruption.
+    - **mixed_script** (default): Allow visually similar cross-script substitutions
+      (Latin↔Cyrillic↔Greek). Maximum visual similarity with some mixed scripts.
+    - **compatibility**: Include Unicode compatibility variants
+      (fullwidth, math alphanumerics). Wider range of substitutions.
+    - **aggressive**: All of the above combined. Most aggressive substitution.
+
+    ## Locality Control
+
+    `max_consecutive` limits how many adjacent characters can be substituted,
+    preventing the "ransom note" effect where every character is from a different
+    script. Default is 3. Set to 0 for unlimited.
+
+    Args:
+        rate: Probability of substituting each eligible character. Default 0.02.
+        classes: Unicode script classes to include.
+            Default ["LATIN", "GREEK", "CYRILLIC", "COMMON"].
+        banned_characters: Characters to never use as substitutes.
+        mode: Substitution mode. One of "single_script", "mixed_script",
+            "compatibility", "aggressive".
+        max_consecutive: Maximum consecutive characters to substitute. Default 3.
+        seed: Random seed for deterministic behavior.
+    """
+
+    flavor = (
+        "Breaks your parser by replacing some characters in strings with "
+        "doppelgangers. Don't worry, this text is clean. ;)"
+    )
+
+    def __init__(
+        self,
+        *,
+        rate: float | None = None,
+        classes: list[str] | Literal["all"] | None = None,
+        banned_characters: Collection[str] | None = None,
+        mode: HomoglyphMode | None = None,
+        max_consecutive: int | None = None,
+        seed: int | None = None,
+        **kwargs: Any,
+    ) -> None:
+        effective_rate = DEFAULT_MIM1C_RATE if rate is None else rate
+        effective_mode = normalize_mim1c_mode(mode, DEFAULT_MIM1C_MODE)
+        effective_max_consecutive = normalize_mim1c_max_consecutive(
+            max_consecutive, DEFAULT_MIM1C_MAX_CONSECUTIVE
+        )
+        normalised_classes = _normalise_classes(classes)
+        normalised_banned = _normalise_banned(banned_characters)
+        super().__init__(
+            name="Mim1c",
+            corruption_function=swap_homoglyphs,
+            scope=AttackWave.CHARACTER,
+            order=AttackOrder.LAST,
+            seed=seed,
+            rate=effective_rate,
+            classes=normalised_classes,
+            banned_characters=normalised_banned,
+            mode=effective_mode,
+            max_consecutive=effective_max_consecutive,
+            **kwargs,
+        )
+
+    def pipeline_operation(self) -> PipelineOperationPayload:
+        rate_value = self.kwargs.get("rate")
+        rate = DEFAULT_MIM1C_RATE if rate_value is None else float(rate_value)
+
+        descriptor: dict[str, object] = {"type": "mimic", "rate": rate}
+
+        classes = self.kwargs.get("classes")
+        serialised_classes = _serialise_classes(classes)
+        if serialised_classes is not None:
+            descriptor["classes"] = serialised_classes
+
+        banned = self.kwargs.get("banned_characters")
+        serialised_banned = _serialise_banned(banned)
+        if serialised_banned:
+            descriptor["banned_characters"] = serialised_banned
+
+        # Add mode and max_consecutive parameters
+        mode = self.kwargs.get("mode")
+        if mode is not None:
+            descriptor["mode"] = str(mode)
+
+        max_consecutive = self.kwargs.get("max_consecutive")
+        if max_consecutive is not None:
+            descriptor["max_consecutive"] = int(max_consecutive)
+
+        return cast(PipelineOperationPayload, descriptor)
+
+    def set_param(self, key: str, value: object) -> None:
+        if key == "classes":
+            super().set_param(key, _normalise_classes(value))
+            return
+        if key == "banned_characters":
+            super().set_param(key, _normalise_banned(value))
+            return
+        if key == "mode":
+            super().set_param(key, normalize_mim1c_mode(str(value) if value else None))
+            return
+        if key == "max_consecutive":
+            int_value: int | None = int(cast(Any, value)) if value is not None else None
+            super().set_param(key, normalize_mim1c_max_consecutive(int_value))
+            return
+        super().set_param(key, value)
+
+
+mim1c = Mim1c()
+
+
+__all__ = ["Mim1c", "mim1c", "swap_homoglyphs", "HomoglyphMode"]

glitchlings/zoo/pedant/__init__.py

@@ -0,0 +1,109 @@
+"""Pedant glitchling integrating grammar evolutions with Rust acceleration."""
+
+from __future__ import annotations
+
+import random
+from typing import Any, cast
+
+from glitchlings.internal.rust_ffi import resolve_seed
+
+from ..core import AttackOrder, AttackWave, Glitchling, PipelineOperationPayload
+from .core import EVOLUTIONS, PedantBase, apply_pedant
+from .stones import STONES, PedantStone
+
+
+def _coerce_stone(value: Any) -> PedantStone:
+    """Return a :class:`PedantStone` enum member for ``value``."""
+
+    return PedantStone.from_value(value)
+
+
+def pedant_transform(
+    text: str,
+    *,
+    stone: PedantStone | str = PedantStone.HYPERCORRECTITE,
+    seed: int | None = None,
+    rng: random.Random | None = None,
+) -> str:
+    """Apply a pedant evolution to text."""
+
+    pedant_stone = _coerce_stone(stone)
+    if pedant_stone not in EVOLUTIONS:
+        raise ValueError(f"Unknown pedant stone: {stone!r}")
+
+    effective_seed = resolve_seed(seed, rng)
+
+    return apply_pedant(
+        text,
+        stone=pedant_stone,
+        seed=effective_seed,
+    )
+
+
+def _build_pipeline_descriptor(glitch: Glitchling) -> PipelineOperationPayload:
+    stone_value = glitch.kwargs.get("stone")
+    if stone_value is None:
+        message = "Pedant requires a stone to build the pipeline descriptor"
+        raise RuntimeError(message)
+
+    pedant_stone = _coerce_stone(stone_value)
+
+    return cast(
+        PipelineOperationPayload,
+        {"type": "pedant", "stone": pedant_stone.label},
+    )
+
+
+class Pedant(Glitchling):
+    """Glitchling that deterministically applies pedant evolutions."""
+
+    _param_aliases = {
+        "form": "stone",
+        "stone_name": "stone",
+    }
+
+    def __init__(
+        self,
+        *,
+        stone: PedantStone | str = PedantStone.HYPERCORRECTITE,
+        seed: int | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(
+            name="Pedant",
+            corruption_function=pedant_transform,
+            scope=AttackWave.WORD,
+            order=AttackOrder.LATE,
+            seed=seed,
+            pipeline_operation=_build_pipeline_descriptor,
+            stone=_coerce_stone(stone),
+            **kwargs,
+        )
+        if seed is not None:
+            self.set_param("seed", int(seed))
+
+    def set_param(self, key: str, value: object) -> None:
+        if key in {"stone", "form", "stone_name"}:
+            super().set_param(key, _coerce_stone(value))
+            return
+        super().set_param(key, value)
+
+    def reset_rng(self, seed: int | None = None) -> None:
+        super().reset_rng(seed)
+        if self.seed is None:
+            self.kwargs.pop("seed", None)
+            return
+        self.kwargs["seed"] = int(self.seed)
+
+
+pedant = Pedant()
+
+__all__ = [
+    "PedantBase",
+    "Pedant",
+    "pedant",
+    "pedant_transform",
+    "EVOLUTIONS",
+    "STONES",
+    "PedantStone",
+]