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

glitchlings/lexicon/graph.py

@@ -2,22 +2,22 @@
 
 from __future__ import annotations
 
-import json
 import re
 from pathlib import Path
 from typing import Iterable, Mapping, MutableMapping, Sequence
 
-from . import Lexicon
+from . import LexiconBackend
+from ._cache import CacheSnapshot
+from ._cache import load_cache as _load_cache_file
+from ._cache import write_cache as _write_cache_file
 from .vector import VectorLexicon
 
-
 _CONCEPT_RE = re.compile(r"^/c/(?P<lang>[a-z]{2})/(?P<term>[^/]+)")
 _PUNCTUATION_RE = re.compile(r"[^\w\s-]+", re.UNICODE)
 
 
 def _lemmatize_token(token: str) -> str:
     """Return a lightweight lemma for ``token`` using heuristic rules."""
-
     irregular = {
         "children": "child",
         "mice": "mouse",
@@ -60,7 +60,6 @@ def _lemmatize_token(token: str) -> str:
 
 def _normalize_phrase(phrase: str) -> str:
     """Normalise ``phrase`` for ConceptNet lookups."""
-
     stripped = _PUNCTUATION_RE.sub(" ", phrase.lower())
     tokens = [token for token in stripped.split() if token]
     if not tokens:
@@ -71,7 +70,6 @@ def _normalize_phrase(phrase: str) -> str:
 
 def _concept_terms(normalized: str) -> list[str]:
     """Return ConceptNet term variants for ``normalized``."""
-
     collapsed = normalized.replace(" ", "_")
     if not collapsed:
         return []
@@ -83,7 +81,6 @@ def _concept_terms(normalized: str) -> list[str]:
 
 def _surface_from_concept(concept: str) -> str | None:
     """Return a human-readable surface form for ``concept``."""
-
     match = _CONCEPT_RE.match(concept)
     if match is None:
         return None
@@ -102,7 +99,6 @@ def _language_from_concept(concept: str) -> str | None:
 
 def _load_numberbatch(path: Path, *, languages: set[str]) -> Mapping[str, list[float]]:
     """Load ConceptNet Numberbatch embeddings from ``path``."""
-
     if not path.exists():
         return {}
 
@@ -140,30 +136,7 @@ def _load_numberbatch(path: Path, *, languages: set[str]) -> Mapping[str, list[f
     return embeddings
 
 
-def _load_cache(path: Path) -> dict[str, list[str]]:
-    if not path.exists():
-        return {}
-    with path.open("r", encoding="utf8") as handle:
-        payload = json.load(handle)
-    if not isinstance(payload, Mapping):
-        raise RuntimeError("Graph lexicon cache must be a mapping of strings to lists.")
-    cache: dict[str, list[str]] = {}
-    for key, values in payload.items():
-        if not isinstance(key, str):
-            raise RuntimeError("Graph lexicon cache keys must be strings.")
-        if not isinstance(values, Sequence):
-            raise RuntimeError("Graph lexicon cache values must be sequences of strings.")
-        cache[key] = [str(value) for value in values]
-    return cache
-
-
-def _write_cache(path: Path, cache: Mapping[str, Sequence[str]]) -> None:
-    serialisable = {key: list(values) for key, values in sorted(cache.items())}
-    with path.open("w", encoding="utf8") as handle:
-        json.dump(serialisable, handle, ensure_ascii=False, indent=2, sort_keys=True)
-
-
-class GraphLexicon(Lexicon):
+class GraphLexicon(LexiconBackend):
     """Lexicon backed by ConceptNet/Numberbatch embeddings."""
 
     def __init__(
@@ -184,9 +157,12 @@ class GraphLexicon(Lexicon):
         self._max_neighbors = max(1, max_neighbors)
         self._min_similarity = min_similarity
         self._cache: MutableMapping[str, list[str]] = {}
-        self._cache_path = Path(cache_path) if cache_path is not None else None
+        self._cache_path: Path | None = Path(cache_path) if cache_path is not None else None
+        self._cache_checksum: str | None = None
         if self._cache_path is not None:
-            self._cache.update(_load_cache(self._cache_path))
+            snapshot = _load_cache_file(self._cache_path)
+            self._cache.update(snapshot.entries)
+            self._cache_checksum = snapshot.checksum
         if cache is not None:
             for key, values in cache.items():
                 self._cache[str(key)] = [str(value) for value in values]
@@ -260,9 +236,7 @@ class GraphLexicon(Lexicon):
             self._cache_dirty = True
         return synonyms
 
-    def get_synonyms(
-        self, word: str, pos: str | None = None, n: int = 5
-    ) -> list[str]:
+    def get_synonyms(self, word: str, pos: str | None = None, n: int = 5) -> list[str]:
         normalized = _normalize_phrase(word)
         if not normalized:
             return []
@@ -278,6 +252,11 @@ class GraphLexicon(Lexicon):
     def export_cache(self) -> dict[str, list[str]]:
         return {key: list(values) for key, values in self._cache.items()}
 
+    @classmethod
+    def load_cache(cls, path: str | Path) -> CacheSnapshot:
+        """Load and validate a persisted ConceptNet cache file."""
+        return _load_cache_file(Path(path))
+
     def save_cache(self, path: str | Path | None = None) -> Path:
         if path is None:
             if self._cache_path is None:
@@ -286,7 +265,8 @@ class GraphLexicon(Lexicon):
         else:
             target = Path(path)
             self._cache_path = target
-        _write_cache(target, self._cache)
+        snapshot = _write_cache_file(target, self._cache)
+        self._cache_checksum = snapshot.checksum
         self._cache_dirty = False
         return target
 
@@ -300,4 +280,3 @@ class GraphLexicon(Lexicon):
             f"GraphLexicon(languages={sorted(self._languages)!r}, "
             f"max_neighbors={self._max_neighbors}, seed={self.seed!r}, state={state})"
         )
-

glitchlings/lexicon/metrics.py

@@ -18,7 +18,6 @@ def _unique_synonyms(
     sample_size: int,
 ) -> list[str]:
     """Return unique synonym candidates excluding the original token."""
-
     collected: list[str] = []
     seen: set[str] = set()
     source = word.lower()
@@ -41,7 +40,6 @@ def synonym_diversity(
     sample_size: int = 5,
 ) -> float:
     """Return the mean unique-synonym count for ``words`` using ``lexicon``."""
-
     totals = []
     for word in words:
         synonyms = _unique_synonyms(lexicon, word, pos=pos, sample_size=sample_size)
@@ -60,7 +58,6 @@ def coverage_ratio(
     min_synonyms: int = 3,
 ) -> float:
     """Return the fraction of ``words`` with at least ``min_synonyms`` candidates."""
-
     total = 0
     hits = 0
     for word in words:
@@ -96,7 +93,6 @@ def mean_cosine_similarity(
     sample_size: int = 5,
 ) -> float:
     """Return the mean cosine similarity between each word and its candidates."""
-
     total = 0.0
     count = 0
     for word in words:
@@ -126,11 +122,8 @@ def compare_lexicons(
     embeddings: Mapping[str, Sequence[float]] | None = None,
 ) -> dict[str, float]:
     """Return comparative coverage and diversity statistics for two lexicons."""
-
     stats = {
-        "baseline_diversity": synonym_diversity(
-            baseline, words, pos=pos, sample_size=sample_size
-        ),
+        "baseline_diversity": synonym_diversity(baseline, words, pos=pos, sample_size=sample_size),
         "candidate_diversity": synonym_diversity(
             candidate, words, pos=pos, sample_size=sample_size
         ),

glitchlings/lexicon/vector.py

@@ -6,16 +6,18 @@ import argparse
 import importlib
 import json
 import math
-from pathlib import Path
 import sys
+from pathlib import Path
 from typing import Any, Callable, Iterable, Iterator, Mapping, MutableMapping, Sequence
 
-from . import Lexicon
+from . import LexiconBackend
+from ._cache import CacheSnapshot
+from ._cache import load_cache as _load_cache_file
+from ._cache import write_cache as _write_cache_file
 
 
 def _cosine_similarity(vector_a: Sequence[float], vector_b: Sequence[float]) -> float:
     """Return the cosine similarity between two dense vectors."""
-
     dot_product = 0.0
     norm_a = 0.0
     norm_b = 0.0
@@ -143,7 +145,6 @@ class _SpaCyAdapter(_Adapter):
 
 def _load_json_vectors(path: Path) -> Mapping[str, Sequence[float]]:
     """Load embeddings from a JSON mapping of token to vector list."""
-
     with path.open("r", encoding="utf8") as handle:
         payload = json.load(handle)
 
@@ -163,11 +164,8 @@ def _load_json_vectors(path: Path) -> Mapping[str, Sequence[float]]:
 
 def _load_gensim_vectors(path: Path, *, binary: bool | None = None) -> Any:
     """Load ``gensim`` vectors from ``path``."""
-
     if importlib.util.find_spec("gensim") is None:
-        raise RuntimeError(
-            "The gensim package is required to load keyed vector embeddings."
-        )
+        raise RuntimeError("The gensim package is required to load keyed vector embeddings.")
 
     keyed_vectors_module = importlib.import_module("gensim.models.keyedvectors")
     if binary is None:
@@ -176,14 +174,11 @@ def _load_gensim_vectors(path: Path, *, binary: bool | None = None) -> Any:
     if path.suffix in {".kv", ".kv2"}:
         return keyed_vectors_module.KeyedVectors.load(str(path), mmap="r")
 
-    return keyed_vectors_module.KeyedVectors.load_word2vec_format(
-        str(path), binary=binary
-    )
+    return keyed_vectors_module.KeyedVectors.load_word2vec_format(str(path), binary=binary)
 
 
 def _load_spacy_language(model_name: str) -> Any:
     """Load a spaCy language pipeline by name."""
-
     if importlib.util.find_spec("spacy") is None:
         raise RuntimeError(
             "spaCy is required to use spaCy-backed vector lexicons; install the 'vectors' extra."
@@ -195,7 +190,6 @@ def _load_spacy_language(model_name: str) -> Any:
 
 def _resolve_source(source: Any | None) -> _Adapter | None:
     """Return an adapter instance for ``source`` if possible."""
-
     if source is None:
         return None
 
@@ -228,9 +222,7 @@ def _resolve_source(source: Any | None) -> _Adapter | None:
 
         if suffix in {".kv", ".kv2", ".bin", ".gz", ".txt", ".vec"}:
             binary_flag = False if suffix in {".txt", ".vec"} else None
-            return _GensimAdapter(
-                _load_gensim_vectors(resolved_path, binary=binary_flag)
-            )
+            return _GensimAdapter(_load_gensim_vectors(resolved_path, binary=binary_flag))
 
     if hasattr(source, "most_similar") and hasattr(source, "key_to_index"):
         return _GensimAdapter(source)
@@ -241,38 +233,7 @@ def _resolve_source(source: Any | None) -> _Adapter | None:
     raise RuntimeError("Unsupported vector source supplied to VectorLexicon.")
 
 
-def _load_cache(path: Path) -> dict[str, list[str]]:
-    """Load a synonym cache from ``path`` if it exists."""
-
-    if not path.exists():
-        return {}
-
-    with path.open("r", encoding="utf8") as handle:
-        payload = json.load(handle)
-
-    if not isinstance(payload, Mapping):
-        raise RuntimeError("Synonym cache must be a JSON mapping of strings to lists.")
-
-    cache: dict[str, list[str]] = {}
-    for key, values in payload.items():
-        if not isinstance(key, str):
-            raise RuntimeError("Synonym cache keys must be strings.")
-        if not isinstance(values, Sequence):
-            raise RuntimeError("Synonym cache values must be lists of strings.")
-        cache[key] = [str(value) for value in values]
-
-    return cache
-
-
-def _write_cache(path: Path, cache: Mapping[str, Sequence[str]]) -> None:
-    """Write ``cache`` to ``path`` deterministically."""
-
-    serialisable = {key: list(values) for key, values in sorted(cache.items())}
-    with path.open("w", encoding="utf8") as handle:
-        json.dump(serialisable, handle, ensure_ascii=False, indent=2, sort_keys=True)
-
-
-class VectorLexicon(Lexicon):
+class VectorLexicon(LexiconBackend):
     """Lexicon implementation backed by dense word embeddings."""
 
     def __init__(
@@ -292,9 +253,13 @@ class VectorLexicon(Lexicon):
         self._max_neighbors = max(1, max_neighbors)
         self._min_similarity = min_similarity
         self._cache: MutableMapping[str, list[str]] = {}
+        self._cache_path: Path | None
+        self._cache_checksum: str | None = None
         if cache_path is not None:
             path = Path(cache_path)
-            self._cache.update(_load_cache(path))
+            snapshot = _load_cache_file(path)
+            self._cache.update(snapshot.entries)
+            self._cache_checksum = snapshot.checksum
             self._cache_path = path
         else:
             self._cache_path = None
@@ -384,36 +349,33 @@ class VectorLexicon(Lexicon):
             self._cache_dirty = True
         return synonyms
 
-    def get_synonyms(
-        self, word: str, pos: str | None = None, n: int = 5
-    ) -> list[str]:
+    def get_synonyms(self, word: str, pos: str | None = None, n: int = 5) -> list[str]:
         normalized = self._normalize_for_lookup(word)
         synonyms = self._ensure_cached(original=word, normalized=normalized)
         return self._deterministic_sample(synonyms, limit=n, word=word, pos=pos)
 
     def precompute(self, word: str, *, limit: int | None = None) -> list[str]:
         """Populate the cache for ``word`` and return the stored synonyms."""
-
         normalized = self._normalize_for_lookup(word)
-        return list(
-            self._ensure_cached(original=word, normalized=normalized, limit=limit)
-        )
+        return list(self._ensure_cached(original=word, normalized=normalized, limit=limit))
 
     def iter_vocabulary(self) -> Iterator[str]:
         """Yield vocabulary tokens from the underlying embedding source."""
-
         if self._adapter is None:
             return iter(())
         return self._adapter.iter_keys()
 
     def export_cache(self) -> dict[str, list[str]]:
         """Return a copy of the in-memory synonym cache."""
-
         return {key: list(values) for key, values in self._cache.items()}
 
+    @classmethod
+    def load_cache(cls, path: str | Path) -> CacheSnapshot:
+        """Load and validate a cache file for reuse."""
+        return _load_cache_file(Path(path))
+
     def save_cache(self, path: str | Path | None = None) -> Path:
         """Persist the current cache to disk, returning the path used."""
-
         if path is None:
             if self._cache_path is None:
                 raise RuntimeError("No cache path supplied to VectorLexicon.")
@@ -422,7 +384,8 @@ class VectorLexicon(Lexicon):
             target = Path(path)
             self._cache_path = target
 
-        _write_cache(target, self._cache)
+        snapshot = _write_cache_file(target, self._cache)
+        self._cache_checksum = snapshot.checksum
         self._cache_dirty = False
         return target
 
@@ -449,7 +412,6 @@ def build_vector_cache(
     normalizer: Callable[[str], str] | None = None,
 ) -> Path:
     """Generate a synonym cache for ``words`` using ``source`` embeddings."""
-
     lexicon = VectorLexicon(
         source=source,
         max_neighbors=max_neighbors,
@@ -467,7 +429,6 @@ def build_vector_cache(
 
 def load_vector_source(spec: str) -> Any:
     """Resolve ``spec`` strings for the cache-building CLI."""
-
     if spec.startswith("spacy:"):
         model_name = spec.split(":", 1)[1]
         return _load_spacy_language(model_name)
@@ -557,7 +518,6 @@ def _iter_tokens_from_file(path: Path) -> Iterator[str]:
 
 def main(argv: Sequence[str] | None = None) -> int:
     """Entry-point for ``python -m glitchlings.lexicon.vector``."""
-
     args = _parse_cli(argv)
 
     if args.output.exists() and not args.overwrite:
@@ -566,11 +526,13 @@ def main(argv: Sequence[str] | None = None) -> int:
         )
 
     if args.normalizer == "lower":
-        normalizer: Callable[[str], str] | None = (
-            None if args.case_sensitive else str.lower
-        )
+        normalizer: Callable[[str], str] | None = None if args.case_sensitive else str.lower
     else:
-        normalizer = lambda value: value
+
+        def _identity(value: str) -> str:
+            return value
+
+        normalizer = _identity
 
     source = load_vector_source(args.source)
     if args.tokens is not None:

glitchlings/lexicon/wordnet.py

@@ -2,38 +2,50 @@
 
 from __future__ import annotations
 
+from importlib import import_module
+from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
-try:  # pragma: no cover - exercised when NLTK is available
-    import nltk  # type: ignore[import]
-except ModuleNotFoundError as exc:  # pragma: no cover - triggered when NLTK missing
-    nltk = None  # type: ignore[assignment]
-    find = None  # type: ignore[assignment]
-    _NLTK_IMPORT_ERROR = exc
-else:  # pragma: no cover - executed when NLTK is present
-    from nltk.corpus.reader import WordNetCorpusReader as _WordNetCorpusReader  # type: ignore[import]
-    from nltk.data import find as _nltk_find  # type: ignore[import]
+from ..compat import nltk as _nltk_dependency
+from . import LexiconBackend
+from ._cache import CacheSnapshot
 
-    find = _nltk_find
-    _NLTK_IMPORT_ERROR = None
+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
 
+find: Any | None = None
+_WORDNET_MODULE: Any | None = None
+
 if nltk is not None:  # pragma: no cover - guarded by import success
     try:
-        from nltk.corpus import wordnet as _WORDNET_MODULE  # type: ignore[import]
+        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]
+    else:
+        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]
+        else:
+            find = getattr(data_module, "find", None)
+
+    try:
+        _WORDNET_MODULE = import_module("nltk.corpus.wordnet")
     except ModuleNotFoundError:  # pragma: no cover - only hit on namespace packages
         _WORDNET_MODULE = None
-    else:
-        WordNetCorpusReader = _WordNetCorpusReader  # type: ignore[assignment]
 else:
+    nltk = None  # type: ignore[assignment]
+    find = None
     _WORDNET_MODULE = None
 
-from . import Lexicon
-
 _WORDNET_HANDLE: WordNetCorpusReader | Any | None = _WORDNET_MODULE
 _wordnet_ready = False
 
@@ -42,26 +54,23 @@ _VALID_POS: tuple[str, ...] = ("n", "v", "a", "r")
 
 def _require_nltk() -> None:
     """Ensure the NLTK dependency is present before continuing."""
-
     if nltk is None or find is None:
         message = (
             "The NLTK package is required for WordNet-backed lexicons; install "
             "`nltk` and its WordNet corpus manually to enable this backend."
         )
-        if '_NLTK_IMPORT_ERROR' in globals() and _NLTK_IMPORT_ERROR is not None:
+        if "_NLTK_IMPORT_ERROR" in globals() and _NLTK_IMPORT_ERROR is not None:
             raise RuntimeError(message) from _NLTK_IMPORT_ERROR
         raise RuntimeError(message)
 
 
 def dependencies_available() -> bool:
     """Return ``True`` when the runtime NLTK dependency is present."""
-
     return nltk is not None and find is not None
 
 
 def _load_wordnet_reader() -> WordNetCorpusReader:
     """Return a WordNet corpus reader from the downloaded corpus files."""
-
     _require_nltk()
 
     try:
@@ -80,7 +89,6 @@ def _load_wordnet_reader() -> WordNetCorpusReader:
 
 def _wordnet(force_refresh: bool = False) -> WordNetCorpusReader | Any:
     """Retrieve the active WordNet handle, rebuilding it on demand."""
-
     global _WORDNET_HANDLE
 
     if force_refresh:
@@ -95,7 +103,6 @@ def _wordnet(force_refresh: bool = False) -> WordNetCorpusReader | Any:
 
 def ensure_wordnet() -> None:
     """Ensure the WordNet corpus is available before use."""
-
     global _wordnet_ready
     if _wordnet_ready:
         return
@@ -112,16 +119,13 @@ def ensure_wordnet() -> None:
             resource = _wordnet(force_refresh=True)
             resource.ensure_loaded()
         except LookupError as exc:  # pragma: no cover - only triggered when download fails
-            raise RuntimeError(
-                "Unable to load NLTK WordNet corpus for synonym lookups."
-            ) from exc
+            raise RuntimeError("Unable to load NLTK WordNet corpus for synonym lookups.") from exc
 
     _wordnet_ready = True
 
 
 def _collect_synonyms(word: str, parts_of_speech: tuple[str, ...]) -> list[str]:
     """Gather deterministic synonym candidates for the supplied word."""
-
     normalized_word = word.lower()
     wordnet = _wordnet()
     synonyms: set[str] = set()
@@ -151,12 +155,10 @@ def _collect_synonyms(word: str, parts_of_speech: tuple[str, ...]) -> list[str]:
     return sorted(synonyms)
 
 
-class WordNetLexicon(Lexicon):
+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]:
+    def get_synonyms(self, word: str, pos: str | None = None, n: int = 5) -> list[str]:
         ensure_wordnet()
 
         if pos is None:
@@ -175,6 +177,13 @@ class WordNetLexicon(Lexicon):
             return True
         return pos.lower() in _VALID_POS
 
+    @classmethod
+    def load_cache(cls, path: str | Path) -> CacheSnapshot:
+        raise RuntimeError("WordNetLexicon does not persist or load caches.")
+
+    def save_cache(self, path: str | Path | None = None) -> Path | None:
+        raise RuntimeError("WordNetLexicon does not persist or load caches.")
+
     def __repr__(self) -> str:  # pragma: no cover - trivial representation
         return f"WordNetLexicon(seed={self.seed!r})"
 

glitchlings/main.py

@@ -4,16 +4,16 @@ from __future__ import annotations
 
 import argparse
 import difflib
-from pathlib import Path
 import sys
+from pathlib import Path
 
 from . import SAMPLE_TEXT
 from .config import DEFAULT_ATTACK_SEED, build_gaggle, load_attack_config
 from .zoo import (
-    Glitchling,
-    Gaggle,
     BUILTIN_GLITCHLINGS,
     DEFAULT_GLITCHLING_NAMES,
+    Gaggle,
+    Glitchling,
     parse_glitchling_spec,
     summon,
 )
@@ -26,8 +26,8 @@ def build_parser() -> argparse.ArgumentParser:
 
     Returns:
         argparse.ArgumentParser: The configured argument parser instance.
-    """
 
+    """
     parser = argparse.ArgumentParser(
         description=(
             "Summon glitchlings to corrupt text. Provide input text as an argument, "
@@ -157,7 +157,6 @@ def build_lexicon_parser() -> argparse.ArgumentParser:
 
 def list_glitchlings() -> None:
     """Print information about the available built-in glitchlings."""
-
     for key in DEFAULT_GLITCHLING_NAMES:
         glitchling = BUILTIN_GLITCHLINGS[key]
         display_name = glitchling.name
@@ -178,8 +177,8 @@ def read_text(args: argparse.Namespace, parser: argparse.ArgumentParser) -> str:
 
     Raises:
         SystemExit: Raised indirectly via ``parser.error`` on failure.
-    """
 
+    """
     if args.file is not None:
         try:
             return args.file.read_text(encoding="utf-8")
@@ -198,7 +197,8 @@ def read_text(args: argparse.Namespace, parser: argparse.ArgumentParser) -> str:
         return SAMPLE_TEXT
 
     parser.error(
-        "No input text provided. Supply text as an argument, use --file, pipe input, or pass --sample."
+        "No input text provided. Supply text as an argument, use --file, pipe input, or "
+        "pass --sample."
     )
     raise AssertionError("parser.error should exit")
 
@@ -211,7 +211,6 @@ def summon_glitchlings(
     config_path: Path | None = None,
 ) -> Gaggle:
     """Instantiate the requested glitchlings and bundle them in a ``Gaggle``."""
-
     if config_path is not None:
         if names:
             parser.error("Cannot combine --config with --glitchling.")
@@ -245,10 +244,8 @@ def summon_glitchlings(
         raise AssertionError("parser.error should exit")
 
 
-
 def show_diff(original: str, corrupted: str) -> None:
     """Display a unified diff between the original and corrupted text."""
-
     diff_lines = list(
         difflib.unified_diff(
             original.splitlines(keepends=True),
@@ -274,8 +271,8 @@ def run_cli(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
 
     Returns:
         int: Exit code for the process (``0`` on success).
-    """
 
+    """
     if args.list:
         list_glitchlings()
         return 0
@@ -300,7 +297,6 @@ def run_cli(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
 
 def run_build_lexicon(args: argparse.Namespace) -> int:
     """Delegate to the vector lexicon cache builder using CLI arguments."""
-
     from glitchlings.lexicon.vector import main as vector_main
 
     vector_args = [
@@ -337,8 +333,8 @@ def main(argv: list[str] | None = None) -> int:
 
     Returns:
         int: Exit code suitable for use with ``sys.exit``.
-    """
 
+    """
     if argv is None:
         raw_args = sys.argv[1:]
     else: