glitchlings 0.4.2__cp312-cp312-macosx_11_0_universal2.whl → 0.4.3__cp312-cp312-macosx_11_0_universal2.whl

glitchlings/lexicon/wordnet.py

@@ -4,49 +4,74 @@ from __future__ import annotations
 
 from importlib import import_module
 from pathlib import Path
-from typing import TYPE_CHECKING, Any
+from types import ModuleType
+from typing import Any, Callable, Protocol, Sequence, cast
 
 from ..compat import nltk as _nltk_dependency
 from . import LexiconBackend
 from ._cache import CacheSnapshot
 
-nltk = _nltk_dependency.get()  # type: ignore[assignment]
-_NLTK_IMPORT_ERROR = _nltk_dependency.error
 
-if TYPE_CHECKING:  # pragma: no cover - typing aid only
-    from nltk.corpus.reader import WordNetCorpusReader  # type: ignore[import]
-else:  # pragma: no cover - runtime fallback to avoid hard dependency
-    WordNetCorpusReader = Any
+class _LemmaProtocol(Protocol):
+    def name(self) -> str:
+        ...
 
-find: Any | None = None
-_WORDNET_MODULE: Any | None = None
+
+class _SynsetProtocol(Protocol):
+    def lemmas(self) -> Sequence[_LemmaProtocol]:
+        ...
+
+
+class _WordNetResource(Protocol):
+    def synsets(self, word: str, pos: str | None = None) -> Sequence[_SynsetProtocol]:
+        ...
+
+    def ensure_loaded(self) -> None:
+        ...
+
+
+WordNetCorpusReaderFactory = Callable[[Any, Any], _WordNetResource]
+
+nltk: ModuleType | None = _nltk_dependency.get()
+_NLTK_IMPORT_ERROR: ModuleNotFoundError | None = _nltk_dependency.error
+
+WordNetCorpusReader: WordNetCorpusReaderFactory | None = None
+find: Callable[[str], Any] | None = None
+_WORDNET_MODULE: _WordNetResource | None = None
 
 if nltk is not None:  # pragma: no cover - guarded by import success
     try:
         corpus_reader_module = import_module("nltk.corpus.reader")
-        WordNetCorpusReader = corpus_reader_module.WordNetCorpusReader  # type: ignore[assignment]
     except ModuleNotFoundError as exc:  # pragma: no cover - triggered when corpus missing
         if _NLTK_IMPORT_ERROR is None:
-            _NLTK_IMPORT_ERROR = exc  # type: ignore[assignment]
+            _NLTK_IMPORT_ERROR = exc
     else:
+        reader_candidate = getattr(corpus_reader_module, "WordNetCorpusReader", None)
+        if reader_candidate is not None:
+            WordNetCorpusReader = cast(WordNetCorpusReaderFactory, reader_candidate)
+
         try:
             data_module = import_module("nltk.data")
         except ModuleNotFoundError as exc:  # pragma: no cover - triggered when data missing
             if _NLTK_IMPORT_ERROR is None:
-                _NLTK_IMPORT_ERROR = exc  # type: ignore[assignment]
+                _NLTK_IMPORT_ERROR = exc
         else:
-            find = getattr(data_module, "find", None)
+            locator = getattr(data_module, "find", None)
+            if callable(locator):
+                find = cast(Callable[[str], Any], locator)
 
     try:
-        _WORDNET_MODULE = import_module("nltk.corpus.wordnet")
+        module_candidate = import_module("nltk.corpus.wordnet")
     except ModuleNotFoundError:  # pragma: no cover - only hit on namespace packages
         _WORDNET_MODULE = None
+    else:
+        _WORDNET_MODULE = cast(_WordNetResource, module_candidate)
 else:
-    nltk = None  # type: ignore[assignment]
+    nltk = None
     find = None
     _WORDNET_MODULE = None
 
