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

glitchlings/zoo/core.py

@@ -1,69 +1,68 @@
 """Core data structures used to model glitchlings and their interactions."""
 
 import inspect
-import logging
-import os
 import random
+from collections.abc import Mapping, Sequence
 from enum import IntEnum, auto
 from hashlib import blake2s
-from typing import TYPE_CHECKING, Any, Callable, Protocol
-
-_datasets_error: ModuleNotFoundError | None = None
-try:  # pragma: no cover - optional dependency
-    from datasets import Dataset as _DatasetsDataset
-except ModuleNotFoundError as error:  # pragma: no cover - optional dependency
-    _DatasetsDataset = None  # type: ignore[assignment]
-    _datasets_error = error
-else:
-    _datasets_error = None
-
-try:  # pragma: no cover - optional dependency
-    from glitchlings._zoo_rust import compose_glitchlings as _compose_glitchlings_rust
-except ImportError:  # pragma: no cover - compiled extension not present
-    _compose_glitchlings_rust = None
-
-
-log = logging.getLogger(__name__)
-
+from typing import TYPE_CHECKING, Any, Callable, Protocol, cast
+
+from glitchlings.internal.rust_ffi import plan_glitchlings_rust
+
+from ..compat.loaders import get_datasets_dataset, require_datasets
+from ..compat.types import Dataset as DatasetProtocol
+from ..util.transcripts import (
+    Transcript,
+    TranscriptTarget,
+    is_transcript,
+)
+from .core_execution import execute_plan
+from .core_planning import (
+    PipelineDescriptor,
+    PipelineOperationPayload,
+    build_execution_plan,
+    build_pipeline_descriptor,
+    normalize_plan_entries,
+)
+from .core_planning import (
+    PlanEntry as _PlanEntry,
+)
+from .corrupt_dispatch import (
+    StringCorruptionTarget,
+    assemble_corruption_result,
+    resolve_corruption_target,
+)
+
+_DatasetsDataset = get_datasets_dataset()
+
+_is_transcript = is_transcript
+
+
+def plan_glitchlings(
+    entries: Sequence[_PlanEntry],
+    master_seed: int | None,
+) -> list[tuple[int, int]]:
+    """Normalize glitchling instances or specs and compute an orchestration plan.
+
+    Notes
+    -----
+    The Rust extension is required for orchestration.
+    """
+    if master_seed is None:
+        message = "Gaggle orchestration requires a master seed"
+        raise ValueError(message)
+
+    normalized_specs = [spec.as_mapping() for spec in normalize_plan_entries(entries)]
+    master_seed_int = int(master_seed)
+    return plan_glitchlings_rust(list(normalized_specs), master_seed_int)
 
-_PIPELINE_FEATURE_FLAG_ENV = "GLITCHLINGS_RUST_PIPELINE"
-
-
-def _pipeline_feature_flag_enabled() -> bool:
-    """Return ``True`` when the environment explicitly opts into the Rust pipeline."""
-
-    value = os.environ.get(_PIPELINE_FEATURE_FLAG_ENV)
-    if value is None:
-        return False
-
-    normalized = value.strip().lower()
-    return normalized in {"1", "true", "yes", "on"}
 
 if TYPE_CHECKING:  # pragma: no cover - typing only
-    from datasets import Dataset  # type: ignore
+    from datasets import Dataset
 elif _DatasetsDataset is not None:
     Dataset = _DatasetsDataset
 else:
-
-    class Dataset(Protocol):  # type: ignore[no-redef]
-        """Typed stub mirroring the Hugging Face dataset interface used here."""
-
-        def with_transform(self, function: Any) -> "Dataset": ...
-
-
-def _is_transcript(value: Any) -> bool:
-    """Return True when the value resembles a chat transcript."""
-
-    if not isinstance(value, list):
-        return False
-
-    if not value:
-        return True
-
-    if not all(isinstance(turn, dict) for turn in value):
-        return False
-
-    return "content" in value[-1]
+    Dataset = DatasetProtocol
 
 
 class CorruptionCallable(Protocol):
@@ -107,7 +106,8 @@ class Glitchling:
         scope: AttackWave,
         order: AttackOrder = AttackOrder.NORMAL,
         seed: int | None = None,
