glitchlings 0.4.1__cp311-cp311-macosx_11_0_universal2.whl → 0.4.2__cp311-cp311-macosx_11_0_universal2.whl

glitchlings/zoo/core.py

@@ -4,24 +4,18 @@ import inspect
 import logging
 import os
 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
+from typing import TYPE_CHECKING, Any, Callable, Protocol, TypedDict, Union
 
-_datasets_error: ModuleNotFoundError | None = None
-try:  # pragma: no cover - optional dependency
-    from datasets import Dataset as _DatasetsDataset
-except ModuleNotFoundError as error:  # pragma: no cover - optional dependency
-    _DatasetsDataset = None  # type: ignore[assignment]
-    _datasets_error = error
-else:
-    _datasets_error = None
+from ..compat import get_datasets_dataset, require_datasets
+
+_DatasetsDataset = get_datasets_dataset()
 
 try:  # pragma: no cover - optional dependency
-    from glitchlings._zoo_rust import (
-        compose_glitchlings as _compose_glitchlings_rust,
-        plan_glitchlings as _plan_glitchlings_rust,
-    )
+    from glitchlings._zoo_rust import compose_glitchlings as _compose_glitchlings_rust
+    from glitchlings._zoo_rust import plan_glitchlings as _plan_glitchlings_rust
 except ImportError:  # pragma: no cover - compiled extension not present
     _compose_glitchlings_rust = None
     _plan_glitchlings_rust = None
@@ -35,9 +29,17 @@ _PIPELINE_ENABLE_VALUES = {"1", "true", "yes", "on"}
 _PIPELINE_DISABLE_VALUES = {"0", "false", "no", "off"}
 
 
-def _pipeline_feature_flag_enabled() -> bool:
-    """Return ``True`` when the environment does not explicitly disable the Rust pipeline."""
+class PlanSpecification(TypedDict):
+    name: str
+    scope: int
+    order: int
 
+
+PlanEntry = Union["Glitchling", Mapping[str, Any]]
+
+
+def pipeline_feature_flag_enabled() -> bool:
+    """Return ``True`` when the environment does not explicitly disable the Rust pipeline."""
     value = os.environ.get(_PIPELINE_FEATURE_FLAG_ENV)
     if value is None:
         return True
@@ -51,12 +53,62 @@ def _pipeline_feature_flag_enabled() -> bool:
 
     return True
 
+
+def _pipeline_feature_flag_enabled() -> bool:
+    """Compatibility shim for legacy callers."""
+    return pipeline_feature_flag_enabled()
+
+
+def is_rust_pipeline_supported() -> bool:
+    """Return ``True`` when the optional Rust extension is importable."""
+    return _compose_glitchlings_rust is not None
+
+
+def is_rust_pipeline_enabled() -> bool:
+    """Return ``True`` when the Rust pipeline is available and not explicitly disabled."""
+    return is_rust_pipeline_supported() and pipeline_feature_flag_enabled()
+
+
+def _spec_from_glitchling(glitchling: "Glitchling") -> PlanSpecification:
+    """Create a plan specification mapping from a glitchling instance."""
+    return {
+        "name": glitchling.name,
+        "scope": int(glitchling.level),
+        "order": int(glitchling.order),
+    }
+
+
+def _normalize_plan_entry(entry: PlanEntry) -> PlanSpecification:
+    """Convert a plan entry (glitchling or mapping) into a normalized specification."""
+    if isinstance(entry, Glitchling):
+        return _spec_from_glitchling(entry)
+
+    if not isinstance(entry, Mapping):
+        message = "plan_glitchlings expects Glitchling instances or mapping specifications"
+        raise TypeError(message)
+
+    try:
+        name = str(entry["name"])
+        scope_value = int(entry["scope"])
+        order_value = int(entry["order"])
+    except KeyError as exc:  # pragma: no cover - defensive guard
+        raise ValueError(f"Plan specification missing required field: {exc.args[0]}") from exc
+    except (TypeError, ValueError) as exc:
+        raise ValueError("Plan specification fields must be coercible to integers") from exc
+
+    return {"name": name, "scope": scope_value, "order": order_value}
+
+
+def _normalize_plan_entries(entries: Sequence[PlanEntry]) -> list[PlanSpecification]:
+    """Normalize a collection of orchestration plan entries."""
+    return [_normalize_plan_entry(entry) for entry in entries]
+
+
 def _plan_glitchlings_python(
-    specs: list[dict[str, Any]],
+    specs: Sequence[Mapping[str, Any]],
     master_seed: int,
 ) -> list[tuple[int, int]]:
     """Pure-Python fallback for orchestrating glitchlings in deterministic order."""
