glitchlings 0.4.1__cp312-cp312-manylinux_2_28_x86_64.whl → 0.4.3__cp312-cp312-manylinux_2_28_x86_64.whl

glitchlings/__init__.py

@@ -1,29 +1,35 @@
+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,
+    Apostrofae,
+    Gaggle,
+    Glitchling,
+    Jargoyle,
+    Mim1c,
     Redactyl,
-    redactyl,
     Reduple,
-    reduple,
     Rushmore,
-    rushmore,
     Scannequin,
-    scannequin,
+    Typogre,
     Zeedub,
-    zeedub,
-    Glitchling,
-    Gaggle,
+    adjax,
+    apostrofae,
+    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",
@@ -34,6 +40,8 @@ __all__ = [
     "jargoyle",
     "Adjax",
     "adjax",
+    "Apostrofae",
+    "apostrofae",
     "Redactyl",
     "redactyl",
     "Reduple",
@@ -47,6 +55,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/__main__.py

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

glitchlings/compat.py

@@ -0,0 +1,284 @@
+"""Compatibility helpers centralising optional dependency imports and extras."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from importlib import import_module, metadata
+from types import ModuleType
+from typing import Any, Callable, Iterable, Protocol, cast
+
+
+class _MissingSentinel:
+    __slots__ = ()
+
+
+_MISSING = _MissingSentinel()
+
+
+class _MarkerProtocol(Protocol):
+    def evaluate(self, environment: dict[str, str]) -> bool:
+        ...
+
+
+class _RequirementProtocol(Protocol):
+    marker: _MarkerProtocol | None
+    name: str
+
+    def __init__(self, requirement: str) -> None:
+        ...
+
+
+try:  # pragma: no cover - packaging is bundled with modern Python environments
+    from packaging.markers import default_environment as _default_environment
+except ModuleNotFoundError:  # pragma: no cover - fallback when packaging missing
+    _default_environment = None
+
+try:  # pragma: no cover - packaging is bundled with modern Python environments
+    from packaging.requirements import Requirement as _RequirementClass
+except ModuleNotFoundError:  # pragma: no cover - fallback when packaging missing
+    _RequirementClass = None
+
+default_environment: Callable[[], dict[str, str]] | None
+if _default_environment is None:
+    default_environment = None
+else:
+    default_environment = cast(Callable[[], dict[str, str]], _default_environment)
+
+Requirement: type[_RequirementProtocol] | None
+if _RequirementClass is None:
+    Requirement = None
+else:
+    Requirement = cast(type[_RequirementProtocol], _RequirementClass)
+
+
+@dataclass
+class OptionalDependency:
+    """Lazily import an optional dependency and retain the import error."""
+
+    module_name: str
+    _cached: ModuleType | None | _MissingSentinel = _MISSING
+    _error: ModuleNotFoundError | None = None
+
+    def _attempt_import(self) -> ModuleType | None:
+        try:
+            module = import_module(self.module_name)
+        except ModuleNotFoundError as exc:
+            self._cached = None
+            self._error = exc
+            return None
+        else:
+            self._cached = module
+            self._error = None
+            return module
+
+    def get(self) -> ModuleType | None:
+        """Return the imported module or ``None`` when unavailable."""
+        cached = self._cached
+        if isinstance(cached, _MissingSentinel):
+            return self._attempt_import()
+        if cached is None:
+            return None
+        return cached
+
+    def load(self) -> ModuleType:
+        """Return the dependency, raising the original import error when absent."""
+        module = self.get()
+        if module is None:
+            error = self._error
+            if error is not None:
+                raise error
+            message = f"{self.module_name} is not installed"
+            raise ModuleNotFoundError(message)
+        return module
+
+    def require(self, message: str) -> ModuleType:
+        """Return the dependency or raise ``ModuleNotFoundError`` with ``message``."""
+        try:
+            return self.load()
+        except ModuleNotFoundError as exc:
+            raise ModuleNotFoundError(message) from exc
+
+    def available(self) -> bool:
+        """Return ``True`` when the dependency can be imported."""
+        return self.get() is not None
+
+    def reset(self) -> None:
+        """Forget any cached import result."""
+        self._cached = _MISSING
+        self._error = None
+
+    def attr(self, attribute: str) -> Any | None:
+        """Return ``attribute`` from the dependency when available."""
+        module = self.get()
+        if module is None:
+            return None
+        return getattr(module, attribute, None)
+
+    @property
+    def error(self) -> ModuleNotFoundError | None:
+        """Return the most recent ``ModuleNotFoundError`` (if any)."""
+        self.get()
+        return self._error
+
+
+pytorch_lightning = OptionalDependency("pytorch_lightning")
+datasets = OptionalDependency("datasets")
+verifiers = OptionalDependency("verifiers")
+jellyfish = OptionalDependency("jellyfish")
+jsonschema = OptionalDependency("jsonschema")
+nltk = OptionalDependency("nltk")
+torch = OptionalDependency("torch")
+
+
+def reset_optional_dependencies() -> None:
+    """Clear cached optional dependency imports (used by tests)."""
+    for dependency in (pytorch_lightning, datasets, verifiers, jellyfish, jsonschema, nltk, torch):
+        dependency.reset()
+
+
+def get_datasets_dataset() -> Any | None:
+    """Return Hugging Face ``Dataset`` class when the dependency is installed."""
+    return datasets.attr("Dataset")
+
+
+def require_datasets(message: str = "datasets is not installed") -> ModuleType:
+    """Ensure the Hugging Face datasets dependency is present."""
+    return datasets.require(message)
+
+
+def get_pytorch_lightning_datamodule() -> Any | None:
+    """Return the PyTorch Lightning ``LightningDataModule`` when available."""
+    return pytorch_lightning.attr("LightningDataModule")
+
+
+def require_pytorch_lightning(message: str = "pytorch_lightning is not installed") -> ModuleType:
+    """Ensure the PyTorch Lightning dependency is present."""
+    return pytorch_lightning.require(message)
+
+
+def require_verifiers(message: str = "verifiers is not installed") -> ModuleType:
+    """Ensure the verifiers dependency is present."""
+    return verifiers.require(message)
+
+
+def require_jellyfish(message: str = "jellyfish is not installed") -> ModuleType:
+    """Ensure the jellyfish dependency is present."""
+    return jellyfish.require(message)
+
+
+def require_torch(message: str = "torch is not installed") -> ModuleType:
+    """Ensure the PyTorch dependency is present."""
+    return torch.require(message)
+
+
+def get_torch_dataloader() -> Any | None:
+    """Return PyTorch ``DataLoader`` when the dependency is installed."""
+    torch_module = torch.get()
+    if torch_module is None:
+        return None
+
+    utils_module = getattr(torch_module, "utils", None)
+    if utils_module is None:
+        return None
+
+    data_module = getattr(utils_module, "data", None)
+    if data_module is None:
+        return None
+
+    return getattr(data_module, "DataLoader", None)
+
+
+def get_installed_extras(
+    extras: Iterable[str] | None = None,
+    *,
+    distribution: str = "glitchlings",
+) -> dict[str, bool]:
+    """Return a mapping of optional extras to installation availability."""
+    try:
+        dist = metadata.distribution(distribution)
+    except metadata.PackageNotFoundError:
+        return {}
+
+    provided = {extra.lower() for extra in dist.metadata.get_all("Provides-Extra") or []}
+    targets = {extra.lower() for extra in extras} if extras is not None else provided
+    requirements = dist.requires or []
+    mapping: dict[str, set[str]] = {extra: set() for extra in provided}
+
+    for requirement in requirements:
+        names = _extras_from_requirement(requirement, provided)
+        if not names:
+            continue
+        req_name = _requirement_name(requirement)
+        for extra in names:
+            mapping.setdefault(extra, set()).add(req_name)
+
+    status: dict[str, bool] = {}
+    for extra in targets:
+        deps = mapping.get(extra)
+        if not deps:
+            status[extra] = False
+            continue
+        status[extra] = all(_distribution_installed(dep) for dep in deps)
+    return status
+
+
+def _distribution_installed(name: str) -> bool:
+    try:
+        metadata.distribution(name)
+    except metadata.PackageNotFoundError:
+        return False
+    return True
+
+
+_EXTRA_PATTERN = re.compile(r'extra\\s*==\\s*"(?P<extra>[^"]+)"')
+
+
+def _extras_from_requirement(requirement: str, candidates: set[str]) -> set[str]:
+    if Requirement is not None and default_environment is not None:
+        req = Requirement(requirement)
+        if req.marker is None:
+            return set()
+        extras: set[str] = set()
+        for extra in candidates:
+            environment = default_environment()
+            environment["extra"] = extra
+            if req.marker.evaluate(environment):
+                extras.add(extra)
+        return extras
+
+    matches = set()
+    for match in _EXTRA_PATTERN.finditer(requirement):
+        extra = match.group("extra").lower()
+        if extra in candidates:
+            matches.add(extra)
+    return matches
+
+
+def _requirement_name(requirement: str) -> str:
+    if Requirement is not None:
+        req = Requirement(requirement)
+        return req.name
+
+    candidate = requirement.split(";", 1)[0].strip()
+    for delimiter in ("[", "(", " ", "<", ">", "=", "!", "~"):
+        index = candidate.find(delimiter)
+        if index != -1:
+            return candidate[:index]
+    return candidate
+
+
+__all__ = [
+    "OptionalDependency",
+    "datasets",
+    "verifiers",
+    "jellyfish",
+    "jsonschema",
+    "nltk",
+    "get_datasets_dataset",
+    "require_datasets",
+    "require_verifiers",
+    "require_jellyfish",
+    "get_installed_extras",
+    "reset_optional_dependencies",
+]

glitchlings/config.py

@@ -2,29 +2,86 @@
 
 from __future__ import annotations
 
+import importlib
 import os
+import warnings
 from dataclasses import dataclass, field
 from io import TextIOBase
 from pathlib import Path
-from typing import Any, Mapping, Sequence, TYPE_CHECKING
+from typing import IO, TYPE_CHECKING, Any, Mapping, Protocol, Sequence, cast
+
+from glitchlings.compat import jsonschema
 
 try:  # Python 3.11+
-    import tomllib
+    import tomllib as _tomllib
 except ModuleNotFoundError:  # pragma: no cover - Python < 3.11
-    import tomli as tomllib  # type: ignore[no-redef]
+    _tomllib = importlib.import_module("tomli")
+
+
+class _TomllibModule(Protocol):
+    def load(self, fp: IO[bytes]) -> Any:
+        ...
+
+
+tomllib = cast(_TomllibModule, _tomllib)
+
+
+class _YamlModule(Protocol):
+    YAMLError: type[Exception]
 
-import yaml
+    def safe_load(self, stream: str) -> Any:
+        ...
 
 
+yaml = cast(_YamlModule, importlib.import_module("yaml"))
+
 if TYPE_CHECKING:  # pragma: no cover - typing only
-    from .zoo import Glitchling
+    from .zoo import Gaggle, Glitchling
 
 
 CONFIG_ENV_VAR = "GLITCHLINGS_CONFIG"
 DEFAULT_CONFIG_PATH = Path(__file__).with_name("config.toml")
-DEFAULT_LEXICON_PRIORITY = ["vector", "graph", "wordnet"]
+DEFAULT_LEXICON_PRIORITY = ["vector", "wordnet"]
 DEFAULT_ATTACK_SEED = 151
 
+ATTACK_CONFIG_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "required": ["glitchlings"],
+    "properties": {
+        "glitchlings": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+                "anyOf": [
+                    {"type": "string", "minLength": 1},
+                    {
+                        "type": "object",
+                        "required": ["name"],
+                        "properties": {
+                            "name": {"type": "string", "minLength": 1},
+                            "type": {"type": "string", "minLength": 1},
+                            "parameters": {"type": "object"},
+                        },
+                        "additionalProperties": True,
+                    },
+                    {
+                        "type": "object",
+                        "required": ["type"],
+                        "properties": {
+                            "name": {"type": "string", "minLength": 1},
+                            "type": {"type": "string", "minLength": 1},
+                            "parameters": {"type": "object"},
+                        },
+                        "additionalProperties": True,
+                    },
+                ]
+            },
+        },
+        "seed": {"type": "integer"},
+    },
+    "additionalProperties": False,
+}
+
 
 @dataclass(slots=True)
 class LexiconConfig:
@@ -32,7 +89,6 @@ class LexiconConfig:
 
     priority: list[str] = field(default_factory=lambda: list(DEFAULT_LEXICON_PRIORITY))
     vector_cache: Path | None = None
-    graph_cache: Path | None = None
 
 
 @dataclass(slots=True)
@@ -48,21 +104,18 @@ _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()
@@ -72,26 +125,27 @@ def get_config() -> RuntimeConfig:
 def _load_runtime_config() -> RuntimeConfig:
     path = _resolve_config_path()
     data = _read_toml(path)
-    lexicon_section = data.get("lexicon", {})
+    mapping = _validate_runtime_config_data(data, source=path)
+
+    lexicon_section = mapping.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]
+    normalized_priority = []
+    for item in priority:
+        string_value = str(item)
+        if not string_value:
+            raise ValueError("lexicon.priority entries must be non-empty strings.")
+        normalized_priority.append(string_value)
 
     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)
@@ -110,7 +164,40 @@ def _read_toml(path: Path) -> dict[str, Any]:
             return {}
         raise FileNotFoundError(f"Configuration file '{path}' not found.")
     with path.open("rb") as handle:
-        return tomllib.load(handle)
+        loaded = tomllib.load(handle)
+    if isinstance(loaded, Mapping):
+        return dict(loaded)
+    raise ValueError(f"Configuration file '{path}' must contain a top-level mapping.")
+
+
+def _validate_runtime_config_data(data: Any, *, source: Path) -> Mapping[str, Any]:
+    if data is None:
+        return {}
+    if not isinstance(data, Mapping):
+        raise ValueError(f"Configuration file '{source}' must contain a top-level mapping.")
+
+    allowed_sections = {"lexicon"}
+    unexpected_sections = [str(key) for key in data if key not in allowed_sections]
+    if unexpected_sections:
+        extras = ", ".join(sorted(unexpected_sections))
+        raise ValueError(f"Configuration file '{source}' has unsupported sections: {extras}.")
+
+    lexicon_section = data.get("lexicon", {})
+    if not isinstance(lexicon_section, Mapping):
+        raise ValueError("Configuration 'lexicon' section must be a table.")
+
+    allowed_lexicon_keys = {"priority", "vector_cache"}
+    unexpected_keys = [str(key) for key in lexicon_section if key not in allowed_lexicon_keys]
+    if unexpected_keys:
+        extras = ", ".join(sorted(unexpected_keys))
+        raise ValueError(f"Unknown lexicon settings: {extras}.")
+
+    for key in ("vector_cache",):
+        value = lexicon_section.get(key)
+        if value is not None and not isinstance(value, (str, os.PathLike)):
+            raise ValueError(f"lexicon.{key} must be a path or string when provided.")
+
+    return data
 
 
 def _resolve_optional_path(value: Any, *, base: Path) -> Path | None:
@@ -137,7 +224,6 @@ def load_attack_config(
     encoding: str = "utf-8",
 ) -> AttackConfig:
     """Load and parse an attack configuration from YAML."""
-
     if isinstance(source, (str, Path)):
         path = Path(source)
         label = str(path)
@@ -155,36 +241,67 @@ def load_attack_config(
     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``."""
-
+def _validate_attack_config_schema(data: Any, *, source: str) -> Mapping[str, Any]:
     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:
+    unexpected = [key for key in data if key not in {"glitchlings", "seed"}]
+    if unexpected:
+        extras = ", ".join(sorted(unexpected))
+        raise ValueError(f"Attack configuration '{source}' has unsupported fields: {extras}.")
+
+    if "glitchlings" not in data:
         raise ValueError(f"Attack configuration '{source}' must define 'glitchlings'.")
 
+    raw_glitchlings = data["glitchlings"]
     if not isinstance(raw_glitchlings, Sequence) or isinstance(raw_glitchlings, (str, bytes)):
         raise ValueError(f"'glitchlings' in '{source}' must be a sequence.")
 
+    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.")
+
+    for index, entry in enumerate(raw_glitchlings, start=1):
+        if isinstance(entry, Mapping):
+            name_candidate = entry.get("name") or entry.get("type")
+            if not isinstance(name_candidate, str) or not name_candidate.strip():
+                raise ValueError(f"{source}: glitchling #{index} is missing a 'name'.")
+            parameters = entry.get("parameters")
+            if parameters is not None and not isinstance(parameters, Mapping):
+                raise ValueError(
+                    f"{source}: glitchling '{name_candidate}' parameters must be a mapping."
+                )
+
+    schema_module = jsonschema.get()
+    if schema_module is not None:
+        try:
+            schema_module.validate(instance=data, schema=ATTACK_CONFIG_SCHEMA)
+        except schema_module.exceptions.ValidationError as exc:  # pragma: no cover - optional dep
+            message = exc.message
+            raise ValueError(f"Attack configuration '{source}' is invalid: {message}") from exc
+
+    return data
+
+
+def parse_attack_config(data: Any, *, source: str = "<config>") -> AttackConfig:
+    """Convert arbitrary YAML data into a validated ``AttackConfig``."""
+    mapping = _validate_attack_config_schema(data, source=source)
+
+    raw_glitchlings = mapping["glitchlings"]
+
     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.")
+    seed = mapping.get("seed")
 
     return AttackConfig(glitchlings=glitchlings, seed=seed)
 
 
-def build_gaggle(config: AttackConfig, *, seed_override: int | None = None):
+def build_gaggle(config: AttackConfig, *, seed_override: int | None = None) -> "Gaggle":
     """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
@@ -201,7 +318,7 @@ def _load_yaml(text: str, label: str) -> Any:
         raise ValueError(f"Failed to parse attack configuration '{label}': {exc}") from exc
 
 
-def _build_glitchling(entry: Any, source: str, index: int):
+def _build_glitchling(entry: Any, source: str, index: int) -> "Glitchling":
     from .zoo import get_glitchling_class, parse_glitchling_spec
 
     if isinstance(entry, str):
@@ -211,14 +328,27 @@ def _build_glitchling(entry: Any, source: str, index: int):
             raise ValueError(f"{source}: glitchling #{index}: {exc}") from exc
 
     if isinstance(entry, Mapping):
-        name_value = entry.get("name", entry.get("type"))
+        name_value = entry.get("name")
+        legacy_type = entry.get("type")
+        if name_value is None and legacy_type is not None:
+            warnings.warn(
+                f"{source}: glitchling #{index} uses 'type'; prefer 'name'.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            name_value = legacy_type
+        elif name_value is None:
+            name_value = legacy_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.")
+                raise ValueError(
+                    f"{source}: glitchling '{name_value}' parameters must be a mapping."
+                )
             kwargs = dict(parameters)
         else:
             kwargs = {

glitchlings/config.toml

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