glitchlings 0.4.5__cp311-cp311-win_amd64.whl

glitchlings/util/__init__.py

@@ -0,0 +1,195 @@
+import difflib
+from collections.abc import Iterable
+
+__all__ = [
+    "SAMPLE_TEXT",
+    "string_diffs",
+    "KeyNeighborMap",
+    "KeyboardLayouts",
+    "KeyNeighbors",
+    "KEYNEIGHBORS",
+]
+
+SAMPLE_TEXT = (
+    "One morning, when Gregor Samsa woke from troubled dreams, he found himself "
+    "transformed in his bed into a horrible vermin. He lay on his armour-like back, and "
+    "if he lifted his head a little he could see his brown belly, slightly domed and "
+    "divided by arches into stiff sections. The bedding was hardly able to cover it and "
+    "seemed ready to slide off any moment. His many legs, pitifully thin compared with "
+    "the size of the rest of him, waved about helplessly as he looked."
+)
+
+
+def string_diffs(a: str, b: str) -> list[list[tuple[str, str, str]]]:
+    """Compare two strings using SequenceMatcher and return
+    grouped adjacent opcodes (excluding 'equal' tags).
+
+    Each element is a tuple: (tag, a_text, b_text).
+    """
+    sm = difflib.SequenceMatcher(None, a, b)
+    ops: list[list[tuple[str, str, str]]] = []
+    buffer: list[tuple[str, str, str]] = []
+
+    for tag, i1, i2, j1, j2 in sm.get_opcodes():
+        if tag == "equal":
+            # flush any buffered operations before skipping
+            if buffer:
+                ops.append(buffer)
+                buffer = []
+            continue
+
+        # append operation to buffer
+        buffer.append((tag, a[i1:i2], b[j1:j2]))
+
+    # flush trailing buffer
+    if buffer:
+        ops.append(buffer)
+
+    return ops
+
+
+KeyNeighborMap = dict[str, list[str]]
+KeyboardLayouts = dict[str, KeyNeighborMap]
+
+
+def _build_neighbor_map(rows: Iterable[str]) -> KeyNeighborMap:
+    """Derive 8-neighbour adjacency lists from keyboard layout rows."""
+    grid: dict[tuple[int, int], str] = {}
+    for y, row in enumerate(rows):
+        for x, char in enumerate(row):
+            if char == " ":
+                continue
+            grid[(x, y)] = char.lower()
+
+    neighbors: KeyNeighborMap = {}
+    for (x, y), char in grid.items():
+        seen: list[str] = []
+        for dy in (-1, 0, 1):
+            for dx in (-1, 0, 1):
+                if dx == 0 and dy == 0:
+                    continue
+                candidate = grid.get((x + dx, y + dy))
+                if candidate is None:
+                    continue
+                seen.append(candidate)
+        # Preserve encounter order but drop duplicates for determinism
+        deduped = list(dict.fromkeys(seen))
+        neighbors[char] = deduped
+
+    return neighbors
+
+
+_KEYNEIGHBORS: KeyboardLayouts = {
+    "CURATOR_QWERTY": {
+        "a": [*"qwsz"],
+        "b": [*"vghn  "],
+        "c": [*"xdfv  "],
+        "d": [*"serfcx"],
+        "e": [*"wsdrf34"],
+        "f": [*"drtgvc"],
+        "g": [*"ftyhbv"],
+        "h": [*"gyujnb"],
+        "i": [*"ujko89"],
+        "j": [*"huikmn"],
+        "k": [*"jilom,"],
+        "l": [*"kop;.,"],
+        "m": [*"njk,  "],
+        "n": [*"bhjm  "],
+        "o": [*"iklp90"],
+        "p": [*"o0-[;l"],
+        "q": [*"was 12"],
+        "r": [*"edft45"],
+        "s": [*"awedxz"],
+        "t": [*"r56ygf"],
+        "u": [*"y78ijh"],
+        "v": [*"cfgb  "],
+        "w": [*"q23esa"],
+        "x": [*"zsdc  "],
+        "y": [*"t67uhg"],
+        "z": [*"asx"],
+    }
+}
+
+
+def _register_layout(name: str, rows: Iterable[str]) -> None:
+    _KEYNEIGHBORS[name] = _build_neighbor_map(rows)
+
+
+_register_layout(
+    "DVORAK",
+    (
+        "`1234567890[]\\",
+        " ',.pyfgcrl/=\\",
+        "  aoeuidhtns-",
+        "   ;qjkxbmwvz",
+    ),
+)
+
+_register_layout(
+    "COLEMAK",
+    (
+        "`1234567890-=",
+        " qwfpgjluy;[]\\",
+        "  arstdhneio'",
+        "   zxcvbkm,./",
+    ),
+)
+
+_register_layout(
+    "QWERTY",
+    (
+        "`1234567890-=",
+        " qwertyuiop[]\\",
+        "  asdfghjkl;'",
+        "   zxcvbnm,./",
+    ),
+)
+
+_register_layout(
+    "AZERTY",
+    (
+        "²&é\"'(-è_çà)=",
+        " azertyuiop^$",
+        "  qsdfghjklmù*",
+        "   <wxcvbn,;:!",
+    ),
+)
+
+_register_layout(
+    "QWERTZ",
+    (
+        "^1234567890ß´",
+        " qwertzuiopü+",
+        "  asdfghjklöä#",
+        "   yxcvbnm,.-",
+    ),
+)
+
+_register_layout(
+    "SPANISH_QWERTY",
+    (
+        "º1234567890'¡",
+        " qwertyuiop´+",
+        "  asdfghjklñ´",
+        "   <zxcvbnm,.-",
+    ),
+)
+
+_register_layout(
+    "SWEDISH_QWERTY",
+    (
+        "§1234567890+´",
+        " qwertyuiopå¨",
+        "  asdfghjklöä'",
+        "   <zxcvbnm,.-",
+    ),
+)
+
+
+class KeyNeighbors:
+    def __init__(self) -> None:
+        for layout_name, layout in _KEYNEIGHBORS.items():
+            setattr(self, layout_name, layout)
+
+
+KEYNEIGHBORS: KeyNeighbors = KeyNeighbors()

