glitchlings 0.4.5__cp312-cp312-macosx_11_0_universal2.whl → 0.5.1__cp312-cp312-macosx_11_0_universal2.whl

glitchlings/zoo/assets/__init__.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import json
+from functools import cache
+from hashlib import blake2b
+from importlib import resources
+from importlib.resources.abc import Traversable
+from pathlib import Path
+from typing import Any, BinaryIO, Iterable, TextIO, cast
+
+_DEFAULT_DIGEST_SIZE = 32
+
+
+def _iter_asset_roots() -> Iterable[Traversable]:
+    """Yield candidate locations for the shared glitchling asset bundle."""
+
+    package_root: Traversable | None
+    try:
+        package_root = resources.files("glitchlings").joinpath("assets")
+    except ModuleNotFoundError:  # pragma: no cover - defensive guard for install issues
+        package_root = None
+    if package_root is not None and package_root.is_dir():
+        yield package_root
+
+    repo_root = Path(__file__).resolve().parents[4] / "assets"
+    if repo_root.is_dir():
+        yield cast(Traversable, repo_root)
+
+
+def _asset(name: str) -> Traversable:
+    asset_roots = list(_iter_asset_roots())
+    for root in asset_roots:
+        candidate = root.joinpath(name)
+        if candidate.is_file():
+            return candidate
+
+    searched = ", ".join(str(root.joinpath(name)) for root in asset_roots) or "<unavailable>"
+    raise FileNotFoundError(f"Asset '{name}' not found in: {searched}")
+
+
+def read_text(name: str, *, encoding: str = "utf-8") -> str:
+    """Return the decoded contents of a bundled text asset."""
+
+    return cast(str, _asset(name).read_text(encoding=encoding))
+
+
+def open_text(name: str, *, encoding: str = "utf-8") -> TextIO:
+    """Open a bundled text asset for reading."""
+
+    return cast(TextIO, _asset(name).open("r", encoding=encoding))
+
+
+def open_binary(name: str) -> BinaryIO:
+    """Open a bundled binary asset for reading."""
+
+    return cast(BinaryIO, _asset(name).open("rb"))
+
+
+def load_json(name: str, *, encoding: str = "utf-8") -> Any:
+    """Deserialize a JSON asset using the shared loader helpers."""
+
+    with open_text(name, encoding=encoding) as handle:
+        return json.load(handle)
+
+
+def hash_asset(name: str) -> str:
+    """Return a BLAKE2b digest for the bundled asset ``name``."""
+
+    digest = blake2b(digest_size=_DEFAULT_DIGEST_SIZE)
+    with open_binary(name) as handle:
+        for chunk in iter(lambda: handle.read(8192), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+@cache
+def load_homophone_groups(name: str = "ekkokin_homophones.json") -> tuple[tuple[str, ...], ...]:
+    """Return the curated homophone sets bundled for the Ekkokin glitchling."""
+
+    data: list[list[str]] = load_json(name)
+    return tuple(tuple(group) for group in data)
+
+
+__all__ = [
+    "read_text",
+    "open_text",
+    "open_binary",
+    "load_json",
+    "hash_asset",
+    "load_homophone_groups",
+]

glitchlings/zoo/ekkokin.py

@@ -0,0 +1,226 @@
+"""Homophone substitution glitchling implementation."""
+
+from __future__ import annotations
+
+import math
+import random
+from typing import Any, Iterable, Mapping, Sequence, cast
+
+from ._rust_extensions import get_rust_operation
+from ._text_utils import WordToken, collect_word_tokens, split_preserving_whitespace
+from .assets import load_homophone_groups
+from .core import AttackOrder, AttackWave, Glitchling
+
+_DEFAULT_RATE = 0.02
+_DEFAULT_WEIGHTING = "flat"
+_VALID_WEIGHTINGS = {_DEFAULT_WEIGHTING}
+
+_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)
+_ekkokin_rust = get_rust_operation("ekkokin_homophones")
+
+
+def _normalise_weighting(weighting: str | None) -> str:
+    if weighting is None:
+        return _DEFAULT_WEIGHTING
+    lowered = weighting.lower()
+    if lowered not in _VALID_WEIGHTINGS:
+        options = ", ".join(sorted(_VALID_WEIGHTINGS))
+        raise ValueError(f"Unsupported weighting '{weighting}'. Expected one of: {options}")
+    return lowered
+
+
+def _apply_casing(template: str, candidate: str) -> str:
+    """Return ``candidate`` adjusted to mirror the casing pattern of ``template``."""
+
+    if not candidate:
+        return candidate
+    if template.isupper():
+        return candidate.upper()
+    if template.islower():
+        return candidate.lower()
+    if template[:1].isupper() and template[1:].islower():
+        return candidate.capitalize()
+    return candidate
+
+
+def _choose_alternative(
+    *,
+    group: Sequence[str],
+    source_word: str,
+    weighting: str,
+    rng: random.Random,
+) -> str | None:
+    """Return a replacement for ``source_word`` drawn from ``group``."""
+
+    del weighting  # Reserved for future weighting strategies.
+    lowered = source_word.lower()
+    candidates = [candidate for candidate in group if candidate != lowered]
+    if not candidates:
+        return None
+    index = rng.randrange(len(candidates))
+    replacement = candidates[index]
+    return _apply_casing(source_word, replacement)
+
+
+def _python_substitute_homophones(
+    text: str,
+    *,
+    rate: float,
+    weighting: str,
+    rng: random.Random,
+) -> str:
+    """Replace words in ``text`` with curated homophones."""
+
+    if not text:
+        return text
+
+    if math.isnan(rate):
+        return text
+
+    clamped_rate = max(0.0, min(1.0, rate))
+    if clamped_rate <= 0.0:
+        return text
+
+    tokens = split_preserving_whitespace(text)
+    word_tokens = collect_word_tokens(tokens)
+    if not word_tokens:
+        return text
+
+    mutated = False
+    for token in word_tokens:
+        replacement = _maybe_replace_token(token, clamped_rate, weighting, rng)
+        if replacement is None:
+            continue
+        tokens[token.index] = replacement
+        mutated = True
+
+    if not mutated:
+        return text
+    return "".join(tokens)
+
+
+def _maybe_replace_token(
+    token: WordToken,
+    rate: float,
+    weighting: str,
+    rng: random.Random,
+) -> str | None:
+    lookup = _homophone_lookup.get(token.core.lower())
+    if lookup is None:
+        return None
+    if rng.random() >= rate:
+        return None
+    replacement_core = _choose_alternative(
+        group=lookup,
+        source_word=token.core,
+        weighting=weighting,
+        rng=rng,
+    )
+    if replacement_core is None:
+        return None
+    return f"{token.prefix}{replacement_core}{token.suffix}"
+
+
+def substitute_homophones(
+    text: str,
+    rate: float | None = None,
+    seed: int | None = None,
+    rng: random.Random | None = None,
+    *,
+    weighting: str | None = None,
+) -> str:
+    """Replace words in ``text`` with curated homophones."""
+
+    effective_rate = _DEFAULT_RATE if rate is None else rate
+    normalized_weighting = _normalise_weighting(weighting)
+
+    active_rng = rng if rng is not None else random.Random(seed)
+
+    clamped_rate = 0.0 if math.isnan(effective_rate) else max(0.0, min(1.0, effective_rate))
+    if _ekkokin_rust is not None:
+        return cast(
+            str,
+            _ekkokin_rust(text, clamped_rate, normalized_weighting, active_rng),
+        )
+    return _python_substitute_homophones(
+        text,
+        rate=clamped_rate,
+        weighting=normalized_weighting,
+        rng=active_rng,
+    )
+
+
+class Ekkokin(Glitchling):
+    """Glitchling that swaps words for curated homophones."""
+
+    def __init__(
+        self,
+        *,
+        rate: float | None = None,
+        seed: int | None = None,
+        weighting: str | None = None,
+    ) -> None:
+        effective_rate = _DEFAULT_RATE if rate is None else rate
+        normalized_weighting = _normalise_weighting(weighting)
+        super().__init__(
+            name="Ekkokin",
+            corruption_function=substitute_homophones,
+            scope=AttackWave.WORD,
+            order=AttackOrder.EARLY,
+            seed=seed,
+            pipeline_operation=_build_pipeline_descriptor,
+            rate=effective_rate,
+            weighting=normalized_weighting,
+        )
+
+    def set_param(self, key: str, value: Any) -> None:
+        """Normalise weighting updates before storing them on the glitchling."""
+        if key == "weighting":
+            value = _normalise_weighting(cast(str | None, value))
+        super().set_param(key, value)
+
+
+def _build_pipeline_descriptor(glitch: Glitchling) -> dict[str, object] | None:
+    rate = glitch.kwargs.get("rate")
+    if rate is None:
+        return None
+    weighting = _normalise_weighting(cast(str | None, glitch.kwargs.get("weighting")))
+    return {
+        "type": "ekkokin",
+        "rate": float(rate),
+        "weighting": str(weighting),
+    }
+
+
+ekkokin = Ekkokin()
+
+
+__all__ = [
+    "Ekkokin",
+    "ekkokin",
+    "substitute_homophones",
+    "_python_substitute_homophones",
+]

