lime-audit 0.1.0__py3-none-any.whl

lime_audit/__init__.py

@@ -0,0 +1,3 @@
+"""lime-audit: Audit LIME explanations for stability and faithfulness."""
+
+__version__ = "0.1.0"

lime_audit/analyse.py

@@ -0,0 +1,290 @@
+"""
+Analyse LIME audit results - compute stability and faithfulness aggregates.
+"""
+
+import csv
+import json
+import os
+from collections import defaultdict
+
+import numpy as np
+
+from lime_audit.config import (
+    FAITHFULNESS_THRESHOLD_DIRECTION,
+    LIME_NUM_FEATURES,
+    STABILITY_THRESHOLD_JACCARD,
+    STABILITY_THRESHOLD_KENDALL,
+    TOP_K_FOR_JACCARD,
+)
+from lime_audit.metrics import bootstrap_ci, compute_pairwise_stability, count_tokenizer_mismatch
+
+
+def load_raw_attributions(path, num_features=LIME_NUM_FEATURES):
+    by_input = defaultdict(dict)
+    with open(path, "r", encoding="utf-8") as f:
+        reader = csv.DictReader(f)
+        for row in reader:
+            if not row.get("input_id") or not row.get("seed"):
+                continue
+            input_id = int(row["input_id"])
+            seed = int(row["seed"])
+            tokens = []
+            for i in range(1, num_features + 1):
+                t = row.get(f"token_{i}", "")
+                w = float(row.get(f"weight_{i}", 0))
+                if t:
+                    tokens.append((t, w))
+            by_input[input_id][seed] = {
+                "tokens": tokens,
+                "base_label": row["base_label"],
+                "base_confidence": float(row["base_confidence"]),
+                "base_positive_score": float(row["base_positive_score"]),
+                "lime_score": float(row["lime_score"]),
+                "duration_ms": int(row["duration_ms"]),
+                "category": row["category"],
+                "text": row["text"],
+            }
+    return dict(by_input)
+
+
+def load_deletion_results(path):
+    by_input = {}
+    with open(path, "r", encoding="utf-8") as f:
+        reader = csv.DictReader(f)
+        for row in reader:
+            status = row.get("status", "tested")
+            if status == "skipped_empty":
+                by_input[int(row["input_id"])] = {
+                    "status": "skipped_empty",
+                    "category": row["category"],
+                    "text": row["text"],
+                }
+                continue
+            entry = {
+                "status": "tested",
+                "removed_token": row["removed_token"],
+                "token_lime_weight": float(row["token_lime_weight"]),
+                "original_label": row["original_label"],
+                "original_positive_score": float(row["original_positive_score"]),
+                "modified_label": row["modified_label"],
+                "modified_positive_score": float(row["modified_positive_score"]),
+                "confidence_delta": float(row["confidence_delta"]),
+                "label_flipped": row["label_flipped"] == "True",
+                "direction_correct": row["direction_correct"] == "True",
+                "category": row["category"],
+                "text": row["text"],
+            }
+            if row.get("delta_top3") and row["delta_top3"] != "":
+                entry["delta_top3"] = float(row["delta_top3"])
+                entry["flipped_top3"] = row["flipped_top3"] == "True"
+            if row.get("delta_top5") and row["delta_top5"] != "":
+                entry["delta_top5"] = float(row["delta_top5"])
+                entry["flipped_top5"] = row["flipped_top5"] == "True"
+            by_input[int(row["input_id"])] = entry
+    return by_input
+
+
+def analyse(output_dir, model_name):
+    raw_csv = os.path.join(output_dir, "raw_attributions.csv")
+    del_csv = os.path.join(output_dir, "deletion_faithfulness.csv")
+    stability_csv = os.path.join(output_dir, "stability_metrics.csv")
+    summary_path = os.path.join(output_dir, "summary.json")
+
+    print("[1/4] Loading raw attributions...")
+    raw = load_raw_attributions(raw_csv)
+    print(f"  {len(raw)} inputs loaded")
+
+    print("[2/4] Loading deletion results...")
+    deletions = load_deletion_results(del_csv)
+    print(f"  {len(deletions)} deletion tests loaded")
+
+    print("[3/4] Computing stability and tokenizer mismatch...")
+    stability_rows = []
+
+    for input_id in sorted(raw.keys()):
+        seeds_data = raw[input_id]
+        first = next(iter(seeds_data.values()))
+        category = first["category"]
+        text = first["text"]
+
+        seed_tokens = {s: d["tokens"] for s, d in seeds_data.items()}
+        pairwise = compute_pairwise_stability(seed_tokens, k=TOP_K_FOR_JACCARD)
+
+        labels = [d["base_label"] for d in seeds_data.values()]
+        confidences = [d["base_confidence"] for d in seeds_data.values()]
+
+        mean_j = round(pairwise["mean_jaccard"], 4)
+        jaccard_ci = bootstrap_ci(pairwise["all_jaccards"])
+        tok_mismatch = count_tokenizer_mismatch(text, model_name)
+
+        stability_rows.append({
+            "input_id": input_id,
+            "category": category,
+            "text": text[:80],
+            "mean_jaccard_top5": mean_j,
+            "jaccard_ci_lower": round(jaccard_ci[0], 4),
+            "jaccard_ci_upper": round(jaccard_ci[1], 4),
+            "min_jaccard_top5": round(pairwise["min_jaccard"], 4),
+            "mean_kendall_tau": round(pairwise["mean_kendall_tau"], 4),
+            "min_kendall_tau": round(pairwise["min_kendall_tau"], 4) if not np.isnan(pairwise["min_kendall_tau"]) else "NaN",
+            "label_stable": len(set(labels)) == 1,
+            "confidence_std": round(float(np.std(confidences)), 6),
+            "top1_unanimous": pairwise["top1_unanimous"],
+            "lime_token_count": tok_mismatch["lime_token_count"],
+            "wordpiece_token_count": tok_mismatch["wordpiece_token_count"],
+            "token_mismatch": tok_mismatch["token_mismatch"],
+        })
+
+    fieldnames = [
+        "input_id", "category", "text", "mean_jaccard_top5",
+        "jaccard_ci_lower", "jaccard_ci_upper",
+        "min_jaccard_top5", "mean_kendall_tau", "min_kendall_tau",
+        "label_stable", "confidence_std", "top1_unanimous",
+        "lime_token_count", "wordpiece_token_count", "token_mismatch",
+    ]
+    with open(stability_csv, "w", newline="", encoding="utf-8") as f:
+        writer = csv.DictWriter(f, fieldnames=fieldnames)
+        writer.writeheader()
+        writer.writerows(stability_rows)
+    print(f"  Saved stability CSV: {stability_csv}")
+
+    print("[4/4] Computing summary...")
+    jaccards = [r["mean_jaccard_top5"] for r in stability_rows]
+    taus = [r["mean_kendall_tau"] for r in stability_rows if not isinstance(r["mean_kendall_tau"], str)]
+    overall_jaccard_ci = bootstrap_ci(jaccards) if jaccards else (None, None)
+    mismatches = [r["token_mismatch"] for r in stability_rows]
+
+    cat_stability = defaultdict(lambda: {"jaccards": [], "taus": []})
+    for r in stability_rows:
+        cat = r["category"]
+        cat_stability[cat]["jaccards"].append(r["mean_jaccard_top5"])
+        if not isinstance(r["mean_kendall_tau"], str):
+            cat_stability[cat]["taus"].append(r["mean_kendall_tau"])
+
+    tested = {k: v for k, v in deletions.items() if v.get("status") != "skipped_empty"}
+    skipped = {k: v for k, v in deletions.items() if v.get("status") == "skipped_empty"}
+
+    del_correct = [d for d in tested.values() if d["direction_correct"]]
+    del_flipped = [d for d in tested.values() if d["label_flipped"]]
+    del_deltas = [abs(d["confidence_delta"]) for d in tested.values() if not np.isnan(d["confidence_delta"])]
+
+    del3_deltas = [abs(d["delta_top3"]) for d in tested.values() if "delta_top3" in d]
+    del3_flipped = [d for d in tested.values() if d.get("flipped_top3")]
+    del5_deltas = [abs(d["delta_top5"]) for d in tested.values() if "delta_top5" in d]
+    del5_flipped = [d for d in tested.values() if d.get("flipped_top5")]
+
+    env_path = os.path.join(output_dir, "environment.json")
+    env_info = {}
+    if os.path.exists(env_path):
+        with open(env_path, "r") as f:
+            env_info = json.load(f)
+
+    cat_faith = defaultdict(lambda: {"correct": 0, "flipped": 0, "total": 0, "deltas": [],
+                                      "deltas_top3": [], "flipped_top3": 0,
+                                      "deltas_top5": [], "flipped_top5": 0})
+    for d in tested.values():
+        cat = d["category"]
+        cat_faith[cat]["total"] += 1
+        if d["direction_correct"]:
+            cat_faith[cat]["correct"] += 1
+        if d["label_flipped"]:
+            cat_faith[cat]["flipped"] += 1
+        if not np.isnan(d["confidence_delta"]):
+            cat_faith[cat]["deltas"].append(abs(d["confidence_delta"]))
+        if "delta_top3" in d:
+            cat_faith[cat]["deltas_top3"].append(abs(d["delta_top3"]))
+            if d.get("flipped_top3"):
+                cat_faith[cat]["flipped_top3"] += 1
+        if "delta_top5" in d:
+            cat_faith[cat]["deltas_top5"].append(abs(d["delta_top5"]))
+            if d.get("flipped_top5"):
+                cat_faith[cat]["flipped_top5"] += 1
+
+    summary = {
+        "experiment_metadata": env_info,
+        "stability_summary": {
+            "overall_mean_jaccard_top5": round(float(np.mean(jaccards)), 4) if jaccards else None,
+            "overall_jaccard_ci_95": [round(overall_jaccard_ci[0], 4), round(overall_jaccard_ci[1], 4)] if overall_jaccard_ci[0] is not None else None,
+            "overall_mean_kendall_tau": round(float(np.mean(taus)), 4) if taus else None,
+            "inputs_with_perfect_jaccard": sum(1 for j in jaccards if j >= 1.0),
+            "inputs_with_jaccard_below_threshold": sum(1 for j in jaccards if j < STABILITY_THRESHOLD_JACCARD),
+            "inputs_with_label_instability": sum(1 for r in stability_rows if not r["label_stable"]),
+            "inputs_with_unanimous_top1": sum(1 for r in stability_rows if r["top1_unanimous"]),
+            "total_inputs": len(stability_rows),
+            "threshold_jaccard": STABILITY_THRESHOLD_JACCARD,
+            "threshold_kendall": STABILITY_THRESHOLD_KENDALL,
+            "per_category": {
+                cat: {
+                    "mean_jaccard": round(float(np.mean(v["jaccards"])), 4),
+                    "jaccard_ci_95": [round(x, 4) for x in bootstrap_ci(v["jaccards"])] if len(v["jaccards"]) > 1 else None,
+                    "mean_kendall_tau": round(float(np.mean(v["taus"])), 4) if v["taus"] else None,
+                }
+                for cat, v in cat_stability.items()
+            },
+        },
+        "tokenizer_mismatch_summary": {
+            "mean_mismatch": round(float(np.mean(mismatches)), 2),
+            "max_mismatch": int(np.max(mismatches)),
+            "inputs_with_mismatch": sum(1 for m in mismatches if m != 0),
+            "total_inputs": len(mismatches),
+        },
+        "faithfulness_summary": {
+            "total_deletion_tests": len(tested),
+            "skipped_inputs": len(skipped),
+            "direction_correct_count": len(del_correct),
+            "direction_correct_rate": round(len(del_correct) / len(tested), 4) if tested else None,
+            "label_flip_count": len(del_flipped),
+            "label_flip_rate": round(len(del_flipped) / len(tested), 4) if tested else None,
+            "mean_abs_confidence_delta": round(float(np.mean(del_deltas)), 4) if del_deltas else None,
+            "threshold_direction_correct": FAITHFULNESS_THRESHOLD_DIRECTION,
+            "top3_deletion": {
+                "mean_abs_delta": round(float(np.mean(del3_deltas)), 4) if del3_deltas else None,
+                "flip_count": len(del3_flipped),
+                "flip_rate": round(len(del3_flipped) / len(del3_deltas), 4) if del3_deltas else None,
+            },
+            "top5_deletion": {
+                "mean_abs_delta": round(float(np.mean(del5_deltas)), 4) if del5_deltas else None,
+                "flip_count": len(del5_flipped),
+                "flip_rate": round(len(del5_flipped) / len(del5_deltas), 4) if del5_deltas else None,
+            },
+            "per_category": {
+                cat: {
+                    "direction_correct_rate": round(v["correct"] / v["total"], 4) if v["total"] else None,
+                    "label_flip_rate": round(v["flipped"] / v["total"], 4) if v["total"] else None,
+                    "mean_abs_delta": round(float(np.mean(v["deltas"])), 4) if v["deltas"] else None,
+                    "mean_abs_delta_top3": round(float(np.mean(v["deltas_top3"])), 4) if v["deltas_top3"] else None,
+                    "flip_rate_top3": round(v["flipped_top3"] / len(v["deltas_top3"]), 4) if v["deltas_top3"] else None,
+                    "mean_abs_delta_top5": round(float(np.mean(v["deltas_top5"])), 4) if v["deltas_top5"] else None,
+                    "flip_rate_top5": round(v["flipped_top5"] / len(v["deltas_top5"]), 4) if v["deltas_top5"] else None,
+                }
+                for cat, v in cat_faith.items()
+            },
+        },
+    }
+
+    with open(summary_path, "w", encoding="utf-8") as f:
+        json.dump(summary, f, indent=2)
+
+    ss = summary["stability_summary"]
+    fs = summary["faithfulness_summary"]
+    ts = summary["tokenizer_mismatch_summary"]
+
+    print(f"\n--- STABILITY ---")
+    ci = ss.get("overall_jaccard_ci_95")
+    ci_str = f" [{ci[0]}, {ci[1]}]" if ci else ""
+    print(f"  Mean Jaccard top-5: {ss['overall_mean_jaccard_top5']}{ci_str}")
+    print(f"  Mean Kendall tau:   {ss['overall_mean_kendall_tau']}")
+
+    print(f"\n--- TOKENIZER MISMATCH ---")
+    print(f"  Mean mismatch: {ts['mean_mismatch']} extra WordPiece tokens")
+
+    print(f"\n--- FAITHFULNESS ---")
+    print(f"  Direction correct: {fs['direction_correct_rate']}")
+    print(f"  Flip rate (top-1): {fs['label_flip_rate']}")
+    t3 = fs["top3_deletion"]
+    t5 = fs["top5_deletion"]
+    print(f"  Mean |delta| top-3: {t3['mean_abs_delta']}, flip rate: {t3['flip_rate']}")
+    print(f"  Mean |delta| top-5: {t5['mean_abs_delta']}, flip rate: {t5['flip_rate']}")
+
+    print(f"\nSaved: {summary_path}")
+    return summary_path