glitchlings/util/adapters.py

@@ -0,0 +1,27 @@
+"""Adapter helpers shared across Python and DLC integrations."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from ..zoo import Gaggle, Glitchling, summon
+
+
+def coerce_gaggle(
+    glitchlings: Glitchling | Gaggle | str | Iterable[str | Glitchling],
+    *,
+    seed: int,
+) -> Gaggle:
+    """Return a :class:`Gaggle` built from any supported glitchling specifier."""
+    if isinstance(glitchlings, Gaggle):
+        return glitchlings
+
+    if isinstance(glitchlings, (Glitchling, str)):
+        resolved: Iterable[str | Glitchling] = [glitchlings]
+    else:
+        resolved = glitchlings
+
+    return summon(list(resolved), seed=seed)
+
+
+__all__ = ["coerce_gaggle"]

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"]

glitchlings/util/stretch_locator.py

@@ -0,0 +1,140 @@
+"""Identify where expressive stretches should occur within a token."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable
+
+VOWELS = set("aeiouyAEIOUY")
+SONORANTS = set("rlmnwyhRLMNWYH")
+SIBILANTS = set("sSzZxXcCjJ") | {"sh", "Sh", "sH", "SH", "zh", "Zh"}
+DIGRAPHS = {
+    "aa",
+    "ae",
+    "ai",
+    "ay",
+    "ee",
+    "ei",
+    "ey",
+    "ie",
+    "io",
+    "oa",
+    "oe",
+    "oi",
+    "oo",
+    "ou",
+    "ua",
+    "ue",
+    "ui",
+    "ya",
+    "yo",
+    "yu",
+}
+
+
+@dataclass(slots=True)
+class StretchSite:
+    """Location of a stretchable grapheme."""
+
+    start: int
+    end: int
+    category: str
+
+    def unit(self, token: str) -> str:
+        return token[self.start : self.end]
+
+
+def _alpha_indices(token: str) -> list[int]:
+    return [idx for idx, char in enumerate(token) if char.isalpha()]
+
+
+def _vowel_clusters(token: str, indices: Iterable[int]) -> list[tuple[int, int]]:
+    clusters: list[tuple[int, int]] = []
+    start: int | None = None
+    prev_idx: int | None = None
+    for idx in indices:
+        char = token[idx]
+        if char in VOWELS:
+            if start is None:
+                start = idx
+            elif prev_idx is not None and idx != prev_idx + 1:
+                clusters.append((start, prev_idx + 1))
+                start = idx
+        else:
+            if start is not None:
+                clusters.append((start, idx))
+                start = None
+        prev_idx = idx
+    if start is not None and prev_idx is not None:
+        clusters.append((start, prev_idx + 1))
+    return clusters
+
+
+def find_stretch_site(token: str) -> StretchSite | None:
+    """Return the most suitable stretch site for ``token``."""
+
+    alpha_indices = _alpha_indices(token)
+    if not alpha_indices:
+        return None
+
+    lower = token.lower()
+    clusters = _vowel_clusters(lower, alpha_indices)
+    candidates: list[tuple[int, StretchSite]] = []
+
+    # Sibilant/sonorant coda extension (yes -> yesss, hmm -> hmmmm)
+    last_idx = alpha_indices[-1]
+    last_char = lower[last_idx]
+    if len(alpha_indices) >= 2:
+        prev_char = lower[alpha_indices[-2]]
+    else:
+        prev_char = ""
+    has_multi_vowel = any(
+        (end - start >= 2) and not (lower[start] == "y" and start == 0) for start, end in clusters
+    )
+    if last_char in {"s", "z"} and prev_char in VOWELS and not has_multi_vowel:
+        candidates.append((5, StretchSite(last_idx, last_idx + 1, "coda")))
+    elif last_char in SONORANTS and prev_char in VOWELS and not has_multi_vowel:
+        candidates.append((4, StretchSite(last_idx, last_idx + 1, "coda")))
+    elif not clusters:
+        candidates.append((2, StretchSite(last_idx, last_idx + 1, "consonant")))
+
+    # CVCe pattern (cute -> cuuute)
+    if lower.endswith("e") and len(alpha_indices) >= 3:
+        final_letter = alpha_indices[-1]
+        if token[final_letter].lower() == "e":
+            c_idx = alpha_indices[-2]
+            v_idx = alpha_indices[-3]
+            if token[c_idx].lower() not in VOWELS and token[v_idx].lower() in VOWELS:
+                candidates.append((4, StretchSite(v_idx, v_idx + 1, "cvce")))
+
+    for cluster in clusters:
+        start, end = cluster
+        substring = lower[start:end]
+        category = "vowel"
+        if any(substring[i : i + 2] in DIGRAPHS for i in range(max(0, len(substring) - 1))):
+            category = "digraph"
+        priority = 3 if cluster == clusters[-1] else 2
+        candidates.append((priority, StretchSite(start, end, category)))
+
+    if not candidates:
+        return None
+
+    candidates.sort(key=lambda item: (item[0], item[1].end - item[1].start, -item[1].start))
+    return candidates[-1][1]
+
+
+def apply_stretch(token: str, site: StretchSite, repeats: int) -> str:
+    """Return ``token`` with ``repeats`` extra copies of the grapheme at ``site``."""
+
+    if repeats <= 0:
+        return token
+    chars = list(token)
+    stretched: list[str] = []
+    for idx, char in enumerate(chars):
+        stretched.append(char)
+        if site.start <= idx < site.end:
+            stretched.append(char * repeats)
+    return "".join(stretched)
+
+
+__all__ = ["StretchSite", "find_stretch_site", "apply_stretch"]