glitchlings/zoo/jargoyle.py

@@ -7,7 +7,6 @@ from typing import Any, Literal, cast
 
 from glitchlings.lexicon import Lexicon, get_default_lexicon
 
-from ._rate import resolve_rate
 from .core import AttackWave, Glitchling
 
 _wordnet_module: ModuleType | None
@@ -119,7 +118,6 @@ def substitute_random_synonyms(
     seed: int | None = None,
     rng: random.Random | None = None,
     *,
-    replacement_rate: float | None = None,
     lexicon: Lexicon | None = None,
 ) -> str:
     """Replace words with random lexicon-driven synonyms.
@@ -144,12 +142,7 @@ def substitute_random_synonyms(
       deterministic subsets per word and part-of-speech using the active seed.
 
     """
-    effective_rate = resolve_rate(
-        rate=rate,
-        legacy_value=replacement_rate,
-        default=0.1,
-        legacy_name="replacement_rate",
-    )
+    effective_rate = 0.1 if rate is None else rate
 
     active_rng: random.Random
     if rng is not None:
@@ -258,23 +251,16 @@ class Jargoyle(Glitchling):
         self,
         *,
         rate: float | None = None,
-        replacement_rate: float | None = None,
         part_of_speech: PartOfSpeechInput = "n",
         seed: int | None = None,
         lexicon: Lexicon | None = None,
     ) -> None:
