evalrx 0.1.2__py3-none-any.whl

evalrx/analyzers/patching/causal_trace.py

@@ -0,0 +1,30 @@
+"""Activation patching / causal tracing (Meng et al., ROME) (Stage 2).
+
+The only CAUSAL white-box method here: read a clean run's activations and WRITE
+them into a corrupted run to localise where information is causally used.
+``requires=HIDDEN_STATES`` (read+write hooks — via nnsight). Memory ∝ layers×positions.
+
+References:
+- Locating and Editing Factual Associations in GPT (ROME, causal tracing)
+  Meng et al., NeurIPS 2022 — arXiv:2202.05262
+- Attribution Patching (scalable approximation): Neel Nanda, 2023.
+"""
+
+from __future__ import annotations
+
+from evalrx.core.analyzer import Analyzer
+from evalrx.core.capability import Capability
+from evalrx.core.registry import register_analyzer
+
+
+@register_analyzer("causal_trace")
+class CausalTraceAnalyzer(Analyzer):
+    name = "causal_trace"
+    requires = frozenset({Capability.HIDDEN_STATES})
+    applies_to_modalities = frozenset({"text", "image"})
+
+    def _run(self, model, cases):
+        raise NotImplementedError(
+            "Stage 2: clean/corrupt runs + patch cached activations at each (layer, position) "
+            "via nnsight; report the causal-effect map. Needs read+write hooks (beyond HF flags)."
+        )

evalrx/analyzers/perturbation/__init__.py

@@ -0,0 +1,23 @@
+"""Input-perturbation analyzers (black-box-feasible; cost driver = many forwards)."""
+
+from evalrx.analyzers.perturbation.context_shap import ContextShapAnalyzer
+from evalrx.analyzers.perturbation.cot_faithfulness import CoTFaithfulnessAnalyzer
+from evalrx.analyzers.perturbation.format_sensitivity import FormatSensitivityAnalyzer
+from evalrx.analyzers.perturbation.mm_shap import MMShapAnalyzer
+from evalrx.analyzers.perturbation.modality_ablation import ModalityAblationAnalyzer
+from evalrx.analyzers.perturbation.perturbation_battery import PerturbationBattery
+from evalrx.analyzers.perturbation.prompt_contrast import PromptContrastAnalyzer
+from evalrx.analyzers.perturbation.rise import RISEAnalyzer
+from evalrx.analyzers.perturbation.vl_shap import VLShapAnalyzer
+
+__all__ = [
+    "RISEAnalyzer",
+    "VLShapAnalyzer",
+    "MMShapAnalyzer",
+    "ModalityAblationAnalyzer",
+    "PromptContrastAnalyzer",
+    "FormatSensitivityAnalyzer",
+    "CoTFaithfulnessAnalyzer",
+    "ContextShapAnalyzer",
+    "PerturbationBattery",
+]

evalrx/analyzers/perturbation/_shapley.py

@@ -0,0 +1,54 @@
+"""Permutation-sampling Shapley values — shared by MM-SHAP and VL-SHAP.
+
+Estimates each player's Shapley value (mean marginal contribution to a coalition
+value) by sampling random permutations.  ``value_fn(kept: set) -> float`` is the
+coalition value (e.g. the model's logprob/confidence with only ``kept`` players
+present).  Results are memoised by coalition so expensive model calls aren't
+repeated.  For an additive game the estimate equals each player's exact weight.
+
+References:
+- Shapley value: 'A Value for n-Person Games', Shapley (1953), Contributions to the Theory of Games II.
+- Sampling estimator: 'Polynomial calculation of the Shapley value based on sampling',
+  Castro, Gomez & Tejada (2009), Computers & Operations Research 36(5).
+- ML attribution: 'A Unified Approach to Interpreting Model Predictions' (SHAP),
+  Lundberg & Lee, NeurIPS 2017 — arXiv:1705.07874
+"""
+
+from __future__ import annotations
+
+import random
+from typing import Callable, Iterable
+
+
+def shapley_values(
+    players: Iterable,
+    value_fn: Callable[[set], float],
+    n_samples: int = 64,
+    seed: int = 0,
+) -> dict:
+    """Return ``{player: shapley_value}`` via permutation sampling."""
+    players = list(players)
+    phi = {p: 0.0 for p in players}
+    if not players:
+        return phi
+    rng = random.Random(seed)
+    memo: dict = {}
+
+    def val(kept: set) -> float:
+        key = frozenset(kept)
+        if key not in memo:
+            memo[key] = float(value_fn(set(kept)))
+        return memo[key]
+
+    base = val(set())
+    for _ in range(n_samples):
+        perm = players[:]
+        rng.shuffle(perm)
+        kept: set = set()
+        prev = base
+        for p in perm:
+            kept.add(p)
+            cur = val(kept)
+            phi[p] += cur - prev
+            prev = cur
+    return {p: phi[p] / n_samples for p in players}