lime_audit/charts.py

@@ -0,0 +1,179 @@
+"""
+Generate charts for LIME audit results.
+"""
+
+import csv
+import os
+
+import matplotlib.pyplot as plt
+import numpy as np
+
+
+CATEGORY_COLORS = {
+    "negation_minimal_pairs": "#e63946",
+    "lexical_shortcuts": "#457b9d",
+    "ambiguity": "#2a9d8f",
+    "distribution_style_shift": "#e9c46a",
+    "strong_baselines": "#f4a261",
+    "edge_cases": "#264653",
+}
+
+CATEGORY_LABELS = {
+    "negation_minimal_pairs": "Negation",
+    "lexical_shortcuts": "Lexical Shortcuts",
+    "ambiguity": "Ambiguity",
+    "distribution_style_shift": "Distribution Shift",
+    "strong_baselines": "Strong Baselines",
+    "edge_cases": "Edge Cases",
+}
+
+STABILITY_THRESHOLD = 0.6
+
+
+def load_stability(output_dir):
+    rows = []
+    path = os.path.join(output_dir, "stability_metrics.csv")
+    with open(path, "r", encoding="utf-8") as f:
+        reader = csv.DictReader(f)
+        for row in reader:
+            rows.append({
+                "input_id": int(row["input_id"]),
+                "category": row["category"],
+                "text": row["text"],
+                "mean_jaccard": float(row["mean_jaccard_top5"]),
+                "ci_lower": float(row.get("jaccard_ci_lower", row["mean_jaccard_top5"])),
+                "ci_upper": float(row.get("jaccard_ci_upper", row["mean_jaccard_top5"])),
+            })
+    return rows
+
+
+def load_deletion(output_dir):
+    rows = []
+    path = os.path.join(output_dir, "deletion_faithfulness.csv")
+    with open(path, "r", encoding="utf-8") as f:
+        reader = csv.DictReader(f)
+        for row in reader:
+            if row.get("status") == "skipped_empty":
+                continue
+            entry = {
+                "input_id": int(row["input_id"]),
+                "category": row["category"],
+                "confidence_delta": abs(float(row["confidence_delta"])),
+                "label_flipped": row["label_flipped"] == "True",
+            }
+            if row.get("delta_top3") and row["delta_top3"] != "":
+                entry["delta_top3"] = abs(float(row["delta_top3"]))
+                entry["flipped_top3"] = row["flipped_top3"] == "True"
+            if row.get("delta_top5") and row["delta_top5"] != "":
+                entry["delta_top5"] = abs(float(row["delta_top5"]))
+                entry["flipped_top5"] = row["flipped_top5"] == "True"
+            rows.append(entry)
+    return rows
+
+
+def chart_jaccard(stability_rows, output_dir):
+    sorted_rows = sorted(stability_rows, key=lambda r: r["mean_jaccard"])
+    fig, ax = plt.subplots(figsize=(12, 6))
+
+    x = np.arange(len(sorted_rows))
+    colors = [CATEGORY_COLORS.get(r["category"], "#888") for r in sorted_rows]
+    means = [r["mean_jaccard"] for r in sorted_rows]
+    ci_lower = [r["mean_jaccard"] - r["ci_lower"] for r in sorted_rows]
+    ci_upper = [r["ci_upper"] - r["mean_jaccard"] for r in sorted_rows]
+
+    ax.bar(x, means, color=colors, edgecolor="white", linewidth=0.5)
+    ax.errorbar(x, means, yerr=[ci_lower, ci_upper], fmt="none", ecolor="#333333",
+                capsize=3, linewidth=1)
+    ax.axhline(y=STABILITY_THRESHOLD, color="#cc0000", linestyle="--",
+               linewidth=1.5, label=f"Threshold ({STABILITY_THRESHOLD})")
+
+    handles = [plt.Rectangle((0, 0), 1, 1, color=c) for c in CATEGORY_COLORS.values()]
+    labels = list(CATEGORY_LABELS.values())
+    ax.legend(handles, labels, loc="upper left", fontsize=8, ncol=2)
+
+    ax.set_xlabel("Inputs (sorted by stability)", fontsize=11)
+    ax.set_ylabel("Mean Jaccard Top-5 Overlap", fontsize=11)
+    ax.set_title("LIME Attribution Stability Across 5 Random Seeds", fontsize=13, fontweight="bold")
+    ax.set_ylim(0, 1.1)
+    ax.set_xticks([])
+
+    fig.tight_layout()
+    path = os.path.join(output_dir, "chart_jaccard_by_input.png")
+    fig.savefig(path, dpi=150)
+    plt.close(fig)
+    print(f"Saved: {path}")
+
+
+def chart_faithfulness(deletion_rows, output_dir):
+    cat_deltas = {}
+    for row in deletion_rows:
+        cat = row["category"]
+        if cat not in cat_deltas:
+            cat_deltas[cat] = {"top1": [], "top3": [], "top5": [], "flip1": [], "flip3": [], "flip5": []}
+        cat_deltas[cat]["top1"].append(row["confidence_delta"])
+        cat_deltas[cat]["flip1"].append(row["label_flipped"])
+        if "delta_top3" in row:
+            cat_deltas[cat]["top3"].append(row["delta_top3"])
+            cat_deltas[cat]["flip3"].append(row.get("flipped_top3", False))
+        if "delta_top5" in row:
+            cat_deltas[cat]["top5"].append(row["delta_top5"])
+            cat_deltas[cat]["flip5"].append(row.get("flipped_top5", False))
+
+    display_order = [
+        "strong_baselines", "distribution_style_shift", "edge_cases",
+        "ambiguity", "negation_minimal_pairs", "lexical_shortcuts",
+    ]
+    cats_present = [c for c in display_order if c in cat_deltas]
+    if not cats_present:
+        cats_present = list(cat_deltas.keys())
+
+    fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(14, 5.5))
+    x = np.arange(len(cats_present))
+    width = 0.25
+
+    means_1 = [np.mean(cat_deltas[c]["top1"]) if cat_deltas[c]["top1"] else 0 for c in cats_present]
+    means_3 = [np.mean(cat_deltas[c]["top3"]) if cat_deltas[c]["top3"] else 0 for c in cats_present]
+    means_5 = [np.mean(cat_deltas[c]["top5"]) if cat_deltas[c]["top5"] else 0 for c in cats_present]
+
+    ax1.bar(x - width, means_1, width, label="Top-1 removed", color="#264653")
+    ax1.bar(x, means_3, width, label="Top-3 removed", color="#2a9d8f")
+    ax1.bar(x + width, means_5, width, label="Top-5 removed", color="#e9c46a")
+
+    ax1.set_xlabel("Category", fontsize=10)
+    ax1.set_ylabel("Mean |Confidence Delta|", fontsize=10)
+    ax1.set_title("Impact of Removing Top-K Tokens", fontsize=12, fontweight="bold")
+    ax1.set_xticks(x)
+    ax1.set_xticklabels([CATEGORY_LABELS.get(c, c) for c in cats_present], rotation=30, ha="right", fontsize=8)
+    ax1.legend(fontsize=8)
+    ax1.set_ylim(0, 1.1)
+
+    flip1 = [np.mean(cat_deltas[c]["flip1"]) * 100 if cat_deltas[c]["flip1"] else 0 for c in cats_present]
+    flip3 = [np.mean(cat_deltas[c]["flip3"]) * 100 if cat_deltas[c]["flip3"] else 0 for c in cats_present]
+    flip5 = [np.mean(cat_deltas[c]["flip5"]) * 100 if cat_deltas[c]["flip5"] else 0 for c in cats_present]
+
+    ax2.bar(x - width, flip1, width, label="Top-1 removed", color="#264653")
+    ax2.bar(x, flip3, width, label="Top-3 removed", color="#2a9d8f")
+    ax2.bar(x + width, flip5, width, label="Top-5 removed", color="#e9c46a")
+
+    ax2.set_xlabel("Category", fontsize=10)
+    ax2.set_ylabel("Label Flip Rate (%)", fontsize=10)
+    ax2.set_title("Label Flip Rate by Deletion Depth", fontsize=12, fontweight="bold")
+    ax2.set_xticks(x)
+    ax2.set_xticklabels([CATEGORY_LABELS.get(c, c) for c in cats_present], rotation=30, ha="right", fontsize=8)
+    ax2.legend(fontsize=8)
+    ax2.set_ylim(0, 110)
+
+    fig.tight_layout()
+    path = os.path.join(output_dir, "chart_faithfulness_bars.png")
+    fig.savefig(path, dpi=150)
+    plt.close(fig)
+    print(f"Saved: {path}")
+
+
+def generate_charts(output_dir):
+    print("Generating charts...")
+    stability = load_stability(output_dir)
+    deletion = load_deletion(output_dir)
+    chart_jaccard(stability, output_dir)
+    chart_faithfulness(deletion, output_dir)
+    print("Done.")

