glitchlings 0.4.4__cp312-cp312-macosx_11_0_universal2.whl → 0.5.0__cp312-cp312-macosx_11_0_universal2.whl

glitchlings/__init__.py

@@ -5,6 +5,7 @@ from .zoo import (
     Apostrofae,
     Gaggle,
     Glitchling,
+    Hokey,
     Jargoyle,
     Mim1c,
     Redactyl,
@@ -15,6 +16,7 @@ from .zoo import (
     Zeedub,
     adjax,
     apostrofae,
+    hokey,
     is_rust_pipeline_enabled,
     is_rust_pipeline_supported,
     jargoyle,
@@ -42,6 +44,8 @@ __all__ = [
     "adjax",
     "Apostrofae",
     "apostrofae",
+    "Hokey",
+    "hokey",
     "Redactyl",
     "redactyl",
     "Reduple",

glitchlings/compat.py

@@ -17,16 +17,14 @@ _MISSING = _MissingSentinel()
 
 
 class _MarkerProtocol(Protocol):
-    def evaluate(self, environment: dict[str, str]) -> bool:
-        ...
+    def evaluate(self, environment: dict[str, str]) -> bool: ...
 
 
 class _RequirementProtocol(Protocol):
     marker: _MarkerProtocol | None
     name: str
 
-    def __init__(self, requirement: str) -> None:
-        ...
+    def __init__(self, requirement: str) -> None: ...
 
 
 try:  # pragma: no cover - packaging is bundled with modern Python environments

glitchlings/config.py

@@ -4,7 +4,6 @@ from __future__ import annotations
 
 import importlib
 import os
-import warnings
 from dataclasses import dataclass, field
 from io import TextIOBase
 from pathlib import Path
@@ -19,8 +18,7 @@ except ModuleNotFoundError:  # pragma: no cover - Python < 3.11
 
 
 class _TomllibModule(Protocol):
-    def load(self, fp: IO[bytes]) -> Any:
-        ...
+    def load(self, fp: IO[bytes]) -> Any: ...
 
 
 tomllib = cast(_TomllibModule, _tomllib)
@@ -29,8 +27,7 @@ tomllib = cast(_TomllibModule, _tomllib)
 class _YamlModule(Protocol):
     YAMLError: type[Exception]
 
-    def safe_load(self, stream: str) -> Any:
-        ...
+    def safe_load(self, stream: str) -> Any: ...
 
 
 yaml = cast(_YamlModule, importlib.import_module("yaml"))
@@ -59,17 +56,6 @@ ATTACK_CONFIG_SCHEMA: dict[str, Any] = {
                         "required": ["name"],
                         "properties": {
                             "name": {"type": "string", "minLength": 1},
-                            "type": {"type": "string", "minLength": 1},
-                            "parameters": {"type": "object"},
-                        },
-                        "additionalProperties": True,
-                    },
-                    {
-                        "type": "object",
-                        "required": ["type"],
-                        "properties": {
-                            "name": {"type": "string", "minLength": 1},
-                            "type": {"type": "string", "minLength": 1},
                             "parameters": {"type": "object"},
                         },
                         "additionalProperties": True,
@@ -265,7 +251,12 @@ def _validate_attack_config_schema(data: Any, *, source: str) -> Mapping[str, An
 
     for index, entry in enumerate(raw_glitchlings, start=1):
         if isinstance(entry, Mapping):
-            name_candidate = entry.get("name") or entry.get("type")
+            if "type" in entry:
+                raise ValueError(
+                    f"{source}: glitchling #{index} uses unsupported 'type'; use 'name'."
+                )
+
+            name_candidate = entry.get("name")
             if not isinstance(name_candidate, str) or not name_candidate.strip():
                 raise ValueError(f"{source}: glitchling #{index} is missing a 'name'.")
             parameters = entry.get("parameters")
@@ -328,17 +319,12 @@ def _build_glitchling(entry: Any, source: str, index: int) -> "Glitchling":
             raise ValueError(f"{source}: glitchling #{index}: {exc}") from exc
 
     if isinstance(entry, Mapping):
-        name_value = entry.get("name")
-        legacy_type = entry.get("type")
-        if name_value is None and legacy_type is not None:
-            warnings.warn(
-                f"{source}: glitchling #{index} uses 'type'; prefer 'name'.",
-                DeprecationWarning,
-                stacklevel=2,
+        if "type" in entry:
+            raise ValueError(
+                f"{source}: glitchling #{index} uses unsupported 'type'; use 'name'."
             )
-            name_value = legacy_type
-        elif name_value is None:
-            name_value = legacy_type
+
+        name_value = entry.get("name")
 
         if not isinstance(name_value, str) or not name_value.strip():
             raise ValueError(f"{source}: glitchling #{index} is missing a 'name'.")
@@ -354,7 +340,7 @@ def _build_glitchling(entry: Any, source: str, index: int) -> "Glitchling":
             kwargs = {
                 key: value
                 for key, value in entry.items()
-                if key not in {"name", "type", "parameters"}
+                if key not in {"name", "parameters"}
             }
 
         try:

glitchlings/dev/__init__.py

@@ -0,0 +1,5 @@
+"""Developer-facing utilities for maintaining the Glitchlings repository."""
+
+from .sync_assets import sync_assets
+
+__all__ = ["sync_assets"]

glitchlings/dev/sync_assets.py

@@ -0,0 +1,153 @@
+"""Synchronise canonical glitchling assets with the vendored Rust copies."""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import sys
+from pathlib import Path
+from typing import Iterator, Sequence
+
+RUST_VENDORED_ASSETS: frozenset[str] = frozenset({
+    "hokey_assets.json",
+    "ocr_confusions.tsv",
+})
+
+
+def _project_root(default: Path | None = None) -> Path:
+    if default is not None:
+        return default
+    return Path(__file__).resolve().parents[3]
+
+
+def _canonical_asset_dir(project_root: Path) -> Path:
+    canonical = project_root / "src" / "glitchlings" / "zoo" / "assets"
+    if not canonical.is_dir():
+        raise RuntimeError(
+            "expected canonical assets under 'src/glitchlings/zoo/assets'; "
+            "run this command from the repository root"
+        )
+    return canonical
+
+
+def _rust_asset_dir(project_root: Path) -> Path:
+    return project_root / "rust" / "zoo" / "assets"
+
+
+def _iter_extraneous_assets(rust_dir: Path) -> Iterator[Path]:
+    if not rust_dir.exists():
+        return
+    for path in rust_dir.iterdir():
+        if path.is_file() and path.name not in RUST_VENDORED_ASSETS:
+            yield path
+
+
+def sync_assets(
+    project_root: Path | None = None,
+    *,
+    check: bool = False,
+    quiet: bool = False,
+) -> bool:
+    """Synchronise the vendored Rust asset copies with the canonical sources."""
+
+    root = _project_root(project_root)
+    canonical_dir = _canonical_asset_dir(root)
+    rust_dir = _rust_asset_dir(root)
+
+    missing_sources = [
+        name
+        for name in RUST_VENDORED_ASSETS
+        if not (canonical_dir / name).is_file()
+    ]
+    if missing_sources:
+        missing_list = ", ".join(sorted(missing_sources))
+        raise RuntimeError(f"missing canonical assets: {missing_list}")
+
+    extraneous = list(_iter_extraneous_assets(rust_dir))
+
+    mismatched: list[tuple[str, str]] = []
+    for name in sorted(RUST_VENDORED_ASSETS):
+        source = canonical_dir / name
+        target = rust_dir / name
+        if not target.exists():
+            mismatched.append((name, "missing"))
+            continue
+        if source.read_bytes() != target.read_bytes():
+            mismatched.append((name, "outdated"))
+
+    if check:
+        if mismatched or extraneous:
+            if not quiet:
+                for name, reason in mismatched:
+                    target = rust_dir / name
+                    print(
+                        f"{target.relative_to(root)} is {reason}; run sync_assets to refresh it",
+                        file=sys.stderr,
+                    )
+                for extra in extraneous:
+                    print(
+                        (
+                            "unexpected vendored asset "
+                            f"{extra.relative_to(root)}; run sync_assets to prune it"
+                        ),
+                        file=sys.stderr,
+                    )
+            return False
+        if not quiet:
+            print("Rust asset bundle is up to date.")
+        return True
+
+    rust_dir.mkdir(parents=True, exist_ok=True)
+
+    for name, reason in mismatched:
+        source = canonical_dir / name
+        target = rust_dir / name
+        shutil.copy2(source, target)
+        if not quiet:
+            verb = "Copied" if reason == "missing" else "Updated"
+            print(
+                f"{verb} {source.relative_to(root)} -> {target.relative_to(root)}",
+            )
+
+    for extra in extraneous:
+        extra.unlink()
+        if not quiet:
+            print(f"Removed extraneous vendored asset {extra.relative_to(root)}")
+
+    if not mismatched and not extraneous and not quiet:
+        print("Rust asset bundle already aligned with canonical copies.")
+
+    return True
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Synchronise canonical glitchling assets with the vendored Rust copies.",
+    )
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="exit with a non-zero status when vendored assets diverge",
+    )
+    parser.add_argument(
+        "--quiet",
+        action="store_true",
+        help="suppress status output",
+    )
+    parser.add_argument(
+        "--project-root",
+        type=Path,
+        help="override the detected project root (useful for testing)",
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    ok = sync_assets(project_root=args.project_root, check=args.check, quiet=args.quiet)
+    return 0 if ok else 1
+
+
+if __name__ == "__main__":  # pragma: no cover - CLI entry point
+    raise SystemExit(main())

glitchlings/dlc/_shared.py

@@ -67,10 +67,10 @@ def resolve_columns(dataset: Any, columns: Sequence[str] | None) -> list[str]:
     raise ValueError("Unable to determine which dataset columns to corrupt.")
 
 
-def normalise_column_spec(
+def normalize_column_spec(
     columns: str | int | Sequence[str | int] | None,
 ) -> list[str | int] | None:
-    """Normalise a column specification into a list of keys or indices.
+    """Normalize a column specification into a list of keys or indices.
 
     Args:
         columns: Column specification as a single value, sequence of values, or None.
@@ -87,10 +87,10 @@ def normalise_column_spec(
     if isinstance(columns, (str, int)):
         return [columns]
 
-    normalised = list(columns)
-    if not normalised:
+    normalized = list(columns)
+    if not normalized:
         raise ValueError("At least one column must be specified")
-    return normalised
+    return normalized
 
 
 def is_textual_candidate(value: Any) -> bool:
@@ -147,7 +147,7 @@ def corrupt_text_value(value: Any, gaggle: Gaggle) -> Any:
 __all__ = [
     "corrupt_text_value",
     "is_textual_candidate",
-    "normalise_column_spec",
+    "normalize_column_spec",
     "resolve_columns",
     "resolve_environment",
 ]

glitchlings/dlc/huggingface.py

@@ -10,15 +10,15 @@ from ..util.adapters import coerce_gaggle
 from ..zoo import Gaggle, Glitchling
 
 
-def _normalise_columns(column: str | Sequence[str]) -> list[str]:
-    """Normalise a column specification to a list."""
+def _normalize_columns(column: str | Sequence[str]) -> list[str]:
+    """Normalize a column specification to a list."""
     if isinstance(column, str):
         return [column]
 
-    normalised = list(column)
-    if not normalised:
+    normalized = list(column)
+    if not normalized:
         raise ValueError("At least one column must be specified")
-    return normalised
+    return normalized
 
 
 def _glitch_dataset(
@@ -29,7 +29,7 @@ def _glitch_dataset(
     seed: int = 151,
 ) -> Any:
     """Apply glitchlings to the provided dataset columns."""
-    columns = _normalise_columns(column)
+    columns = _normalize_columns(column)
     gaggle = coerce_gaggle(glitchlings, seed=seed)
     return gaggle.corrupt_dataset(dataset, columns)
 

glitchlings/dlc/prime.py

@@ -117,7 +117,7 @@ def _as_gaggle(
 
 
 def _extract_completion_text(completion: Any) -> str:
-    """Normalise a completion payload into a plain string."""
+    """Normalize a completion payload into a plain string."""
     if isinstance(completion, str):
         return completion
 

glitchlings/dlc/pytorch.py

@@ -9,7 +9,7 @@ from ..compat import get_torch_dataloader, require_torch
 from ..compat import torch as _torch_dependency
 from ..util.adapters import coerce_gaggle
 from ..zoo import Gaggle, Glitchling
-from ._shared import corrupt_text_value, is_textual_candidate, normalise_column_spec
+from ._shared import corrupt_text_value, is_textual_candidate, normalize_column_spec
 
 
 def _apply_to_batch(batch: Any, targets: list[str | int] | None, gaggle: Gaggle) -> Any:
@@ -134,8 +134,8 @@ def _ensure_dataloader_class() -> type[Any]:
         ) -> _GlitchedDataLoader:
             """Return a lazily glitched view of the loader's batches."""
             gaggle = coerce_gaggle(glitchlings, seed=seed)
-            normalised = normalise_column_spec(columns)
-            return _GlitchedDataLoader(self, gaggle, columns=normalised)
+            normalized = normalize_column_spec(columns)
+            return _GlitchedDataLoader(self, gaggle, columns=normalized)
 
         setattr(dataloader_cls, "glitch", glitch)
 

glitchlings/dlc/pytorch_lightning.py

@@ -8,7 +8,7 @@ from typing import Any, cast
 from ..compat import get_pytorch_lightning_datamodule, require_pytorch_lightning
 from ..util.adapters import coerce_gaggle
 from ..zoo import Gaggle, Glitchling
-from ._shared import corrupt_text_value, normalise_column_spec
+from ._shared import corrupt_text_value, normalize_column_spec
 
 
 def _glitch_batch(batch: Any, columns: list[str], gaggle: Gaggle) -> Any:
@@ -40,10 +40,7 @@ def _wrap_dataloader(dataloader: Any, columns: list[str], gaggle: Gaggle) -> Any
     if isinstance(dataloader, Mapping):
         mapping_type = cast(type[Any], dataloader.__class__)
         return mapping_type(
-            {
-                key: _wrap_dataloader(value, columns, gaggle)
-                for key, value in dataloader.items()
-            }
+            {key: _wrap_dataloader(value, columns, gaggle) for key, value in dataloader.items()}
         )
 
     if isinstance(dataloader, list):
@@ -54,9 +51,7 @@ def _wrap_dataloader(dataloader: Any, columns: list[str], gaggle: Gaggle) -> Any
 
     if isinstance(dataloader, Sequence) and not isinstance(dataloader, (str, bytes, bytearray)):
         sequence_type = cast(type[Any], dataloader.__class__)
-        return sequence_type(
-            _wrap_dataloader(value, columns, gaggle) for value in dataloader
-        )
+        return sequence_type(_wrap_dataloader(value, columns, gaggle) for value in dataloader)
 
     return _GlitchedDataLoader(dataloader, columns, gaggle)
 
@@ -89,7 +84,7 @@ def _glitch_datamodule(
 ) -> Any:
     """Return a proxy that applies glitchlings to batches from the datamodule."""
 
-    columns = normalise_column_spec(column)
+    columns = normalize_column_spec(column)
     if columns is None:  # pragma: no cover - defensive
         raise ValueError("At least one column must be specified")
     # Lightning datamodules only support string column names (mapping keys)
@@ -212,4 +207,3 @@ else:  # pragma: no cover - optional dependency
 
 
 __all__ = ["LightningDataModule", "install"]
-

glitchlings/lexicon/_cache.py

@@ -19,7 +19,7 @@ class CacheSnapshot:
     checksum: str | None = None
 
 
-def _normalise_entries(payload: Mapping[str, object]) -> CacheEntries:
+def _normalize_entries(payload: Mapping[str, object]) -> CacheEntries:
     """Convert raw cache payloads into canonical mapping form."""
     entries: CacheEntries = {}
     for key, values in payload.items():
@@ -75,7 +75,7 @@ def load_cache(path: Path) -> CacheSnapshot:
     else:
         entries_payload = payload  # legacy format without metadata
 
-    entries = _normalise_entries(entries_payload)
+    entries = _normalize_entries(entries_payload)
     if checksum is not None:
         expected = compute_checksum(entries)
         if checksum != expected:
@@ -88,9 +88,7 @@ def load_cache(path: Path) -> CacheSnapshot:
 
 def write_cache(path: Path, entries: Mapping[str, Sequence[str]]) -> CacheSnapshot:
     """Persist ``entries`` to ``path`` with checksum metadata."""
-    serialisable: CacheEntries = {
-        key: list(values) for key, values in sorted(entries.items())
-    }
+    serialisable: CacheEntries = {key: list(values) for key, values in sorted(entries.items())}
     checksum = compute_checksum(serialisable)
     payload = {
         "__meta__": {

glitchlings/lexicon/vector.py

@@ -16,6 +16,9 @@ from ._cache import CacheSnapshot
 from ._cache import load_cache as _load_cache_file
 from ._cache import write_cache as _write_cache_file
 
+# Minimum number of neighbors to consider for similarity queries
+MIN_NEIGHBORS = 1
+
 
 def _cosine_similarity(vector_a: Sequence[float], vector_b: Sequence[float]) -> float:
     """Return the cosine similarity between two dense vectors."""
@@ -304,7 +307,7 @@ class VectorLexicon(LexiconBackend):
         """Initialise the lexicon with an embedding ``source`` and optional cache."""
         super().__init__(seed=seed)
         self._adapter = _resolve_source(source)
-        self._max_neighbors = max(1, max_neighbors)
+        self._max_neighbors = max(MIN_NEIGHBORS, max_neighbors)
         self._min_similarity = min_similarity
         self._cache: MutableMapping[str, list[str]] = {}
         self._cache_path: Path | None
@@ -371,7 +374,7 @@ class VectorLexicon(LexiconBackend):
         if cache_key in self._cache:
             return self._cache[cache_key]
 
-        neighbor_limit = self._max_neighbors if limit is None else max(1, limit)
+        neighbor_limit = self._max_neighbors if limit is None else max(MIN_NEIGHBORS, limit)
         neighbors = self._fetch_neighbors(
             original=original, normalized=normalized, limit=neighbor_limit
         )
@@ -624,9 +627,7 @@ def main(argv: Sequence[str] | None = None) -> int:
             )
             iterator = lexicon.iter_vocabulary()
             if args.limit is not None:
-                token_iter = (
-                    token for index, token in enumerate(iterator) if index < args.limit
-                )
+                token_iter = (token for index, token in enumerate(iterator) if index < args.limit)
             else:
                 token_iter = iterator
 

glitchlings/lexicon/wordnet.py

@@ -13,21 +13,17 @@ from ._cache import CacheSnapshot
 
 
 class _LemmaProtocol(Protocol):
-    def name(self) -> str:
-        ...
+    def name(self) -> str: ...
 
 
 class _SynsetProtocol(Protocol):
-    def lemmas(self) -> Sequence[_LemmaProtocol]:
-        ...
+    def lemmas(self) -> Sequence[_LemmaProtocol]: ...
 
 
 class _WordNetResource(Protocol):
-    def synsets(self, word: str, pos: str | None = None) -> Sequence[_SynsetProtocol]:
-        ...
+    def synsets(self, word: str, pos: str | None = None) -> Sequence[_SynsetProtocol]: ...
 
-    def ensure_loaded(self) -> None:
-        ...
+    def ensure_loaded(self) -> None: ...
 
 
 WordNetCorpusReaderFactory = Callable[[Any, Any], _WordNetResource]

glitchlings/util/hokey_generator.py

@@ -0,0 +1,144 @@
+"""Hokey expressive lengthening generator."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .stretch_locator import StretchSite, apply_stretch, find_stretch_site
+from .stretchability import RandomLike, StretchabilityAnalyzer, StretchabilityFeatures
+
+
+@dataclass(slots=True)
+class HokeyConfig:
+    rate: float = 0.3
+    extension_min: int = 2
+    extension_max: int = 5
+    base_p: float = 0.45
+    word_length_threshold: int = 6
+
+
+@dataclass(slots=True)
+class StretchEvent:
+    token_index: int
+    original: str
+    stretched: str
+    repeats: int
+    site: StretchSite
+    score: float
+    features: StretchabilityFeatures
+
+
+class NegativeBinomialSampler:
+    """Sample stretch lengths from a clipped negative binomial distribution."""
+
+    def __init__(self, base_p: float = 0.45) -> None:
+        self.base_p = base_p
+
+    def sample(
+        self,
+        rng: RandomLike,
+        *,
+        intensity: float,
+        minimum: int,
+        maximum: int,
+    ) -> int:
+        minimum = max(0, int(minimum))
+        maximum = max(minimum, int(maximum))
+        if maximum == 0:
+            return 0
+        if maximum == minimum:
+            return maximum
+
+        r = max(1, int(round(1 + 2 * intensity)))
+        adjusted_p = self.base_p / (1.0 + 0.75 * max(0.0, intensity))
+        adjusted_p = max(0.05, min(0.95, adjusted_p))
+        failures = sum(self._geometric_sample(rng, adjusted_p) for _ in range(r))
+        extra = minimum + failures
+        return max(minimum, min(maximum, extra))
+
+    @staticmethod
+    def _geometric_sample(rng: RandomLike, p: float) -> int:
+        count = 0
+        while rng.random() > p:
+            count += 1
+        return count
+
+
+class HokeyGenerator:
+    """Full expressive lengthening pipeline."""
+
+    def __init__(
+        self,
+        analyzer: StretchabilityAnalyzer | None = None,
+        sampler: NegativeBinomialSampler | None = None,
+    ) -> None:
+        self.analyzer = analyzer or StretchabilityAnalyzer()
+        self.sampler = sampler or NegativeBinomialSampler()
+
+    def generate(
+        self,
+        text: str,
+        *,
+        rng: RandomLike,
+        config: HokeyConfig,
+    ) -> tuple[str, list[StretchEvent]]:
+        if not text:
+            return text, []
+
+        if config.base_p != self.sampler.base_p:
+            self.sampler.base_p = config.base_p
+
+        tokens = self.analyzer.tokenise(text)
+        candidates = self.analyzer.analyse_tokens(tokens)
+        selected = self.analyzer.select_candidates(candidates, rate=config.rate, rng=rng)
+        if not selected:
+            return text, []
+
+        token_strings = [token.text for token in tokens]
+        events: list[StretchEvent] = []
+
+        for candidate in selected:
+            token_idx = candidate.token.index
+            original = token_strings[token_idx]
+            site = find_stretch_site(original)
+            if site is None:
+                continue
+
+            intensity = min(1.5, candidate.features.intensity() + 0.35 * candidate.score)
+            alpha_count = sum(1 for ch in original if ch.isalpha())
+            if config.word_length_threshold > 0 and alpha_count > config.word_length_threshold * 2:
+                continue
+            if config.word_length_threshold > 0 and alpha_count > config.word_length_threshold:
+                excess = alpha_count - config.word_length_threshold
+                intensity = intensity / (1.0 + 0.35 * excess)
+                if candidate.score < 0.35 and excess >= 2:
+                    continue
+            intensity = max(0.05, intensity)
+
+            repeats = self.sampler.sample(
+                rng,
+                intensity=intensity,
+                minimum=config.extension_min,
+                maximum=config.extension_max,
+            )
+            if repeats <= 0:
+                continue
+
+            stretched_word = apply_stretch(original, site, repeats)
+            token_strings[token_idx] = stretched_word
+            events.append(
+                StretchEvent(
+                    token_index=token_idx,
+                    original=original,
+                    stretched=stretched_word,
+                    repeats=repeats,
+                    site=site,
+                    score=candidate.score,
+                    features=candidate.features,
+                )
+            )
+
+        return "".join(token_strings), events
+
+
+__all__ = ["HokeyGenerator", "HokeyConfig", "StretchEvent", "NegativeBinomialSampler"]