Financial Fraud Detection via Explainable AI Pipeline

This repository contains a reproducible, human-in-the-loop benchmark for auditing how multiple language models explain fraud vs. no-fraud decisions on real SEC EDGAR filings. The focus is no longer on generic model training; instead we provide:

1. Dataset preparation that samples balanced excerpts from EDGAR statements.
2. Multi-model inference + verification that runs FinBERT variants (and future API models) while checking every prediction against the ground truth.
3. Rich explainability artifacts (SHAP, LIME, attention, permutation feature importance, counterfactual search) saved as JSON + composite PNGs.
4. Blind human-evaluation surveys—single-file HTML packets with embedded visualizations so reviewers judge explanations without seeing labels.

---

Key Research Questions

1. Which explanation style helps humans most when deciding whether a disclosure is fraudulent?
2. How do legacy vs. modern FinBERT-class models differ in both accuracy and explanation quality?
3. Can the verification layer + survey feedback highlight when models over-trust spurious cues?

---

Repository Layout

├── data_ingestion/           # EDGAR parsing & dataset utilities
├── models/                   # FinBERT classifiers + shared prompt templates + CV tooling
├── scripts/                  # Small CLIs (e.g., hold-out splitter)
├── xai/                      # Comparator, explanation runner, visualization helpers
├── evaluation/               # Survey template + HTML generator
├── archive/legacy_gpt4/      # Archived GPT‑4 comparison framework + analyzer
├── explanations/             # (Generated) per-model artifacts: sample_i.json/.png, metrics, reports
├── results/                  # Optional analysis outputs / notebooks
├── research_proposal.md      # Living design document for the study
└── README.md                 # You are here

Legacy training notebooks and the original LLM comparison framework live under archive/ so the main root stays focused on the XAI experiment.

---

Pipeline at a Glance

1. Dataset Prep – python evaluation/create_evaluation_dataset.py

   • Draws a stratified sample (default 10 fraud / 10 non-fraud) from real_edgar_data/real_edgar_financial_statements.csv.
   • Output: evaluation_dataset.csv

2. FinBERT Fine-tuning (CV) – python -m models.finbert_finetune_cv

   • Stratified K-fold CV with class-weighted trainer, partial unfreezing, and full metrics per fold.
   • Produces checkpoints under finbert_finetune_weighted*/fold_<k> plus cv_metrics.csv & cv_predictions.csv.

3. Hold-out Split (optional) – python scripts/create_holdout.py

   • Carves out 30 samples (stratified) for unbiased XAI evaluation while leaving the remainder for CV.
   • Outputs evaluation_dataset_cv.csv + evaluation_holdout.csv.

4. Explanation Generation – python xai/generate_explanations.py

   • Iterates over MODEL_CONFIGS (FinBERT fine-tuned checkpoints by default).
   • Logs prediction correctness per sample (verification layer) and aggregates accuracy/precision/recall/F1 + confusion matrix counts in both per-model JSON and explanations/model_metrics_summary.csv.
   • Saves explanations to explanations/<model_id>/sample_{i}.json/.png.

5. Blind Survey Creation – python evaluation/generate_survey.py

   • For each model folder inside explanations/, randomly selects ~10 samples, base64-embeds the visualization, and writes a self-contained HTML file (surveys/xai_survey_<model_id>.html).
   • Each card asks participants to make a fraud/no-fraud decision, rate confidence, score clarity/actionability/financial relevance, describe evidence, and state trust delta—without revealing the true label.

6. Human Evaluation & Analysis

   • Distribute HTML packets (per model or combined if desired).
   • Compare responses against verification_report.csv and explanation metadata to reason about human vs. model alignment.

---

Installation

python -m venv xai_env               # or your preferred env name
# PowerShell
xai_env\Scripts\Activate.ps1
pip install -r requirements_xai.txt

If you plan to run any API models (e.g., GPT-4o or Llama 3.1 70B via a hosted endpoint), set the corresponding credentials via environment variables before executing the explanation script.

---

Running the End-to-End Flow

# 0. (Optional) Recreate the hold-out split
python scripts/create_holdout.py \
  --dataset evaluation_dataset.csv \
  --holdout-size 30