lime_audit/cli.py

@@ -0,0 +1,75 @@
+"""
+CLI entry point for lime-audit.
+
+Usage:
+    lime-audit run --model distilbert/distilbert-base-uncased-finetuned-sst-2-english
+    lime-audit run --model <name> --test-set my_inputs.json --output results/
+    lime-audit report --output results/
+    lime-audit charts --output results/
+"""
+
+import argparse
+import sys
+
+from lime_audit import __version__
+
+
+DEFAULT_MODEL = "distilbert/distilbert-base-uncased-finetuned-sst-2-english"
+
+
+def cmd_run(args):
+    from lime_audit.runner import run_audit
+    output_dir = run_audit(
+        model_name=args.model,
+        test_set_path=args.test_set if args.test_set else None,
+        output_dir=args.output if args.output else None,
+    )
+    if not args.skip_report:
+        from lime_audit.analyse import analyse
+        analyse(output_dir, args.model)
+    if not args.skip_charts:
+        from lime_audit.charts import generate_charts
+        generate_charts(output_dir)
+
+
+def cmd_report(args):
+    from lime_audit.analyse import analyse
+    analyse(args.output, args.model)
+
+
+def cmd_charts(args):
+    from lime_audit.charts import generate_charts
+    generate_charts(args.output)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="lime-audit",
+        description="Audit LIME explanations for stability and faithfulness",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    run_parser = subparsers.add_parser("run", help="Run the full LIME audit")
+    run_parser.add_argument("--model", default=DEFAULT_MODEL, help="HuggingFace model name (default: distilbert-sst2)")
+    run_parser.add_argument("--test-set", default=None, help="Path to test set JSON (default: bundled 30 inputs)")
+    run_parser.add_argument("--output", default=None, help="Output directory (default: ./lime_audit_results)")
+    run_parser.add_argument("--skip-report", action="store_true", help="Skip analysis report after run")
+    run_parser.add_argument("--skip-charts", action="store_true", help="Skip chart generation after run")
+    run_parser.set_defaults(func=cmd_run)
+
+    report_parser = subparsers.add_parser("report", help="Generate analysis report from existing results")
+    report_parser.add_argument("--output", default="lime_audit_results", help="Results directory")
+    report_parser.add_argument("--model", default=DEFAULT_MODEL, help="Model name (for tokenizer mismatch)")
+    report_parser.set_defaults(func=cmd_report)
+
+    charts_parser = subparsers.add_parser("charts", help="Generate charts from existing results")
+    charts_parser.add_argument("--output", default="lime_audit_results", help="Results directory")
+    charts_parser.set_defaults(func=cmd_charts)
+
+    args = parser.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

