Metadata-Version: 2.4
Name: ice-faithfulness
Version: 1.0.1
Summary: ICE: Intervention-Consistent Explanation Evaluation for LLMs
Author-email: Abhinaba Basu <mail@abhinaba.com>, Pavan Chakraborty <pavan@iiita.ac.in>
License: MIT
Project-URL: Homepage, https://github.com/abhinaba/ice-faithfulness
Project-URL: Paper, https://arxiv.org/abs/2603.18579
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21
Requires-Dist: scipy>=1.7
Requires-Dist: torch>=1.10
Requires-Dist: transformers>=4.20
Requires-Dist: pandas
Requires-Dist: tqdm
Provides-Extra: full
Requires-Dist: pandas; extra == "full"
Requires-Dist: datasets; extra == "full"
Requires-Dist: peft; extra == "full"
Requires-Dist: accelerate; extra == "full"
Dynamic: license-file

# ICE: Intervention-Consistent Explanation Evaluation

[![Paper](https://img.shields.io/badge/Paper-EMNLP%202026%20Findings-blue)](https://arxiv.org/abs/2603.18579)
[![PyPI](https://img.shields.io/pypi/v/ice-faithfulness)](https://pypi.org/project/ice-faithfulness/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

Official implementation of **"ICE: Intervention-Consistent Explanation Evaluation with Statistical Grounding for LLMs"** (EMNLP 2026 Findings).

## Key Finding

Faithfulness is **operator-dependent**: switching the intervention operator crosses the positive-evidence threshold in **18% of configurations** (5/28), with gaps up to 44 percentage points. Nearly one-third of English deletion configurations are anti-faithful (18/56, worse than random), invisible without randomized baselines.

## What ICE Does

ICE evaluates whether model explanations (attention, gradient) identify tokens that are genuinely more important than random tokens, under multiple intervention operators.

```
Input: "a gorgeous, witty, seductive movie"   (positive sentiment)
Rationale: {gorgeous, seductive}

               Deletion    Retrieval Infill
NSR:           0.79        0.39
Win Rate:      92%         68%
Verdict:       Faithful    Weakly Faithful   <-- operator changes conclusion
```

## Installation

```bash
pip install ice-faithfulness
```

## Quick Start

```python
from ice import ICEEvaluator, ICEConfig

config = ICEConfig(
    k_values=[0.2],          # top 20% tokens as rationale
    n_permutations=50,        # random baselines
    operators="lite",         # "lite" (delete+retrieval) or "full"
)

evaluator = ICEEvaluator(model, tokenizer, config)
results = evaluator.evaluate_dataset(dataset, extractor="attention")

print(f"Win Rate: {results.win_rate:.1%}")
print(f"Effect Size (d_null): {results.effect_size:.2f}")
```

### Causal LMs: restrict scoring to label tokens

For prompted classification with causal LMs (Llama, Mistral, Qwen, ...), restrict
prediction and scoring to the task's label tokens via `candidate_token_ids`.
Without this, argmax runs over the full vocabulary and most examples are
filtered out by the confidence threshold.

```python
# For sentiment classification with causal LMs
pos_id = tokenizer.encode(" positive", add_special_tokens=False)[0]
neg_id = tokenizer.encode(" negative", add_special_tokens=False)[0]

config = ICEConfig(
    k_values=[0.2],
    operators="lite",
    candidate_token_ids=[neg_id, pos_id],  # restrict to task labels
)
```

## Core Modules

| Module | Purpose |
|--------|---------|
| `ice.evaluation` | Main evaluator (`ICEEvaluator`, `ICEConfig`) |
| `ice.extractors` | Attention, gradient, IG, LIME extractors |
| `ice.operators` | Deletion, mask, retrieval infill operators |
| `ice.metrics` | NSR scoring, AUC-over-k |
| `ice.stats` | Randomization tests, bootstrap CI, BH correction |
| `ice.retrieval_operator` | Leave-one-out retrieval infill |

## Evaluation Scripts

```bash
# English benchmarks (7 models x 4 tasks)
python scripts_for_repo/run_ice_llm.py --model meta-llama/Llama-3.2-3B-Instruct --dataset sst2

# Multilingual (6 languages)
python scripts_for_repo/run_ice_multilingual.py --model Qwen/Qwen2.5-7B-Instruct --languages french german turkish arabic

# Operator comparison
python scripts_for_repo/run_ice_llm_retrieval.py --model mistralai/Mistral-7B-Instruct-v0.3 --dataset esnli
```

## Key Metrics

| Metric | Range | Meaning |
|--------|-------|---------|
| Win Rate | 0-100% | % of random baselines beaten by the rationale |
| Effect Size | d_null | Standardized distance from null (>0.8 = large, <0 = anti-faithful) |
| Operator Agreement | bool | Both operators give same verdict |

## Results Summary

Evaluated on **7 LLMs** (1.5B-8B), **4 English tasks**, **6 non-English languages**, **2 attribution methods**:

- Operator gaps reach **44 pp** (e.g., Llama-3.2 e-SNLI: 86% deletion vs 43% retrieval)
- **Anti-faithfulness** in nearly 1/3 of English deletion configurations (18/56; gradient selects function words)
- No correlation between faithfulness and human plausibility (|r| < 0.04)
- Cross-lingual faithfulness spans 12%-83%, not predicted by tokenization alone

## Citation

```bibtex
@inproceedings{basu2026ice,
    title={ICE: Intervention-Consistent Explanation Evaluation with Statistical Grounding for LLMs},
    author={Basu, Abhinaba and Chakraborty, Pavan},
    booktitle={Findings of the Association for Computational Linguistics: EMNLP 2026},
    year={2026}
}
```

## License

MIT
