glitchlings 0.4.0__tar.gz → 0.4.2__tar.gz

{glitchlings-0.4.0/src/glitchlings.egg-info → glitchlings-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: glitchlings
-Version: 0.4.0
+Version: 0.4.2
 Summary: Monsters for your language games.
 Author: osoleve
 License:                                  Apache License
@@ -239,6 +239,16 @@ Provides-Extra: dev
 Requires-Dist: pytest>=8.0.0; extra == "dev"
 Requires-Dist: hypothesis>=6.140.0; extra == "dev"
 Requires-Dist: numpy<=2.0,>=1.24; extra == "dev"
+Requires-Dist: mkdocs>=1.6.0; extra == "dev"
+Requires-Dist: mkdocstrings[python]>=0.24.0; extra == "dev"
+Requires-Dist: mkdocs-material>=9.5.0; extra == "dev"
+Requires-Dist: mkdocstrings-python>=1.10.0; extra == "dev"
+Requires-Dist: interrogate>=1.5.0; extra == "dev"
+Requires-Dist: black>=24.4.0; extra == "dev"
+Requires-Dist: isort>=5.13.0; extra == "dev"
+Requires-Dist: ruff>=0.6.0; extra == "dev"
+Requires-Dist: mypy>=1.8.0; extra == "dev"
+Requires-Dist: pre-commit>=3.8.0; extra == "dev"
 Dynamic: license-file
 
 #
@@ -338,10 +348,66 @@ They're horrible little gremlins, but they're not _unreasonable_.
 
 Keyboard warriors can challenge them directly via the `glitchlings` command:
 
+<!-- BEGIN: CLI_USAGE -->
 ```bash
 # Discover which glitchlings are currently on the loose.
 glitchlings --list
+```
+
+```text
+   Typogre — scope: Character, order: early
+     Mim1c — scope: Character, order: last
+  Jargoyle — scope: Word, order: normal
+     Adjax — scope: Word, order: normal
+   Reduple — scope: Word, order: normal
+  Rushmore — scope: Word, order: normal
+  Redactyl — scope: Word, order: normal
+Scannequin — scope: Character, order: late
+    Zeedub — scope: Character, order: last
+```
+
+```bash
+# Review the full CLI contract.
+glitchlings --help
+```
 
+```text
+usage: glitchlings [-h] [-g SPEC] [-s SEED] [-f FILE] [--sample] [--diff]
+                   [--list] [-c CONFIG]
+                   [text]
+
+Summon glitchlings to corrupt text. Provide input text as an argument, via
+--file, or pipe it on stdin.
+
+positional arguments:
+  text                  Text to corrupt. If omitted, stdin is used or --sample
+                        provides fallback text.
+
+options:
+  -h, --help            show this help message and exit
+  -g SPEC, --glitchling SPEC
+                        Glitchling to apply, optionally with parameters like
+                        Typogre(rate=0.05). Repeat for multiples; defaults to
+                        all built-ins.
+  -s SEED, --seed SEED  Seed controlling deterministic corruption order
+                        (default: 151).
+  -f FILE, --file FILE  Read input text from a file instead of the command
+                        line argument.
+  --sample              Use the included SAMPLE_TEXT when no other input is
+                        provided.
+  --diff                Show a unified diff between the original and corrupted
+                        text.
+  --list                List available glitchlings and exit.
+  -c CONFIG, --config CONFIG
+                        Load glitchlings from a YAML configuration file.
+```
+<!-- 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
 
@@ -355,8 +421,6 @@ echo "Beware LLM-written flavor-text" | glitchlings -g mim1c
 glitchlings --config experiments/chaos.yaml "Let slips the glitchlings of war"
 ```
 
-Use `--help` for a complete breakdown of available options, including support for parameterised glitchlings via `-g "Name(arg=value, ...)"` to mirror the Python API.
-
 Attack configurations live in plain YAML files so you can version-control experiments without touching code:
 
 ```yaml
@@ -420,7 +484,7 @@ _How can a computer need reading glasses?_
 
 ### Zeedub
 
-_A whispering glyph parasite that lives in the interstices of codepoints, marking territory with invisible traces._
+_Watch your step around here._
 
 > _**Invisible Ink.**_ Zeedub slips zero-width codepoints between non-space character pairs, forcing models to reason about text whose visible form masks hidden glyphs.
 >

{glitchlings-0.4.0 → glitchlings-0.4.2}/README.md

@@ -95,10 +95,66 @@ They're horrible little gremlins, but they're not _unreasonable_.
 
 Keyboard warriors can challenge them directly via the `glitchlings` command:
 
+<!-- BEGIN: CLI_USAGE -->
 ```bash
 # Discover which glitchlings are currently on the loose.
 glitchlings --list
+```
+
+```text
+   Typogre — scope: Character, order: early
+     Mim1c — scope: Character, order: last
+  Jargoyle — scope: Word, order: normal
+     Adjax — scope: Word, order: normal
+   Reduple — scope: Word, order: normal
+  Rushmore — scope: Word, order: normal
+  Redactyl — scope: Word, order: normal
+Scannequin — scope: Character, order: late
+    Zeedub — scope: Character, order: last
+```
+
+```bash
+# Review the full CLI contract.
+glitchlings --help
+```
 
+```text
+usage: glitchlings [-h] [-g SPEC] [-s SEED] [-f FILE] [--sample] [--diff]
+                   [--list] [-c CONFIG]
+                   [text]
+
+Summon glitchlings to corrupt text. Provide input text as an argument, via
+--file, or pipe it on stdin.
+
+positional arguments:
+  text                  Text to corrupt. If omitted, stdin is used or --sample
+                        provides fallback text.
+
+options:
+  -h, --help            show this help message and exit
+  -g SPEC, --glitchling SPEC
+                        Glitchling to apply, optionally with parameters like
+                        Typogre(rate=0.05). Repeat for multiples; defaults to
+                        all built-ins.
+  -s SEED, --seed SEED  Seed controlling deterministic corruption order
+                        (default: 151).
+  -f FILE, --file FILE  Read input text from a file instead of the command
+                        line argument.
+  --sample              Use the included SAMPLE_TEXT when no other input is
+                        provided.
+  --diff                Show a unified diff between the original and corrupted
+                        text.
+  --list                List available glitchlings and exit.
+  -c CONFIG, --config CONFIG
+                        Load glitchlings from a YAML configuration file.
+```
+<!-- 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
 
@@ -112,8 +168,6 @@ echo "Beware LLM-written flavor-text" | glitchlings -g mim1c
 glitchlings --config experiments/chaos.yaml "Let slips the glitchlings of war"
 ```
 
-Use `--help` for a complete breakdown of available options, including support for parameterised glitchlings via `-g "Name(arg=value, ...)"` to mirror the Python API.
-
 Attack configurations live in plain YAML files so you can version-control experiments without touching code:
 
 ```yaml
@@ -177,7 +231,7 @@ _How can a computer need reading glasses?_
 
 ### Zeedub
 
-_A whispering glyph parasite that lives in the interstices of codepoints, marking territory with invisible traces._
+_Watch your step around here._
 
 > _**Invisible Ink.**_ Zeedub slips zero-width codepoints between non-space character pairs, forcing models to reason about text whose visible form masks hidden glyphs.
 >

{glitchlings-0.4.0 → glitchlings-0.4.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "glitchlings"
-version = "0.4.0"
+version = "0.4.2"
 description = "Monsters for your language games."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -56,6 +56,16 @@ dev = [
     "pytest>=8.0.0",
     "hypothesis>=6.140.0",
     "numpy>=1.24,<=2.0",
+    "mkdocs>=1.6.0",
+    "mkdocstrings[python]>=0.24.0",
+    "mkdocs-material>=9.5.0",
+    "mkdocstrings-python>=1.10.0",
+    "interrogate>=1.5.0",
+    "black>=24.4.0",
+    "isort>=5.13.0",
+    "ruff>=0.6.0",
+    "mypy>=1.8.0",
+    "pre-commit>=3.8.0",
 ]
 
 [build-system]
@@ -85,3 +95,66 @@ debug = false
 pythonpath = [
     "src",
 ]
+
+[tool.interrogate]
+config = true
+fail-under = 80
+ignore-init-module = true
+ignore-module = true
+ignore-nested-functions = true
+ignore-private = true
+ignore-semiprivate = true
+ignore-magic = true
+ignore-property-decorators = false
+color = true
+quiet = false
+exclude = [
+    "tests",
+    "docs",
+    "rust",
+    "benchmarks",
+]
+
+[tool.black]
+line-length = 100
+target-version = ["py310"]
+
+[tool.isort]
+profile = "black"
+line_length = 100
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+
+[tool.mypy]
+python_version = "3.10"
+follow_imports = "skip"
+ignore_missing_imports = true
+enable_error_code = ["ignore-without-code"]
+
+[[tool.mypy.overrides]]
+module = [
+    "glitchlings.util.adapters",
+    "glitchlings.dlc._shared",
+    "glitchlings.dlc.huggingface",
+    "glitchlings.dlc.prime",
+]
+strict = true
+
+[[tool.mypy.overrides]]
+module = [
+    "glitchlings.compat",
+    "glitchlings.config",
+    "glitchlings.lexicon",
+    "glitchlings.lexicon.*",
+    "glitchlings.zoo",
+    "glitchlings.zoo.*",
+    "glitchlings.main",
+    "glitchlings.__main__",
+    "glitchlings.__init__",
+]
+ignore_errors = true

{glitchlings-0.4.0 → glitchlings-0.4.2}/rust/zoo/src/glitch_ops.rs

@@ -398,6 +398,7 @@ impl GlitchOp for SwapAdjacentWordsOp {
         }
 
         let mut index = 0usize;
+        let mut replacements: SmallVec<[(usize, String); 8]> = SmallVec::new();
         while index + 1 < total_words {
             let left_segment = match buffer.word_segment(index) {
                 Some(segment) => segment,
@@ -423,13 +424,17 @@ impl GlitchOp for SwapAdjacentWordsOp {
             if should_swap {
                 let left_replacement = format!("{left_prefix}{right_core}{left_suffix}");
                 let right_replacement = format!("{right_prefix}{left_core}{right_suffix}");
-                buffer.replace_word(index, &left_replacement)?;
-                buffer.replace_word(index + 1, &right_replacement)?;
+                replacements.push((index, left_replacement));
+                replacements.push((index + 1, right_replacement));
             }
 
             index += 2;
         }
 
+        if !replacements.is_empty() {
+            buffer.replace_words_bulk(replacements.into_iter())?;
+        }
+
         Ok(())
     }
 }

{glitchlings-0.4.0 → glitchlings-0.4.2}/rust/zoo/src/lib.rs

@@ -122,6 +122,47 @@ fn cached_layout_vec(layout_dict: &PyDict) -> PyResult<Arc<Vec<(String, Vec<Stri
     Ok(entry.clone())
 }
 
+#[derive(Debug)]
+struct PyGagglePlanInput {
+    name: String,
+    scope: i32,
+    order: i32,
+}
+
+impl<'py> FromPyObject<'py> for PyGagglePlanInput {
+    fn extract(obj: &'py PyAny) -> PyResult<Self> {
+        if let Ok(dict) = obj.downcast::<PyDict>() {
+            let name: String = dict
+                .get_item("name")?
+                .ok_or_else(|| PyValueError::new_err("plan input missing 'name' field"))?
+                .extract()?;
+            let scope: i32 = dict
+                .get_item("scope")?
+                .ok_or_else(|| PyValueError::new_err("plan input missing 'scope' field"))?
+                .extract()?;
+            let order: i32 = dict
+                .get_item("order")?
+                .ok_or_else(|| PyValueError::new_err("plan input missing 'order' field"))?
+                .extract()?;
+            return Ok(Self { name, scope, order });
+        }
+
+        let name = obj
+            .getattr("name")
+            .map_err(|_| PyValueError::new_err("plan input missing attribute 'name'"))?
+            .extract()?;
+        let scope = obj
+            .getattr("scope")
+            .map_err(|_| PyValueError::new_err("plan input missing attribute 'scope'"))?
+            .extract()?;
+        let order = obj
+            .getattr("order")
+            .map_err(|_| PyValueError::new_err("plan input missing attribute 'order'"))?
+            .extract()?;
+        Ok(Self { name, scope, order })
+    }
+}
+
 #[derive(Debug)]
 enum PyGlitchOperation {
     Reduplicate {
@@ -346,6 +387,30 @@ fn redact_words(
     apply_operation(text, op, rng).map_err(glitch_ops::GlitchOpError::into_pyerr)
 }
 
+#[pyfunction]
+fn plan_glitchlings(
+    glitchlings: Vec<PyGagglePlanInput>,
+    master_seed: i128,
+) -> PyResult<Vec<(usize, u64)>> {
+    let plan = pipeline::plan_gaggle(
+        glitchlings
+            .into_iter()
+            .enumerate()
+            .map(|(index, input)| pipeline::GagglePlanInput {
+                index,
+                name: input.name,
+                scope: input.scope,
+                order: input.order,
+            })
+            .collect(),
+        master_seed,
+    );
+    Ok(plan
+        .into_iter()
+        .map(|entry| (entry.index, entry.seed))
+        .collect())
+}
+
 #[pyfunction]
 fn compose_glitchlings(
     text: &str,
@@ -418,6 +483,7 @@ fn _zoo_rust(_py: Python, m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(swap_adjacent_words, m)?)?;
     m.add_function(wrap_pyfunction!(ocr_artifacts, m)?)?;
     m.add_function(wrap_pyfunction!(redact_words, m)?)?;
+    m.add_function(wrap_pyfunction!(plan_glitchlings, m)?)?;
     m.add_function(wrap_pyfunction!(compose_glitchlings, m)?)?;
     m.add_function(wrap_pyfunction!(typogre::fatfinger, m)?)?;
     m.add_function(wrap_pyfunction!(zeedub::inject_zero_widths, m)?)?;

{glitchlings-0.4.0 → glitchlings-0.4.2}/rust/zoo/src/pipeline.rs

@@ -68,6 +68,57 @@ impl Pipeline {
     }
 }
 
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct GagglePlanEntry {
+    pub index: usize,
+    pub seed: u64,
+}
+
+#[derive(Debug, Clone)]
+pub struct GagglePlanInput {
+    pub index: usize,
+    pub name: String,
+    pub scope: i32,
+    pub order: i32,
+}
+
+struct PlannedGlitchling {
+    index: usize,
+    name: String,
+    scope: i32,
+    order: i32,
+    seed: u64,
+}
+
+pub fn plan_gaggle(inputs: Vec<GagglePlanInput>, master_seed: i128) -> Vec<GagglePlanEntry> {
+    let mut planned: Vec<PlannedGlitchling> = inputs
+        .into_iter()
+        .map(|input| PlannedGlitchling {
+            seed: derive_seed(master_seed, &input.name, input.index as i128),
+            index: input.index,
+            name: input.name,
+            scope: input.scope,
+            order: input.order,
+        })
+        .collect();
+
+    planned.sort_by(|left, right| {
+        left.scope
+            .cmp(&right.scope)
+            .then(left.order.cmp(&right.order))
+            .then(left.name.cmp(&right.name))
+            .then(left.index.cmp(&right.index))
+    });
+
+    planned
+        .into_iter()
+        .map(|item| GagglePlanEntry {
+            index: item.index,
+            seed: item.seed,
+        })
+        .collect()
+}
+
 pub fn derive_seed(master_seed: i128, glitchling_name: &str, index: i128) -> u64 {
     let mut hasher = Blake2s::<U8>::new();
     Digest::update(&mut hasher, int_to_bytes(master_seed));
@@ -109,7 +160,9 @@ fn int_to_bytes(value: i128) -> Vec<u8> {
 
 #[cfg(test)]
 mod tests {
-    use super::{derive_seed, GlitchDescriptor, Pipeline};
+    use super::{
+        derive_seed, plan_gaggle, GagglePlanEntry, GagglePlanInput, GlitchDescriptor, Pipeline,
+    };
     use crate::glitch_ops::{
         DeleteRandomWordsOp, GlitchOperation, OcrArtifactsOp, RedactWordsOp, ReduplicateWordsOp,
         SwapAdjacentWordsOp,
@@ -222,4 +275,55 @@ mod tests {
             .expect("pipeline succeeds");
         assert_eq!(output, "this Echo please line");
     }
+
+    #[test]
+    fn plan_gaggle_orders_by_scope_order_and_name() {
+        let master_seed = 5151i128;
+        let inputs = vec![
+            GagglePlanInput {
+                index: 0,
+                name: "Typogre".to_string(),
+                scope: 5,
+                order: 3,
+            },
+            GagglePlanInput {
+                index: 1,
+                name: "Reduple".to_string(),
+                scope: 4,
+                order: 3,
+            },
+            GagglePlanInput {
+                index: 2,
+                name: "Rushmore".to_string(),
+                scope: 4,
+                order: 2,
+            },
+            GagglePlanInput {
+                index: 3,
+                name: "Mim1c".to_string(),
+                scope: 5,
+                order: 2,
+            },
+        ];
+        let plan = plan_gaggle(inputs, master_seed);
+        let expected = vec![
+            GagglePlanEntry {
+                index: 2,
+                seed: derive_seed(master_seed, "Rushmore", 2),
+            },
+            GagglePlanEntry {
+                index: 1,
+                seed: derive_seed(master_seed, "Reduple", 1),
+            },
+            GagglePlanEntry {
+                index: 3,
+                seed: derive_seed(master_seed, "Mim1c", 3),
+            },
+            GagglePlanEntry {
+                index: 0,
+                seed: derive_seed(master_seed, "Typogre", 0),
+            },
+        ];
+        assert_eq!(plan, expected);
+    }
 }

{glitchlings-0.4.0 → glitchlings-0.4.2}/rust/zoo/src/rng.rs

@@ -323,6 +323,25 @@ mod tests {
         }
     }
 
+    #[test]
+    fn random_matches_python_for_additional_seed() {
+        let mut rng = PyRng::new(3815924951222172525);
+        let expected = [
+            0.18518006574496737,
+            0.5841689581060610,
+            0.3699113163178772,
+            0.7394349068470196,
+            0.6855497906317899,
+        ];
+        for value in expected {
+            let actual = rng.random();
+            assert!(
+                (actual - value).abs() < 1e-15,
+                "expected {value}, got {actual}"
+            );
+        }
+    }
+
     #[test]
     fn randrange_supports_default_arguments() {
         let mut rng = PyRng::new(151);

{glitchlings-0.4.0 → glitchlings-0.4.2}/rust/zoo/src/text_buffer.rs

@@ -171,6 +171,32 @@ impl TextBuffer {
         Ok(())
     }
 
+    /// Replace multiple words in a single pass, avoiding repeated reindexing.
+    pub fn replace_words_bulk<I>(&mut self, replacements: I) -> Result<(), TextBufferError>
+    where
+        I: IntoIterator<Item = (usize, String)>,
+    {
+        let mut applied_any = false;
+        for (word_index, replacement) in replacements {
+            let segment_index = self
+                .word_segment_indices
+                .get(word_index)
+                .copied()
+                .ok_or(TextBufferError::InvalidWordIndex { index: word_index })?;
+            let segment = self
+                .segments
+                .get_mut(segment_index)
+                .ok_or(TextBufferError::InvalidWordIndex { index: word_index })?;
+            segment.set_text(replacement, SegmentKind::Word);
+            applied_any = true;
+        }
+
+        if applied_any {
+            self.reindex();
+        }
+        Ok(())
+    }
+
     /// Deletes the word at the requested index.
     pub fn delete_word(&mut self, word_index: usize) -> Result<(), TextBufferError> {
         let segment_index = self
@@ -402,6 +428,19 @@ mod tests {
         assert_eq!(buffer.spans().len(), 5);
     }
 
+    #[test]
+    fn bulk_replace_words_updates_multiple_entries() {
+        let mut buffer = TextBuffer::from_str("alpha beta gamma delta");
+        buffer
+            .replace_words_bulk(vec![(0, "delta".to_string()), (3, "alpha".to_string())])
+            .expect("bulk replace succeeds");
+        assert_eq!(buffer.to_string(), "delta beta gamma alpha");
+        let spans = buffer.spans();
+        assert_eq!(spans[0].char_range, 0..5);
+        assert_eq!(spans.len(), 7);
+        assert_eq!(spans.last().unwrap().char_range, 17..22);
+    }
+
     #[test]
     fn replace_char_range_handles_multisegment_updates() {
         let mut buffer = TextBuffer::from_str("Hello world");

{glitchlings-0.4.0 → glitchlings-0.4.2}/src/glitchlings/__init__.py

@@ -1,29 +1,33 @@
+from .config import AttackConfig, build_gaggle, load_attack_config
+from .util import SAMPLE_TEXT
 from .zoo import (
-    Typogre,
-    typogre,
-    Mim1c,
-    mim1c,
-    Jargoyle,
-    jargoyle,
     Adjax,
-    adjax,
+    Gaggle,
+    Glitchling,
+    Jargoyle,
+    Mim1c,
     Redactyl,
-    redactyl,
     Reduple,
-    reduple,
     Rushmore,
-    rushmore,
     Scannequin,
-    scannequin,
+    Typogre,
     Zeedub,
-    zeedub,
-    Glitchling,
-    Gaggle,
+    adjax,
+    is_rust_pipeline_enabled,
+    is_rust_pipeline_supported,
+    jargoyle,
+    mim1c,
+    pipeline_feature_flag_enabled,
+    plan_glitchling_specs,
+    plan_glitchlings,
+    redactyl,
+    reduple,
+    rushmore,
+    scannequin,
     summon,
+    typogre,
+    zeedub,
 )
-from .config import AttackConfig, build_gaggle, load_attack_config
-from .util import SAMPLE_TEXT
-
 
 __all__ = [
     "Typogre",
@@ -47,6 +51,11 @@ __all__ = [
     "summon",
     "Glitchling",
     "Gaggle",
+    "plan_glitchlings",
+    "plan_glitchling_specs",
+    "is_rust_pipeline_enabled",
+    "is_rust_pipeline_supported",
+    "pipeline_feature_flag_enabled",
     "SAMPLE_TEXT",
     "AttackConfig",
     "build_gaggle",

{glitchlings-0.4.0 → glitchlings-0.4.2}/src/glitchlings/__main__.py

@@ -4,6 +4,5 @@ import sys
 
 from .main import main
 
-
 if __name__ == "__main__":
     sys.exit(main())