lime_audit/config.py

@@ -0,0 +1,14 @@
+"""Default configuration for lime-audit runs."""
+
+LIME_NUM_SAMPLES = 300
+LIME_NUM_FEATURES = 10
+LIME_CLASS_NAMES = ["negative", "positive"]
+
+RANDOM_SEEDS = [42, 123, 456, 789, 1024]
+CANONICAL_SEED = 42
+
+TOP_K_FOR_JACCARD = 5
+
+STABILITY_THRESHOLD_JACCARD = 0.6
+STABILITY_THRESHOLD_KENDALL = 0.5
+FAITHFULNESS_THRESHOLD_DIRECTION = 0.7

lime_audit/default_test_set.json

@@ -0,0 +1,36 @@
+{
+  "version": "1.0",
+  "description": "Default test set for LIME attribution audit. 30 inputs across 6 categories.",
+  "inputs": [
+    {"id": 1, "category": "negation_minimal_pairs", "text": "I am not entirely unhappy with this result."},
+    {"id": 2, "category": "negation_minimal_pairs", "text": "This is not good."},
+    {"id": 3, "category": "negation_minimal_pairs", "text": "This is good."},
+    {"id": 4, "category": "negation_minimal_pairs", "text": "I would not recommend this to anyone."},
+    {"id": 5, "category": "negation_minimal_pairs", "text": "Nothing about this experience was disappointing."},
+    {"id": 6, "category": "lexical_shortcuts", "text": "The movie was terrible but I loved every minute of it."},
+    {"id": 7, "category": "lexical_shortcuts", "text": "Excellent packaging, but the product itself is useless."},
+    {"id": 8, "category": "lexical_shortcuts", "text": "I love how badly this was designed."},
+    {"id": 9, "category": "lexical_shortcuts", "text": "Fine."},
+    {"id": 10, "category": "lexical_shortcuts", "text": "Absolutely phenomenal waste of my time."},
+    {"id": 11, "category": "ambiguity", "text": "It was okay, I guess."},
+    {"id": 12, "category": "ambiguity", "text": "That is one way to do it."},
+    {"id": 13, "category": "ambiguity", "text": "I have seen worse."},
+    {"id": 14, "category": "ambiguity", "text": "The service was exactly what I expected."},
+    {"id": 15, "category": "ambiguity", "text": "It is what it is."},
+    {"id": 16, "category": "distribution_style_shift", "text": "ngl this slaps fr fr no cap"},
+    {"id": 17, "category": "distribution_style_shift", "text": "The patient presents with acute exacerbation of chronic symptoms."},
+    {"id": 18, "category": "distribution_style_shift", "text": "Revenue increased 12% YoY driven by strong Q4 performance."},
+    {"id": 19, "category": "distribution_style_shift", "text": "lmaooo this is so bad its good"},
+    {"id": 20, "category": "distribution_style_shift", "text": "Per the attached memo, please advise on next steps."},
+    {"id": 21, "category": "strong_baselines", "text": "This is the best product I have ever purchased."},
+    {"id": 22, "category": "strong_baselines", "text": "Terrible experience, complete waste of money."},
+    {"id": 23, "category": "strong_baselines", "text": "I absolutely love everything about this."},
+    {"id": 24, "category": "strong_baselines", "text": "This is awful and I regret buying it."},
+    {"id": 25, "category": "strong_baselines", "text": "The quality exceeded all my expectations and I am thrilled."},
+    {"id": 26, "category": "edge_cases", "text": "good good good good good"},
+    {"id": 27, "category": "edge_cases", "text": "The the the the movie was great."},
+    {"id": 28, "category": "edge_cases", "text": "I think that maybe it could possibly be somewhat decent."},
+    {"id": 29, "category": "edge_cases", "text": "Amazing! Horrible! Amazing! Horrible!"},
+    {"id": 30, "category": "edge_cases", "text": " "}
+  ]
+}

