glitchlings 0.4.4__cp313-cp313-macosx_11_0_universal2.whl → 0.4.5__cp313-cp313-macosx_11_0_universal2.whl

glitchlings/zoo/hokey.py

@@ -0,0 +1,173 @@
+"""Hokey glitchling that performs expressive lengthening."""
+
+from __future__ import annotations
+
+import random
+from typing import Any, cast
+
+from ..util.hokey_generator import HokeyConfig, HokeyGenerator, StretchEvent
+from ..util.stretchability import StretchabilityAnalyzer
+from ._rust_extensions import get_rust_operation
+from .core import AttackOrder, AttackWave, Gaggle
+from .core import Glitchling as GlitchlingBase
+
+_hokey_rust = get_rust_operation("hokey")
+_ANALYZER = StretchabilityAnalyzer()
+_GENERATOR = HokeyGenerator(analyzer=_ANALYZER)
+
+
+def _python_extend_vowels(
+    text: str,
+    *,
+    rate: float,
+    extension_min: int,
+    extension_max: int,
+    word_length_threshold: int,
+    base_p: float,
+    rng: random.Random,
+    return_trace: bool = False,
+) -> str | tuple[str, list[StretchEvent]]:
+    config = HokeyConfig(
+        rate=rate,
+        extension_min=extension_min,
+        extension_max=extension_max,
+        word_length_threshold=word_length_threshold,
+        base_p=base_p,
+    )
+    result, events = _GENERATOR.generate(text, rng=rng, config=config)
+    return (result, events) if return_trace else result
+
+
+def extend_vowels(
+    text: str,
+    rate: float = 0.3,
+    extension_min: int = 2,
+    extension_max: int = 5,
+    word_length_threshold: int = 6,
+    seed: int | None = None,
+    rng: random.Random | None = None,
+    *,
+    return_trace: bool = False,
+    base_p: float | None = None,
+) -> str | tuple[str, list[StretchEvent]]:
+    """Extend expressive segments of words for emphasis.
+
+    Parameters
+    ----------
+    text : str
+        Input text to transform.
+    rate : float, optional
+        Global selection rate for candidate words.
+    extension_min : int, optional
+        Minimum number of extra repetitions for the stretch unit.
+    extension_max : int, optional
+        Maximum number of extra repetitions for the stretch unit.
+    word_length_threshold : int, optional
+        Preferred maximum alphabetic length; longer words are de-emphasised but not
+        excluded.
+    seed : int, optional
+        Deterministic seed when ``rng`` is not supplied.
+    rng : random.Random, optional
+        Random number generator to drive sampling.
+    return_trace : bool, optional
+        When ``True`` also return the stretch events for introspection.
+    base_p : float, optional
+        Base probability for the negative-binomial sampler (heavier tails for smaller
+        values). Defaults to ``0.45``.
+    """
+    if not text:
+        empty_trace: list[StretchEvent] = []
+        return (text, empty_trace) if return_trace else text
+
+    if rng is None:
+        rng = random.Random(seed)
+    base_probability = base_p if base_p is not None else 0.45
+
+    if return_trace or _hokey_rust is None:
+        return _python_extend_vowels(
+            text,
+            rate=rate,
+            extension_min=extension_min,
+            extension_max=extension_max,
+            word_length_threshold=word_length_threshold,
+            base_p=base_probability,
+            rng=rng,
+            return_trace=return_trace,
+        )
+
+    return cast(
+        str,
+        _hokey_rust(
+            text,
+            rate,
+            extension_min,
+            extension_max,
+            word_length_threshold,
+            base_probability,
+            rng,
+        ),
+    )
+
+
+class Hokey(GlitchlingBase):
+    """Glitchling that stretches words using linguistic heuristics."""
+
+    seed: int | None
+
+    def __init__(
+        self,
+        *,
+        rate: float = 0.3,
+        extension_min: int = 2,
+        extension_max: int = 5,
+        word_length_threshold: int = 6,
+        base_p: float = 0.45,
+        seed: int | None = None,
+    ) -> None:
+        self._master_seed: int | None = seed
+
+        def _corruption_wrapper(text: str, **kwargs: Any) -> str:
+            result = extend_vowels(text, **kwargs)
+            return result if isinstance(result, str) else result[0]
+
+        super().__init__(
+            name="Hokey",
+            corruption_function=_corruption_wrapper,
+            scope=AttackWave.CHARACTER,
+            order=AttackOrder.FIRST,
+            seed=seed,
+            rate=rate,
+            extension_min=extension_min,
+            extension_max=extension_max,
+            word_length_threshold=word_length_threshold,
+            base_p=base_p,
+        )
+
+    def pipeline_operation(self) -> dict[str, Any] | None:
+        return {
+            "type": "hokey",
+            "rate": self.kwargs.get("rate", 0.3),
+            "extension_min": self.kwargs.get("extension_min", 2),
+            "extension_max": self.kwargs.get("extension_max", 5),
+            "word_length_threshold": self.kwargs.get("word_length_threshold", 6),
+            "base_p": self.kwargs.get("base_p", 0.45),
+        }
+
+    def reset_rng(self, seed: int | None = None) -> None:
+        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)
+
+
+hokey = Hokey()
+
+
+__all__ = ["Hokey", "hokey", "extend_vowels"]