-        self._param_aliases = {"replacement_rate": "rate"}
         self._owns_lexicon = lexicon is None
         self._external_lexicon_original_seed = (
             lexicon.seed if isinstance(lexicon, Lexicon) else None
         )
         self._initializing = True
-        effective_rate = resolve_rate(
-            rate=rate,
-            legacy_value=replacement_rate,
-            default=0.01,
-            legacy_name="replacement_rate",
-        )
+        effective_rate = 0.01 if rate is None else rate
         prepared_lexicon = lexicon or get_default_lexicon(seed=seed)
         if lexicon is not None and seed is not None:
             prepared_lexicon.reseed(seed)

glitchlings/zoo/mim1c.py

@@ -4,7 +4,6 @@ from typing import Literal
 
 from confusable_homoglyphs import confusables
 
-from ._rate import resolve_rate
 from .core import AttackOrder, AttackWave, Glitchling
 
 
@@ -15,8 +14,6 @@ def swap_homoglyphs(
     banned_characters: Collection[str] | None = None,
     seed: int | None = None,
     rng: random.Random | None = None,
-    *,
-    replacement_rate: float | None = None,
 ) -> str:
     """Replace characters with visually confusable homoglyphs.
 
@@ -37,12 +34,7 @@ def swap_homoglyphs(
     - Maintains determinism by shuffling candidates and sampling via the provided RNG.
 
     """
-    effective_rate = resolve_rate(
-        rate=rate,
-        legacy_value=replacement_rate,
-        default=0.02,
-        legacy_name="replacement_rate",
-    )
+    effective_rate = 0.02 if rate is None else rate
 
     if rng is None:
         rng = random.Random(seed)
@@ -79,18 +71,11 @@ class Mim1c(Glitchling):
         self,
         *,
         rate: float | None = None,
-        replacement_rate: float | None = None,
         classes: list[str] | Literal["all"] | None = None,
         banned_characters: Collection[str] | None = None,
         seed: int | None = None,
     ) -> None:
