glitchlings 0.10.2__cp312-cp312-macosx_11_0_universal2.whl

glitchlings/util/keyboards.py

@@ -0,0 +1,356 @@
+"""Keyboard layout neighbor maps for typo simulation.
+
+This module centralizes keyboard layout data that was previously stored
+directly in :mod:`glitchlings.util.__init__`. It defines adjacency maps
+for various keyboard layouts used by typo-generating glitchlings.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+__all__ = [
+    "KeyboardLayouts",
+    "KeyNeighbors",
+    "KEYNEIGHBORS",
+    "ShiftMap",
+    "ShiftMaps",
+    "SHIFT_MAPS",
+    "KeyNeighborMap",
+    "build_keyboard_neighbor_map",
+]
+
+# Type alias for keyboard neighbor maps
+KeyNeighborMap = dict[str, list[str]]
+
+
+def build_keyboard_neighbor_map(rows: Iterable[str]) -> KeyNeighborMap:
+    """Derive 8-neighbour adjacency lists from keyboard layout rows.
+
+    Each row represents a keyboard row with characters positioned by index.
+    Spaces are treated as empty positions. Characters are normalized to lowercase.
+
+    Args:
+        rows: Iterable of strings representing keyboard rows, with
+            characters positioned to reflect their physical layout.
+
+    Returns:
+        Dictionary mapping each lowercase character to its adjacent characters.
+
+    Example:
+        >>> rows = ["qwerty", " asdfg"]  # 'a' offset by 1
+        >>> neighbors = build_keyboard_neighbor_map(rows)
+        >>> neighbors['s']  # adjacent to q, w, e, a, d on QWERTY
+        ['q', 'w', 'e', 'a', 'd']
+    """
+    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
+
+
+KeyboardLayouts = dict[str, KeyNeighborMap]
+ShiftMap = dict[str, str]
+ShiftMaps = dict[str, ShiftMap]
+
+
+_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_keyboard_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:
+    """Attribute-based access to keyboard layout neighbor maps."""
+
+    def __init__(self) -> None:
+        for layout_name, layout in _KEYNEIGHBORS.items():
+            setattr(self, layout_name, layout)
+
+
+KEYNEIGHBORS: KeyNeighbors = KeyNeighbors()
+
+
+def _uppercase_keys(layout: str) -> ShiftMap:
+    mapping: ShiftMap = {}
+    for key in _KEYNEIGHBORS.get(layout, {}):
+        if key.isalpha():
+            mapping[key] = key.upper()
+    return mapping
+
+
+def _with_letters(base: ShiftMap, layout: str) -> ShiftMap:
+    mapping = dict(base)
+    mapping.update(_uppercase_keys(layout))
+    return mapping
+
+
+def _qwerty_symbols() -> ShiftMap:
+    return {
+        "`": "~",
+        "1": "!",
+        "2": "@",
+        "3": "#",
+        "4": "$",
+        "5": "%",
+        "6": "^",
+        "7": "&",
+        "8": "*",
+        "9": "(",
+        "0": ")",
+        "-": "_",
+        "=": "+",
+        "[": "{",
+        "]": "}",
+        "\\": "|",
+        ";": ":",
+        "'": '"',
+        ",": "<",
+        ".": ">",
+        "/": "?",
+    }
+
+
+def _azerty_symbols() -> ShiftMap:
+    return {
+        "&": "1",
+        "\u00e9": "2",
+        '"': "3",
+        "'": "4",
+        "(": "5",
+        "-": "6",
+        "\u00e8": "7",
+        "_": "8",
+        "\u00e7": "9",
+        "\u00e0": "0",
+        ")": "\u00b0",
+        "=": "+",
+        "^": "\u00a8",
+        "$": "\u00a3",
+        "*": "\u00b5",
+        "\u00f9": "%",
+        "<": ">",
+        ",": "?",
+        ";": ".",
+        ":": "/",
+        "!": "\u00a7",
+    }
+
+
+def _qwertz_symbols() -> ShiftMap:
+    return {
+        "^": "\u00b0",
+        "1": "!",
+        "2": '"',
+        "3": "\u00a7",
+        "4": "$",
+        "5": "%",
+        "6": "&",
+        "7": "/",
+        "8": "(",
+        "9": ")",
+        "0": "=",
+        "\u00df": "?",
+        "\u00b4": "`",
+        "+": "*",
+        "#": "'",
+        "-": "_",
+        ",": ";",
+        ".": ":",
+        "\u00e4": "\u00c4",
+        "\u00f6": "\u00d6",
+        "\u00fc": "\u00dc",
+    }
+
+
+def _spanish_symbols() -> ShiftMap:
+    return {
+        "\u00ba": "\u00aa",
+        "1": "!",
+        "2": '"',
+        "3": "\u00b7",
+        "4": "$",
+        "5": "%",
+        "6": "&",
+        "7": "/",
+        "8": "(",
+        "9": ")",
+        "0": "=",
+        "'": "?",
+        "\u00a1": "\u00bf",
+        "+": "*",
+        "\u00b4": "\u00a8",
+        "-": "_",
+        ",": ";",
+        ".": ":",
+        "<": ">",
+        "\u00f1": "\u00d1",
+    }
+
+
+def _swedish_symbols() -> ShiftMap:
+    return {
+        "\u00a7": "\u00bd",
+        "1": "!",
+        "2": '"',
+        "3": "#",
+        "4": "\u00a4",
+        "5": "%",
+        "6": "&",
+        "7": "/",
+        "8": "(",
+        "9": ")",
+        "0": "=",
+        "+": "?",
+        "\u00b4": "\u00a8",
+        "-": "_",
+        ",": ";",
+        ".": ":",
+        "<": ">",
+        "\u00e5": "\u00c5",
+        "\u00e4": "\u00c4",
+        "\u00f6": "\u00d6",
+    }
+
+
+_SHIFT_MAPS: ShiftMaps = {
+    "CURATOR_QWERTY": _with_letters(_qwerty_symbols(), "CURATOR_QWERTY"),
+    "QWERTY": _with_letters(_qwerty_symbols(), "QWERTY"),
+    "COLEMAK": _with_letters(_qwerty_symbols(), "COLEMAK"),
+    "DVORAK": _with_letters(_qwerty_symbols(), "DVORAK"),
+    "AZERTY": _with_letters(_azerty_symbols(), "AZERTY"),
+    "QWERTZ": _with_letters(_qwertz_symbols(), "QWERTZ"),
+    "SPANISH_QWERTY": _with_letters(_spanish_symbols(), "SPANISH_QWERTY"),
+    "SWEDISH_QWERTY": _with_letters(_swedish_symbols(), "SWEDISH_QWERTY"),
+}
+
+
+class ShiftMapsAccessor:
+    """Attribute-based access to per-layout shift maps."""
+
+    def __init__(self) -> None:
+        for layout_name, mapping in _SHIFT_MAPS.items():
+            setattr(self, layout_name, mapping)
+
+
+SHIFT_MAPS: ShiftMapsAccessor = ShiftMapsAccessor()

glitchlings/util/transcripts.py

@@ -0,0 +1,108 @@
+"""Shared transcript type helpers used across attack and DLC modules."""
+
+from __future__ import annotations
+
+from typing import Any, Literal, Sequence, TypeGuard, Union
+
+TranscriptTurn = dict[str, Any]
+Transcript = list[TranscriptTurn]
+
+# Type alias for transcript target specifications.
+# - "last": corrupt only the last turn (default behavior)
+# - "all": corrupt all turns
+# - "assistant": corrupt only turns with role="assistant"
+# - "user": corrupt only turns with role="user"
+# - int: corrupt a specific index (negative indexing supported)
+# - Sequence[int]: corrupt specific indices
+TranscriptTarget = Union[Literal["last", "all", "assistant", "user"], int, Sequence[int]]
+
+
+def is_transcript(
+    value: Any,
+    *,
+    allow_empty: bool = True,
+    require_all_content: bool = False,
+) -> TypeGuard[Transcript]:
+    """Return True when ``value`` appears to be a chat transcript mapping list."""
+    if not isinstance(value, list):
+        return False
+
+    if not value:
+        return allow_empty
+
+    if not all(isinstance(turn, dict) for turn in value):
+        return False
+
+    if require_all_content:
+        return all("content" in turn for turn in value)
+
+    return "content" in value[-1]
+
+
+def resolve_transcript_indices(
+    transcript: Transcript,
+    target: TranscriptTarget,
+) -> list[int]:
+    """Resolve a transcript target specification to concrete indices.
+
+    Args:
+        transcript: The transcript to resolve indices for.
+        target: The target specification indicating which turns to corrupt.
+
+    Returns:
+        A list of valid indices into the transcript, sorted in ascending order.
+
+    Raises:
+        ValueError: If the target specification is invalid or references
+            indices outside the transcript bounds.
+    """
+    if not transcript:
+        return []
+
+    length = len(transcript)
+
+    if target == "last":
+        return [length - 1]
+
+    if target == "all":
+        return list(range(length))
+
+    if target == "assistant":
+        return [i for i, turn in enumerate(transcript) if turn.get("role") == "assistant"]
+
+    if target == "user":
+        return [i for i, turn in enumerate(transcript) if turn.get("role") == "user"]
+
+    if isinstance(target, int):
+        # Normalize negative indices
+        normalized = target if target >= 0 else length + target
+        if not 0 <= normalized < length:
+            raise ValueError(f"Transcript index {target} out of bounds for length {length}")
+        return [normalized]
+
+    # Handle sequence of indices
+    if isinstance(target, Sequence) and not isinstance(target, str):
+        indices: list[int] = []
+        for idx in target:
+            if not isinstance(idx, int):
+                raise ValueError(f"Transcript indices must be integers, got {type(idx).__name__}")
+            normalized = idx if idx >= 0 else length + idx
+            if not 0 <= normalized < length:
+                raise ValueError(f"Transcript index {idx} out of bounds for length {length}")
+            indices.append(normalized)
+        # Deduplicate and sort
+        return sorted(set(indices))
+
+    raise ValueError(
+        f"Invalid transcript target: {target!r}. "
+        "Expected 'last', 'all', 'assistant', 'user', int, or sequence of ints."
+    )
+
+
+__all__ = [
+    "Transcript",
+    "TranscriptTarget",
+    "TranscriptTurn",
+    "is_transcript",
+    "resolve_transcript_indices",
+]

glitchlings/zoo/__init__.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+import ast
+from typing import Any
+
+from .core import Gaggle, Glitchling, plan_glitchlings
+from .hokey import Hokey, hokey
+from .jargoyle import Jargoyle, jargoyle
+from .mim1c import Mim1c, mim1c
+from .pedant import Pedant, pedant
+from .redactyl import Redactyl, redactyl
+from .rushmore import Rushmore, RushmoreMode, rushmore
+from .scannequin import Scannequin, scannequin
+from .typogre import Typogre, typogre
+from .wherewolf import Wherewolf, wherewolf
+from .zeedub import Zeedub, zeedub
+
+__all__ = [
+    "Typogre",
+    "typogre",
+    "Mim1c",
+    "mim1c",
+    "Jargoyle",
+    "jargoyle",
+    "Wherewolf",
+    "wherewolf",
+    "Hokey",
+    "hokey",
+    "Rushmore",
+    "RushmoreMode",
+    "rushmore",
+    "Redactyl",
+    "redactyl",
+    "Scannequin",
+    "scannequin",
+    "Zeedub",
+    "zeedub",
+    "Pedant",
+    "pedant",
+    "Glitchling",
+    "Gaggle",
+    "plan_glitchlings",
+    "summon",
+    "BUILTIN_GLITCHLINGS",
+    "DEFAULT_GLITCHLING_NAMES",
+    "parse_glitchling_spec",
+    "get_glitchling_class",
+]
+
+_BUILTIN_GLITCHLING_LIST: list[Glitchling] = [
+    typogre,
+    hokey,
+    mim1c,
+    wherewolf,
+    pedant,
+    jargoyle,
+    rushmore,
+    redactyl,
+    scannequin,
+    zeedub,
+]
+
+BUILTIN_GLITCHLINGS: dict[str, Glitchling] = {
+    glitchling.name.lower(): glitchling for glitchling in _BUILTIN_GLITCHLING_LIST
+}
+
+_BUILTIN_GLITCHLING_TYPES: dict[str, type[Glitchling]] = {
+    typogre.name.lower(): Typogre,
+    wherewolf.name.lower(): Wherewolf,
+    hokey.name.lower(): Hokey,
+    mim1c.name.lower(): Mim1c,
+    pedant.name.lower(): Pedant,
+    jargoyle.name.lower(): Jargoyle,
+    rushmore.name.lower(): Rushmore,
+    redactyl.name.lower(): Redactyl,
+    scannequin.name.lower(): Scannequin,
+    zeedub.name.lower(): Zeedub,
+}
+
+DEFAULT_GLITCHLING_NAMES: list[str] = ["typogre", "scannequin"]
+
+
+def parse_glitchling_spec(specification: str) -> Glitchling:
+    """Return a glitchling instance configured according to ``specification``."""
+    text = specification.strip()
+    if not text:
+        raise ValueError("Glitchling specification cannot be empty.")
+
+    if "(" not in text:
+        glitchling = BUILTIN_GLITCHLINGS.get(text.lower())
+        if glitchling is None:
+            raise ValueError(f"Glitchling '{text}' not found.")
+        return glitchling
+
+    if not text.endswith(")"):
+        raise ValueError(f"Invalid parameter syntax for glitchling '{text}'.")
+
+    name_part, arg_source = text[:-1].split("(", 1)
+    name = name_part.strip()
+    if not name:
+        raise ValueError(f"Invalid glitchling specification '{text}'.")
+
+    lower_name = name.lower()
+    glitchling_type = _BUILTIN_GLITCHLING_TYPES.get(lower_name)
+    if glitchling_type is None:
+        raise ValueError(f"Glitchling '{name}' not found.")
+
+    try:
+        call_expr = ast.parse(f"_({arg_source})", mode="eval").body
+    except SyntaxError as exc:
+        raise ValueError(f"Invalid parameter syntax for glitchling '{name}': {exc.msg}") from exc
+
+    if not isinstance(call_expr, ast.Call) or call_expr.args:
+        raise ValueError(f"Glitchling '{name}' parameters must be provided as keyword arguments.")
+
+    kwargs: dict[str, Any] = {}
+    for keyword in call_expr.keywords:
+        if keyword.arg is None:
+            raise ValueError(
+                f"Glitchling '{name}' does not support unpacking arbitrary keyword arguments."
+            )
+        try:
+            kwargs[keyword.arg] = ast.literal_eval(keyword.value)
+        except (ValueError, SyntaxError) as exc:
+            raise ValueError(
+                f"Failed to parse value for parameter '{keyword.arg}' on glitchling '{name}': {exc}"
+            ) from exc
+
+    try:
+        return glitchling_type(**kwargs)
+    except TypeError as exc:
+        raise ValueError(f"Failed to instantiate glitchling '{name}': {exc}") from exc
+
+
+def get_glitchling_class(name: str) -> type[Glitchling]:
+    """Look up the glitchling class registered under ``name``."""
+    key = name.strip().lower()
+    if not key:
+        raise ValueError("Glitchling name cannot be empty.")
+
+    glitchling_type = _BUILTIN_GLITCHLING_TYPES.get(key)
+    if glitchling_type is None:
+        raise ValueError(f"Glitchling '{name}' not found.")
+
+    return glitchling_type
+
+
+def summon(glitchlings: list[str | Glitchling], seed: int = 151) -> Gaggle:
+    """Summon glitchlings by name (using defaults) or instance (to change parameters)."""
+    summoned: list[Glitchling] = []
+    for entry in glitchlings:
+        if isinstance(entry, Glitchling):
+            summoned.append(entry)
+            continue
+
+        try:
+            summoned.append(parse_glitchling_spec(entry))
+        except ValueError as exc:
+            raise ValueError(str(exc)) from exc
+
+    return Gaggle(summoned, seed=seed)

glitchlings/zoo/assets/__init__.py

@@ -0,0 +1,29 @@
+"""Compatibility shim for the relocated asset helpers."""
+
+from __future__ import annotations
+
+from glitchlings.assets import (
+    PIPELINE_ASSET_SPECS,
+    PIPELINE_ASSETS,
+    AssetKind,
+    PipelineAsset,
+    hash_asset,
+    load_homophone_groups,
+    load_json,
+    open_binary,
+    open_text,
+    read_text,
+)
+
+__all__ = [
+    "AssetKind",
+    "PipelineAsset",
+    "PIPELINE_ASSETS",
+    "PIPELINE_ASSET_SPECS",
+    "hash_asset",
+    "load_homophone_groups",
+    "load_json",
+    "open_binary",
+    "open_text",
+    "read_text",
+]