lime_audit/metrics.py

@@ -0,0 +1,96 @@
+"""Stability and faithfulness metrics for LIME audit."""
+
+import numpy as np
+from scipy import stats
+from itertools import combinations
+from transformers import AutoTokenizer
+
+
+def jaccard_top_k(tokens_a: list[str], tokens_b: list[str], k: int = 5) -> float:
+    set_a = set(tokens_a[:k])
+    set_b = set(tokens_b[:k])
+    if not set_a and not set_b:
+        return 1.0
+    if not set_a or not set_b:
+        return 0.0
+    return len(set_a & set_b) / len(set_a | set_b)
+
+
+def kendall_tau_top_k(
+    ranking_a: list[tuple[str, float]],
+    ranking_b: list[tuple[str, float]],
+) -> float:
+    tokens_a = {t: i for i, (t, _) in enumerate(ranking_a)}
+    tokens_b = {t: i for i, (t, _) in enumerate(ranking_b)}
+    common = sorted(set(tokens_a.keys()) & set(tokens_b.keys()))
+    if len(common) < 2:
+        return float("nan")
+    ranks_a = [tokens_a[t] for t in common]
+    ranks_b = [tokens_b[t] for t in common]
+    tau, _ = stats.kendalltau(ranks_a, ranks_b)
+    return tau
+
+
+def confidence_delta(original_pos: float, modified_pos: float) -> float:
+    return modified_pos - original_pos
+
+
+def faithfulness_direction_correct(token_weight: float, conf_delta: float) -> bool:
+    if abs(token_weight) < 1e-6 or abs(conf_delta) < 1e-6:
+        return True
+    return (token_weight > 0 and conf_delta < 0) or (token_weight < 0 and conf_delta > 0)
+
+
+def bootstrap_ci(
+    values: list[float],
+    n_bootstrap: int = 10000,
+    alpha: float = 0.05,
+    rng_seed: int = 42,
+) -> tuple[float, float]:
+    rng = np.random.RandomState(rng_seed)
+    arr = np.array(values)
+    boot_means = np.array([
+        np.mean(rng.choice(arr, size=len(arr), replace=True))
+        for _ in range(n_bootstrap)
+    ])
+    lower = float(np.percentile(boot_means, 100 * alpha / 2))
+    upper = float(np.percentile(boot_means, 100 * (1 - alpha / 2)))
+    return lower, upper
+
+
+def count_tokenizer_mismatch(text: str, model_name: str) -> dict:
+    lime_tokens = text.split()
+    tokenizer = AutoTokenizer.from_pretrained(model_name)
+    wp_tokens = tokenizer.tokenize(text)
+    return {
+        "lime_token_count": len(lime_tokens),
+        "wordpiece_token_count": len(wp_tokens),
+        "token_mismatch": len(wp_tokens) - len(lime_tokens),
+    }
+
+
+def compute_pairwise_stability(
+    seed_results: dict[int, list[tuple[str, float]]],
+    k: int = 5,
+) -> dict:
+    seeds = sorted(seed_results.keys())
+    jaccards = []
+    taus = []
+
+    for s1, s2 in combinations(seeds, 2):
+        tokens_a = [t for t, _ in seed_results[s1]]
+        tokens_b = [t for t, _ in seed_results[s2]]
+        jaccards.append(jaccard_top_k(tokens_a, tokens_b, k))
+        taus.append(kendall_tau_top_k(seed_results[s1], seed_results[s2]))
+
+    top1_tokens = [seed_results[s][0][0] if seed_results[s] else "" for s in seeds]
+
+    return {
+        "mean_jaccard": float(np.mean(jaccards)),
+        "min_jaccard": float(np.min(jaccards)),
+        "mean_kendall_tau": float(np.nanmean(taus)),
+        "min_kendall_tau": float(np.nanmin(taus)) if not all(np.isnan(taus)) else float("nan"),
+        "top1_unanimous": len(set(top1_tokens)) == 1 and top1_tokens[0] != "",
+        "all_jaccards": jaccards,
+        "all_taus": taus,
+    }

lime_audit/runner.py

