glitchlings 0.4.0__cp312-cp312-macosx_11_0_universal2.whl → 0.4.2__cp312-cp312-macosx_11_0_universal2.whl

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/__main__.py

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

glitchlings/compat.py

@@ -0,0 +1,215 @@
+"""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, Iterable
+
+try:  # pragma: no cover - packaging is bundled with modern Python environments
+    from packaging.markers import default_environment
+    from packaging.requirements import Requirement
+except ModuleNotFoundError:  # pragma: no cover - fallback when packaging missing
+    Requirement = None  # type: ignore[assignment]
+    default_environment = None  # type: ignore[assignment]
+
+_MISSING = object()
+
+
+@dataclass
+class OptionalDependency:
+    """Lazily import an optional dependency and retain the import error."""
+
+    module_name: str
+    _cached: ModuleType | object = _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."""
+        if self._cached is _MISSING:
+            return self._attempt_import()
+        if self._cached is None:
+            return None
+        return self._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
+
+
+datasets = OptionalDependency("datasets")
+verifiers = OptionalDependency("verifiers")
+jellyfish = OptionalDependency("jellyfish")
+jsonschema = OptionalDependency("jsonschema")
+nltk = OptionalDependency("nltk")
+
+
+def reset_optional_dependencies() -> None:
+    """Clear cached optional dependency imports (used by tests)."""
+    for dependency in (datasets, verifiers, jellyfish, jsonschema, nltk):
+        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 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 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

@@ -3,10 +3,11 @@
 from __future__ import annotations
 
 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 TYPE_CHECKING, Any, Mapping, Sequence
 
 try:  # Python 3.11+
     import tomllib
@@ -15,6 +16,7 @@ except ModuleNotFoundError:  # pragma: no cover - Python < 3.11
 
 import yaml
 
+from .compat import jsonschema
 
 if TYPE_CHECKING:  # pragma: no cover - typing only
     from .zoo import Glitchling
@@ -25,6 +27,44 @@ DEFAULT_CONFIG_PATH = Path(__file__).with_name("config.toml")
 DEFAULT_LEXICON_PRIORITY = ["vector", "graph", "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:
@@ -48,21 +88,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,12 +109,19 @@ 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"),
@@ -113,6 +157,36 @@ def _read_toml(path: Path) -> dict[str, Any]:
         return tomllib.load(handle)
 
 
+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", "graph_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", "graph_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:
     if value in (None, ""):
         return None
@@ -137,7 +211,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 +228,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):
     """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
@@ -211,14 +315,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/dlc/_shared.py

@@ -0,0 +1,68 @@
+"""Shared utilities for DLC integrations."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import Any
+
+
+def resolve_environment(
+    env: Any,
+    *,
+    loader: Callable[[str], Any],
+    environment_type: type[Any],
+) -> Any:
+    """Return a fully-instantiated verifier environment."""
+    if isinstance(env, str):
+        env = loader(env)
+
+    if not isinstance(env, environment_type):
+        raise TypeError("Invalid environment type")
+
+    return env
+
+
+def resolve_columns(dataset: Any, columns: Sequence[str] | None) -> list[str]:
+    """Identify which dataset columns should be corrupted."""
+    available = set(getattr(dataset, "column_names", ()))
+
+    if columns is not None:
+        missing = sorted(set(columns) - available)
+        if missing:
+            missing_str = ", ".join(missing)
+            raise ValueError(f"Columns not found in dataset: {missing_str}")
+        return list(columns)
+
+    for candidate in ("prompt", "question"):
+        if candidate in available:
+            return [candidate]
+
+    try:
+        dataset_length = len(dataset)
+    except TypeError:
+        preview_rows: list[dict[str, Any]]
+        take_fn = getattr(dataset, "take", None)
+        if callable(take_fn):
+            preview_rows = list(take_fn(1))
+        else:
+            iterator = iter(dataset)
+            try:
+                first_row = next(iterator)
+            except StopIteration:
+                preview_rows = []
+            else:
+                preview_rows = [first_row]
+        sample = dict(preview_rows[0]) if preview_rows else {}
+    else:
+        sample = dataset[0] if dataset_length else {}
+    inferred = [
+        name for name in getattr(dataset, "column_names", ()) if isinstance(sample.get(name), str)
+    ]
+
+    if inferred:
+        return inferred
+
+    raise ValueError("Unable to determine which dataset columns to corrupt.")
+
+
+__all__ = ["resolve_columns", "resolve_environment"]