glitchlings 0.3.0__cp312-cp312-manylinux_2_28_x86_64.whl → 0.4.0__cp312-cp312-manylinux_2_28_x86_64.whl

glitchlings/__init__.py

@@ -21,6 +21,7 @@ from .zoo import (
     Gaggle,
     summon,
 )
+from .config import AttackConfig, build_gaggle, load_attack_config
 from .util import SAMPLE_TEXT
 
 
@@ -47,4 +48,7 @@ __all__ = [
     "Glitchling",
     "Gaggle",
     "SAMPLE_TEXT",
+    "AttackConfig",
+    "build_gaggle",
+    "load_attack_config",
 ]

glitchlings/config.py

@@ -0,0 +1,258 @@
+"""Configuration utilities for runtime behaviour and declarative attack setups."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from io import TextIOBase
+from pathlib import Path
+from typing import Any, Mapping, Sequence, TYPE_CHECKING
+
+try:  # Python 3.11+
+    import tomllib
+except ModuleNotFoundError:  # pragma: no cover - Python < 3.11
+    import tomli as tomllib  # type: ignore[no-redef]
+
+import yaml
+
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from .zoo import Glitchling
+
+
+CONFIG_ENV_VAR = "GLITCHLINGS_CONFIG"
+DEFAULT_CONFIG_PATH = Path(__file__).with_name("config.toml")
+DEFAULT_LEXICON_PRIORITY = ["vector", "graph", "wordnet"]
+DEFAULT_ATTACK_SEED = 151
+
+
+@dataclass(slots=True)
+class LexiconConfig:
+    """Lexicon-specific configuration section."""
+
+    priority: list[str] = field(default_factory=lambda: list(DEFAULT_LEXICON_PRIORITY))
+    vector_cache: Path | None = None
+    graph_cache: Path | None = None
+
+
+@dataclass(slots=True)
+class RuntimeConfig:
+    """Top-level runtime configuration loaded from ``config.toml``."""
+
+    lexicon: LexiconConfig
+    path: Path
+
+
+_CONFIG: RuntimeConfig | None = None
+
+
+def reset_config() -> None:
+    """Forget any cached runtime configuration."""
+
+    global _CONFIG
+    _CONFIG = None
+
+
+def reload_config() -> RuntimeConfig:
+    """Reload the runtime configuration from disk."""
+
+    reset_config()
+    return get_config()
+
+
+def get_config() -> RuntimeConfig:
+    """Return the cached runtime configuration, loading it if necessary."""
+
+    global _CONFIG
+    if _CONFIG is None:
+        _CONFIG = _load_runtime_config()
+    return _CONFIG
+
+
+def _load_runtime_config() -> RuntimeConfig:
+    path = _resolve_config_path()
+    data = _read_toml(path)
+    lexicon_section = data.get("lexicon", {})
+
+    priority = lexicon_section.get("priority", DEFAULT_LEXICON_PRIORITY)
+    if not isinstance(priority, Sequence) or isinstance(priority, (str, bytes)):
+        raise ValueError("lexicon.priority must be a sequence of strings.")
+    normalized_priority = [str(item) for item in priority]
+
+    vector_cache = _resolve_optional_path(
+        lexicon_section.get("vector_cache"),
+        base=path.parent,
+    )
+    graph_cache = _resolve_optional_path(
+        lexicon_section.get("graph_cache"),
+        base=path.parent,
+    )
+
+    lexicon_config = LexiconConfig(
+        priority=normalized_priority,
+        vector_cache=vector_cache,
+        graph_cache=graph_cache,
+    )
+
+    return RuntimeConfig(lexicon=lexicon_config, path=path)
+
+
+def _resolve_config_path() -> Path:
+    override = os.environ.get(CONFIG_ENV_VAR)
+    if override:
+        return Path(override)
+    return DEFAULT_CONFIG_PATH
+
+
+def _read_toml(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        if path == DEFAULT_CONFIG_PATH:
+            return {}
+        raise FileNotFoundError(f"Configuration file '{path}' not found.")
+    with path.open("rb") as handle:
+        return tomllib.load(handle)
+
+
+def _resolve_optional_path(value: Any, *, base: Path) -> Path | None:
+    if value in (None, ""):
+        return None
+
+    candidate = Path(str(value))
+    if not candidate.is_absolute():
+        candidate = (base / candidate).resolve()
+    return candidate
+
+
+@dataclass(slots=True)
+class AttackConfig:
+    """Structured representation of a glitchling roster loaded from YAML."""
+
+    glitchlings: list["Glitchling"]
+    seed: int | None = None
+
+
+def load_attack_config(
+    source: str | Path | TextIOBase,
+    *,
+    encoding: str = "utf-8",
+) -> AttackConfig:
+    """Load and parse an attack configuration from YAML."""
+
+    if isinstance(source, (str, Path)):
+        path = Path(source)
+        label = str(path)
+        try:
+            text = path.read_text(encoding=encoding)
+        except FileNotFoundError as exc:
+            raise ValueError(f"Attack configuration '{label}' was not found.") from exc
+    elif isinstance(source, TextIOBase):
+        label = getattr(source, "name", "<stream>")
+        text = source.read()
+    else:
+        raise TypeError("Attack configuration source must be a path or text stream.")
+
+    data = _load_yaml(text, label)
+    return parse_attack_config(data, source=label)
+
+
+def parse_attack_config(data: Any, *, source: str = "<config>") -> AttackConfig:
+    """Convert arbitrary YAML data into a validated ``AttackConfig``."""
+
+    if data is None:
+        raise ValueError(f"Attack configuration '{source}' is empty.")
+
+    if not isinstance(data, Mapping):
+        raise ValueError(f"Attack configuration '{source}' must be a mapping.")
+
+    raw_glitchlings = data.get("glitchlings")
+    if raw_glitchlings is None:
+        raise ValueError(f"Attack configuration '{source}' must define 'glitchlings'.")
+
+    if not isinstance(raw_glitchlings, Sequence) or isinstance(raw_glitchlings, (str, bytes)):
+        raise ValueError(f"'glitchlings' in '{source}' must be a sequence.")
+
+    glitchlings: list["Glitchling"] = []
+    for index, entry in enumerate(raw_glitchlings, start=1):
+        glitchlings.append(_build_glitchling(entry, source, index))
+
+    seed = data.get("seed")
+    if seed is not None and not isinstance(seed, int):
+        raise ValueError(f"Seed in '{source}' must be an integer if provided.")
+
+    return AttackConfig(glitchlings=glitchlings, seed=seed)
+
+
+def build_gaggle(config: AttackConfig, *, seed_override: int | None = None):
+    """Instantiate a ``Gaggle`` according to ``config``."""
+
+    from .zoo import Gaggle  # Imported lazily to avoid circular dependencies
+
+    seed = seed_override if seed_override is not None else config.seed
+    if seed is None:
+        seed = DEFAULT_ATTACK_SEED
+
+    return Gaggle(config.glitchlings, seed=seed)
+
+
+def _load_yaml(text: str, label: str) -> Any:
+    try:
+        return yaml.safe_load(text)
+    except yaml.YAMLError as exc:
+        raise ValueError(f"Failed to parse attack configuration '{label}': {exc}") from exc
+
+
+def _build_glitchling(entry: Any, source: str, index: int):
+    from .zoo import get_glitchling_class, parse_glitchling_spec
+
+    if isinstance(entry, str):
+        try:
+            return parse_glitchling_spec(entry)
+        except ValueError as exc:
+            raise ValueError(f"{source}: glitchling #{index}: {exc}") from exc
+
+    if isinstance(entry, Mapping):
+        name_value = entry.get("name", entry.get("type"))
+        if not isinstance(name_value, str) or not name_value.strip():
+            raise ValueError(f"{source}: glitchling #{index} is missing a 'name'.")
+
+        parameters = entry.get("parameters")
+        if parameters is not None:
+            if not isinstance(parameters, Mapping):
+                raise ValueError(f"{source}: glitchling '{name_value}' parameters must be a mapping.")
+            kwargs = dict(parameters)
+        else:
+            kwargs = {
+                key: value
+                for key, value in entry.items()
+                if key not in {"name", "type", "parameters"}
+            }
+
+        try:
+            glitchling_type = get_glitchling_class(name_value)
+        except ValueError as exc:
+            raise ValueError(f"{source}: glitchling #{index}: {exc}") from exc
+
+        try:
+            return glitchling_type(**kwargs)
+        except TypeError as exc:
+            raise ValueError(
+                f"{source}: glitchling #{index}: failed to instantiate '{name_value}': {exc}"
+            ) from exc
+
+    raise ValueError(f"{source}: glitchling #{index} must be a string or mapping.")
+
+
+__all__ = [
+    "AttackConfig",
+    "DEFAULT_ATTACK_SEED",
+    "DEFAULT_CONFIG_PATH",
+    "DEFAULT_LEXICON_PRIORITY",
+    "RuntimeConfig",
+    "LexiconConfig",
+    "build_gaggle",
+    "get_config",
+    "load_attack_config",
+    "parse_attack_config",
+    "reload_config",
+    "reset_config",
+]

glitchlings/config.toml

@@ -0,0 +1,3 @@
+[lexicon]
+priority = ["vector", "graph", "wordnet"]
+vector_cache = "lexicon/data/default_vector_cache.json"

glitchlings/lexicon/__init__.py

@@ -0,0 +1,191 @@
+"""Lexicon abstractions and default backend resolution helpers."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from hashlib import blake2s
+import random
+from typing import Callable, Iterable
+
+from glitchlings.config import get_config
+
+
+class Lexicon(ABC):
+    """Abstract interface describing synonym lookup backends.
+
+    Parameters
+    ----------
+    seed:
+        Optional integer used to derive deterministic random number generators
+        for synonym sampling. Identical seeds guarantee reproducible results for
+        the same word/part-of-speech queries.
+    """
+
+    def __init__(self, *, seed: int | None = None) -> None:
+        self._seed = seed
+
+    @property
+    def seed(self) -> int | None:
+        """Return the current base seed used for deterministic sampling."""
+
+        return self._seed
+
+    def reseed(self, seed: int | None) -> None:
+        """Update the base seed driving deterministic synonym sampling."""
+
+        self._seed = seed
+
+    def _derive_rng(self, word: str, pos: str | None) -> random.Random:
+        """Return an RNG derived from the base seed, word, and POS tag."""
+
+        seed_material = blake2s(digest_size=8)
+        seed_material.update(word.lower().encode("utf8"))
+        if pos is not None:
+            seed_material.update(pos.lower().encode("utf8"))
+        seed_repr = "None" if self._seed is None else str(self._seed)
+        seed_material.update(seed_repr.encode("utf8"))
+        derived_seed = int.from_bytes(seed_material.digest(), "big", signed=False)
+        return random.Random(derived_seed)
+
+    def _deterministic_sample(
+        self, values: Iterable[str], *, limit: int, word: str, pos: str | None
+    ) -> list[str]:
+        """Return up to ``limit`` values sampled deterministically."""
+
+        if limit <= 0:
+            return []
+
+        items = list(values)
+        if len(items) <= limit:
+            return items
+
+        rng = self._derive_rng(word, pos)
+        indices = rng.sample(range(len(items)), k=limit)
+        indices.sort()
+        return [items[index] for index in indices]
+
+    @abstractmethod
+    def get_synonyms(
+        self, word: str, pos: str | None = None, n: int = 5
+    ) -> list[str]:
+        """Return up to ``n`` synonyms for ``word`` constrained by ``pos``."""
+
+    def supports_pos(self, pos: str | None) -> bool:
+        """Return ``True`` when the backend can service ``pos`` queries."""
+
+        return True
+
+    def __repr__(self) -> str:  # pragma: no cover - trivial representation
+        return f"{self.__class__.__name__}(seed={self._seed!r})"
+
+
+from .graph import GraphLexicon
+from .metrics import (
+    compare_lexicons,
+    coverage_ratio,
+    mean_cosine_similarity,
+    synonym_diversity,
+)
+from .vector import VectorLexicon, build_vector_cache
+
+try:  # pragma: no cover - optional dependency
+    from .wordnet import WordNetLexicon
+except Exception:  # pragma: no cover - triggered when nltk unavailable
+    WordNetLexicon = None  # type: ignore[assignment]
+
+
+_BACKEND_FACTORIES: dict[str, Callable[[int | None], Lexicon | None]] = {}
+
+
+def register_backend(
+    name: str, factory: Callable[[int | None], Lexicon | None]
+) -> None:
+    """Register ``factory`` for ``name`` so it can be selected via config."""
+
+    normalized = name.lower()
+    _BACKEND_FACTORIES[normalized] = factory
+
+
+def unregister_backend(name: str) -> None:
+    """Remove a previously registered backend."""
+
+    _BACKEND_FACTORIES.pop(name.lower(), None)
+
+
+def available_backends() -> list[str]:
+    """Return the names of registered lexicon factories."""
+
+    return sorted(_BACKEND_FACTORIES)
+
+
+def _vector_backend(seed: int | None) -> Lexicon | None:
+    config = get_config()
+    cache_path = config.lexicon.vector_cache
+    if cache_path is None:
+        return None
+    if not cache_path.exists():
+        return None
+    return VectorLexicon(cache_path=cache_path, seed=seed)
+
+
+def _graph_backend(seed: int | None) -> Lexicon | None:
+    config = get_config()
+    cache_path = config.lexicon.graph_cache
+    if cache_path is None:
+        return None
+    if not cache_path.exists():
+        return None
+    return GraphLexicon(cache_path=cache_path, seed=seed)
+
+
+def _wordnet_backend(seed: int | None) -> Lexicon | None:  # pragma: no cover - optional
+    if WordNetLexicon is None:
+        return None
+    try:
+        lexicon = WordNetLexicon(seed=seed)
+    except RuntimeError:
+        return None
+    return lexicon
+
+
+register_backend("vector", _vector_backend)
+register_backend("graph", _graph_backend)
+register_backend("wordnet", _wordnet_backend)
+
+
+def get_default_lexicon(seed: int | None = None) -> Lexicon:
+    """Return the first available lexicon according to configuration priority."""
+
+    config = get_config()
+    attempts: list[str] = []
+    for name in config.lexicon.priority:
+        factory = _BACKEND_FACTORIES.get(name.lower())
+        if factory is None:
+            attempts.append(f"{name} (unknown)")
+            continue
+        lexicon = factory(seed)
+        if lexicon is not None:
+            return lexicon
+        attempts.append(f"{name} (unavailable)")
+    attempted = ", ".join(attempts) or "<none>"
+    raise RuntimeError(
+        "No lexicon backends available; configure lexicon.priority with at least one "
+        f"working backend. Attempts: {attempted}."
+    )
+
+
+__all__ = [
+    "Lexicon",
+    "VectorLexicon",
+    "GraphLexicon",
+    "WordNetLexicon",
+    "build_vector_cache",
+    "compare_lexicons",
+    "coverage_ratio",
+    "mean_cosine_similarity",
+    "synonym_diversity",
+    "get_default_lexicon",
+    "register_backend",
+    "unregister_backend",
+    "available_backends",
+]

glitchlings/lexicon/data/default_vector_cache.json

@@ -0,0 +1,16 @@
+{
+  "sing": ["croon", "warble", "chant", "serenade"],
+  "happy": ["cheerful", "joyful", "contented", "gleeful"],
+  "songs": ["tunes", "melodies", "ballads", "airs"],
+  "quickly": ["rapidly", "swiftly", "speedily", "promptly"],
+  "text": ["passage", "excerpt", "phrase", "content"],
+  "words": ["terms", "phrases", "lexemes", "expressions"],
+  "alpha": ["beta", "gamma", "delta"],
+  "beta": ["alpha", "gamma", "delta"],
+  "gamma": ["alpha", "beta", "delta"],
+  "delta": ["alpha", "beta", "gamma"],
+  "they": ["these people", "those folks", "those individuals"],
+  "quick": ["rapid", "swift", "brisk", "prompt"],
+  "fast": ["rapid", "swift", "quick", "speedy"],
+  "slow": ["sluggish", "lethargic", "unhurried", "deliberate"]
+}