glitchlings 0.2.5__cp312-cp312-win_amd64.whl → 0.9.3__cp312-cp312-win_amd64.whl

glitchlings/main.py

@@ -4,15 +4,22 @@ from __future__ import annotations
 
 import argparse
 import difflib
-from pathlib import Path
+import json
 import sys
+from collections.abc import Sequence
+from pathlib import Path
+from typing import cast
+
+import yaml
 
 from . import SAMPLE_TEXT
+from .attack import Attack
+from .conf import DEFAULT_ATTACK_SEED, build_gaggle, load_attack_config
 from .zoo import (
-    Glitchling,
-    Gaggle,
     BUILTIN_GLITCHLINGS,
     DEFAULT_GLITCHLING_NAMES,
+    Gaggle,
+    Glitchling,
     parse_glitchling_spec,
     summon,
 )
@@ -20,24 +27,30 @@ from .zoo import (
 MAX_NAME_WIDTH = max(len(glitchling.name) for glitchling in BUILTIN_GLITCHLINGS.values())
 
 
-def build_parser() -> argparse.ArgumentParser:
+def build_parser(
+    *,
+    exit_on_error: bool = True,
+    include_text: bool = True,
+) -> argparse.ArgumentParser:
     """Create and configure the CLI argument parser.
 
     Returns:
         argparse.ArgumentParser: The configured argument parser instance.
-    """
 
+    """
     parser = argparse.ArgumentParser(
         description=(
             "Summon glitchlings to corrupt text. Provide input text as an argument, "
             "via --file, or pipe it on stdin."
-        )
-    )
-    parser.add_argument(
-        "text",
-        nargs="?",
-        help="Text to corrupt. If omitted, stdin is used or --sample provides fallback text.",
+        ),
+        exit_on_error=exit_on_error,
     )
+    if include_text:
+        parser.add_argument(
+            "text",
+            nargs="*",
+            help="Text to corrupt. If omitted, stdin is used or --sample provides fallback text.",
+        )
     parser.add_argument(
         "-g",
         "--glitchling",
@@ -53,7 +66,7 @@ def build_parser() -> argparse.ArgumentParser:
         "-s",
         "--seed",
         type=int,
-        default=151,
+        default=None,
         help="Seed controlling deterministic corruption order (default: 151).",
     )
     parser.add_argument(
@@ -77,12 +90,30 @@ def build_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="List available glitchlings and exit.",
     )
+    parser.add_argument(
+        "-c",
+        "--config",
+        type=Path,
+        help="Load glitchlings from a YAML configuration file.",
+    )
+    parser.add_argument(
+        "--report",
+        "--attack",
+        dest="report_format",
+        nargs="?",
+        const="json",
+        choices=["json", "yaml", "yml"],
+        help=(
+            "Output a structured Attack report (default: json). Use --attack as an alias. "
+            "Includes tokens, token IDs, metrics, and counts."
+        ),
+    )
+
     return parser
 
 
 def list_glitchlings() -> None:
     """Print information about the available built-in glitchlings."""
-
     for key in DEFAULT_GLITCHLING_NAMES:
         glitchling = BUILTIN_GLITCHLINGS[key]
         display_name = glitchling.name
@@ -103,58 +134,83 @@ def read_text(args: argparse.Namespace, parser: argparse.ArgumentParser) -> str:
 
     Raises:
         SystemExit: Raised indirectly via ``parser.error`` on failure.
-    """
 
-    if args.file is not None:
+    """
+    file_path = cast(Path | None, getattr(args, "file", None))
+    if file_path is not None:
         try:
-            return args.file.read_text(encoding="utf-8")
+            return file_path.read_text(encoding="utf-8")
         except OSError as exc:
-            filename = getattr(exc, "filename", None) or args.file
+            filename = getattr(exc, "filename", None) or file_path
             reason = exc.strerror or str(exc)
             parser.error(f"Failed to read file {filename}: {reason}")
 
-    if args.text:
-        return args.text
+    text_argument = cast(str | list[str] | None, getattr(args, "text", None))
+    if isinstance(text_argument, list):
+        if text_argument:
+            return " ".join(text_argument)
+        text_argument = None
+    if isinstance(text_argument, str) and text_argument:
+        return text_argument
 
     if not sys.stdin.isatty():
         return sys.stdin.read()
 
-    if args.sample:
+    if bool(getattr(args, "sample", False)):
         return SAMPLE_TEXT
 
     parser.error(
-        "No input text provided. Supply text as an argument, use --file, pipe input, or pass --sample."
+        "No input text provided. Supply text as an argument, use --file, pipe input, or "
+        "pass --sample."
     )
     raise AssertionError("parser.error should exit")
 
 
 def summon_glitchlings(
-    names: list[str] | None, parser: argparse.ArgumentParser, seed: int
+    names: list[str] | None,
+    parser: argparse.ArgumentParser,
+    seed: int | None,
+    *,
+    config_path: Path | None = None,
 ) -> Gaggle:
     """Instantiate the requested glitchlings and bundle them in a ``Gaggle``."""
+    if config_path is not None:
+        if names:
+            parser.error("Cannot combine --config with --glitchling.")
+            raise AssertionError("parser.error should exit")
 
+        try:
+            config = load_attack_config(config_path)
+        except (TypeError, ValueError) as exc:
+            parser.error(str(exc))
+            raise AssertionError("parser.error should exit")
+
+        return build_gaggle(config, seed_override=seed)
+
+    normalized: Sequence[str | Glitchling]
     if names:
-        normalized: list[str | Glitchling] = []
+        parsed: list[str | Glitchling] = []
         for specification in names:
             try:
-                normalized.append(parse_glitchling_spec(specification))
+                parsed.append(parse_glitchling_spec(specification))
             except ValueError as exc:
                 parser.error(str(exc))
                 raise AssertionError("parser.error should exit")
+        normalized = parsed
     else:
-        normalized = DEFAULT_GLITCHLING_NAMES
+        normalized = list(DEFAULT_GLITCHLING_NAMES)
+
+    effective_seed = seed if seed is not None else DEFAULT_ATTACK_SEED
 
     try:
-        return summon(normalized, seed=seed)
+        return summon(list(normalized), seed=effective_seed)
     except ValueError as exc:
         parser.error(str(exc))
         raise AssertionError("parser.error should exit")
 
 
-
 def show_diff(original: str, corrupted: str) -> None:
     """Display a unified diff between the original and corrupted text."""
-
     diff_lines = list(
         difflib.unified_diff(
             original.splitlines(keepends=True),
@@ -180,16 +236,46 @@ def run_cli(args: argparse.Namespace, parser: argparse.ArgumentParser) -> int:
 
     Returns:
         int: Exit code for the process (``0`` on success).
-    """
 
+    """
     if args.list:
         list_glitchlings()
         return 0
 
+    report_format = cast(str | None, getattr(args, "report_format", None))
+    if report_format and args.diff:
+        parser.error("--diff cannot be combined with --report/--attack output.")
+        raise AssertionError("parser.error should exit")
+
+    normalized_report_format = None
+    if report_format:
+        normalized_report_format = "yaml" if report_format == "yml" else report_format
+
     text = read_text(args, parser)
-    gaggle = summon_glitchlings(args.glitchlings, parser, args.seed)
+    gaggle = summon_glitchlings(
+        args.glitchlings,
+        parser,
+        args.seed,
+        config_path=args.config,
+    )
+
+    if normalized_report_format:
+        attack_seed = args.seed if args.seed is not None else getattr(gaggle, "seed", None)
+        attack = Attack(gaggle, seed=attack_seed)
+        result = attack.run(text)
+        payload = result.to_report()
+        payload["summary"] = result.summary()
+
+        if normalized_report_format == "json":
+            print(json.dumps(payload, indent=2))
+        else:
+            print(yaml.safe_dump(payload, sort_keys=False))
+        return 0
 
-    corrupted = gaggle(text)
+    corrupted = gaggle.corrupt(text)
+    if not isinstance(corrupted, str):
+        message = "Gaggle returned non-string output for string input"
+        raise TypeError(message)
 
     if args.diff:
         show_diff(text, corrupted)
@@ -207,10 +293,15 @@ def main(argv: list[str] | None = None) -> int:
 
     Returns:
         int: Exit code suitable for use with ``sys.exit``.
+
     """
+    if argv is None:
+        raw_args = sys.argv[1:]
+    else:
+        raw_args = list(argv)
 
     parser = build_parser()
-    args = parser.parse_args(argv)
+    args = parser.parse_args(raw_args)
     return run_cli(args, parser)
 
 

glitchlings/runtime_config.py

@@ -0,0 +1,24 @@
+"""Compatibility wrapper for runtime configuration helpers.
+
+Prefer ``glitchlings.conf`` for imports.
+"""
+
+from __future__ import annotations
+
+from .conf import (
+    CONFIG_ENV_VAR,
+    DEFAULT_CONFIG_PATH,
+    RuntimeConfig,
+    get_config,
+    reload_config,
+    reset_config,
+)
+
+__all__ = [
+    "CONFIG_ENV_VAR",
+    "DEFAULT_CONFIG_PATH",
+    "RuntimeConfig",
+    "get_config",
+    "reload_config",
+    "reset_config",
+]

glitchlings/util/__init__.py

@@ -1,181 +1,34 @@
-import difflib
-from collections.abc import Iterable
-
-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,./",
-    ),
+from glitchlings.zoo.transforms import KeyNeighborMap
+from glitchlings.zoo.transforms import (
+    compute_string_diffs as string_diffs,
 )
 