-        pipeline_operation: Callable[["Glitchling"], dict[str, Any] | None] | None = None,
+        pipeline_operation: Callable[["Glitchling"], Mapping[str, Any] | None] | None = None,
+        transcript_target: TranscriptTarget = "last",
         **kwargs: Any,
     ) -> None:
         """Initialize a glitchling.
@@ -118,9 +118,17 @@ class Glitchling:
             scope: Text granularity on which the glitchling operates.
             order: Relative ordering within the same scope.
             seed: Optional seed for deterministic random behaviour.
+            pipeline_operation: Optional factory for Rust pipeline descriptors.
+            transcript_target: Which transcript turns to corrupt. Accepts:
+                - ``"last"`` (default): corrupt only the last turn
+                - ``"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
             **kwargs: Additional parameters forwarded to the corruption callable.
-        """
 
+        """
         # Each Glitchling maintains its own RNG for deterministic yet isolated behavior.
         # If no seed is supplied, we fall back to Python's default entropy.
         self.seed = seed
@@ -130,6 +138,7 @@ class Glitchling:
         self.level: AttackWave = scope
         self.order: AttackOrder = order
         self._pipeline_descriptor_factory = pipeline_operation
+        self.transcript_target: TranscriptTarget = transcript_target
         self.kwargs: dict[str, Any] = {}
         self._cached_rng_callable: CorruptionCallable | None = None
         self._cached_rng_expectation: bool | None = None
@@ -138,7 +147,6 @@ class Glitchling:
 
     def set_param(self, key: str, value: Any) -> None:
         """Persist a parameter for use by the corruption callable."""
-
         aliases = getattr(self, "_param_aliases", {})
         canonical = aliases.get(key, key)
 
@@ -158,26 +166,42 @@ class Glitchling:
             if target == canonical:
                 setattr(self, alias, value)
 
-    def pipeline_operation(self) -> dict[str, Any] | None:
-        """Return the Rust pipeline operation descriptor for this glitchling."""
+    def pipeline_operation(self) -> PipelineOperationPayload | None:
+        """Return the Rust pipeline descriptor or ``None`` when unavailable.
+
+        Glitchlings that cannot provide a compiled pipeline (for example the
+        lightweight helpers used in tests) should override this hook or supply
+        a ``pipeline_operation`` factory that returns ``None`` to indicate that
+        Python orchestration must be used instead. When a descriptor mapping is
+        returned it is validated and forwarded to the Rust pipeline.
+        """
 
         factory = self._pipeline_descriptor_factory
         if factory is None:
             return None
 
-        return factory(self)
+        descriptor = factory(self)
+        if descriptor is None:
+            return None
+
+        if not isinstance(descriptor, Mapping):  # pragma: no cover - defensive
+            raise TypeError("Pipeline descriptor factories must return a mapping or None")
+
+        payload = dict(descriptor)
+        payload_type = payload.get("type")
+        if not isinstance(payload_type, str):
+            message = f"Pipeline descriptor for {self.name} is missing a string 'type' field"
+            raise RuntimeError(message)
+
+        return cast(PipelineOperationPayload, payload)
 
     def _corruption_expects_rng(self) -> bool:
         """Return `True` when the corruption function accepts an rng keyword."""
-
         cached_callable = self._cached_rng_callable
         cached_expectation = self._cached_rng_expectation
         corruption_function = self.corruption_function
 
-        if (
-            cached_callable is corruption_function
-            and cached_expectation is not None
-        ):
+        if cached_callable is corruption_function and cached_expectation is not None:
             return cached_expectation
 
         expects_rng = False
@@ -195,7 +219,6 @@ class Glitchling:
 
     def __corrupt(self, text: str, *args: Any, **kwargs: Any) -> str:
         """Execute the corruption callable, injecting the RNG when required."""
-
         # Pass rng to underlying corruption function if it expects it.
         expects_rng = self._corruption_expects_rng()
 
@@ -205,41 +228,66 @@ class Glitchling:
             corrupted = self.corruption_function(text, *args, **kwargs)
         return corrupted
 
-    def corrupt(self, text: str | list[dict[str, Any]]) -> str | list[dict[str, Any]]:
-        """Apply the corruption function to text or conversational transcripts."""
+    def _execute_corruption(self, text: str) -> str:
+        """Execute the actual corruption on a single text string.
 
-        if _is_transcript(text):
-            transcript = [dict(turn) for turn in text]
-            if transcript:
-                transcript[-1]["content"] = self.__corrupt(
-                    transcript[-1]["content"], **self.kwargs
-                )
-            return transcript
+        This is the impure execution point that invokes the corruption callable.
+        All corruption for this glitchling flows through this single method.
 
+        Args:
+            text: The text to corrupt.
+
+        Returns:
+            The corrupted text.
+        """
         return self.__corrupt(text, **self.kwargs)
 
-    def corrupt_dataset(self, dataset: Dataset, columns: list[str]) -> Dataset:
-        """Apply corruption lazily across dataset columns."""
+    def corrupt(self, text: str | Transcript) -> str | Transcript:
+        """Apply the corruption function to text or conversational transcripts.
 