-        self._param_aliases = {"replacement_rate": "rate"}
-        effective_rate = resolve_rate(
-            rate=rate,
-            legacy_value=replacement_rate,
-            default=0.02,
-            legacy_name="replacement_rate",
-        )
+        effective_rate = 0.02 if rate is None else rate
         super().__init__(
             name="Mim1c",
             corruption_function=swap_homoglyphs,

glitchlings/zoo/redactyl.py

@@ -2,7 +2,6 @@ import random
 import re
 from typing import Any, cast
 
-from ._rate import resolve_rate
 from ._rust_extensions import get_rust_operation
 from ._sampling import weighted_sample_without_replacement
 from ._text_utils import (
@@ -97,16 +96,10 @@ def redact_words(
     seed: int = 151,
     rng: random.Random | None = None,
     *,
-    redaction_rate: float | None = None,
     unweighted: bool = False,
 ) -> str:
     """Redact random words by replacing their characters."""
-    effective_rate = resolve_rate(
-        rate=rate,
-        legacy_value=redaction_rate,
-        default=0.025,
-        legacy_name="redaction_rate",
-    )
+    effective_rate = 0.025 if rate is None else rate
 
     if rng is None:
         rng = random.Random(seed)
@@ -148,18 +141,11 @@ class Redactyl(Glitchling):
         *,
         replacement_char: str = FULL_BLOCK,
         rate: float | None = None,
-        redaction_rate: float | None = None,
         merge_adjacent: bool = False,
         seed: int = 151,
         unweighted: bool = False,
     ) -> None:
-        self._param_aliases = {"redaction_rate": "rate"}
-        effective_rate = resolve_rate(
-            rate=rate,
-            legacy_value=redaction_rate,
-            default=0.025,
-            legacy_name="redaction_rate",
-        )
+        effective_rate = 0.025 if rate is None else rate
         super().__init__(
             name="Redactyl",
             corruption_function=redact_words,
@@ -181,7 +167,7 @@ class Redactyl(Glitchling):
         return {
             "type": "redact",
             "replacement_char": str(replacement_char),
-            "redaction_rate": float(rate),
+            "rate": float(rate),
             "merge_adjacent": bool(merge_adjacent),
             "unweighted": unweighted,
         }

glitchlings/zoo/reduple.py

@@ -1,7 +1,6 @@
 import random
 from typing import Any, cast
 
-from ._rate import resolve_rate
 from ._rust_extensions import get_rust_operation
 from ._text_utils import WordToken, collect_word_tokens, split_preserving_whitespace
 from .core import AttackWave, Glitchling
@@ -71,7 +70,6 @@ def reduplicate_words(
     seed: int | None = None,
     rng: random.Random | None = None,
     *,
-    reduplication_rate: float | None = None,
     unweighted: bool = False,
 ) -> str:
     """Randomly reduplicate words in the text.
@@ -79,12 +77,7 @@ def reduplicate_words(
     Falls back to the Python implementation when the optional Rust
     extension is unavailable.
     """
-    effective_rate = resolve_rate(
-        rate=rate,
-        legacy_value=reduplication_rate,
-        default=0.01,
-        legacy_name="reduplication_rate",
-    )
+    effective_rate = 0.01 if rate is None else rate
 
     if rng is None:
         rng = random.Random(seed)
@@ -110,17 +103,10 @@ class Reduple(Glitchling):
         self,
         *,
         rate: float | None = None,
-        reduplication_rate: float | None = None,
         seed: int | None = None,
         unweighted: bool = False,
     ) -> None:
-        self._param_aliases = {"reduplication_rate": "rate"}
-        effective_rate = resolve_rate(
-            rate=rate,
-            legacy_value=reduplication_rate,
-            default=0.01,
-            legacy_name="reduplication_rate",
-        )
+        effective_rate = 0.01 if rate is None else rate
         super().__init__(
             name="Reduple",
             corruption_function=reduplicate_words,
@@ -137,7 +123,7 @@ class Reduple(Glitchling):
         unweighted = bool(self.kwargs.get("unweighted", False))
         return {
             "type": "reduplicate",
-            "reduplication_rate": float(rate),
+            "rate": float(rate),
             "unweighted": unweighted,
         }
 

glitchlings/zoo/rushmore.py

@@ -3,7 +3,6 @@ import random
 import re
 from typing import Any, cast
 
-from ._rate import resolve_rate
 from ._rust_extensions import get_rust_operation
 from ._text_utils import WordToken, collect_word_tokens, split_preserving_whitespace
 from .core import AttackWave, Glitchling
@@ -74,20 +73,13 @@ def delete_random_words(
     rate: float | None = None,
     seed: int | None = None,
     rng: random.Random | None = None,
-    *,
-    max_deletion_rate: float | None = None,
     unweighted: bool = False,
 ) -> str:
     """Delete random words from the input text.
 
     Uses the optional Rust implementation when available.
     """
-    effective_rate = resolve_rate(
-        rate=rate,
-        legacy_value=max_deletion_rate,
-        default=0.01,
-        legacy_name="max_deletion_rate",
-    )
+    effective_rate = 0.01 if rate is None else rate
 
     if rng is None:
         rng = random.Random(seed)
@@ -113,17 +105,10 @@ class Rushmore(Glitchling):
         self,
         *,
         rate: float | None = None,
-        max_deletion_rate: float | None = None,
         seed: int | None = None,
         unweighted: bool = False,
     ) -> None:
-        self._param_aliases = {"max_deletion_rate": "rate"}
-        effective_rate = resolve_rate(
-            rate=rate,
-            legacy_value=max_deletion_rate,
-            default=0.01,
-            legacy_name="max_deletion_rate",
-        )
+        effective_rate = 0.01 if rate is None else rate
         super().__init__(
             name="Rushmore",
             corruption_function=delete_random_words,
@@ -135,14 +120,12 @@ class Rushmore(Glitchling):
 
     def pipeline_operation(self) -> dict[str, Any] | None:
         rate = self.kwargs.get("rate")
-        if rate is None:
-            rate = self.kwargs.get("max_deletion_rate")
         if rate is None:
             return None
         unweighted = bool(self.kwargs.get("unweighted", False))
         return {
             "type": "delete",
-            "max_deletion_rate": float(rate),
+            "rate": float(rate),
             "unweighted": unweighted,
         }
 

glitchlings/zoo/scannequin.py

@@ -3,7 +3,6 @@ import re
 from typing import Any, cast
 
 from ._ocr_confusions import load_confusion_table
-from ._rate import resolve_rate
 from ._rust_extensions import get_rust_operation
 from .core import AttackOrder, AttackWave, Glitchling
 
@@ -102,8 +101,6 @@ def ocr_artifacts(
     rate: float | None = None,
     seed: int | None = None,
     rng: random.Random | None = None,
-    *,
-    error_rate: float | None = None,
 ) -> str:
     """Introduce OCR-like artifacts into text.
 
@@ -112,12 +109,7 @@ def ocr_artifacts(
     if not text:
         return text
 
-    effective_rate = resolve_rate(
-        rate=rate,
-        legacy_value=error_rate,
-        default=0.02,
-        legacy_name="error_rate",
-    )
+    effective_rate = 0.02 if rate is None else rate
 
     if rng is None:
         rng = random.Random(seed)
@@ -137,16 +129,9 @@ class Scannequin(Glitchling):
         self,
         *,
         rate: float | None = None,
-        error_rate: float | None = None,
         seed: int | None = None,
     ) -> None:
-        self._param_aliases = {"error_rate": "rate"}
-        effective_rate = resolve_rate(
-            rate=rate,
-            legacy_value=error_rate,
-            default=0.02,
-            legacy_name="error_rate",
-        )
+        effective_rate = 0.02 if rate is None else rate
         super().__init__(
             name="Scannequin",
             corruption_function=ocr_artifacts,
@@ -158,11 +143,9 @@ class Scannequin(Glitchling):
 
     def pipeline_operation(self) -> dict[str, Any] | None:
         rate = self.kwargs.get("rate")
-        if rate is None:
-            rate = self.kwargs.get("error_rate")
         if rate is None:
             return None
-        return {"type": "ocr", "error_rate": float(rate)}
+        return {"type": "ocr", "rate": float(rate)}
 
 
 scannequin = Scannequin()