@@ -0,0 +1,297 @@
+"""
+LIME Audit Runner - runs LIME on test inputs, measures stability and faithfulness.
+"""
+
+import csv
+import json
+import os
+import platform
+import sys
+import time
+from datetime import datetime, timezone
+
+import numpy as np
+from lime.lime_text import LimeTextExplainer
+from transformers import pipeline as hf_pipeline
+
+from lime_audit.config import (
+    CANONICAL_SEED,
+    LIME_CLASS_NAMES,
+    LIME_NUM_FEATURES,
+    LIME_NUM_SAMPLES,
+    RANDOM_SEEDS,
+)
+from lime_audit.metrics import faithfulness_direction_correct
+
+
+def _get_default_test_set_path():
+    return os.path.join(os.path.dirname(__file__), "default_test_set.json")
+
+
+def load_test_set(path: str) -> list[dict]:
+    with open(path, "r", encoding="utf-8") as f:
+        data = json.load(f)
+    return data["inputs"]
+
+
+def load_model(model_name: str):
+    print(f"Loading model: {model_name}")
+    model = hf_pipeline("text-classification", model=model_name, top_k=None)
+    print("Model loaded.")
+    return model
+
+
+def get_positive_score(pipeline_output: list) -> float:
+    for item in pipeline_output[0]:
+        if "pos" in item["label"].lower():
+            return item["score"]
+    return 1.0 - max(item["score"] for item in pipeline_output[0])
+
+
+def make_predict_fn(model):
+    def predict_proba(texts: list[str]) -> np.ndarray:
+        results = []
+        for text in texts:
+            output = model(text, truncation=True, max_length=512)
+            pos = get_positive_score(output)
+            results.append([1.0 - pos, pos])
+        return np.array(results)
+    return predict_proba
+
+
+def run_lime_single(text, predict_fn, seed, num_samples=LIME_NUM_SAMPLES, num_features=LIME_NUM_FEATURES):
+    np.random.seed(seed)
+    explainer = LimeTextExplainer(class_names=LIME_CLASS_NAMES, random_state=seed)
+    explanation = explainer.explain_instance(text, predict_fn, num_features=num_features, num_samples=num_samples)
+    token_weights = explanation.as_list()
+    sorted_by_abs = sorted(token_weights, key=lambda x: abs(x[1]), reverse=True)
+    return {"tokens": sorted_by_abs, "lime_score": explanation.score, "intercept": explanation.intercept.get(1, 0.0)}
+
+
+def run_deletion_test(text, top_token, predict_fn):
+    words = text.split()
+    masked_words = [w for w in words if w != top_token]
+    if not masked_words or masked_words == words:
+        for i, w in enumerate(words):
+            if top_token.lower() in w.lower():
+                masked_words = words[:i] + words[i + 1:]
+                break
+    if not masked_words:
+        return {"modified_text": "", "modified_label": "error", "modified_positive_score": float("nan")}
+    masked_text = " ".join(masked_words)
+    proba = predict_fn([masked_text])
+    modified_pos = float(proba[0][1])
+    return {"modified_text": masked_text, "modified_label": "positive" if modified_pos >= 0.5 else "negative", "modified_positive_score": modified_pos}
+
+
+def run_deletion_topk(text, top_tokens, predict_fn):
+    words = text.split()
+    token_set = set(top_tokens)
+    masked_words = [w for w in words if w not in token_set]
+    if not masked_words:
+        return {"modified_text": "", "modified_label": "error", "modified_positive_score": float("nan")}
+    masked_text = " ".join(masked_words)
+    proba = predict_fn([masked_text])
+    modified_pos = float(proba[0][1])
+    return {"modified_text": masked_text, "modified_label": "positive" if modified_pos >= 0.5 else "negative", "modified_positive_score": modified_pos}
+
+
+def get_environment_info(model_name):
+    import lime
+    import scipy
+    import sklearn
+    import torch
+    import transformers
+    return {
+        "model": model_name,
+        "lime_version": getattr(lime, "__version__", "0.2.0.1"),
+        "torch_version": torch.__version__,
+        "transformers_version": transformers.__version__,
+        "numpy_version": np.__version__,
+        "scipy_version": scipy.__version__,
+        "sklearn_version": sklearn.__version__,
+        "python_version": sys.version,
+        "platform": platform.platform(),
+        "seeds": RANDOM_SEEDS,
+        "num_samples": LIME_NUM_SAMPLES,
+        "num_features": LIME_NUM_FEATURES,
+    }
+
+
+RAW_FIELDNAMES = (
+    ["input_id", "category", "text", "seed", "base_label", "base_confidence", "base_positive_score"]
+    + [f"token_{i}" for i in range(1, LIME_NUM_FEATURES + 1)]
+    + [f"weight_{i}" for i in range(1, LIME_NUM_FEATURES + 1)]
+    + ["lime_score", "duration_ms"]
+)
+
+DELETION_FIELDNAMES = [
+    "input_id", "category", "text", "status",
+    "removed_token", "token_lime_weight",
+    "original_label", "original_positive_score",
+    "modified_label", "modified_positive_score",
+    "confidence_delta", "label_flipped", "direction_correct",
+    "removed_top3", "delta_top3", "flipped_top3",
+    "removed_top5", "delta_top5", "flipped_top5",
+]
+
+
+def run_audit(model_name: str, test_set_path: str = None, output_dir: str = None):
+    if test_set_path is None:
+        test_set_path = _get_default_test_set_path()
+    if output_dir is None:
+        output_dir = os.path.join(os.getcwd(), "lime_audit_results")
+
+    os.makedirs(output_dir, exist_ok=True)
+    raw_csv = os.path.join(output_dir, "raw_attributions.csv")
+    del_csv = os.path.join(output_dir, "deletion_faithfulness.csv")
+
+    inputs = load_test_set(test_set_path)
+    print(f"Loaded {len(inputs)} inputs")
+
+    model = load_model(model_name)
+    predict_fn = make_predict_fn(model)
+    env_info = get_environment_info(model_name)
+
+    start_total = time.perf_counter()
+    skipped_inputs = []
+    canonical_results = {}
+
+    with open(raw_csv, "w", newline="", encoding="utf-8") as raw_f:
+        raw_writer = csv.DictWriter(raw_f, fieldnames=RAW_FIELDNAMES)
+        raw_writer.writeheader()
+
+        for inp in inputs:
+            input_id = inp["id"]
+            text = inp["text"]
+            category = inp.get("category", "uncategorized")
+
+            if not text.strip():
+                skipped_inputs.append({"input_id": input_id, "category": category, "reason": "empty_or_whitespace"})
+                print(f"  [{input_id}] SKIP empty input")
+                continue
+
+            base_proba = predict_fn([text])
+            base_pos = float(base_proba[0][1])
+            base_label = "positive" if base_pos >= 0.5 else "negative"
+            base_conf = base_pos if base_label == "positive" else 1.0 - base_pos
+            print(f"  [{input_id}] {base_label} ({base_conf:.4f})")
+
+            for seed in RANDOM_SEEDS:
+                start_call = time.perf_counter()
+                try:
+                    result = run_lime_single(text, predict_fn, seed)
+                except Exception as e:
+                    print(f"    Seed {seed}: ERROR {e}")
+                    continue
+
+                duration_ms = round((time.perf_counter() - start_call) * 1000)
+                tokens = result["tokens"]
+
+                row = {
+                    "input_id": input_id, "category": category, "text": text,
+                    "seed": seed, "base_label": base_label,
+                    "base_confidence": round(base_conf, 6),
+                    "base_positive_score": round(base_pos, 6),
+                    "lime_score": round(result["lime_score"], 6),
+                    "duration_ms": duration_ms,
+                }
+                for i in range(LIME_NUM_FEATURES):
+                    if i < len(tokens):
+                        row[f"token_{i + 1}"] = tokens[i][0]
+                        row[f"weight_{i + 1}"] = round(tokens[i][1], 6)
+                    else:
+                        row[f"token_{i + 1}"] = ""
+                        row[f"weight_{i + 1}"] = 0.0
+                raw_writer.writerow(row)
+                raw_f.flush()
+
+                if seed == CANONICAL_SEED:
+                    canonical_results[input_id] = {
+                        "tokens": tokens, "base_label": base_label,
+                        "base_pos": base_pos, "base_conf": base_conf,
+                    }
+
+    print(f"\nRunning deletion faithfulness tests...")
+
+    with open(del_csv, "w", newline="", encoding="utf-8") as del_f:
+        del_writer = csv.DictWriter(del_f, fieldnames=DELETION_FIELDNAMES)
+        del_writer.writeheader()
+
+        for inp in inputs:
+            input_id = inp["id"]
+            text = inp["text"]
+            category = inp.get("category", "uncategorized")
+
+            if not text.strip():
+                row = {"input_id": input_id, "category": category, "text": repr(text), "status": "skipped_empty"}
+                for field in DELETION_FIELDNAMES:
+                    row.setdefault(field, "")
+                del_writer.writerow(row)
+                del_f.flush()
+                continue
+
+            if input_id not in canonical_results:
+                continue
+
+            canon = canonical_results[input_id]
+            if not canon["tokens"]:
+                continue
+
+            top_token = canon["tokens"][0][0]
+            top_weight = canon["tokens"][0][1]
+            deletion = run_deletion_test(text, top_token, predict_fn)
+
+            if deletion["modified_label"] == "error":
+                continue
+
+            delta = deletion["modified_positive_score"] - canon["base_pos"]
+            flipped = deletion["modified_label"] != canon["base_label"]
+            dir_correct = faithfulness_direction_correct(top_weight, delta)
+
+            top3_tokens = [t for t, _ in canon["tokens"][:3]]
+            del3 = run_deletion_topk(text, top3_tokens, predict_fn)
+            delta3 = flipped3 = ""
+            if del3["modified_label"] != "error":
+                delta3 = round(del3["modified_positive_score"] - canon["base_pos"], 6)
+                flipped3 = del3["modified_label"] != canon["base_label"]
+
+            top5_tokens = [t for t, _ in canon["tokens"][:5]]
+            del5 = run_deletion_topk(text, top5_tokens, predict_fn)
+            delta5 = flipped5 = ""
+            if del5["modified_label"] != "error":
+                delta5 = round(del5["modified_positive_score"] - canon["base_pos"], 6)
+                flipped5 = del5["modified_label"] != canon["base_label"]
+
+            row = {
+                "input_id": input_id, "category": category, "text": text,
+                "status": "tested",
+                "removed_token": top_token,
+                "token_lime_weight": round(top_weight, 6),
+                "original_label": canon["base_label"],
+                "original_positive_score": round(canon["base_pos"], 6),
+                "modified_label": deletion["modified_label"],
+                "modified_positive_score": round(deletion["modified_positive_score"], 6),
+                "confidence_delta": round(delta, 6),
+                "label_flipped": flipped,
+                "direction_correct": dir_correct,
+                "removed_top3": "|".join(top3_tokens),
+                "delta_top3": delta3, "flipped_top3": flipped3,
+                "removed_top5": "|".join(top5_tokens),
+                "delta_top5": delta5, "flipped_top5": flipped5,
+            }
+            del_writer.writerow(row)
+            del_f.flush()
+
+    total_time = time.perf_counter() - start_total
+
+    env_info["run_timestamp"] = datetime.now(timezone.utc).isoformat()
+    env_info["total_duration_seconds"] = round(total_time, 1)
+    env_info["skipped_inputs"] = skipped_inputs
+    env_path = os.path.join(output_dir, "environment.json")
+    with open(env_path, "w", encoding="utf-8") as f:
+        json.dump(env_info, f, indent=2)
+
+    print(f"\nAudit complete in {total_time:.1f}s ({total_time / 60:.1f} min)")
+    print(f"Results in: {output_dir}")
+    return output_dir