-        if _DatasetsDataset is None:
-            message = "datasets is not installed"
-            raise ModuleNotFoundError(message) from _datasets_error
+        This method uses a pure dispatch pattern:
+        1. Resolve the corruption target (pure - what to corrupt)
+        2. Execute corruption (impure - single isolated point)
+        3. Assemble the result (pure - combine results)
 
-        def _is_transcript(value: Any) -> bool:
-            """Return ``True`` when the value resembles a chat transcript."""
+        When the input is a transcript, the ``transcript_target`` setting
+        controls which turns are corrupted:
 
-            if not isinstance(value, list) or not value:
-                return False
+        - ``"last"``: corrupt only the last turn (default)
+        - ``"all"``: corrupt all turns
+        - ``"assistant"``: corrupt only turns with ``role="assistant"``
+        - ``"user"``: corrupt only turns with ``role="user"``
+        - ``int``: corrupt a specific turn by index
+        - ``Sequence[int]``: corrupt specific turns by index
+        """
+        # Step 1: Pure dispatch - determine what to corrupt
+        target = resolve_corruption_target(text, self.transcript_target)
 
-            return all(
-                isinstance(turn, dict) and "content" in turn for turn in value
-            )
+        # Step 2: Impure execution - apply corruption via isolated method
+        if isinstance(target, StringCorruptionTarget):
+            corrupted: str | dict[int, str] = self._execute_corruption(target.text)
+        else:
+            # TranscriptCorruptionTarget
+            corrupted = {
+                turn.index: self._execute_corruption(turn.content) for turn in target.turns
+            }
+
+        # Step 3: Pure assembly - combine results
+        return assemble_corruption_result(target, corrupted)
+
+    def corrupt_dataset(self, dataset: Dataset, columns: list[str]) -> Dataset:
+        """Apply corruption lazily across dataset columns."""
+        require_datasets("datasets is not installed")
 
         def __corrupt_row(row: dict[str, Any]) -> dict[str, Any]:
             row = dict(row)
             for column in columns:
                 value = row[column]
-                if _is_transcript(value):
+                if _is_transcript(
+                    value,
+                    allow_empty=False,
+                    require_all_content=True,
+                ):
                     row[column] = self.corrupt(value)
                 elif isinstance(value, list):
                     row[column] = [self.corrupt(item) for item in value]
@@ -249,14 +297,12 @@ class Glitchling:
 
         return dataset.with_transform(__corrupt_row)
 
-    def __call__(self, text: str, *args: Any, **kwds: Any) -> str | list[dict[str, Any]]:
+    def __call__(self, text: str, *args: Any, **kwds: Any) -> str | Transcript:
         """Allow a glitchling to be invoked directly like a callable."""
-
         return self.corrupt(text, *args, **kwds)
 
     def reset_rng(self, seed: int | None = None) -> None:
         """Reset the glitchling's RNG to its initial seed."""
-
         if seed is not None:
             self.seed = seed
         if self.seed is not None:
@@ -264,57 +310,98 @@ class Glitchling:
 
     def clone(self, seed: int | None = None) -> "Glitchling":
         """Create a copy of this glitchling, optionally with a new seed."""
-
         cls = self.__class__
         filtered_kwargs = {k: v for k, v in self.kwargs.items() if k != "seed"}
         clone_seed = seed if seed is not None else self.seed
-        if clone_seed is not None:
-            filtered_kwargs["seed"] = clone_seed
 
         if cls is Glitchling:
+            if clone_seed is not None:
+                filtered_kwargs["seed"] = clone_seed
             return Glitchling(
                 self.name,
                 self.corruption_function,
                 self.level,
                 self.order,
                 pipeline_operation=self._pipeline_descriptor_factory,
+                transcript_target=self.transcript_target,
                 **filtered_kwargs,
             )
 
-        return cls(**filtered_kwargs)
+        # Check which kwargs subclass accepts via **kwargs or explicit params
+        try:
+            signature = inspect.signature(cls.__init__)
+            params = signature.parameters
+            has_var_keyword = any(p.kind == inspect.Parameter.VAR_KEYWORD for p in params.values())
+        except (TypeError, ValueError):
+            # If we can't introspect, play it safe and pass nothing extra
+            return cls(**filtered_kwargs)
 
+        # Only include seed if subclass accepts it
+        if clone_seed is not None:
+            if has_var_keyword or "seed" in params:
+                filtered_kwargs["seed"] = clone_seed
 