-_WORDNET_HANDLE: WordNetCorpusReader | Any | None = _WORDNET_MODULE
+_WORDNET_HANDLE: _WordNetResource | None = _WORDNET_MODULE
 _wordnet_ready = False
 
 _VALID_POS: tuple[str, ...] = ("n", "v", "a", "r")
@@ -69,15 +94,22 @@ def dependencies_available() -> bool:
     return nltk is not None and find is not None
 
 
-def _load_wordnet_reader() -> WordNetCorpusReader:
+def _load_wordnet_reader() -> _WordNetResource:
     """Return a WordNet corpus reader from the downloaded corpus files."""
     _require_nltk()
 
+    if WordNetCorpusReader is None:
+        raise RuntimeError("The NLTK WordNet corpus reader is unavailable.")
+
+    locator = find
+    if locator is None:
+        raise RuntimeError("The NLTK data locator is unavailable.")
+
     try:
-        root = find("corpora/wordnet")
+        root = locator("corpora/wordnet")
     except LookupError:
         try:
-            zip_root = find("corpora/wordnet.zip")
+            zip_root = locator("corpora/wordnet.zip")
         except LookupError as exc:
             raise RuntimeError(
                 "The NLTK WordNet corpus is not installed; run `nltk.download('wordnet')`."
@@ -87,18 +119,20 @@ def _load_wordnet_reader() -> WordNetCorpusReader:
     return WordNetCorpusReader(root, None)
 
 
-def _wordnet(force_refresh: bool = False) -> WordNetCorpusReader | Any:
+def _wordnet(force_refresh: bool = False) -> _WordNetResource:
     """Retrieve the active WordNet handle, rebuilding it on demand."""
     global _WORDNET_HANDLE
 
     if force_refresh:
         _WORDNET_HANDLE = _WORDNET_MODULE
 
-    if _WORDNET_HANDLE is not None:
-        return _WORDNET_HANDLE
+    cached = _WORDNET_HANDLE
+    if cached is not None:
+        return cached
 
-    _WORDNET_HANDLE = _load_wordnet_reader()
-    return _WORDNET_HANDLE
+    resource = _load_wordnet_reader()
+    _WORDNET_HANDLE = resource
+    return resource
 
 
 def ensure_wordnet() -> None:
@@ -110,11 +144,14 @@ def ensure_wordnet() -> None:
     _require_nltk()
 
     resource = _wordnet()
+    nltk_module = nltk
+    if nltk_module is None:
+        raise RuntimeError("The NLTK dependency is unexpectedly unavailable.")
 
     try:
         resource.ensure_loaded()
     except LookupError:
-        nltk.download("wordnet", quiet=True)
+        nltk_module.download("wordnet", quiet=True)
         try:
             resource = _wordnet(force_refresh=True)
             resource.ensure_loaded()
@@ -159,6 +196,7 @@ class WordNetLexicon(LexiconBackend):
     """Lexicon that retrieves synonyms from the NLTK WordNet corpus."""
 
     def get_synonyms(self, word: str, pos: str | None = None, n: int = 5) -> list[str]:
+        """Return up to ``n`` WordNet lemmas for ``word`` filtered by ``pos`` if provided."""
         ensure_wordnet()
 
         if pos is None:
@@ -173,15 +211,18 @@ class WordNetLexicon(LexiconBackend):
         return self._deterministic_sample(synonyms, limit=n, word=word, pos=pos)
 
     def supports_pos(self, pos: str | None) -> bool:
+        """Return ``True`` when ``pos`` is unset or recognised by the WordNet corpus."""
         if pos is None:
             return True
         return pos.lower() in _VALID_POS
 
     @classmethod
     def load_cache(cls, path: str | Path) -> CacheSnapshot:
+        """WordNet lexicons do not persist caches; raising keeps the contract explicit."""
         raise RuntimeError("WordNetLexicon does not persist or load caches.")
 
     def save_cache(self, path: str | Path | None = None) -> Path | None:
+        """WordNet lexicons do not persist caches; raising keeps the contract explicit."""
         raise RuntimeError("WordNetLexicon does not persist or load caches.")
 
     def __repr__(self) -> str:  # pragma: no cover - trivial representation

glitchlings/main.py

@@ -5,7 +5,9 @@ from __future__ import annotations
 import argparse
 import difflib
 import sys
+from collections.abc import Sequence
 from pathlib import Path
+from typing import cast
 
 from . import SAMPLE_TEXT
 from .config import DEFAULT_ATTACK_SEED, build_gaggle, load_attack_config
@@ -88,6 +90,7 @@ def build_parser() -> argparse.ArgumentParser:
 
 
 def build_lexicon_parser() -> argparse.ArgumentParser:
+    """Create the ``build-lexicon`` subcommand parser with vector cache options."""
     builder = argparse.ArgumentParser(
         prog="glitchlings build-lexicon",
         description=(
@@ -179,21 +182,23 @@ def read_text(args: argparse.Namespace, parser: argparse.ArgumentParser) -> str:
         SystemExit: Raised indirectly via ``parser.error`` on failure.
 
     """
-    if args.file is not None:
+    file_path = cast(Path | None, getattr(args, "file", None))
+    if file_path is not None:
         try:
-            return args.file.read_text(encoding="utf-8")
+            return file_path.read_text(encoding="utf-8")
         except OSError as exc:
-            filename = getattr(exc, "filename", None) or args.file
+            filename = getattr(exc, "filename", None) or file_path
             reason = exc.strerror or str(exc)
             parser.error(f"Failed to read file {filename}: {reason}")
 
-    if args.text:
-        return args.text
+    text_argument = cast(str | None, getattr(args, "text", None))
+    if text_argument:
+        return text_argument
 
     if not sys.stdin.isatty():
         return sys.stdin.read()
 
-    if args.sample:
+    if bool(getattr(args, "sample", False)):
         return SAMPLE_TEXT
 
     parser.error(
@@ -224,21 +229,23 @@ def summon_glitchlings(
 
         return build_gaggle(config, seed_override=seed)
 
+    normalized: Sequence[str | Glitchling]
     if names:
-        normalized: list[str | Glitchling] = []
+        parsed: list[str | Glitchling] = []
         for specification in names:
             try:
-                normalized.append(parse_glitchling_spec(specification))
+                parsed.append(parse_glitchling_spec(specification))
             except ValueError as exc:
                 parser.error(str(exc))
                 raise AssertionError("parser.error should exit")
+        normalized = parsed
     else:
-        normalized = DEFAULT_GLITCHLING_NAMES
+        normalized = list(DEFAULT_GLITCHLING_NAMES)
 
     effective_seed = seed if seed is not None else DEFAULT_ATTACK_SEED
 
     try:
-        return summon(normalized, seed=effective_seed)
+        return summon(list(normalized), seed=effective_seed)
     except ValueError as exc:
         parser.error(str(exc))
         raise AssertionError("parser.error should exit")
@@ -285,7 +292,10 @@ def run_cli(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
         config_path=args.config,
     )
 
-    corrupted = gaggle(text)
+    corrupted = gaggle.corrupt(text)
+    if not isinstance(corrupted, str):
+        message = "Gaggle returned non-string output for string input"
+        raise TypeError(message)
 
     if args.diff:
         show_diff(text, corrupted)

glitchlings/zoo/__init__.py

@@ -4,6 +4,7 @@ import ast
 from typing import Any
 
 from .adjax import Adjax, adjax
+from .apostrofae import Apostrofae, apostrofae
 from .core import (
     Gaggle,
     Glitchling,
@@ -30,6 +31,8 @@ __all__ = [
     "mim1c",
     "Jargoyle",
     "jargoyle",
+    "Apostrofae",
+    "apostrofae",
     "Adjax",
     "adjax",
     "Reduple",
@@ -58,7 +61,7 @@ __all__ = [
 
 _HAS_JARGOYLE = _jargoyle_available()
 
-_BUILTIN_GLITCHLING_LIST: list[Glitchling] = [typogre, mim1c]
+_BUILTIN_GLITCHLING_LIST: list[Glitchling] = [typogre, apostrofae, mim1c]
 if _HAS_JARGOYLE:
     _BUILTIN_GLITCHLING_LIST.append(jargoyle)
 _BUILTIN_GLITCHLING_LIST.extend([adjax, reduple, rushmore, redactyl, scannequin, zeedub])
@@ -69,6 +72,7 @@ BUILTIN_GLITCHLINGS: dict[str, Glitchling] = {
 
 _BUILTIN_GLITCHLING_TYPES: dict[str, type[Glitchling]] = {
     typogre.name.lower(): Typogre,
+    apostrofae.name.lower(): Apostrofae,
     mim1c.name.lower(): Mim1c,
     adjax.name.lower(): Adjax,
     reduple.name.lower(): Reduple,

glitchlings/zoo/adjax.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import random
-from typing import Any
+from typing import Any, cast
 
 from ._rate import resolve_rate
 from ._text_utils import split_preserving_whitespace, split_token_edges
@@ -83,7 +83,7 @@ def swap_adjacent_words(
         rng = random.Random(seed)
 
     if _swap_adjacent_words_rust is not None:
-        return _swap_adjacent_words_rust(text, clamped_rate, rng)
+        return cast(str, _swap_adjacent_words_rust(text, clamped_rate, rng))
 
     return _python_swap_adjacent_words(text, rate=clamped_rate, rng=rng)
 

glitchlings/zoo/apostrofae.py

@@ -0,0 +1,128 @@
+"""Smart-quote glitchling that swaps straight quotes for fancy counterparts."""
+
+from __future__ import annotations
+
+import json
+import random
+from functools import cache
+from importlib import resources
+from typing import Any, Sequence, cast
+
+from .core import AttackOrder, AttackWave, Gaggle, Glitchling
+
+try:  # pragma: no cover - compiled extension not present in pure-Python envs
+    from glitchlings._zoo_rust import apostrofae as _apostrofae_rust
+except ImportError:  # pragma: no cover - compiled extension not present
+    _apostrofae_rust = None
+
+
+@cache
+def _load_replacement_pairs() -> dict[str, list[tuple[str, str]]]:
+    """Load the curated mapping of straight quotes to fancy pairs."""
+
+    resource = resources.files(f"{__package__}.assets").joinpath("apostrofae_pairs.json")
+    with resource.open("r", encoding="utf-8") as handle:
+        data: dict[str, list[Sequence[str]]] = json.load(handle)
+
+    parsed: dict[str, list[tuple[str, str]]] = {}
+    for straight, replacements in data.items():
+        parsed[straight] = [(pair[0], pair[1]) for pair in replacements if len(pair) == 2]
+    return parsed
+
+
+def _find_quote_pairs(text: str) -> list[tuple[int, int, str]]:
+    """Return all balanced pairs of straight quotes in ``text``.
+
+    The search walks the string once, pairing sequential occurrences of each quote
+    glyph. Unmatched openers remain untouched so contractions (e.g. ``it's``)
+    survive unmodified.
+    """
+
+    stacks: dict[str, int | None] = {'"': None, "'": None, "`": None}
+    pairs: list[tuple[int, int, str]] = []
+
+    for index, ch in enumerate(text):
+        if ch not in stacks:
+            continue
+        start = stacks[ch]
+        if start is None:
+            stacks[ch] = index
+        else:
+            pairs.append((start, index, ch))
+            stacks[ch] = None
+
+    return pairs
+
+
+def _apostrofae_python(text: str, *, rng: random.Random) -> str:
+    """Python fallback that replaces paired straight quotes with fancy glyphs."""
+
+    pairs = _load_replacement_pairs()
+    candidates = _find_quote_pairs(text)
+    if not candidates:
+        return text
+
+    chars = list(text)
+    for start, end, glyph in candidates:
+        options = pairs.get(glyph)
+        if not options:
+            continue
+        left, right = rng.choice(options)
+        chars[start] = left
+        chars[end] = right
+    return "".join(chars)
+
+
+def smart_quotes(
+    text: str,
+    seed: int | None = None,
+    rng: random.Random | None = None,
+) -> str:
+    """Replace straight quotes, apostrophes, and backticks with fancy pairs."""
+
+    if not text:
+        return text
+
+    if rng is None:
+        rng = random.Random(seed)
+
+    if _apostrofae_rust is not None:
+        return cast(str, _apostrofae_rust(text, rng))
+
+    return _apostrofae_python(text, rng=rng)
+
+
+class Apostrofae(Glitchling):
+    """Glitchling that swaps straight quotes for decorative Unicode pairs."""
+
+    def __init__(self, *, seed: int | None = None) -> None:
+        self._master_seed: int | None = seed
+        super().__init__(
+            name="Apostrofae",
+            corruption_function=smart_quotes,
+            scope=AttackWave.CHARACTER,
+            order=AttackOrder.NORMAL,
+            seed=seed,
+        )
+
+    def pipeline_operation(self) -> dict[str, Any] | None:
+        return {"type": "apostrofae"}
+
+    def reset_rng(self, seed: int | None = None) -> None:  # pragma: no cover - exercised indirectly
+        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)
+
+
+apostrofae = Apostrofae()
+
+
+__all__ = ["Apostrofae", "apostrofae", "smart_quotes"]

glitchlings/zoo/assets/apostrofae_pairs.json

@@ -0,0 +1,32 @@
+{
+  "\"": [
+    ["“", "”"],
+    ["„", "“"],
+    ["«", "»"],
+    ["‹", "›"],
+    ["『", "』"],
+    ["「", "」"],
+    ["﹁", "﹂"],
+    ["﹃", "﹄"],
+    ["〝", "〞"],
+    ["❝", "❞"]
+  ],
+  "'": [
+    ["‘", "’"],
+    ["‚", "‘"],
+    ["‹", "›"],
+    ["❮", "❯"],
+    ["❛", "❜"],
+    ["﹇", "﹈"]
+  ],
+  "`": [
+    ["‵", "′"],
+    ["﹁", "﹂"],
+    ["﹃", "﹄"],
+    ["⌈", "⌉"],
+    ["⌊", "⌋"],
+    ["⎡", "⎤"],
+    ["⎣", "⎦"],
+    ["〝", "〞"]
+  ]
+}

glitchlings/zoo/core.py

@@ -7,7 +7,7 @@ import random
 from collections.abc import Mapping, Sequence
 from enum import IntEnum, auto
 from hashlib import blake2s
-from typing import TYPE_CHECKING, Any, Callable, Protocol, TypedDict, Union
+from typing import TYPE_CHECKING, Any, Callable, Protocol, TypedDict, TypeGuard, Union, cast
 
 from ..compat import get_datasets_dataset, require_datasets
 
@@ -35,6 +35,9 @@ class PlanSpecification(TypedDict):
     order: int
 
 
+TranscriptTurn = dict[str, Any]
+Transcript = list[TranscriptTurn]
+
 PlanEntry = Union["Glitchling", Mapping[str, Any]]
 
 
@@ -186,7 +189,7 @@ def plan_glitchlings(
 
 
 if TYPE_CHECKING:  # pragma: no cover - typing only
-    from datasets import Dataset  # type: ignore
+    from datasets import Dataset
 elif _DatasetsDataset is not None:
     Dataset = _DatasetsDataset
 else:
@@ -202,8 +205,8 @@ def _is_transcript(
     *,
     allow_empty: bool = True,
     require_all_content: bool = False,
-) -> bool:
-    """Return `True` when `value` appears to be a chat transcript."""
+) -> TypeGuard[Transcript]:
+    """Return ``True`` when ``value`` appears to be a chat transcript."""
     if not isinstance(value, list):
         return False
 
@@ -351,15 +354,17 @@ class Glitchling:
             corrupted = self.corruption_function(text, *args, **kwargs)
         return corrupted
 
-    def corrupt(self, text: str | list[dict[str, Any]]) -> str | list[dict[str, Any]]:
+    def corrupt(self, text: str | Transcript) -> str | Transcript:
         """Apply the corruption function to text or conversational transcripts."""
         if _is_transcript(text):
-            transcript = [dict(turn) for turn in text]
+            transcript: Transcript = [dict(turn) for turn in text]
             if transcript:
-                transcript[-1]["content"] = self.__corrupt(transcript[-1]["content"], **self.kwargs)
+                content = transcript[-1].get("content")
+                if isinstance(content, str):
+                    transcript[-1]["content"] = self.__corrupt(content, **self.kwargs)
             return transcript
 
-        return self.__corrupt(text, **self.kwargs)
+        return self.__corrupt(cast(str, text), **self.kwargs)
 
     def corrupt_dataset(self, dataset: Dataset, columns: list[str]) -> Dataset:
         """Apply corruption lazily across dataset columns."""
@@ -383,7 +388,7 @@ class Glitchling:
 
         return dataset.with_transform(__corrupt_row)
 
-    def __call__(self, text: str, *args: Any, **kwds: Any) -> str | list[dict[str, Any]]:
+    def __call__(self, text: str, *args: Any, **kwds: Any) -> str | Transcript:
         """Allow a glitchling to be invoked directly like a callable."""
         return self.corrupt(text, *args, **kwds)
 
@@ -426,7 +431,7 @@ class Gaggle(Glitchling):
             seed: Master seed used to derive per-glitchling seeds.
 
         """
-        super().__init__("Gaggle", self.corrupt, AttackWave.DOCUMENT, seed=seed)
+        super().__init__("Gaggle", self._corrupt_text, AttackWave.DOCUMENT, seed=seed)
         self._clones_by_index: list[Glitchling] = []
         for idx, glitchling in enumerate(glitchlings):
             clone = glitchling.clone()
@@ -528,17 +533,38 @@ class Gaggle(Glitchling):
 
         return descriptors
 
-    def corrupt(self, text: str) -> str:
-        """Apply each glitchling to the provided text sequentially."""
+    def _corrupt_text(self, text: str) -> str:
+        """Apply each glitchling to string input sequentially."""
         master_seed = self.seed
         descriptors = self._pipeline_descriptors()
         if master_seed is not None and descriptors is not None:
             try:
-                return _compose_glitchlings_rust(text, descriptors, master_seed)
+                return cast(str, _compose_glitchlings_rust(text, descriptors, master_seed))
             except Exception:  # pragma: no cover - fall back to Python execution
                 log.debug("Rust pipeline failed; falling back", exc_info=True)
 
         corrupted = text
         for glitchling in self.apply_order:
-            corrupted = glitchling(corrupted)
+            next_value = glitchling.corrupt(corrupted)
+            if not isinstance(next_value, str):
+                message = "Glitchling pipeline produced non-string output for string input"
+                raise TypeError(message)
+            corrupted = next_value
+
         return corrupted
+
+    def corrupt(self, text: str | Transcript) -> str | Transcript:
+        """Apply each glitchling to the provided text sequentially."""
+        if isinstance(text, str):
+            return self._corrupt_text(text)
+
+        if _is_transcript(text):
+            transcript: Transcript = [dict(turn) for turn in text]
+            if transcript and "content" in transcript[-1]:
+                content = transcript[-1]["content"]
+                if isinstance(content, str):
+                    transcript[-1]["content"] = self._corrupt_text(content)
+            return transcript
+
+        message = f"Unsupported text type for Gaggle corruption: {type(text)!r}"
+        raise TypeError(message)