evalrx/analyzers/perturbation/context_shap.py

@@ -0,0 +1,174 @@
+"""Context-chunk Shapley — which parts of the provided context carry the answer?
+
+The text sibling of :class:`ToolShap` and MM-SHAP: ablate CHUNKS OF THE GIVEN
+CONTEXT (paragraphs or sentences) instead of tools or image patches, and
+Shapley-attribute the answer to them.  Directly serves RAG/long-context LLM
+diagnosis: a failing case whose answer depends on no chunk is answering from
+priors; one dominated by a single chunk inherits that chunk's quality.
+
+Black-box (``requires=GENERATE``): the coalition value is the similarity of
+the ablated-context answer to the full-context baseline answer.  Uses the
+shared permutation-sampling estimator (memoised), so model calls are bounded.
+
+References:
+- TokenSHAP: Interpreting Large Language Models with Monte Carlo Shapley Value
+  Estimation — Goldshmidt & Horovicz, 2024 — arXiv:2407.10114
+- ContextCite: Attributing Model Generation to Context —
+  Cohen-Wang et al., NeurIPS 2024 — arXiv:2409.00729
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import difflib
+import re
+from typing import TYPE_CHECKING, Any, Callable, Optional
+
+from evalrx.analyzers.perturbation._shapley import shapley_values
+from evalrx.core.analyzer import Analyzer
+from evalrx.core.capability import Capability
+from evalrx.core.registry import register_analyzer
+from evalrx.core.result import Result
+
+if TYPE_CHECKING:
+    from evalrx.core.case import CaseBatch, FailureCase
+    from evalrx.core.model import Model
+
+
+def _similarity(a: str, b: str) -> float:
+    na = " ".join(str(a or "").lower().split())
+    nb = " ".join(str(b or "").lower().split())
+    if not na and not nb:
+        return 1.0
+    return difflib.SequenceMatcher(None, na, nb).ratio()
+
+
+def default_context_fn(case: "FailureCase") -> Optional[str]:
+    """The ablatable context: ``metadata['context']`` when present."""
+    meta = case.metadata if isinstance(case.metadata, dict) else {}
+    value = meta.get("context")
+    return str(value) if value else None
+
+
+def split_chunks(context: str, granularity: str, max_chunks: int) -> list[str]:
+    if granularity == "sentence":
+        parts = [p.strip() for p in re.split(r"(?<=[.!?])\s+", context) if p.strip()]
+    else:
+        parts = [p.strip() for p in re.split(r"\n\s*\n", context) if p.strip()]
+        if len(parts) <= 1:  # single paragraph — fall back to sentences
+            parts = [p.strip() for p in re.split(r"(?<=[.!?])\s+", context) if p.strip()]
+    if len(parts) > max_chunks:  # merge the tail so players stay bounded
+        head, tail = parts[: max_chunks - 1], " ".join(parts[max_chunks - 1:])
+        parts = head + [tail]
+    return parts
+
+
+@register_analyzer("context_shap")
+class ContextShapAnalyzer(Analyzer):
+    """Shapley attribution of the answer to provided-context chunks (RAG dependence probe).
+
+    Hyper-parameters:
+        granularity: ``"paragraph"`` (default) or ``"sentence"`` chunking.
+        n_samples:   permutation samples for the Shapley estimator.
+        max_chunks:  chunk cap per case (tail chunks are merged).
+        max_cases:   label-stratified cap on probed cases; 0 (the default) = every case.
+        seed:        permutation-sampling seed.
+        context_fn:  ``callable(case) -> str | None`` supplying the ablatable
+                     context (default: ``metadata['context']``). The context
+                     must appear verbatim inside the prompt.
+    """
+
+    name = "context_shap"
+    requires = frozenset({Capability.GENERATE})
+    applies_to_modalities = frozenset({"text", "image"})
+
+    def __init__(
+        self,
+        granularity: str = "paragraph",
+        n_samples: int = 16,
+        max_chunks: int = 6,
+        max_cases: int = 0,
+        seed: int = 0,
+        context_fn: Optional[Callable[["FailureCase"], Optional[str]]] = None,
+    ) -> None:
+        super().__init__(
+            granularity=granularity,
+            n_samples=max(1, int(n_samples)),
+            max_chunks=max(2, int(max_chunks)),
+            max_cases=max_cases,
+            seed=seed,
+        )
+        # ctor name, so sklearn-style get_params() reflection works
+        self.context_fn = context_fn or default_context_fn
+
+    def _run(self, model: "Model", cases: "CaseBatch") -> Result:
+        per_case: list[dict[str, Any]] = []
+        for case in cases.stratified_head(self.max_cases):
+            context = self.context_fn(case)
+            prompt = case.inputs.prompt or ""
+            entry: dict[str, Any] = {"sample_id": case.id}
+            if not context:
+                entry["skipped"] = "no context supplied (metadata['context'] or context_fn)"
+                per_case.append(entry)
+                continue
+            if prompt.count(context) != 1:
+                entry["skipped"] = (
+                    "context must occur exactly once verbatim in the prompt "
+                    f"(found {prompt.count(context)} occurrences)"
+                )
+                per_case.append(entry)
+                continue
+            chunks = split_chunks(context, self.granularity, self.max_chunks)
+            entry["n_chunks"] = len(chunks)
+            if len(chunks) < 2:
+                entry["skipped"] = "context has a single chunk — nothing to attribute"
+                per_case.append(entry)
+                continue
+
+            baseline = str(case.observed or "") or str(model.generate(case.inputs))
+
+            def value_fn(kept: set) -> float:
+                kept_text = "\n\n".join(chunks[i] for i in sorted(kept))
+                ablated = prompt.replace(context, kept_text, 1)
+                answer = str(model.generate(dataclasses.replace(case.inputs, prompt=ablated)))
+                return _similarity(answer, baseline)
+
+            coalition_cache: dict[frozenset, float] = {}
+
+            def cached_value(kept: set) -> float:
+                key = frozenset(kept)
+                if key not in coalition_cache:
+                    coalition_cache[key] = value_fn(set(key))
+                return coalition_cache[key]
+
+            phi = shapley_values(
+                range(len(chunks)), cached_value, n_samples=self.n_samples, seed=self.seed
+            )
+            no_context = cached_value(set())
+            top_index = max(phi, key=lambda k: abs(phi[k]))
+            total_abs = sum(abs(v) for v in phi.values()) or 1.0
+            entry["context_dependence"] = round(1.0 - no_context, 4)
+            entry["top_chunk_index"] = int(top_index)
+            entry["top_chunk_share"] = round(abs(phi[top_index]) / total_abs, 4)
+            entry["shapley"] = {str(k): round(v, 4) for k, v in phi.items()}
+            per_case.append(entry)
+
+        deps = [c["context_dependence"] for c in per_case if "context_dependence" in c]
+        findings: dict[str, Any] = {
+            "n_cases": len(per_case),
+            "granularity": self.granularity,
+            "n_samples": self.n_samples,
+            "mean_context_dependence": round(sum(deps) / len(deps), 4) if deps else None,
+            "per_case": per_case,
+            "_caveat": (
+                "context_dependence near 0 = the answer survives with the "
+                "context removed (answering from priors — a hallucination risk "
+                "on context-grounded tasks); top_chunk_share near 1 = one chunk "
+                "carries the answer. Value function is answer SIMILARITY to the "
+                "full-context baseline, not correctness. Requires the context "
+                "verbatim inside the prompt; deterministic decoding assumed "
+                "(each coalition sampled once, memoised). INTERVENTIONAL: "
+                "held-out verification must RE-RUN the ablations."
+            ),
+        }
+        return Result(analyzer=self.name, model=repr(model), cases=cases, findings=findings)

evalrx/analyzers/perturbation/cot_faithfulness.py

@@ -0,0 +1,239 @@
+"""Chain-of-thought faithfulness — does the answer actually depend on the reasoning?
+
+Lanham et al.'s early-answering test: elicit a chain of thought, then truncate
+it at several points and ask for the answer from the partial reasoning.  If the
+model reaches its final answer from almost any prefix, the chain is post-hoc
+rationalisation rather than load-bearing computation — prompt-level fixes that
+edit the reasoning will not move the answer on such cases.
+
+Black-box (``requires=GENERATE``), deterministic truncation points, per-case
+numeric columns for M2/M3.
+
+When the case carries a gold answer the same generations also yield the
+**answer trajectory** — correctness at each truncation point — for free, and
+that is where the actionable columns live: a chain that was already right at
+25% and wrong at the end (``drift_away``) is over-reasoning that needs to be
+stopped early, while one that only becomes right at the end (``late_rescue``)
+is reasoning that is doing real work and must not be shortened.  Both are
+invisible to ``early_answer_match_rate``, which only compares early answers to
+the model's own final answer and cannot tell a stable-correct chain from a
+stable-wrong one.
+
+References:
+- Measuring Faithfulness in Chain-of-Thought Reasoning —
+  Lanham et al., 2023 — arXiv:2307.13702
+- Self-Consistency Improves Chain of Thought Reasoning — Wang et al.,
+  ICLR 2023 — arXiv:2203.11171 (answer-extraction convention)
+- Do NOT Think That Much for 2+3=? On the Overthinking of o1-Like LLMs —
+  Chen et al., 2024 — arXiv:2412.21187 (answer-trajectory / early-correctness)
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import math
+import re
+from typing import TYPE_CHECKING, Any, Callable, Optional
+
+from evalrx.core.analyzer import Analyzer
+from evalrx.core.capability import Capability
+from evalrx.core.registry import register_analyzer
+from evalrx.core.result import Result
+
+if TYPE_CHECKING:
+    from evalrx.core.case import CaseBatch
+    from evalrx.core.model import Model
+
+_COT_SUFFIX = (
+    "Think step by step. After your reasoning, give the final answer on its own "
+    "last line in the form 'Answer: <answer>'."
+)
+_ANSWER_TAG = re.compile(r"answer\s*[:=]\s*(.+)", re.IGNORECASE)
+
+
+def default_answer_fn(text: str) -> str:
+    """Text after the last 'Answer:' tag, else the last non-empty line."""
+    matches = _ANSWER_TAG.findall(str(text or ""))
+    if matches:
+        return matches[-1].strip()
+    lines = [line.strip() for line in str(text or "").splitlines() if line.strip()]
+    return lines[-1] if lines else ""
+
+
+def _normalize(answer: str) -> str:
+    return re.sub(r"[^a-z0-9 ]", "", str(answer or "").lower()).strip()
+
+
+def _default_grader(prediction: Any, case: Any) -> Optional[bool]:
+    """Gold-answer grading; ``None`` when the case carries no gold."""
+    from evalrx.analyzers.reasoning._text import answer_equal, extract_answer
+
+    if getattr(case, "expected", None) is None:
+        return None
+    return answer_equal(extract_answer(prediction), case.expected)
+
+
+def _mean(values: list) -> Optional[float]:
+    clean = [v for v in values if v is not None]
+    return round(sum(clean) / len(clean), 4) if clean else None
+
+
+def _split_reasoning(text: str) -> list[str]:
+    text = str(text or "")
+    matches = list(_ANSWER_TAG.finditer(text))
+    body = text[: matches[-1].start()] if matches else text
+    parts = [p.strip() for p in re.split(r"(?<=[.!?])\s+|\n+", body)]
+    return [p for p in parts if p]
+
+
+@register_analyzer("cot_faithfulness")
+class CoTFaithfulnessAnalyzer(Analyzer):
+    """Early-answering probe: truncate the chain of thought and test whether the final answer survives.
+
+    Hyper-parameters:
+        truncation_fracs: reasoning prefixes to test (fractions of sentences).
+        max_cases:        label-stratified cap (2 + len(fracs) generations each); 0 (the default) = every case.
+        answer_fn:        ``callable(text) -> str`` answer extractor
+                          (default: last 'Answer:' tag, else last line).
+        grader:           ``callable(prediction, case) -> bool | None`` used for
+                          the gold-graded trajectory columns; ``None`` gold ⇒
+                          those columns are simply absent.
+    """
+
+    name = "cot_faithfulness"
+    requires = frozenset({Capability.GENERATE})
+    applies_to_modalities = frozenset({"text", "image"})
+
+    def __init__(
+        self,
+        truncation_fracs: tuple = (0.25, 0.5, 0.75),
+        max_cases: int = 0,
+        answer_fn: Optional[Callable[[str], str]] = None,
+        grader: Optional[Callable[[Any, Any], Optional[bool]]] = None,
+    ) -> None:
+        super().__init__(truncation_fracs=tuple(truncation_fracs) or (0.5,), max_cases=max_cases)
+        # ctor names, so sklearn-style get_params() reflection works
+        self.answer_fn = answer_fn or default_answer_fn
+        self.grader = grader or _default_grader
+
+    def _run(self, model: "Model", cases: "CaseBatch") -> Result:
+        per_case: list[dict[str, Any]] = []
+        answer_trajectory_by_case: dict[str, list[int]] = {}
+        for case in cases.stratified_head(self.max_cases):
+            prompt = case.inputs.prompt or ""
+            direct = str(model.generate(case.inputs))
+            cot_out = str(
+                model.generate(dataclasses.replace(case.inputs, prompt=f"{prompt}\n\n{_COT_SUFFIX}"))
+            )
+            full_answer = _normalize(self.answer_fn(cot_out))
+            direct_answer = _normalize(self.answer_fn(direct))
+            sentences = _split_reasoning(cot_out)
+            entry: dict[str, Any] = {
+                "sample_id": case.id,
+                "cot_sentences": len(sentences),
+            }
+            if not full_answer or not sentences:
+                entry["skipped"] = "no extractable answer or empty reasoning"
+                per_case.append(entry)
+                continue
+            entry["cot_changed_answer"] = int(direct_answer != full_answer)
+            matches = 0
+            early_outputs: list[str] = []
+            # never replay the WHOLE chain as an "early" probe (trivial match)
+            cap = len(sentences) - 1 if len(sentences) > 1 else 1
+            for frac in self.truncation_fracs:
+                keep = max(1, min(cap, math.ceil(frac * len(sentences))))
+                partial = " ".join(sentences[:keep])
+                early_prompt = (
+                    f"{prompt}\n\nReasoning so far:\n{partial}\n\n"
+                    "Given only this reasoning, give the final answer now in the "
+                    "form 'Answer: <answer>'."
+                )
+                early = str(model.generate(dataclasses.replace(case.inputs, prompt=early_prompt)))
+                early_outputs.append(early)
+                if _normalize(self.answer_fn(early)) == full_answer:
+                    matches += 1
+            entry["early_answer_match_rate"] = round(matches / len(self.truncation_fracs), 4)
+            entry.update(self._trajectory_columns(case, early_outputs, cot_out, direct))
+            # Contract: numeric vectors must not sit in a per-case row (they read
+            # as signals and reach no statistic). The trajectory moves to
+            # findings["answer_trajectory_by_case"]; its scalar reductions
+            # (first_correct_frac/drift_away/late_rescue/...) stay on the row.
+            trajectory = entry.pop("answer_trajectory", None)
+            if trajectory is not None:
+                answer_trajectory_by_case[case.id] = trajectory
+            per_case.append(entry)
+
+        rates = [c["early_answer_match_rate"] for c in per_case if "early_answer_match_rate" in c]
+        graded = [c for c in per_case if "final_correct" in c]
+        findings: dict[str, Any] = {
+            "n_cases": len(per_case),
+            "truncation_fracs": list(self.truncation_fracs),
+            "mean_early_match_rate": round(sum(rates) / len(rates), 4) if rates else None,
+            "mean_cot_effect": (
+                round(sum(effects) / len(effects), 4)
+                if (effects := [c["cot_changed_answer"] for c in per_case
+                                if "cot_changed_answer" in c])
+                else None
+            ),
+            # answer-trajectory summary — present only when golds were available
+            "n_graded": len(graded),
+            "drift_away_rate": _mean([c["drift_away"] for c in graded]),
+            "late_rescue_rate": _mean([c["late_rescue"] for c in graded]),
+            "mean_first_correct_frac": _mean(
+                [c["first_correct_frac"] for c in graded if c["first_correct_frac"] is not None]
+            ),
+            "mean_wasted_reasoning_frac": _mean(
+                [c["wasted_reasoning_frac"] for c in graded
+                 if c.get("wasted_reasoning_frac") is not None]
+            ),
+            "per_case": per_case,
+            "answer_trajectory_by_case": answer_trajectory_by_case,
+            "_caveat": (
+                "High early_answer_match_rate = the conclusion barely depends on "
+                "the later reasoning (post-hoc CoT); with cot_changed_answer=0 "
+                "the chain is decorative end to end. Low match rate means the "
+                "reasoning is load-bearing — it does NOT mean it is correct, "
+                "which is exactly what the gold-graded trajectory columns "
+                "separate: drift_away (right early, wrong at the end ⇒ stop "
+                "earlier) and late_rescue (wrong early, right at the end ⇒ do "
+                "NOT shorten) point at opposite fixes and cancel out if pooled. "
+                "wasted_reasoning_frac is defined only for cases that END "
+                "correct — on a wrong final answer 'wasted' is meaningless. "
+                "INTERVENTIONAL columns: held-out verification must RE-RUN the "
+                "truncations. Deterministic decoding recommended; under "
+                "sampling, repeat runs before reading small differences."
+            ),
+        }
+        return Result(analyzer=self.name, model=repr(model), cases=cases, findings=findings)
+
+    # ------------------------------------------------------------------
+    def _trajectory_columns(
+        self, case: Any, early_outputs: list[str], cot_out: str, direct: str
+    ) -> dict[str, Any]:
+        """Gold-graded correctness at each truncation point (empty without a gold)."""
+        final = self.grader(cot_out, case)
+        if final is None:
+            return {}
+        trajectory = [self.grader(text, case) for text in early_outputs]
+        # ungradable early answers would silently read as "wrong"; drop them and
+        # say how many survived instead
+        pairs = [
+            (frac, bool(ok))
+            for frac, ok in zip(self.truncation_fracs, trajectory)
+            if ok is not None
+        ]
+        out: dict[str, Any] = {
+            "final_correct": int(final),
+            "direct_correct": int(bool(self.grader(direct, case))),
+            "answer_trajectory": [int(ok) for _, ok in pairs] + [int(final)],
+            "n_trajectory_points": len(pairs),
+        }
+        first_correct = next((frac for frac, ok in pairs if ok), 1.0 if final else None)
+        out["first_correct_frac"] = first_correct
+        out["drift_away"] = int(any(ok for _, ok in pairs) and not final)
+        out["late_rescue"] = int(bool(final) and not any(ok for _, ok in pairs) and bool(pairs))
+        if final and first_correct is not None:
+            # the share of the chain that ran after the answer was already right
+            out["wasted_reasoning_frac"] = round(1.0 - first_correct, 4)
+        return out