+        # Only include transcript_target if subclass accepts it
+        if "transcript_target" not in filtered_kwargs:
+            if has_var_keyword or "transcript_target" in params:
+                filtered_kwargs["transcript_target"] = self.transcript_target
 
+        return cls(**filtered_kwargs)
 
 
 class Gaggle(Glitchling):
     """A collection of glitchlings executed in a deterministic order."""
 
-    def __init__(self, glitchlings: list[Glitchling], seed: int = 151):
+    def __init__(
+        self,
+        glitchlings: list[Glitchling],
+        seed: int = 151,
+        transcript_target: TranscriptTarget = "last",
+    ):
         """Initialize the gaggle and derive per-glitchling RNG seeds.
 
         Args:
             glitchlings: Glitchlings to orchestrate.
             seed: Master seed used to derive per-glitchling seeds.
-        """
+            transcript_target: Which transcript turns to corrupt. Accepts:
+                - ``"last"`` (default): corrupt only the last turn
+                - ``"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
 
-        super().__init__("Gaggle", self.corrupt, AttackWave.DOCUMENT, seed=seed)
-        self.glitchlings: dict[AttackWave, list[Glitchling]] = {
-            level: [] for level in AttackWave
-        }
+        """
+        super().__init__(
+            "Gaggle",
+            self._corrupt_text,
+            AttackWave.DOCUMENT,
+            seed=seed,
+            transcript_target=transcript_target,
+        )
+        self._clones_by_index: list[Glitchling] = []
+        for idx, glitchling in enumerate(glitchlings):
+            clone = glitchling.clone()
+            setattr(clone, "_gaggle_index", idx)
+            self._clones_by_index.append(clone)
+
+        self.glitchlings: dict[AttackWave, list[Glitchling]] = {level: [] for level in AttackWave}
         self.apply_order: list[Glitchling] = []
-        # Derive deterministic per-glitchling seeds from master seed if provided
-        for idx, g in enumerate(glitchlings):
-            _g = g.clone()
-            derived_seed = Gaggle.derive_seed(seed, _g.name, idx)
-            _g.reset_rng(derived_seed)
-            setattr(_g, "_gaggle_index", idx)
-            self.glitchlings[g.level].append(_g)
+        self._plan: list[tuple[int, int]] = []
         self.sort_glitchlings()
 
+    def clone(self, seed: int | None = None) -> "Gaggle":
+        """Create a copy of this gaggle, cloning member glitchlings."""
+        clone_seed = seed if seed is not None else self.seed
+        if clone_seed is None:
+            clone_seed = 151  # Default seed for Gaggle
+        cloned_members = [glitchling.clone() for glitchling in self._clones_by_index]
+        return Gaggle(cloned_members, seed=clone_seed, transcript_target=self.transcript_target)
+
     @staticmethod
     def derive_seed(master_seed: int, glitchling_name: str, index: int) -> int:
         """Derive a deterministic seed for a glitchling based on the master seed."""
+
         def _int_to_bytes(value: int) -> bytes:
             if value == 0:
                 return b"\x00"
@@ -341,65 +428,112 @@ class Gaggle(Glitchling):
 
     def sort_glitchlings(self) -> None:
         """Sort glitchlings by wave then order to produce application order."""
-
-        self.apply_order = [
-            g
-            for _, glitchlings in sorted(self.glitchlings.items())
-            for g in sorted(glitchlings, key=lambda x: (x.order, x.name))
-        ]
-
-    @staticmethod
-    def rust_pipeline_supported() -> bool:
-        """Return ``True`` when the compiled Rust pipeline is importable."""
-
-        return _compose_glitchlings_rust is not None
-
-    @staticmethod
-    def rust_pipeline_enabled() -> bool:
-        """Return ``True`` when the Rust pipeline is available and opted in."""
-
-        return Gaggle.rust_pipeline_supported() and _pipeline_feature_flag_enabled()
-
-    def _pipeline_descriptors(self) -> list[dict[str, Any]] | None:
-        if not self.rust_pipeline_enabled():
-            return None
-
-        descriptors: list[dict[str, Any]] = []
+        plan = plan_glitchlings(self._clones_by_index, self.seed)
+        self._plan = plan
+
+        self.glitchlings = {level: [] for level in AttackWave}
+        for clone in self._clones_by_index:
+            self.glitchlings[clone.level].append(clone)
+
+        missing = set(range(len(self._clones_by_index)))
+        apply_order: list[Glitchling] = []
+        for index, derived_seed in plan:
+            clone = self._clones_by_index[index]
+            clone.reset_rng(int(derived_seed))
+            apply_order.append(clone)
+            missing.discard(index)
+
+        if missing:
+            missing_indices = ", ".join(str(idx) for idx in sorted(missing))
+            message = f"Orchestration plan missing glitchlings at indices: {missing_indices}"
+            raise RuntimeError(message)
+
+        self.apply_order = apply_order
+
+    def _pipeline_descriptors(self) -> tuple[list[PipelineDescriptor], list[Glitchling]]:
+        """Collect pipeline descriptors and track glitchlings missing them."""
+        descriptors: list[PipelineDescriptor] = []
+        missing: list[Glitchling] = []
+        master_seed = self.seed
         for glitchling in self.apply_order:
-            operation = glitchling.pipeline_operation()
-            if operation is None:
-                return None
-
-            seed = glitchling.seed
-            if seed is None:
-                index = getattr(glitchling, "_gaggle_index", None)
-                master_seed = self.seed
-                if index is None or master_seed is None:
-                    return None
-                seed = Gaggle.derive_seed(master_seed, glitchling.name, index)
-
-            descriptors.append(
-                {
-                    "name": glitchling.name,
-                    "operation": operation,
-                    "seed": int(seed),
-                }
+            descriptor = build_pipeline_descriptor(
+                glitchling,
+                master_seed=master_seed,
+                derive_seed_fn=Gaggle.derive_seed,
             )
-
-        return descriptors
-
-    def corrupt(self, text: str) -> str:
-        """Apply each glitchling to the provided text sequentially."""
-
+            if descriptor is None:
+                missing.append(glitchling)
+                continue
+            descriptors.append(descriptor.as_mapping())
+
+        return descriptors, missing
+
+    def _corrupt_text(self, text: str) -> str:
+        """Apply each glitchling to string input sequentially.
+
+        This method uses a batched execution strategy to minimize tokenization
+        overhead. Consecutive glitchlings with pipeline support are grouped and
+        executed together via the Rust pipeline, while glitchlings without
+        pipeline support are executed individually. This hybrid approach ensures
+        the text is tokenized fewer times compared to executing every glitchling
+        individually.
+        """
         master_seed = self.seed
-        descriptors = self._pipeline_descriptors()
-        if master_seed is not None and descriptors is not None:
-            try:
-                return _compose_glitchlings_rust(text, descriptors, master_seed)
-            except Exception:  # pragma: no cover - fall back to Python execution
-                log.debug("Rust pipeline failed; falling back", exc_info=True)
-
-        corrupted = text
-        for glitchling in self.apply_order:
-            corrupted = glitchling(corrupted)
-        return corrupted
+        if master_seed is None:
+            message = "Gaggle orchestration requires a master seed"
+            raise RuntimeError(message)
+
+        # Build the pure execution plan
+        plan = build_execution_plan(
+            self.apply_order,
+            master_seed=master_seed,
+            derive_seed_fn=Gaggle.derive_seed,
+        )
+
+        # Execute via the impure dispatch layer
+        return execute_plan(text, plan, master_seed)
+
+    def corrupt(self, text: str | Transcript) -> str | Transcript:
+        """Apply each glitchling to the provided text sequentially.
+
+        This method uses a pure dispatch pattern:
+        1. Resolve the corruption target (pure - what to corrupt)
+        2. Execute corruption (impure - single isolated point)
+        3. Assemble the result (pure - combine results)
+
+        When the input is a transcript, the ``transcript_target`` setting
+        controls which turns are corrupted:
+
+        - ``"last"``: corrupt only the last turn (default)
+        - ``"all"``: corrupt all turns
+        - ``"assistant"``: corrupt only turns with ``role="assistant"``
+        - ``"user"``: corrupt only turns with ``role="user"``
+        - ``int``: corrupt a specific turn by index
+        - ``Sequence[int]``: corrupt specific turns by index
+        """
+        # Step 1: Pure dispatch - determine what to corrupt
+        target = resolve_corruption_target(text, self.transcript_target)
+
+        # Step 2: Impure execution - apply corruption via isolated method
+        if isinstance(target, StringCorruptionTarget):
+            corrupted: str | dict[int, str] = self._corrupt_text(target.text)
+        else:
+            # TranscriptCorruptionTarget
+            corrupted = {turn.index: self._corrupt_text(turn.content) for turn in target.turns}
+
+        # Step 3: Pure assembly - combine results
+        return assemble_corruption_result(target, corrupted)
+
+
+__all__ = [
+    # Enums
+    "AttackWave",
+    "AttackOrder",
+    # Core classes
+    "Glitchling",
+    "Gaggle",
+    # Planning functions
+    "plan_glitchlings",
+    "PipelineOperationPayload",
+    "PipelineDescriptor",
+]