lime_audit-0.1.0.dist-info/METADATA

@@ -0,0 +1,248 @@
+Metadata-Version: 2.5
+Name: lime-audit
+Version: 0.1.0
+Summary: Audit LIME explanations for stability and faithfulness on any HuggingFace text classifier
+Project-URL: Homepage, https://github.com/parshvi1508/XAI_Forensic
+Project-URL: Documentation, https://github.com/parshvi1508/XAI_Forensic#readme
+Project-URL: Issues, https://github.com/parshvi1508/XAI_Forensic/issues
+Author-email: Parshvi Jain <parshvijain1508@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: LIME,NLP,XAI,audit,explainability,transformers
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: lime>=0.2
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: numpy>=1.24
+Requires-Dist: scikit-learn>=1.2
+Requires-Dist: scipy>=1.10
+Requires-Dist: torch>=2.0
+Requires-Dist: transformers>=4.30
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# XAI Forensics
+
+A diagnostic tool for evaluating when LIME token attributions are trustworthy on transformer sentiment classifiers. Runs three independent forensic checks (attribution stability, counterfactual faithfulness, cross-model agreement) and validates results against a 30-input pre-registered audit.
+
+**Key finding:** high-confidence predictions (>95%) produce the least stable attributions (mean Jaccard 0.46 on strong baselines), while lexical-shortcut inputs are perfectly faithful (Jaccard 1.0, 100% flip rate). This tool shows you when LIME is signal vs. noise.
+
+Sentiment classification is the controlled test task. The project evaluates the explanation method, not the classifier output.
+
+
+
+## Live Demo
+
+| Component | Link |
+|-----------|------|
+| Frontend | [xai-forensic.vercel.app](https://xai-forensic.vercel.app/) |
+| Backend API | [jainparshvi-xai-forensics-backend.hf.space](https://jainparshvi-xai-forensics-backend.hf.space) |
+| API Docs (Swagger) | [/docs](https://jainparshvi-xai-forensics-backend.hf.space/docs) |
+
+**Demo input:** `I am not entirely unhappy with this result.`
+
+This sentence contains a double negation that causes the two models to genuinely disagree.
+
+> The backend runs on Hugging Face Spaces free tier. If the Space has been idle, the first request triggers a cold start (30-60 seconds) while models download. Subsequent requests are faster.
+
+
+
+![alt text](public/image.png)
+![alt text](public/image-1.png)
+![alt text](public/image-2.png)
+![alt text](public/image-3.png)
+![alt text](public/image-4.png)
+![alt text](public/image-5.png)
+
+## What This Does
+
+XAI Forensics runs three independent diagnostic checks on any short English text:
+
+1. **WHY (Attribution Stability)** - Tests whether LIME can produce a stable, reproducible token ranking for a given prediction. Seeds the random state for deterministic output.
+2. **FLIP (Counterfactual Faithfulness)** - Tests whether the tokens LIME identifies as important are actually causally influential. Removes the top-attributed word and measures the real confidence shift.
+3. **DISAGREE (Cross-Model Consistency)** - Tests whether the prediction itself is domain-stable enough to warrant attribution analysis. Compares DistilBERT-SST2 against Twitter-RoBERTa.
+
+Each check targets a different failure mode of LIME: instability under re-sampling, unfaithfulness to the model's actual reasoning, and domain sensitivity of the underlying prediction.
+
+### Audit Results
+
+A pre-registered 30-input audit (5 seeds each, 150 total LIME runs) found:
+- Overall mean Jaccard stability: **0.81** (passes 0.6 threshold)
+- Deletion faithfulness direction correct: **89.3%** (passes 70% threshold)
+- Strong baselines category (high confidence): **Jaccard 0.67** (lowest category, driven by redundant evidence)
+- Lexical shortcuts category: **100% label flip rate** (highest faithfulness)
+
+Full interactive results available at [/audit](https://xai-forensic.vercel.app/audit).
+
+## How It Works
+
+### WHY: LIME Token Attribution
+
+Uses [LIME](https://arxiv.org/abs/1602.04938) (Ribeiro et al., 2016) for model-agnostic local explanations. LIME generates perturbed versions of the input text, reruns the classifier on each perturbation, and fits a local linear model to estimate which tokens most influenced the prediction.
+
+- Runs 300 perturbation samples per explanation
+- Returns the top 10 tokens with signed weights (positive = pushes toward positive class)
+- SHAP was considered and rejected: slower for transformers, expensive on free-tier CPU
+- Attention weights were rejected as explanations per Jain and Wallace (2019)
+
+### FLIP: Counterfactual Word Removal
+
+Removes each word one at a time, reruns inference, and finds the word whose removal causes the largest confidence shift. Shows the full before-and-after comparison: original label, modified label, confidence delta, and whether the verdict changed.
+
+- Greedy O(n) search over words in the input
+- Deterministic, no generation model required
+- Word removal can create ungrammatical text (documented limitation)
+- Does not always flip the label on highly confident predictions
+
+### DISAGREE: Dual-Model Divergence
+
+Runs the same text through both models and computes the absolute difference in their positive-class confidence scores. A high divergence score means the models have different views on the same text, which reveals linguistic ambiguity across training domains.
+
+- Divergence = abs(positive_score_A - positive_score_B)
+- This is an interpretable confidence delta, not a formal divergence metric like KL divergence
+- KL divergence was considered and rejected: harder to interpret for non-technical audiences
+
+
+## Models Used
+
+| Model | Training Data | Strength |
+|-------|---------------|----------|
+| [distilbert-base-uncased-finetuned-sst-2-english](https://huggingface.co/distilbert-base-uncased-finetuned-sst-2-english) | SST-2 movie reviews | Formal, structured English |
+| [cardiffnlp/twitter-roberta-base-sentiment-latest](https://huggingface.co/cardiffnlp/twitter-roberta-base-sentiment-latest) | 124M tweets | Sarcasm, slang, informal tone |
+
+These two models are chosen because they genuinely disagree on informal or ambiguous language. DistilBERT expects clean, formal text. Twitter-RoBERTa handles internet language better. This domain mismatch makes the DISAGREE panel meaningful rather than artificial.
+
+## Architecture
+
+```
+Frontend (Vercel)              Backend (HF Spaces Docker)
+Next.js + Tailwind             FastAPI + PyTorch
+       |                              |
+       |--- POST /why   ------------->|--- LIME (300 perturbations)
+       |--- POST /flip  ------------->|--- Greedy word removal
+       |--- POST /disagree ---------->|--- Dual model inference
+       |                              |
+       |<---- JSON responses ---------|
+```
+
+- Frontend and backend are fully decoupled
+- All endpoints accept `{"text": "..."}` and return structured JSON
+- Frontend calls all three endpoints in parallel using `Promise.allSettled`
+- Models load once at container startup, not per request
+
+## Run it Locally
+
+### Backend
+
+```bash
+cd backend
+python -m venv venv
+source venv/bin/activate  # Windows: venv\Scripts\activate
+pip install -r requirements.txt
+uvicorn main:app --reload --port 8000
+```
+
+First run downloads models (~500MB total). Subsequent starts use cached weights.
+
+### Frontend
+
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+Frontend runs at `http://localhost:3000` and calls the backend at `http://localhost:8000` by default. To change the backend URL, set `NEXT_PUBLIC_API_URL` in `frontend/.env.local`.
+
+
+## API Endpoints
+
+All endpoints accept POST with `Content-Type: application/json` and a body of `{"text": "your input"}`.
+
+| Endpoint | Returns |
+|----------|---------|
+| `POST /why` | Predicted label, confidence, and top 10 token weights from LIME |
+| `POST /flip` | Original and modified labels, removed word, confidence delta, verdict changed status |
+| `POST /disagree` | Both model predictions, divergence score, agreement status |
+| `GET /` | Health check: `{"status": "ok"}` |
+| `GET /docs` | Interactive Swagger API documentation |
+
+Input is limited to 1000 characters. Requests with longer text return HTTP 400.
+
+
+## Latency Notes
+
+| Endpoint | Approx. CPU time | Why |
+|----------|-------------------|-----|
+| `/why` | 15-45 seconds | LIME runs 300 model inference calls per explanation |
+| `/flip` | 2-10 seconds | One model call per word in the input |
+| `/disagree` | Under 1 second | Two forward passes |
+
+LIME is the main latency source. CPU inference is used because deployment is on the Hugging Face free tier, which does not guarantee GPU availability. This is acceptable for a demo tool with short text inputs.
+
+
+## Latency Benchmark
+
+The backend runs on Hugging Face Spaces free-tier CPU. The table below reports median endpoint runtime across 3 runs after one warmup request. Timings are approximate because free-tier CPU performance varies.
+
+| Words | WHY median | FLIP median | DISAGREE median |
+|---:|---:|---:|---:|
+| 5 | 4.5s | 414ms | 98ms |
+| 10 | 5.8s | 270ms | 75ms |
+| 20 | 6.1s | 475ms | 72ms |
+| 50 | 8.3s | 4.2s | 104ms |
+
+WHY is slowest because LIME generates perturbed versions of the input and reruns model inference many times. FLIP scales with word count because it removes candidate words one at a time and reruns inference. DISAGREE is fastest because it only runs two model forward passes.
+
+The benchmark can be reproduced with `scripts/benchmark_latency.py`.
+
+
+## Security and Cost
+
+- No paid APIs. Both models are public Hugging Face models.
+- No database. Nothing is stored.
+- No authentication. This is a public demo tool.
+- No user data is collected, logged, or persisted.
+- CORS allows all origins (appropriate for a public demo with no sensitive operations).
+- Input capped at 1000 characters to prevent LIME timeouts on free-tier CPU.
+
+
+## Known Behavior and Limitations
+
+Single-word inputs are not ideal for this tool. LIME works by perturbing parts of the input and observing prediction changes. With only one word, there is very little structure to perturb, so the explanation can be unstable or uninformative. In testing, short inputs such as "Fine." can produce domain-sensitive behavior because different models interpret minimal context differently.
+
+Highly confident predictions may not flip after one-word removal. For example, strongly positive sentences such as "I absolutely love this, it is the best thing ever." often remain positive after removing one word. This does not mean every word is irrelevant. It means the model found enough evidence across the sentence that removing one token did not change the final verdict.
+
+Counterfactual removal can create ungrammatical text because the method deletes a word rather than rewriting the sentence. This is a deliberate MVP tradeoff. The FLIP panel is a fragility test, not a full natural-language counterfactual generator. For example, removing a key word from "I am not entirely unhappy with this result." can flip the verdict, but the modified sentence may not always be natural English.
+
+Additional limitations:
+
+- LIME explanation takes 15-45 seconds on CPU for short text
+- Input limited to 1000 characters
+- Hugging Face free tier sleeps after inactivity; first request after sleep has a 30-60 second cold start
+- Only tested on English text
+- Sentiment-specific; adapting to other tasks would require different models and possibly different XAI methods
+
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Backend | Python, FastAPI, PyTorch, Hugging Face Transformers, LIME |
+| Frontend | Next.js, React, Tailwind CSS |
+| Backend deployment | Hugging Face Spaces (Docker) |
+| Frontend deployment | Vercel |
+| ML models | DistilBERT-SST2, Twitter-RoBERTa |
+| Infrastructure cost | Zero (free tier only) |
+
+
+## License
+
+MIT

lime_audit-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+lime_audit/__init__.py,sha256=9dECzSKe22L8jLzar7wgc03KG7cIKsnTvmmUDL3LNbo,97
+lime_audit/analyse.py,sha256=RxBNDNkq6uV8mUj1wJzNtsghSViYIpE9LZtNGXjNeDw,13700
+lime_audit/charts.py,sha256=Oap1ERywe_w47cMYqtBoLQzG70fJXg6TnN7aPmv_azk,7207
+lime_audit/cli.py,sha256=ATwCQTTB_XdwAQ_7JiaOgz2YZyS2w9E14axIaMIqZyQ,2835
+lime_audit/config.py,sha256=JudPbPku6R6eUuMGPcn4yGSzCwhQFHVEbwBsnZinHeo,333
+lime_audit/metrics.py,sha256=YuVBzuMuY1CO1HEXW6YWIlzQchUQ61KM24OOwLpS7Ec,3186
+lime_audit/runner.py,sha256=Q1KII97vRCNc0-N_oWN41jwHUdZGFn4Ed3U7t3-6M_s,11558
+lime_audit/default_test_set.json,sha256=MihT_tWrudFytT1AuU94s4_ljZ0lpu7UzhgakKXJYGQ,3014
+lime_audit-0.1.0.dist-info/METADATA,sha256=e5ZrnkyDt6vOoiQ6_8A3UP36nyKnmdmlyNMDP-ync3M,12035
+lime_audit-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+lime_audit-0.1.0.dist-info/entry_points.txt,sha256=_LAbstv2k2DyUBcMmP4CM_wi39PybvK4V-r7gHJLCuU,51
+lime_audit-0.1.0.dist-info/licenses/LICENSE,sha256=yKv5VwH3OO6SDwLig_aibiZylHT-PATHcRtxED9_Mz8,1069
+lime_audit-0.1.0.dist-info/RECORD,,

lime_audit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

lime_audit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+lime-audit = lime_audit.cli:main

lime_audit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Parshvi Jain
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.