grudge-cli 0.1.0__py3-none-any.whl

grudge/shrinker/cassette_builder.py

@@ -0,0 +1,328 @@
+"""Two-level cassette shrinking orchestration.
+
+Level one removes whole cassette entries using ordered delta debugging.  Level
+two removes irrelevant response fields, list members, text tokens, and matcher
+detail.  Every attempted candidate is recorded in ``history`` so callers can
+animate or audit the deterministic search.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Mapping, Sequence
+from typing import Any, TypeAlias
+
+from grudge.errors import OracleError
+from grudge.schema.cassette import ArgMatcher, Cassette, CassetteEntry
+from grudge.shrinker.oracle import Oracle, PredicateOracle, SeedPredicate
+
+ReductionEvent: TypeAlias = dict[str, Any]
+ContentReducer: TypeAlias = Callable[[Cassette], Iterable[tuple[str, Cassette]]]
+
+
+class ShrinkResult:
+    """The original cassette, its minimal candidate, and deterministic history."""
+
+    def __init__(
+        self,
+        original: Cassette,
+        minimal: Cassette,
+        stats: Mapping[str, int],
+        history: Sequence[ReductionEvent],
+    ) -> None:
+        self.original = original
+        self.minimal = minimal
+        self.stats = dict(stats)
+        self.history = list(history)
+
+
+def _candidate(
+    current: Cassette,
+    entries: Sequence[CassetteEntry],
+) -> Cassette:
+    """Copy a cassette while replacing its ordered world."""
+
+    return current.model_copy(update={"world": list(entries)}, deep=True)
+
+
+def _event(
+    *,
+    level: str,
+    reducer: str,
+    kept: bool,
+    before: Cassette,
+    after: Cassette,
+    attempted_removal: int,
+) -> ReductionEvent:
+    return {
+        "level": level,
+        "reducer": reducer,
+        "attempted_removal": attempted_removal,
+        "kept": kept,
+        "size_before": len(before.world),
+        "size_after": len(after.world),
+        "bytes_before": before.size_bytes(),
+        "bytes_after": after.size_bytes(),
+    }
+
+
+def _chunks(items: Sequence[CassetteEntry], count: int) -> list[list[CassetteEntry]]:
+    """Partition items into contiguous, stable chunks."""
+
+    size, remainder = divmod(len(items), count)
+    chunks: list[list[CassetteEntry]] = []
+    start = 0
+    for index in range(count):
+        width = size + (1 if index < remainder else 0)
+        if width:
+            chunks.append(list(items[start : start + width]))
+        start += width
+    return chunks
+
+
+def _complement(
+    items: Sequence[CassetteEntry], subset: Sequence[CassetteEntry]
+) -> list[CassetteEntry]:
+    """Remove one occurrence of each subset item, preserving duplicates."""
+
+    remaining = list(subset)
+    complement: list[CassetteEntry] = []
+    for item in items:
+        try:
+            index = remaining.index(item)
+        except ValueError:
+            complement.append(item)
+        else:
+            remaining.pop(index)
+    return complement
+
+
+def _entry_ddmin(
+    cassette: Cassette,
+    oracle: Oracle,
+    history: list[ReductionEvent],
+) -> Cassette:
+    """Perform classic Zeller ddmin over the ordered cassette entries."""
+
+    current = cassette
+    granularity = 2
+    while len(current.world) >= 2:
+        granularity = min(granularity, len(current.world))
+        partitions = _chunks(current.world, granularity)
+        reduced = False
+
+        # First try each subset, then each complement.  This is the classic
+        # algorithm and handles both single culprits and interacting pairs.
+        for subset in partitions:
+            candidate = _candidate(current, subset)
+            result = oracle.reproduces(candidate)
+            history.append(
+                _event(
+                    level="entries",
+                    reducer="ddmin-subset",
+                    kept=result.reproduced,
+                    before=current,
+                    after=candidate if result.reproduced else current,
+                    attempted_removal=len(current.world) - len(subset),
+                )
+            )
+            if result.reproduced:
+                current = candidate
+                granularity = max(granularity - 1, 2)
+                reduced = True
+                break
+        if reduced:
+            continue
+
+        for subset in partitions:
+            complement = _complement(current.world, subset)
+            candidate = _candidate(current, complement)
+            result = oracle.reproduces(candidate)
+            history.append(
+                _event(
+                    level="entries",
+                    reducer="ddmin-complement",
+                    kept=result.reproduced,
+                    before=current,
+                    after=candidate if result.reproduced else current,
+                    attempted_removal=len(current.world) - len(complement),
+                )
+            )
+            if result.reproduced:
+                current = candidate
+                granularity = max(granularity - 1, 2)
+                reduced = True
+                break
+        if reduced:
+            continue
+
+        if granularity == len(current.world):
+            break
+        granularity = min(len(current.world), granularity * 2)
+    return current
+
+
+def _string_variants(value: str) -> Iterable[str]:
+    """Yield stable text reductions from coarse to fine."""
+
+    if not value:
+        return
+    yield ""
+    words = value.split()
+    if len(words) > 1:
+        # Chunk removal is enough to preserve the two meaningful fragments in
+        # the demo injection while discarding its prose and filler.
+        for count in range(2, len(words) + 1):
+            chunks = _word_chunks(words, count)
+            for chunk in chunks:
+                yield " ".join(
+                    word for index, word in enumerate(words) if index not in chunk
+                )
+    if len(value) > 1:
+        yield value[: len(value) // 2]
+
+
+def _word_chunks(words: Sequence[str], count: int) -> list[set[int]]:
+    """Return index chunks for deterministic token-level reduction."""
+
+    width, remainder = divmod(len(words), count)
+    chunks: list[set[int]] = []
+    start = 0
+    for index in range(count):
+        chunk_width = width + (1 if index < remainder else 0)
+        if chunk_width:
+            chunks.append(set(range(start, start + chunk_width)))
+        start += chunk_width
+    return chunks
+
+
+def _value_variants(value: Any) -> Iterable[Any]:
+    """Yield one deterministic, local reduction for a JSON-like value."""
+
+    if isinstance(value, str):
+        yield from _string_variants(value)
+        return
+    if isinstance(value, Mapping):
+        for key in value:
+            reduced = dict(value)
+            del reduced[key]
+            yield reduced
+        for key, child in value.items():
+            for replacement in _value_variants(child):
+                reduced = dict(value)
+                reduced[key] = replacement
+                yield reduced
+        return
+    if isinstance(value, list):
+        for index in range(len(value)):
+            yield value[:index] + value[index + 1 :]
+        for index, child in enumerate(value):
+            for replacement in _value_variants(child):
+                reduced_list = list(value)
+                reduced_list[index] = replacement
+                yield reduced_list
+
+
+def _content_candidates(cassette: Cassette) -> Iterable[tuple[str, Cassette]]:
+    """Yield candidate cassettes for the current level-two pass."""
+
+    for entry_index, entry in enumerate(cassette.world):
+        for replacement in _value_variants(entry.response):
+            entries = list(cassette.world)
+            entries[entry_index] = entry.model_copy(update={"response": replacement})
+            yield "content", _candidate(cassette, entries)
+        if entry.match.kind != "any":
+            entries = list(cassette.world)
+            entries[entry_index] = entry.model_copy(update={"match": ArgMatcher.any()})
+            yield "matcher", _candidate(cassette, entries)
+
+
+def _reduce_content(
+    cassette: Cassette,
+    oracle: Oracle,
+    history: list[ReductionEvent],
+) -> Cassette:
+    """Apply content reductions to a fixed point in stable order."""
+
+    current = cassette
+    while True:
+        accepted = False
+        for reducer, candidate in _content_candidates(current):
+            result = oracle.reproduces(candidate)
+            history.append(
+                _event(
+                    level="content",
+                    reducer=reducer,
+                    kept=result.reproduced,
+                    before=current,
+                    after=candidate if result.reproduced else current,
+                    attempted_removal=0,
+                )
+            )
+            if result.reproduced:
+                current = candidate
+                accepted = True
+                break
+        if not accepted:
+            return current
+
+
+def build_minimal_cassette(
+    original: Cassette,
+    oracle: Oracle | None = None,
+    *,
+    agent_fn: Callable[..., Any] | None = None,
+    seed_predicate: SeedPredicate | Any | None = None,
+    llm: Any = None,
+    repeats: int = 1,
+    max_oracle_calls: int | None = 1000,
+    timeout: float = 2.0,
+    max_steps: int = 128,
+) -> ShrinkResult:
+    """Build a minimal reproducing cassette with ordered reduction history.
+
+    Callers may provide an existing ``Oracle`` or the ``agent_fn`` and
+    ``seed_predicate`` needed to construct a :class:`PredicateOracle`.
+    """
+
+    if oracle is None:
+        if agent_fn is None or seed_predicate is None:
+            raise TypeError(
+                "provide oracle, or provide both agent_fn and seed_predicate"
+            )
+        oracle = PredicateOracle(
+            agent_fn,
+            seed_predicate,
+            llm=llm,
+            repeats=repeats,
+            max_oracle_calls=max_oracle_calls,
+            timeout=timeout,
+            max_steps=max_steps,
+        )
+    original_copy = original.model_copy(deep=True)
+    initial = oracle.reproduces(original_copy)
+    if not initial.reproduced:
+        raise OracleError(
+            "cannot shrink a cassette that does not reproduce: " + initial.reason
+        )
+
+    history: list[ReductionEvent] = []
+    entry_minimal = _entry_ddmin(original_copy, oracle, history)
+    minimal = _reduce_content(entry_minimal, oracle, history)
+    stats = {
+        "oracle_calls": int(getattr(oracle, "calls", 0)),
+        "cache_hits": int(getattr(oracle, "cache_hits", 0)),
+        "history_events": len(history),
+        "original_entries": len(original_copy.world),
+        "minimal_entries": len(minimal.world),
+        "original_bytes": original_copy.size_bytes(),
+        "minimal_bytes": minimal.size_bytes(),
+    }
+    return ShrinkResult(original_copy, minimal, stats, history)
+
+
+__all__ = [
+    "ContentReducer",
+    "ReductionEvent",
+    "ShrinkResult",
+    "build_minimal_cassette",
+]

grudge/shrinker/ddmin.py

@@ -0,0 +1,243 @@
+"""Pure Zeller delta debugging for the cassette shrinker.
+
+This module deliberately knows nothing about cassettes or agents.  It takes a
+sequence and a deterministic reproduction predicate, then returns a reduced
+list together with the ordered attempts made while searching.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from typing import Any, TypeVar
+
+ItemT = TypeVar("ItemT")
+ProgressEvent = dict[str, Any]
+ProgressCallback = Callable[[ProgressEvent], None]
+
+
+@dataclass(frozen=True, slots=True)
+class DdminStats:
+    """Deterministic accounting and history for one ddmin invocation."""
+
+    attempts: int
+    reductions: int
+    test_calls: int
+    granularity: int
+    budget_exhausted: bool
+    history: tuple[ProgressEvent, ...]
+
+    @property
+    def calls(self) -> int:
+        """Compatibility alias for the number of predicate calls."""
+
+        return self.test_calls
+
+    def __getitem__(self, key: str) -> Any:
+        """Allow stats to be consumed like the small mapping it represents."""
+
+        if key == "calls":
+            return self.test_calls
+        return getattr(self, key)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Return a field without requiring callers to know the dataclass API."""
+
+        try:
+            return self[key]
+        except AttributeError:
+            return default
+
+    def as_dict(self) -> dict[str, Any]:
+        """Return JSON-compatible stats for event and report consumers."""
+
+        return {
+            "attempts": self.attempts,
+            "reductions": self.reductions,
+            "test_calls": self.test_calls,
+            "calls": self.test_calls,
+            "granularity": self.granularity,
+            "budget_exhausted": self.budget_exhausted,
+            "history": [dict(event) for event in self.history],
+        }
+
+
+def _jsonish(value: Any) -> Any:
+    """Keep progress history serializable for cassette-entry viewers."""
+
+    dump = getattr(value, "model_dump", None)
+    if callable(dump):
+        return dump(mode="json")
+    if isinstance(value, list):
+        return [_jsonish(item) for item in value]
+    if isinstance(value, tuple):
+        return [_jsonish(item) for item in value]
+    if isinstance(value, dict):
+        return {str(key): _jsonish(item) for key, item in value.items()}
+    return value
+
+
+def _partitions(items: list[ItemT], granularity: int) -> list[list[ItemT]]:
+    """Split ``items`` into deterministic, contiguous, non-empty chunks."""
+
+    count = min(max(granularity, 1), len(items))
+    quotient, remainder = divmod(len(items), count)
+    partitions: list[list[ItemT]] = []
+    start = 0
+    for index in range(count):
+        width = quotient + (1 if index < remainder else 0)
+        partitions.append(items[start : start + width])
+        start += width
+    return partitions
+
+
+def _event(
+    removed: list[ItemT], kept: bool, size_before: int, size_after: int
+) -> ProgressEvent:
+    """Build one stable progress record."""
+
+    return {
+        "attempted_removal": [_jsonish(item) for item in removed],
+        "kept": kept,
+        "size_before": size_before,
+        "size_after": size_after,
+    }
+
+
+def minimize(
+    items: Sequence[ItemT],
+    test: Callable[[list[ItemT]], bool],
+    *,
+    progress: ProgressCallback | None = None,
+    progress_callback: ProgressCallback | None = None,
+    on_progress: ProgressCallback | None = None,
+    max_attempts: int | None = None,
+    max_calls: int | None = None,
+) -> tuple[list[ItemT], DdminStats]:
+    """Return a 1-minimal subsequence that still satisfies ``test``.
+
+    The implementation follows Zeller's algorithm: start with two chunks,
+    test each chunk before its complement, and double the granularity when a
+    pass makes no progress.  A successful reduction resets granularity toward
+    two.  ``test`` receives a fresh list for every candidate and is never
+    allowed to mutate the working list through the public API.
+
+    ``progress``, ``progress_callback``, and ``on_progress`` are aliases;
+    supplying more than one is an error.  A budget is optional and only
+    affects calls when explicitly set.
+    Without a budget, termination checks every singleton removal and is thus
+    1-minimal.  A budget-limited result is reported through
+    :attr:`DdminStats.budget_exhausted`.
+    """
+
+    callbacks = [
+        callback
+        for callback in (progress, progress_callback, on_progress)
+        if callback is not None
+    ]
+    if len(callbacks) > 1:
+        raise TypeError("provide only one progress callback")
+    callback = callbacks[0] if callbacks else None
+    if max_attempts is not None and max_attempts < 0:
+        raise ValueError("max_attempts must be non-negative")
+    if max_calls is not None and max_calls < 0:
+        raise ValueError("max_calls must be non-negative")
+    if max_attempts is not None and max_calls is not None:
+        if max_attempts != max_calls:
+            raise ValueError("max_attempts and max_calls disagree")
+    budget = max_attempts if max_attempts is not None else max_calls
+
+    current = list(items)
+    history: list[ProgressEvent] = []
+    attempts = 0
+    reductions = 0
+    granularity = 2 if len(current) > 1 else len(current)
+    budget_exhausted = False
+
+    def try_candidate(candidate: list[ItemT], removed: list[ItemT]) -> bool:
+        nonlocal attempts, reductions, budget_exhausted, current
+        if budget is not None and attempts >= budget:
+            budget_exhausted = True
+            return False
+        size_before = len(current)
+        attempts += 1
+        kept = bool(test(list(candidate)))
+        event = _event(
+            removed,
+            kept,
+            size_before,
+            len(candidate) if kept else size_before,
+        )
+        history.append(event)
+        if callback is not None:
+            callback(dict(event))
+        if kept:
+            current = candidate
+            reductions += 1
+        return kept
+
+    while len(current) > 1 and not budget_exhausted:
+        granularity = min(max(granularity, 2), len(current))
+        partitions = _partitions(current, granularity)
+        reduced = False
+
+        # First try retaining each partition (removing its complement).
+        for index, subset in enumerate(partitions):
+            removed = [
+                item
+                for part_index, part in enumerate(partitions)
+                if part_index != index
+                for item in part
+            ]
+            if try_candidate(list(subset), removed):
+                granularity = max(granularity - 1, 2)
+                reduced = True
+                break
+            if budget_exhausted:
+                break
+        if reduced or budget_exhausted:
+            continue
+
+        # Then try retaining each complement (removing the partition).
+        for index, subset in enumerate(partitions):
+            complement = [
+                item
+                for part_index, part in enumerate(partitions)
+                if part_index != index
+                for item in part
+            ]
+            if try_candidate(complement, list(subset)):
+                granularity = max(granularity - 1, 2)
+                reduced = True
+                break
+            if budget_exhausted:
+                break
+        if reduced or budget_exhausted:
+            continue
+
+        if granularity >= len(current):
+            break
+        granularity = min(len(current), granularity * 2)
+
+    stats = DdminStats(
+        attempts=attempts,
+        reductions=reductions,
+        test_calls=attempts,
+        granularity=granularity,
+        budget_exhausted=budget_exhausted,
+        history=tuple(dict(event) for event in history),
+    )
+    return current, stats
+
+
+def ddmin(
+    items: Sequence[ItemT],
+    test: Callable[[list[ItemT]], bool],
+    **kwargs: Any,
+) -> tuple[list[ItemT], DdminStats]:
+    """Explicit algorithm name; an alias of :func:`minimize`."""
+
+    return minimize(items, test, **kwargs)
+
+
+__all__ = ["DdminStats", "ProgressEvent", "ddmin", "minimize"]