# 1. Run FinBERT CV on the training portion
python -m models.finbert_finetune_cv \
  --dataset evaluation_dataset_cv.csv \
  --output-dir finbert_finetune_weighted_cv130 \
  --freeze-base --train-last-n-layers 6 \
  --class-weight-no-fraud 1.0 \
  --class-weight-fraud 3.0

# 2. Generate explanations + surveys on the hold-out set
python pipeline.py \
  --skip-dataset \
  --dataset-output evaluation_holdout.csv \
  --explanations-dir explanations_holdout_fold2 \
  --samples-per-class 200 \
  --survey-sample-count 10

Artifacts you should see:

explanations/
├── finbert_base/                # points to the best CV fold (e.g., finbert_finetune_weighted/fold_2)
│   ├── sample_0.json
│   ├── sample_0.png
│   ├── ...
│   ├── verification_report.csv
│   └── metrics.json
├── verification_report_all_models.csv
└── model_metrics_summary.csv

surveys/
└── xai_survey_finbert_base.html

---

FinBERT Fine-tuning + Hold-out Evaluation

Step	Command / Script	Notes
CV fine-tune	python -m models.finbert_finetune_cv	Handles stratified folds, class weights, partial unfreezing, metrics CSV/JSON.
Hold-out creation	python scripts/create_holdout.py	Stratified 30-sample set (15/15) for unbiased explanation review.
Pipeline run	python pipeline.py --skip-dataset --dataset-output evaluation_holdout.csv ...	Loads the best CV checkpoint (configured in xai/generate_explanations.py) and regenerates explanations/surveys on the hold-out samples.

By default xai/generate_explanations.py points to finbert_finetune_weighted/fold_2, the top-performing fold from the most recent CV run. Update MODEL_CONFIGS if you select a different checkpoint.

---

---

Metrics Cheat Sheet

Metric	How it is computed	Why it matters here
Accuracy	(TP + TN) / Total	Overall fraction of correct calls (fraud + no-fraud).
Precision	TP / (TP + FP)	Of the disclosures flagged as fraud, how many were actually fraud? High precision prevents overwhelming analysts with false alarms.
Recall	TP / (TP + FN)	Of the truly fraudulent disclosures, how many did we catch? High recall is critical for fraud detection coverage.
F1	Harmonic mean of precision and recall	Single score balancing false positives vs. false negatives—useful when classes are imbalanced and we cannot sacrifice one side.

These metrics appear in:

• finbert_finetune_weighted*/cv_metrics.csv for each CV fold.
• explanations_holdout_fold2/*/verification_report.csv for hold-out verification.
• README tables detailing the workflow so reviewers interpret the numbers correctly.

---

Verification Layer Highlights

• Every prediction stores is_prediction_correct, numeric confusion counts, and probabilities.
• CSV + JSON metrics let you spot regressions quickly before involving human annotators.
• Combined summaries (verification_report_all_models.csv) make cross-model comparison trivial.
• Pass --auto-survey (default) to xai/generate_explanations.py or use pipeline.py to automatically refresh HTML survey packets after explanations finish.

---

Explainability Methods

Method	Purpose
SHAP	Token-level additive contributions for local faithfulness
LIME	Interpretable surrogate model with finance-aware kernel
Attention Visualization	Layer/head averages projected onto the input tokens
Permutation Importance	Mask tokens/groups to measure probability drop
Counterfactual Search	Remove sentences/tokens until the prediction flips (TextFooler-style)

All methods are orchestrated via xai/xai_comparator.py, which also renders a unified PNG grid for survey consumption.

---

Blind Survey Template

The HTML template (evaluation/xai_survey_template.html) embeds each visualization as a base64 image so participants only need a single file. Questions per card:

1. Fraud decision (binary radio, required).
2. Confidence slider (0–100).
3. Likert ratings for Clarity, Actionability, Financial Relevance.
4. Free-text justification of the cues they used.
5. Trust delta (Higher / Lower / Unchanged).

Responses can be collected via email attachment, shared drive, Qualtrics, or any workflow that supports HTML uploads.

---

Roadmap / TODO

• Automate the dataset → explanations → survey orchestration under a single CLI entrypoint.
• Integrate GPT-4o or Llama 3.1 70B API client once access is available.
• Add combined survey mode (mixed models) for fully blind cross-model studies if needed.
• Document recommended analysis scripts for aggregating survey responses.

---

License & Contact

See LICENSE for usage terms. For questions or collaboration proposals, please open an issue or reach out directly.