-
     master_seed_int = int(master_seed)
     planned: list[tuple[int, int, int, int, str]] = []
     for index, spec in enumerate(specs):
@@ -71,11 +123,10 @@ def _plan_glitchlings_python(
 
 
 def _plan_glitchlings_with_rust(
-    specs: list[dict[str, Any]],
+    specs: Sequence[Mapping[str, Any]],
     master_seed: int,
 ) -> list[tuple[int, int]] | None:
     """Attempt to obtain the orchestration plan from the compiled Rust module."""
-
     if _plan_glitchlings_rust is None:
         return None
 
@@ -88,38 +139,51 @@ def _plan_glitchlings_with_rust(
     return [(int(index), int(seed)) for index, seed in plan]
 
 
-def _plan_glitchling_specs(
-    specs: list[dict[str, Any]],
+def _resolve_orchestration_plan(
+    specs: Sequence[PlanSpecification],
+    master_seed: int,
+    prefer_rust: bool,
+) -> list[tuple[int, int]]:
+    """Dispatch to the Rust planner when available, otherwise fall back to Python."""
+    if prefer_rust:
+        plan = _plan_glitchlings_with_rust(list(specs), master_seed)
+        if plan is not None:
+            return plan
+
+    return _plan_glitchlings_python(list(specs), master_seed)
+
+
+def plan_glitchling_specs(
+    specs: Sequence[Mapping[str, Any]],
     master_seed: int | None,
+    *,
+    prefer_rust: bool = True,
 ) -> list[tuple[int, int]]:
     """Resolve orchestration order and seeds from glitchling specifications."""
-
     if master_seed is None:
         message = "Gaggle orchestration requires a master seed"
         raise ValueError(message)
 
+    normalized_specs = [_normalize_plan_entry(spec) for spec in specs]
     master_seed_int = int(master_seed)
-    plan = _plan_glitchlings_with_rust(specs, master_seed_int)
-    if plan is not None:
-        return plan
-
-    return _plan_glitchlings_python(specs, master_seed_int)
+    return _resolve_orchestration_plan(normalized_specs, master_seed_int, prefer_rust)
 
 
-def _plan_glitchling_sequence(
-    glitchlings: list["Glitchling"], master_seed: int | None
+def plan_glitchlings(
+    entries: Sequence[PlanEntry],
+    master_seed: int | None,
+    *,
+    prefer_rust: bool = True,
 ) -> list[tuple[int, int]]:
-    """Derive orchestration plan for concrete glitchling instances."""
-
-    specs = [
-        {
-            "name": glitchling.name,
-            "scope": int(glitchling.level),
-            "order": int(glitchling.order),
-        }
-        for glitchling in glitchlings
-    ]
-    return _plan_glitchling_specs(specs, master_seed)
+    """Normalize glitchling instances or specs and compute an orchestration plan."""
+    if master_seed is None:
+        message = "Gaggle orchestration requires a master seed"
+        raise ValueError(message)
+
+    normalized_specs = _normalize_plan_entries(entries)
+    master_seed_int = int(master_seed)
+    return _resolve_orchestration_plan(normalized_specs, master_seed_int, prefer_rust)
+
 
 if TYPE_CHECKING:  # pragma: no cover - typing only
     from datasets import Dataset  # type: ignore
@@ -140,7 +204,6 @@ def _is_transcript(
     require_all_content: bool = False,
 ) -> bool:
     """Return `True` when `value` appears to be a chat transcript."""
-
     if not isinstance(value, list):
         return False
 
@@ -209,8 +272,8 @@ class Glitchling:
             order: Relative ordering within the same scope.
             seed: Optional seed for deterministic random behaviour.
             **kwargs: Additional parameters forwarded to the corruption callable.
-        """
 
+        """
         # Each Glitchling maintains its own RNG for deterministic yet isolated behavior.
         # If no seed is supplied, we fall back to Python's default entropy.
         self.seed = seed
@@ -228,7 +291,6 @@ class Glitchling:
 
     def set_param(self, key: str, value: Any) -> None:
         """Persist a parameter for use by the corruption callable."""
-
         aliases = getattr(self, "_param_aliases", {})
         canonical = aliases.get(key, key)
 
@@ -250,7 +312,6 @@ class Glitchling:
 
     def pipeline_operation(self) -> dict[str, Any] | None:
         """Return the Rust pipeline operation descriptor for this glitchling."""
-
         factory = self._pipeline_descriptor_factory
         if factory is None:
             return None
@@ -259,15 +320,11 @@ class Glitchling:
 
     def _corruption_expects_rng(self) -> bool:
         """Return `True` when the corruption function accepts an rng keyword."""
-
         cached_callable = self._cached_rng_callable
         cached_expectation = self._cached_rng_expectation
         corruption_function = self.corruption_function
 
-        if (
-            cached_callable is corruption_function
-            and cached_expectation is not None
-        ):
+        if cached_callable is corruption_function and cached_expectation is not None:
             return cached_expectation
 
         expects_rng = False
@@ -285,7 +342,6 @@ class Glitchling:
 
     def __corrupt(self, text: str, *args: Any, **kwargs: Any) -> str:
         """Execute the corruption callable, injecting the RNG when required."""
-
         # Pass rng to underlying corruption function if it expects it.
         expects_rng = self._corruption_expects_rng()
 
@@ -297,23 +353,17 @@ class Glitchling:
 
     def corrupt(self, text: str | list[dict[str, Any]]) -> str | list[dict[str, Any]]:
         """Apply the corruption function to text or conversational transcripts."""
-
         if _is_transcript(text):
             transcript = [dict(turn) for turn in text]
             if transcript:
-                transcript[-1]["content"] = self.__corrupt(
-                    transcript[-1]["content"], **self.kwargs
-                )
+                transcript[-1]["content"] = self.__corrupt(transcript[-1]["content"], **self.kwargs)
             return transcript
 
         return self.__corrupt(text, **self.kwargs)
 
     def corrupt_dataset(self, dataset: Dataset, columns: list[str]) -> Dataset:
         """Apply corruption lazily across dataset columns."""
-
-        if _DatasetsDataset is None:
-            message = "datasets is not installed"
-            raise ModuleNotFoundError(message) from _datasets_error
+        require_datasets("datasets is not installed")
 
         def __corrupt_row(row: dict[str, Any]) -> dict[str, Any]:
             row = dict(row)
@@ -335,12 +385,10 @@ class Glitchling:
 
     def __call__(self, text: str, *args: Any, **kwds: Any) -> str | list[dict[str, Any]]:
         """Allow a glitchling to be invoked directly like a callable."""
-
         return self.corrupt(text, *args, **kwds)
 
     def reset_rng(self, seed: int | None = None) -> None:
         """Reset the glitchling's RNG to its initial seed."""
-
         if seed is not None:
             self.seed = seed
         if self.seed is not None:
@@ -348,7 +396,6 @@ class Glitchling:
 
     def clone(self, seed: int | None = None) -> "Glitchling":
         """Create a copy of this glitchling, optionally with a new seed."""
-
         cls = self.__class__
         filtered_kwargs = {k: v for k, v in self.kwargs.items() if k != "seed"}
         clone_seed = seed if seed is not None else self.seed
@@ -368,9 +415,6 @@ class Glitchling:
         return cls(**filtered_kwargs)
 
 
-
-
-
 class Gaggle(Glitchling):
     """A collection of glitchlings executed in a deterministic order."""
 
@@ -380,8 +424,8 @@ class Gaggle(Glitchling):
         Args:
             glitchlings: Glitchlings to orchestrate.
             seed: Master seed used to derive per-glitchling seeds.
-        """
 
+        """
         super().__init__("Gaggle", self.corrupt, AttackWave.DOCUMENT, seed=seed)
         self._clones_by_index: list[Glitchling] = []
         for idx, glitchling in enumerate(glitchlings):
@@ -389,9 +433,7 @@ class Gaggle(Glitchling):
             setattr(clone, "_gaggle_index", idx)
             self._clones_by_index.append(clone)
 
-        self.glitchlings: dict[AttackWave, list[Glitchling]] = {
-            level: [] for level in AttackWave
-        }
+        self.glitchlings: dict[AttackWave, list[Glitchling]] = {level: [] for level in AttackWave}
         self.apply_order: list[Glitchling] = []
         self._plan: list[tuple[int, int]] = []
         self.sort_glitchlings()
@@ -399,6 +441,7 @@ class Gaggle(Glitchling):
     @staticmethod
     def derive_seed(master_seed: int, glitchling_name: str, index: int) -> int:
         """Derive a deterministic seed for a glitchling based on the master seed."""
+
         def _int_to_bytes(value: int) -> bytes:
             if value == 0:
                 return b"\x00"
@@ -425,8 +468,7 @@ class Gaggle(Glitchling):
 
     def sort_glitchlings(self) -> None:
         """Sort glitchlings by wave then order to produce application order."""
-
-        plan = _plan_glitchling_sequence(self._clones_by_index, self.seed)
+        plan = plan_glitchlings(self._clones_by_index, self.seed)
         self._plan = plan
 
         self.glitchlings = {level: [] for level in AttackWave}
@@ -451,14 +493,12 @@ class Gaggle(Glitchling):
     @staticmethod
     def rust_pipeline_supported() -> bool:
         """Return ``True`` when the compiled Rust pipeline is importable."""
-
-        return _compose_glitchlings_rust is not None
+        return is_rust_pipeline_supported()
 
     @staticmethod
     def rust_pipeline_enabled() -> bool:
         """Return ``True`` when the Rust pipeline is available and not explicitly disabled."""
-
-        return Gaggle.rust_pipeline_supported() and _pipeline_feature_flag_enabled()
+        return is_rust_pipeline_enabled()
 
     def _pipeline_descriptors(self) -> list[dict[str, Any]] | None:
         if not self.rust_pipeline_enabled():
@@ -490,7 +530,6 @@ class Gaggle(Glitchling):
 
     def corrupt(self, text: str) -> str:
         """Apply each glitchling to the provided text sequentially."""
-
         master_seed = self.seed
         descriptors = self._pipeline_descriptors()
         if master_seed is not None and descriptors is not None:

glitchlings/zoo/jargoyle.py

@@ -9,9 +9,11 @@ from glitchlings.lexicon import Lexicon, get_default_lexicon
 try:  # pragma: no cover - optional WordNet dependency
     from glitchlings.lexicon.wordnet import (
         WordNetLexicon,
+    )
+    from glitchlings.lexicon.wordnet import (
         dependencies_available as _lexicon_dependencies_available,
-        ensure_wordnet as _lexicon_ensure_wordnet,
     )
+    from glitchlings.lexicon.wordnet import ensure_wordnet as _lexicon_ensure_wordnet
 except Exception:  # pragma: no cover - triggered when nltk unavailable
     WordNetLexicon = None  # type: ignore[assignment]
 
@@ -33,7 +35,6 @@ ensure_wordnet = _lexicon_ensure_wordnet
 
 def dependencies_available() -> bool:
     """Return ``True`` when a synonym backend is accessible."""
-
     if _lexicon_dependencies_available():
         return True
 
@@ -58,7 +59,6 @@ _VALID_POS: tuple[PartOfSpeech, ...] = ("n", "v", "a", "r")
 
 def _split_token(token: str) -> tuple[str, str, str]:
     """Split a token into leading punctuation, core word, and trailing punctuation."""
-
     match = re.match(r"^(\W*)(.*?)(\W*)$", token)
     if not match:
         return "", token, ""
@@ -70,23 +70,18 @@ def _normalize_parts_of_speech(
     part_of_speech: PartOfSpeechInput,
 ) -> NormalizedPartsOfSpeech:
     """Coerce user input into a tuple of valid WordNet POS tags."""
-
     if isinstance(part_of_speech, str):
         lowered = part_of_speech.lower()
         if lowered == "any":
             return _VALID_POS
         if lowered not in _VALID_POS:
-            raise ValueError(
-                "part_of_speech must be one of 'n', 'v', 'a', 'r', or 'any'"
-            )
+            raise ValueError("part_of_speech must be one of 'n', 'v', 'a', 'r', or 'any'")
         return (cast(PartOfSpeech, lowered),)
 
     normalized: list[PartOfSpeech] = []
     for pos in part_of_speech:
         if pos not in _VALID_POS:
-            raise ValueError(
-                "part_of_speech entries must be one of 'n', 'v', 'a', or 'r'"
-            )
+            raise ValueError("part_of_speech entries must be one of 'n', 'v', 'a', or 'r'")
         if pos not in normalized:
             normalized.append(pos)
     if not normalized:
@@ -118,6 +113,7 @@ def substitute_random_synonyms(
     """Replace words with random lexicon-driven synonyms.
 
     Parameters
+    ----------
     - text: Input text.
     - rate: Max proportion of candidate words to replace (default 0.01).
     - part_of_speech: WordNet POS tag(s) to target. Accepts "n", "v", "a", "r",
@@ -134,6 +130,7 @@ def substitute_random_synonyms(
     - Replacement positions chosen via rng.sample.
     - Synonyms sourced through the lexicon; the default backend derives
       deterministic subsets per word and part-of-speech using the active seed.
+
     """
     effective_rate = resolve_rate(
         rate=rate,
@@ -168,7 +165,7 @@ def substitute_random_synonyms(
         # Split but keep whitespace separators so we can rebuild easily
         tokens = re.split(r"(\s+)", text)
 
-        # Collect indices of candidate tokens (even positions 0,2,.. are words given our split design)
+        # Collect candidate word indices (even positions are words because separators are kept)
         candidate_indices: list[int] = []
         candidate_metadata: dict[int, CandidateInfo] = {}
         for idx, tok in enumerate(tokens):
@@ -296,9 +293,7 @@ class Jargoyle(Glitchling):
                         current_lexicon.reseed(self.seed)
                     else:
                         if hasattr(self, "_external_lexicon_original_seed"):
-                            original_seed = getattr(
-                                self, "_external_lexicon_original_seed", None
-                            )
+                            original_seed = getattr(self, "_external_lexicon_original_seed", None)
                             current_lexicon.reseed(original_seed)
         elif canonical == "lexicon" and isinstance(value, Lexicon):
             if getattr(self, "_initializing", False):

glitchlings/zoo/mim1c.py

@@ -1,11 +1,11 @@
-from collections.abc import Collection
 import random
+from collections.abc import Collection
 from typing import Literal
 
 from confusable_homoglyphs import confusables
 
-from .core import AttackOrder, AttackWave, Glitchling
 from ._rate import resolve_rate
+from .core import AttackOrder, AttackWave, Glitchling
 
 
 def swap_homoglyphs(
@@ -21,16 +21,21 @@ def swap_homoglyphs(
     """Replace characters with visually confusable homoglyphs.
 
     Parameters
+    ----------
     - text: Input text.
     - rate: Max proportion of eligible characters to replace (default 0.02).
-    - classes: Restrict replacements to these Unicode script classes (default ["LATIN","GREEK","CYRILLIC"]). Use "all" to allow any.
+    - classes: Restrict replacements to these Unicode script classes (default
+      ["LATIN", "GREEK", "CYRILLIC"]). Use "all" to allow any.
     - banned_characters: Characters that must never appear as replacements.
     - seed: Optional seed if `rng` not provided.
     - rng: Optional RNG; overrides seed.
 
     Notes
-    - Only replaces characters present in confusables.confusables_data with single-codepoint alternatives.
+    -----
+    - Only replaces characters present in ``confusables.confusables_data`` with
+      single-codepoint alternatives.
     - Maintains determinism by shuffling candidates and sampling via the provided RNG.
+
     """
     effective_rate = resolve_rate(
         rate=rate,
@@ -46,9 +51,7 @@ def swap_homoglyphs(
         classes = ["LATIN", "GREEK", "CYRILLIC"]
 
     target_chars = [char for char in text if char.isalnum()]
-    confusable_chars = [
-        char for char in target_chars if char in confusables.confusables_data
-    ]
+    confusable_chars = [char for char in target_chars if char in confusables.confusables_data]
     clamped_rate = max(0.0, effective_rate)
     num_replacements = int(len(confusable_chars) * clamped_rate)
     done = 0
@@ -57,9 +60,7 @@ def swap_homoglyphs(
     for char in confusable_chars:
         if done >= num_replacements:
             break
-        options = [
-            o["c"] for o in confusables.confusables_data[char] if len(o["c"]) == 1
-        ]
+        options = [o["c"] for o in confusables.confusables_data[char] if len(o["c"]) == 1]
         if classes != "all":
             options = [opt for opt in options if confusables.alias(opt) in classes]
         if banned_set:

glitchlings/zoo/redactyl.py

@@ -1,5 +1,5 @@
-import re
 import random
+import re
 from typing import Any
 
 from ._rate import resolve_rate
@@ -32,24 +32,22 @@ def _python_redact_words(
     """Redact random words by replacing their characters.
 
     Parameters
+    ----------
     - text: Input text.
     - replacement_char: The character to use for redaction (default FULL_BLOCK).
     - rate: Max proportion of words to redact (default 0.05).
     - merge_adjacent: If True, merges adjacent redactions across intervening non-word chars.
     - rng: RNG used for sampling decisions.
     - unweighted: When True, sample words uniformly instead of by length.
+
     """
     tokens = split_preserving_whitespace(text)
     word_tokens = collect_word_tokens(tokens)
     if not word_tokens:
-        raise ValueError(
-            "Cannot redact words because the input text contains no redactable words."
-        )
+        raise ValueError("Cannot redact words because the input text contains no redactable words.")
 
     population = [token.index for token in word_tokens]
-    weights = [
-        1.0 if unweighted else float(token.core_length) for token in word_tokens
-    ]
+    weights = [1.0 if unweighted else float(token.core_length) for token in word_tokens]
 
     clamped_rate = max(0.0, min(rate, 1.0))
     raw_quota = len(population) * clamped_rate
@@ -105,7 +103,6 @@ def redact_words(
     unweighted: bool = False,
 ) -> str:
     """Redact random words by replacing their characters."""
-
     effective_rate = resolve_rate(
         rate=rate,
         legacy_value=redaction_rate,

glitchlings/zoo/reduple.py

@@ -21,14 +21,17 @@ def _python_reduplicate_words(
     """Randomly reduplicate words in the text.
 
     Parameters
+    ----------
     - text: Input text.
     - rate: Max proportion of words to reduplicate (default 0.05).
     - rng: RNG used for sampling decisions.
     - unweighted: When True, sample words uniformly instead of length-weighted.
 
     Notes
+    -----
     - Preserves spacing and punctuation by tokenizing with separators.
     - Deterministic when run with a fixed seed or via Gaggle.
+
     """
     tokens = split_preserving_whitespace(text)
     word_tokens = collect_word_tokens(tokens)
@@ -77,7 +80,6 @@ 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,

glitchlings/zoo/rushmore.py

@@ -21,7 +21,6 @@ def _python_delete_random_words(
     unweighted: bool = False,
 ) -> str:
     """Delete random words from the input text while preserving whitespace."""
-
     effective_rate = max(rate, 0.0)
     if effective_rate <= 0.0:
         return text
@@ -37,15 +36,11 @@ def _python_delete_random_words(
     if not weighted_tokens:
         return text
 
-    allowed_deletions = min(
-        len(weighted_tokens), math.floor(len(weighted_tokens) * effective_rate)
-    )
+    allowed_deletions = min(len(weighted_tokens), math.floor(len(weighted_tokens) * effective_rate))
     if allowed_deletions <= 0:
         return text
 
-    mean_weight = sum(weight for _, weight, _ in weighted_tokens) / len(
-        weighted_tokens
-    )
+    mean_weight = sum(weight for _, weight, _ in weighted_tokens) / len(weighted_tokens)
 
     deletions = 0
     for index, weight, token in weighted_tokens:
@@ -88,7 +83,6 @@ def delete_random_words(
 
     Uses the optional Rust implementation when available.
     """
-
     effective_rate = resolve_rate(
         rate=rate,
         legacy_value=max_deletion_rate,

glitchlings/zoo/scannequin.py

@@ -1,10 +1,10 @@
-import re
 import random
+import re
 from typing import Any
 
 from ._ocr_confusions import load_confusion_table
-from .core import Glitchling, AttackWave, AttackOrder
 from ._rate import resolve_rate
+from .core import AttackOrder, AttackWave, Glitchling
 
 try:
     from glitchlings._zoo_rust import ocr_artifacts as _ocr_artifacts_rust
@@ -21,17 +21,20 @@ def _python_ocr_artifacts(
     """Introduce OCR-like artifacts into text.
 
     Parameters
+    ----------
     - text: Input text to corrupt.
     - rate: Max proportion of eligible confusion matches to replace (default 0.02).
     - seed: Optional seed if `rng` not provided.
     - rng: Optional RNG; overrides seed.
 
     Notes
+    -----
     - Uses a curated set of common OCR confusions (rn↔m, cl↔d, O↔0, l/I/1, etc.).
     - Collects all non-overlapping candidate spans in reading order, then samples
       a subset deterministically with the provided RNG.
     - Replacements can change length (e.g., m→rn), so edits are applied from left
       to right using precomputed spans to avoid index drift.
+
     """
     if not text:
         return text
@@ -107,7 +110,6 @@ def ocr_artifacts(
 
     Prefers the Rust implementation when available.
     """
-
     if not text:
         return text
 
@@ -164,7 +166,6 @@ class Scannequin(Glitchling):
         return {"type": "ocr", "error_rate": float(rate)}
 
 
-
 scannequin = Scannequin()