-_register_layout(
-    "AZERTY",
-    (
-        "²&é\"'(-è_çà)=",
-        " azertyuiop^$",
-        "  qsdfghjklmù*",
-        "   <wxcvbn,;:!",
-    ),
+from .keyboards import (
+    KEYNEIGHBORS,
+    SHIFT_MAPS,
+    KeyboardLayouts,
+    KeyNeighbors,
+    ShiftMap,
+    ShiftMaps,
 )
 
-_register_layout(
-    "QWERTZ",
-    (
-        "^1234567890ß´",
-        " qwertzuiopü+",
-        "  asdfghjklöä#",
-        "   yxcvbnm,.-",
-    ),
+__all__ = [
+    "SAMPLE_TEXT",
+    "string_diffs",
+    "KeyNeighborMap",
+    "KeyboardLayouts",
+    "ShiftMap",
+    "ShiftMaps",
+    "KeyNeighbors",
+    "KEYNEIGHBORS",
+    "SHIFT_MAPS",
+]
+
+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."
 )
-
-_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,65 @@
+"""Adapter helpers shared across Python and DLC integrations."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+from ..zoo import Gaggle, Glitchling, summon
+from .transcripts import TranscriptTarget
+
+
+def coerce_gaggle(
+    glitchlings: Glitchling | Gaggle | str | Iterable[str | Glitchling],
+    *,
+    seed: int,
+    apply_seed_to_existing: bool = False,
+    transcript_target: TranscriptTarget | None = None,
+) -> Gaggle:
+    """Return a :class:`Gaggle` built from any supported glitchling specifier.
+
+    Args:
+        glitchlings: A single Glitchling, Gaggle, string specification, or iterable
+            of glitchlings/specs.
+        seed: Seed to use when constructing a new Gaggle from the input.
+        apply_seed_to_existing: When True, also apply the seed to an existing
+            Gaggle instance. When False (default), existing Gaggles keep their
+            current seed.
+        transcript_target: Which transcript turns to corrupt. When None (default),
+            uses the Gaggle default ("last"). Accepts:
+            - "last": corrupt only the last turn (default)
+            - "all": corrupt all turns
+            - "assistant": corrupt only assistant turns
+            - "user": corrupt only user turns
+            - int: corrupt a specific index (negative indexing supported)
+            - Sequence[int]: corrupt specific indices
+    """
+    if isinstance(glitchlings, Gaggle):
+        if apply_seed_to_existing:
+            glitchlings.seed = seed
+            glitchlings.sort_glitchlings()
+        if transcript_target is not None:
+            glitchlings.transcript_target = transcript_target
+        return glitchlings
+
+    if isinstance(glitchlings, (Glitchling, str)):
+        resolved: Iterable[Any] = [glitchlings]
+    else:
+        resolved = glitchlings
+
+    # Validate entries before passing to summon to give better error messages
+    resolved_list = list(resolved)
+    for index, entry in enumerate(resolved_list):
+        if not isinstance(entry, (str, Glitchling)):
+            raise TypeError(
+                f"glitchlings sequence entries must be Glitchling instances "
+                f"or string specifications (index {index})"
+            )
+
+    gaggle = summon(resolved_list, seed=seed)
+    if transcript_target is not None:
+        gaggle.transcript_target = transcript_target
+    return gaggle
+
+
+__all__ = ["coerce_gaggle"]