{glitchlings-0.4.4.dist-info → glitchlings-0.4.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: glitchlings
-Version: 0.4.4
+Version: 0.4.5
 Summary: Monsters for your language games.
 Author: osoleve
 License:                                  Apache License
@@ -294,6 +294,12 @@ Dynamic: license-file
                         Every language game breeds monsters.
 ```
 
+[![PyPI version](https://img.shields.io/pypi/v/glitchlings.svg)](https://pypi.org/project/glitchlings/)
+[![PyPI Status](https://github.com/osoleve/glitchlings/actions/workflows/publish.yml/badge.svg)](https://github.com/osoleve/glitchlings/actions/workflows/publish.yml)
+[![Lint and Type](https://github.com/osoleve/glitchlings/actions/workflows/ci.yml/badge.svg)](https://github.com/osoleve/glitchlings/actions/workflows/ci.yml)
+[![Website status](https://img.shields.io/website-up-down-green-red/https/osoleve.github.io/glitchlings)](https://osoleve.github.io/glitchlings/)
+[![License](https://img.shields.io/github/license/osoleve/glitchlings.svg)](https://github.com/osoleve/glitchlings/blob/main/LICENSE)
+
 `Glitchlings` are **utilities for corrupting the text inputs to your language models in deterministic, _linguistically principled_** ways.  
 Each embodies a different way that documents can be compromised in the wild.
 
@@ -382,6 +388,7 @@ glitchlings --list
 ```text
    Typogre — scope: Character, order: early
 Apostrofae — scope: Character, order: normal
+     Hokey — scope: Character, order: first
      Mim1c — scope: Character, order: last
   Jargoyle — scope: Word, order: normal
      Adjax — scope: Word, order: normal
@@ -429,10 +436,6 @@ options:
 ```
 <!-- END: CLI_USAGE -->
 
-Run `python docs/build_cli_reference.py` whenever you tweak the CLI so the README stays in sync with the actual output. The script executes the commands above and replaces the block between the markers automatically.
-
-Prefer inline tweaks? You can still configure glitchlings directly in the shell:
-
 ```bash
 # Run Typogre against the contents of a file and inspect the diff.
 glitchlings -g typogre --file documents/report.txt --diff
@@ -507,6 +510,22 @@ _Wait, was that...?_
 > - `banned_characters (Collection[str])`: Characters that must never appear as replacements (default: none).
 > - `seed (int)`: The random seed for reproducibility (default: 151).
 
+### Hokey
+
+_She's soooooo coooool!_
+
+> _**Passionista.**_ Hokey sometimes gets a little excited and elongates words for emphasis.
+>
+> Args
+>
+> - `rate (float)`: Share of high-scoring tokens to stretch (default: 0.3).
+> - `extension_min` / `extension_max (int)`: Bounds for extra repetitions (defaults: 2 / 5).
+> - `word_length_threshold (int)`: Preferred maximum alphabetic length; longer words are damped instead of excluded (default: 6).
+> - `base_p (float)`: Base probability for the heavy-tailed sampler (default: 0.45).
+> - `seed (int)`: The random seed for reproducibility (default: 151).
+
+_Apocryphal Glitchling contributed by Chloé Nunes_
+
 ### Scannequin
 
 _How can a computer need reading glasses?_
@@ -539,7 +558,9 @@ _Uh oh. The worst person you know just bought a thesaurus._
 > Args
 >
 > - `rate (float)`: The maximum proportion of words to replace (default: 0.01, 1%).
+>
 - `part_of_speech`: The WordNet-style part(s) of speech to target (default: nouns). Accepts `wn.NOUN`, `wn.VERB`, `wn.ADJ`, `wn.ADV`, any iterable of those tags, or the string `"any"` to include them all. Vector/graph backends ignore this filter while still honouring deterministic sampling.
+>
 > - `seed (int)`: The random seed for reproducibility (default: 151).
 
 ### Reduple

{glitchlings-0.4.4.dist-info → glitchlings-0.4.5.dist-info}/RECORD

@@ -1,25 +1,30 @@
-glitchlings/__init__.py,sha256=bkyRgzjC8ssidEO9UL9VpbYXQxTV1Hz3VAPOIqd9uMg,1182
+glitchlings/__init__.py,sha256=A6m-sj1Gnq5DXdaD7IRsPnMvXW9UjZh3fQGcvps22uw,1230
 glitchlings/__main__.py,sha256=f-P4jiVBd7ZpS6QxRpa_6SJgOG03UhZhcWasMDRWLs8,120
-glitchlings/_zoo_rust.cpython-313-darwin.so,sha256=UOcVJduXd_2QvSHzgOdWIujAl-NGbk4ulhUPcF29ExI,2603296
-glitchlings/compat.py,sha256=T_5Ia8yCzZvsMdicZ2TCcOgDO53_AjNGkSXWTR_qEnA,8908
-glitchlings/config.py,sha256=ofxDMkoMg4j51CFube54aca1Ky9y_ZeVktXpeUEdWmA,12953
+glitchlings/_zoo_rust.cpython-313-darwin.so,sha256=1r9-InXhPIMfF5aQu5uiphWat3qF0LswlN_rwrjrCe8,2697808
+glitchlings/compat.py,sha256=lswR7J3kXER5hPXeyfkO-7USJvUhdtTi1ovJgEpspKc,8892
+glitchlings/config.py,sha256=J_Bk901-WLeqDhrmvTrjUZLxgIgSqR0qYU2oDaNPjt8,12937
 glitchlings/config.toml,sha256=04-Y_JCdQU68SRmwk2qZqrH_bbX4jEH9uh7URtxdIHA,99
 glitchlings/main.py,sha256=uw8VbDgxov1m-wYHPDl2dP5ItpLB4ZHpb0ChJXzcL0o,10623
+glitchlings/data/__init__.py,sha256=JZwsJhnZHnr2onnukNduNjfNSurzGn3v7r1flq_3yl4,68
+glitchlings/data/hokey_assets.json,sha256=9drpOv_PHHxs7jZOcgMr9G-Nswx_UuMzC4yQ0O8mIZ0,2890
 glitchlings/dlc/__init__.py,sha256=qlY4nuagy4AAWuPMwmuhwK2m36ktp-qkeiIxC7OXg34,305
-glitchlings/dlc/_shared.py,sha256=OmEjJmSs1pQ7j1ggR_H8D8RDp5E1ZqOnzSIxyqRE1aE,4407
-glitchlings/dlc/huggingface.py,sha256=9lW7TnTHA_bXyo4Is8pymZchrB9BIL1bMCP2p7LCMtg,2576
-glitchlings/dlc/prime.py,sha256=qGFI1d4BiOEIgQZ5v9QnlbYx4J4q-vNlh5tWZng11xs,8607
-glitchlings/dlc/pytorch.py,sha256=QaiIYyQ3koy2-enhUI9WY3SIMRX65gmsnjDvCsf8xbg,6233
-glitchlings/dlc/pytorch_lightning.py,sha256=Ls7Xh5Mg643Tyk3KvCMq_MsB4vvekfUUZOhE0z4K22c,8074
+glitchlings/dlc/_shared.py,sha256=moQwnJdHMo-dx5uK0zM8XdPy5cs-OlAzYKVWfUP0RSQ,4407
+glitchlings/dlc/huggingface.py,sha256=BWceVUm28Yd8b7Tf_lmnPGgSVN1hZEmseRjf17nAPJw,2576
+glitchlings/dlc/prime.py,sha256=zhm0oTVKNDa1ByxZTP42rmMVaJDyx77w2g6NHy4jndc,8607
+glitchlings/dlc/pytorch.py,sha256=Laqz5o0UZXE1X9P-Qxb6KE0D5lcBKAoBbKsn-fnd6c0,6233
+glitchlings/dlc/pytorch_lightning.py,sha256=rhDwRgOGVzaEet27QG8GigKh6hK5ZdTBOxGE2G0MPxw,8005
 glitchlings/lexicon/__init__.py,sha256=ooEPcAJhCI2Nw5z8OsQ0EtVpKBfiTrU0-AQJq8Zn2nQ,6007
-glitchlings/lexicon/_cache.py,sha256=aWSUb5Ex162dr3HouO2Ic2O8ck3ViEFWs8-XMLKMeJ0,4086
+glitchlings/lexicon/_cache.py,sha256=oWdQtiU3csUAs-fYJRHuS_314j8JJ-T8AL73-GxVXzA,4072
 glitchlings/lexicon/metrics.py,sha256=VBFfFpxjiEwZtK-jS55H8xP7MTC_0OjY8lQ5zSQ9aTY,4572
-glitchlings/lexicon/vector.py,sha256=yWf-vlN2OEHnTCPu7tgDnJbhm47cmhdrTtjR0RZKkUM,22530
-glitchlings/lexicon/wordnet.py,sha256=YcOliPHuesdlekmGspwAyR4fWDDxZWR_dIt_Nsq7ag0,7608
+glitchlings/lexicon/vector.py,sha256=hUtMewkdLdMscQWjFgWcspSg0C_C0JdhFSMAs0HA-i0,22600
+glitchlings/lexicon/wordnet.py,sha256=8wEN3XHI8Cf01h4h9cP4F25FLlGIoUrvk5l2nsgkfx4,7576
 glitchlings/lexicon/data/default_vector_cache.json,sha256=3iVH0nX8EqMbqOkKWvORCGYtN0LKHn5G_Snlizsnm1g,997
 glitchlings/util/__init__.py,sha256=vc3EAY8ehRjbOiryFdaqvvljXcyNGtZSPiEp9ok1vVw,4674
 glitchlings/util/adapters.py,sha256=psxQFYSFmh1u7NuqtIrKwQP5FOhOrZoxZzc7X7DDi9U,693
-glitchlings/zoo/__init__.py,sha256=1dWZPCTXuh5J7WdCxHX7ZX9bNd8bakzYndxQRhF43i8,5243
+glitchlings/util/hokey_generator.py,sha256=NCbOGw55SG720VYnuwEdFAfdOvYlmjsZ0hAr5Y0Ja0Y,4483
+glitchlings/util/stretch_locator.py,sha256=INTMz7PXe-0HoDaMnQIQxJ266nABMXBYD67oJM8ur8g,4194
+glitchlings/util/stretchability.py,sha256=W_FC1-6x1LICLjEyv5rqpsnKnBcj6Lhc5u5A_5cWWIM,12819
+glitchlings/zoo/__init__.py,sha256=xCVVAHLJ4lxl1JQUzff9fr84pJbB04fyXBjuX1m3YSw,5339
 glitchlings/zoo/_ocr_confusions.py,sha256=Ju2_avXiwsr1p8zWFUTOzMxJ8vT5PpYobuGIn4L_sqI,1204
 glitchlings/zoo/_rate.py,sha256=tkIlXHewE8s9w1jpCw8ZzkVN31690FAnvTM_R3dCIpY,3579
 glitchlings/zoo/_rust_extensions.py,sha256=Bsd0kiPB1rUn5x3k7ykydFuk2YSvXS9CQGPRlE5XzXY,4211
@@ -28,6 +33,7 @@ glitchlings/zoo/_text_utils.py,sha256=fS5L_eq-foBbBdiv4ymI8-O0D0csc3yDekHpX8bqfV
 glitchlings/zoo/adjax.py,sha256=XT5kKqPOUPgKSDOcR__HBnv4OXtBKee40GuNNmm1GYI,3518
 glitchlings/zoo/apostrofae.py,sha256=qjpfnxdPWXMNzZnSD7UMfvHyzGKa7TLsvUhMsIvjwj8,3822
 glitchlings/zoo/core.py,sha256=dRzUTmhOswDV0hWcaD-Sx7rZdPlrszn7C_1G2xd4ECk,20675
+glitchlings/zoo/hokey.py,sha256=71z1JGzKGb_N8Wo7LVuS7qAqH2T0Y0h2LemIw66eprs,5298
 glitchlings/zoo/jargoyle.py,sha256=2TGU_z8gILwQ-lyZEqvmsrLupxqb8ydlDiwcp-O6WwY,11679
 glitchlings/zoo/mim1c.py,sha256=-fgodKWZq--Xw8L2t1EqNbsh48bwX5jZxmiXdoaQShI,3437
 glitchlings/zoo/ocr_confusions.tsv,sha256=KhtR7vJDTITpfTSGa-I7RHr6CK7LkGi2KjdhEWipI6o,183
@@ -39,9 +45,9 @@ glitchlings/zoo/typogre.py,sha256=BQotNL-gn4PXQI9j63d2w9mQ4X6ZJKSJ4de-GN-gmUI,66
 glitchlings/zoo/zeedub.py,sha256=aNnjZGeTmMqA2WjgtGh7Fgl9pUQo3AZ2B-tYs2ZFOQE,4840
 glitchlings/zoo/assets/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 glitchlings/zoo/assets/apostrofae_pairs.json,sha256=bfjSEaMTI_axGNJ93nI431KXU0IVp7ayO42gGcMgL6U,521
-glitchlings-0.4.4.dist-info/licenses/LICENSE,sha256=YCvGip-LoaRyu6h0nPo71q6eHEkzUpsE11psDJOIRkw,11337
-glitchlings-0.4.4.dist-info/METADATA,sha256=onpPJTtANv13MyyvYS930OWiJb_Ipxvje5sTrNmNPQw,32388
-glitchlings-0.4.4.dist-info/WHEEL,sha256=3s_eT7rbkGQeiKRiW_YCG21vqO2C4rGI4Jg-le1fLJ0,114
-glitchlings-0.4.4.dist-info/entry_points.txt,sha256=kGOwuAsjFDLtztLisaXtOouq9wFVMOJg5FzaAkg-Hto,54
-glitchlings-0.4.4.dist-info/top_level.txt,sha256=VHFNBrLjtDwPCYXbGKi6o17Eueedi81eNbR3hBOoST0,12
-glitchlings-0.4.4.dist-info/RECORD,,
+glitchlings-0.4.5.dist-info/licenses/LICENSE,sha256=YCvGip-LoaRyu6h0nPo71q6eHEkzUpsE11psDJOIRkw,11337
+glitchlings-0.4.5.dist-info/METADATA,sha256=3h0Eb8nUL3NXb67OQBYEnuL-aNs0oJ8-dLVAQDeFfD8,33498
+glitchlings-0.4.5.dist-info/WHEEL,sha256=3s_eT7rbkGQeiKRiW_YCG21vqO2C4rGI4Jg-le1fLJ0,114
+glitchlings-0.4.5.dist-info/entry_points.txt,sha256=kGOwuAsjFDLtztLisaXtOouq9wFVMOJg5FzaAkg-Hto,54
+glitchlings-0.4.5.dist-info/top_level.txt,sha256=VHFNBrLjtDwPCYXbGKi6o17Eueedi81eNbR3hBOoST0,12
+glitchlings-0.4.5.dist-info/RECORD,,