shortkit-ml 0.1.0__tar.gz

shortkit_ml-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 ShortKIT-ML Team
+
+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.

shortkit_ml-0.1.0/PKG-INFO

@@ -0,0 +1,524 @@
+Metadata-Version: 2.4
+Name: shortkit-ml
+Version: 0.1.0
+Summary: ShortKIT-ML: A toolkit for detecting shortcuts and biases in embedding spaces
+Author: Sebastian Cajas, Aldo Marzullo, Sahil Kapadia, Qingpeng Kong, Filipe Santos, Alessandro Quarta, Leo Celi
+License: MIT
+Project-URL: Homepage, https://github.com/criticaldata/ShortKit-ML
+Project-URL: Documentation, https://criticaldata.github.io/ShortKit-ML/
+Project-URL: Repository, https://github.com/criticaldata/ShortKit-ML
+Project-URL: Issues, https://github.com/criticaldata/ShortKit-ML/issues
+Keywords: machine-learning,bias-detection,embeddings,fairness,shortcuts
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: <3.13,>=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<2.0.0,>=1.24.0
+Requires-Dist: pandas<3.0.0,>=2.0.0
+Requires-Dist: scikit-learn<2.0.0,>=1.3.0
+Requires-Dist: scipy<2.0.0,>=1.11.0
+Requires-Dist: statsmodels<1.0.0,>=0.14.0
+Requires-Dist: matplotlib<4.0.0,>=3.7.0
+Requires-Dist: seaborn<1.0.0,>=0.12.0
+Requires-Dist: joblib<2.0.0,>=1.3.0
+Requires-Dist: torch<2.3.0,>=2.2.0
+Requires-Dist: torchvision<0.18.0,>=0.17.0
+Requires-Dist: openpyxl<4.0.0,>=3.1.0
+Requires-Dist: gradio>=5.0.0
+Requires-Dist: plotly>=5.17.0
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: markdown>=3.5.0
+Requires-Dist: weasyprint>=60.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: pytest-xdist>=3.3.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.5.0; extra == "dev"
+Requires-Dist: pre-commit>=3.5.0; extra == "dev"
+Provides-Extra: e2e
+Requires-Dist: playwright>=1.40.0; extra == "e2e"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.5.0; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5.0; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.24.0; extra == "docs"
+Requires-Dist: pymdown-extensions>=10.0; extra == "docs"
+Provides-Extra: jupyter
+Requires-Dist: jupyter>=1.0.0; extra == "jupyter"
+Requires-Dist: ipykernel>=6.25.0; extra == "jupyter"
+Requires-Dist: nbconvert>=7.8.0; extra == "jupyter"
+Requires-Dist: ipywidgets>=8.1.0; extra == "jupyter"
+Provides-Extra: reporting
+Requires-Dist: plotly>=5.17.0; extra == "reporting"
+Requires-Dist: jinja2>=3.1.0; extra == "reporting"
+Requires-Dist: markdown>=3.5.0; extra == "reporting"
+Requires-Dist: weasyprint>=60.0; extra == "reporting"
+Requires-Dist: openpyxl>=3.1.0; extra == "reporting"
+Provides-Extra: dashboard
+Requires-Dist: gradio>=5.0.0; extra == "dashboard"
+Provides-Extra: hf
+Requires-Dist: transformers>=4.39.0; extra == "hf"
+Provides-Extra: vae
+Requires-Dist: torch<2.3.0,>=2.2.0; extra == "vae"
+Requires-Dist: torchvision<0.18.0,>=0.17.0; extra == "vae"
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == "mcp"
+Provides-Extra: all
+Requires-Dist: black>=23.0.0; extra == "all"
+Requires-Dist: mcp>=1.0.0; extra == "all"
+Requires-Dist: gradio>=5.0.0; extra == "all"
+Requires-Dist: ipykernel>=6.25.0; extra == "all"
+Requires-Dist: ipywidgets>=8.1.0; extra == "all"
+Requires-Dist: jinja2>=3.1.0; extra == "all"
+Requires-Dist: markdown>=3.5.0; extra == "all"
+Requires-Dist: mypy>=1.5.0; extra == "all"
+Requires-Dist: mkdocstrings[python]>=0.24.0; extra == "all"
+Requires-Dist: mkdocs-material>=9.5.0; extra == "all"
+Requires-Dist: mkdocs>=1.5.0; extra == "all"
+Requires-Dist: nbconvert>=7.8.0; extra == "all"
+Requires-Dist: openpyxl>=3.1.0; extra == "all"
+Requires-Dist: plotly>=5.17.0; extra == "all"
+Requires-Dist: pre-commit>=3.5.0; extra == "all"
+Requires-Dist: pymdown-extensions>=10.0; extra == "all"
+Requires-Dist: pytest-cov>=4.1.0; extra == "all"
+Requires-Dist: pytest-xdist>=3.3.0; extra == "all"
+Requires-Dist: pytest>=7.4.0; extra == "all"
+Requires-Dist: ruff>=0.1.0; extra == "all"
+Requires-Dist: torch<2.3.0,>=2.2.0; extra == "all"
+Requires-Dist: torchvision<0.18.0,>=0.17.0; extra == "all"
+Requires-Dist: transformers>=4.39.0; extra == "all"
+Requires-Dist: weasyprint>=60.0; extra == "all"
+Dynamic: license-file
+
+# ShortKit-ML
+
+> **ShortKit-ML** — Detect and mitigate shortcuts and biases in machine learning embedding spaces. 20+ detection and mitigation methods with a unified API. **Multi-attribute support** tests multiple sensitive attributes simultaneously. Model Comparison mode for benchmarking multiple embedding models.
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![PyTorch](https://img.shields.io/badge/PyTorch-2.2+-ee4c2c.svg)](https://pytorch.org/)
+[![CI](https://github.com/criticaldata/ShortKit-ML/actions/workflows/tests.yml/badge.svg)](https://github.com/criticaldata/ShortKit-ML/actions/workflows/tests.yml)
+[![Dataset on HF](https://img.shields.io/badge/%F0%9F%A4%97%20HuggingFace-ShortKIT--ML--data-yellow.svg)](https://huggingface.co/datasets/MITCriticalData/ShortKit-ML-data)
+[![Docs](https://img.shields.io/badge/docs-criticaldata.github.io-blue.svg)](https://criticaldata.github.io/ShortKit-ML/)
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Detection Methods](#detection-methods)
+- [Overall Assessment Conditions](#overall-assessment-conditions)
+- [MCP Server](#mcp-server)
+- [Paper Benchmarks](#paper-benchmark-datasets)
+- [Reproducing Paper Results](#reproducing-paper-results)
+- [GPU Support](#gpu-support)
+- [Interactive Dashboard](#interactive-dashboard)
+- [Testing](#testing)
+- [Contributing](#contributing)
+- [Citation](#citation)
+
+## Overview
+
+ShortKit-ML provides a comprehensive toolkit for detecting and mitigating shortcuts (unwanted biases) in embedding spaces:
+
+- **20+ detection methods**: HBAC, Probe, Statistical, Geometric, Bias Direction PCA, Equalized Odds, Demographic Parity, Intersectional, GroupDRO, GCE, Causal Effect, SSA, SIS, CAV, VAE, Early-Epoch Clustering, and more
+- **6 mitigation methods**: Shortcut Masking, Background Randomization, Adversarial Debiasing, Explanation Regularization, Last Layer Retraining, Contrastive Debiasing
+- **5 pluggable risk conditions**: indicator_count, majority_vote, weighted_risk, multi_attribute, meta_classifier
+
+**Key Features:**
+- Unified `ShortcutDetector` API for all methods
+- Interactive Gradio dashboard with real-time analysis
+- PDF/HTML/Markdown reports with visualizations
+- Embedding-only mode (no model access needed)
+- Multi-attribute support: test race, gender, age simultaneously
+- Model Comparison mode: compare multiple embedding models side-by-side
+
+## Installation
+
+```bash
+pip install shortkit-ml
+```
+
+For all optional extras (dashboard, reporting, VAE, HuggingFace, etc.):
+
+```bash
+pip install "shortkit-ml[all]"
+```
+
+### Development Install (from source)
+
+```bash
+git clone https://github.com/criticaldata/ShortKit-ML.git
+cd ShortKit-ML
+pip install -e ".[all]"
+```
+
+Or with `uv`:
+
+```bash
+uv venv --python 3.10
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+uv pip install -e ".[all]"
+```
+
+### Optional: PDF Export Dependencies
+
+```bash
+# macOS
+brew install pango gdk-pixbuf libffi
+# Ubuntu/Debian
+sudo apt-get install libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf2.0-0
+```
+
+> HTML and Markdown reports work without these. PDF export is optional.
+
+## Quick Start
+
+```python
+from shortcut_detect import ShortcutDetector
+import numpy as np
+
+embeddings = np.load("embeddings.npy")  # (n_samples, embedding_dim)
+labels = np.load("labels.npy")          # (n_samples,)
+
+detector = ShortcutDetector(methods=['hbac', 'probe', 'statistical', 'geometric', 'equalized_odds'])
+detector.fit(embeddings, labels)
+
+detector.generate_report("report.html", format="html")
+print(detector.summary())
+```
+
+### Embedding-Only Mode
+
+For closed-source models or systems that only expose embeddings:
+
+```python
+from shortcut_detect import ShortcutDetector, HuggingFaceEmbeddingSource
+
+hf_source = HuggingFaceEmbeddingSource(model_name="sentence-transformers/all-MiniLM-L6-v2")
+detector = ShortcutDetector(methods=["probe", "statistical"])
+detector.fit(embeddings=None, labels=labels, group_labels=groups,
+             raw_inputs=texts, embedding_source=hf_source)
+```
+
+> See [Embedding-Only Guide](docs/methods/overview.md) for `CallableEmbeddingSource` and caching options.
+
+## Detection Methods
+
+| Method | Key | What It Detects | Reference |
+|--------|-----|-----------------|-----------|
+| **HBAC** | `hbac` | Clustering by protected attributes | - |
+| **Probe** | `probe` | Group info recoverable from embeddings | - |
+| **Statistical** | `statistical` | Dimensions with group differences | - |
+| **Geometric** | `geometric` | Bias directions & prototype overlap | - |
+| **Bias Direction PCA** | `bias_direction_pca` | Projection gap along bias direction | Bolukbasi 2016 |
+| **Equalized Odds** | `equalized_odds` | TPR/FPR disparities | Hardt 2016 |
+| **Demographic Parity** | `demographic_parity` | Prediction rate disparities | Feldman 2015 |
+| **Early Epoch Clustering** | `early_epoch_clustering` | Shortcut reliance in early reps | Yang 2023 |
+| **GCE** | `gce` | High-loss minority samples | - |
+| **Frequency** | `frequency` | Signal in few dimensions | - |
+| **GradCAM Mask Overlap** | `gradcam_mask_overlap` | Attention overlap with shortcut masks | - |
+| **SpRAy** | `spray` | Spectral clustering of heatmaps | Lapuschkin 2019 |
+| **CAV** | `cav` | Concept-level sensitivity | Kim 2018 |
+| **Causal Effect** | `causal_effect` | Spurious attribute influence | - |
+| **VAE** | `vae` | Latent disentanglement signatures | - |
+| **SSA** | `ssa` | Semi-supervised spectral shift | [arXiv:2204.02070](https://arxiv.org/abs/2204.02070) |
+| **Generative CVAE** | `generative_cvae` | Counterfactual embedding shifts | - |
+| **GroupDRO** | `groupdro` | Worst-group performance gaps | Sagawa 2020 |
+| **SIS** | `sis` | Sufficient input subsets (minimal dims for prediction) | Carter 2019 |
+| **Intersectional** | `intersectional` | Intersectional fairness gaps (2+ attributes) | Buolamwini 2018 |
+
+### Mitigation Methods
+
+| Method | Class | Strategy | Reference |
+|--------|-------|----------|-----------|
+| **Shortcut Masking** | `ShortcutMasker` | Zero/randomize/inpaint shortcut regions | - |
+| **Background Randomization** | `BackgroundRandomizer` | Swap foreground across backgrounds | - |
+| **Adversarial Debiasing** | `AdversarialDebiasing` | Remove group information adversarially | Zhang 2018 |
+| **Explanation Regularization** | `ExplanationRegularization` | Penalize attention on shortcuts (RRR) | Ross 2017 |
+| **Last Layer Retraining** | `LastLayerRetraining` | Retrain final layer balanced (DFR) | Kirichenko 2023 |
+| **Contrastive Debiasing** | `ContrastiveDebiasing` | Contrastive loss to align groups (CNC) | - |
+
+> See [Detection Methods Overview](docs/methods/overview.md) for per-method usage, interpretation guides, and code examples.
+
+## Overall Assessment Conditions
+
+`ShortcutDetector` supports pluggable risk aggregation conditions that control how method-level results map to the final HIGH/MODERATE/LOW summary.
+
+| Condition | Best For | Description |
+|-----------|----------|-------------|
+| `indicator_count` | General use (default) | Count of risk signals: 2+ = HIGH, 1 = MODERATE, 0 = LOW |
+| `majority_vote` | Conservative screening | Consensus across methods |
+| `weighted_risk` | Nuanced analysis | Evidence strength matters (probe accuracy, effect sizes, etc.) |
+| `multi_attribute` | Multi-demographic | Escalates when multiple attributes flag risk |
+| `meta_classifier` | Trained pipelines | Logistic regression meta-model on detector outputs (bundled model included) |
+
+```python
+detector = ShortcutDetector(
+    methods=["probe", "statistical"],
+    condition_name="weighted_risk",
+    condition_kwargs={"high_threshold": 0.6, "moderate_threshold": 0.3},
+)
+```
+
+Custom conditions can be registered via `@register_condition("name")`. See [Conditions API](docs/api/shortcut-detector.md) for details.
+
+## MCP Server
+
+ShortKit-ML ships an [MCP](https://modelcontextprotocol.io/) server so AI assistants (Claude, Cursor, etc.) can call detection tools directly from chat — no Python script required.
+
+### Install the MCP extra
+
+```bash
+pip install -e ".[mcp]"
+```
+
+### Start the server
+
+```bash
+# via entry point (after install)
+shortkit-ml-mcp
+
+# or directly
+python -m shortcut_detect.mcp_server
+```
+
+### Available tools
+
+| Tool | Description |
+|------|-------------|
+| `list_methods` | List all 19 detection methods with descriptions |
+| `generate_synthetic_data` | Generate a synthetic shortcut dataset (linear / nonlinear / none) |
+| `run_detector` | Run selected methods on embeddings — returns verdict, risk level, per-method breakdown |
+| `get_summary` | Human-readable summary from a prior `run_detector` call |
+| `get_method_detail` | Full raw result dict for a single method |
+| `compare_methods` | Side-by-side comparison table + consensus vote across methods |
+
+### Connect to Claude Desktop
+
+Add the following to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
+
+```json
+{
+  "mcpServers": {
+    "shortkit-ml": {
+      "command": "python",
+      "args": ["-m", "shortcut_detect.mcp_server"],
+      "cwd": "/path/to/ShortKit-ML"
+    }
+  }
+}
+```
+
+A ready-to-edit template is included at [`claude_desktop_config.json`](claude_desktop_config.json).
+
+## Paper Benchmark Datasets
+
+### Dataset 1 -- Synthetic Grid
+
+Configure `examples/paper_benchmark_config.json` to control effect sizes, sample sizes, imbalance ratios, and embedding dimensionalities. A smoke profile (`examples/paper_benchmark_config_smoke.json`) is provided for quick sanity checks.
+
+```bash
+python -m shortcut_detect.benchmark.paper_run --config examples/paper_benchmark_config.json
+```
+
+Outputs CSVs, figures, and summary markdown into `output/paper_benchmark/`.
+
+### Dataset 2 -- CheXpert Real Data
+
+Requires a CheXpert manifest (`data/chexpert_manifest.csv`) plus model-specific embedding pickles. Supported models: `medclip`, `biomedclip`, `cxr-foundation`.
+
+```bash
+python3 scripts/run_dataset2_benchmark.py \
+  --manifest data/chexpert_manifest.csv \
+  --model medclip \
+  --root . \
+  --artifacts-dir output/paper_benchmark/chexpert_embeddings \
+  --config examples/paper_benchmark_config.json
+```
+
+See `scripts/reproduce_paper.sh` and the Dockerfile for full reproducibility.
+
+## Reproducing Paper Results
+
+All paper results are fully reproducible with fixed seeds (`seed=42`). Every table and figure in the paper can be regenerated from the scripts and data in this repository.
+
+**13 benchmark methods** are evaluated across all datasets: `hbac`, `probe`, `statistical`, `geometric`, `frequency`, `bias_direction_pca`, `sis`, `demographic_parity`, `equalized_odds`, `intersectional`, `groupdro`, `gce`, `ssa`. These span 5 paradigms: embedding-level analysis, representation geometry, fairness evaluation, explainability, and training dynamics.
+
+### Step-by-step Reproduction
+
+| Step | Command | Output | Time |
+|------|---------|--------|------|
+| 1. Install | `pip install -e ".[all]"` | Package + deps | 2 min |
+| 2. Synthetic benchmarks | `python scripts/generate_all_paper_tables.py` | `output/paper_tables/*.tex` | ~10 min |
+| 3. Paper figures | `python scripts/generate_paper_figures.py` | `output/paper_figures/*.pdf` | ~2 min |
+| 4. CheXpert benchmark | `python scripts/run_chexpert_benchmark.py` | `output/paper_benchmark/chexpert_results/` | ~1 min |
+| 5. MIMIC-CXR setup | `python scripts/setup_mimic_cxr_data.py` | `data/mimic_cxr/*.npy` | ~1 min |
+| 6. MIMIC-CXR benchmark | `python scripts/run_mimic_benchmark.py` | `output/paper_benchmark/mimic_cxr_results/` | ~2 min |
+| 7. CelebA extraction | `python scripts/extract_celeba_embeddings.py` | `data/celeba/celeba_real_*.npy` | ~5 min (MPS) |
+| 8. CelebA benchmark | `python scripts/run_celeba_real_benchmark.py` | `output/paper_benchmark/celeba_real_results/` | ~1 min |
+| 9. Full pipeline (smoke) | `./scripts/reproduce_paper.sh smoke` | All synthetic outputs | ~5 min |
+| 10. Full pipeline | `./scripts/reproduce_paper.sh full` | All synthetic outputs | ~2-4 hrs |
+
+### Docker (fully self-contained)
+```bash
+docker build -t shortcut-detect .
+docker run --rm -v $(pwd)/output:/app/output shortcut-detect full
+```
+
+### Data Sources
+
+All embeddings are hosted on HuggingFace: **[MITCriticalData/ShortKit-ML-data](https://huggingface.co/datasets/MITCriticalData/ShortKit-ML-data)**
+
+```bash
+# Download all data into data/
+huggingface-cli download MITCriticalData/ShortKit-ML-data --repo-type dataset --local-dir data/
+```
+
+| Dataset | Location | Embedding Models | Dim | Samples |
+|---------|----------|-----------------|-----|---------|
+| Synthetic | Generated at runtime | `SyntheticGenerator(seed=42)` | 128 | Configurable |
+| CheXpert | `data/chexpert/` | MedCLIP, ResNet-50, DenseNet-121, ViT-B/16, ViT-B/32, DINOv2, RAD-DINO, MedSigLIP | 512-2048 | 2,000 each |
+| MIMIC-CXR | `data/mimic_cxr/` | RAD-DINO, ViT-B/16, ViT-B/32, MedSigLIP | 768-1152 | ~1,500 each |
+| CelebA | `data/celeba/` | ResNet-50 (ImageNet) | 2,048 | 10,000 |
+
+### Paper Tables → Scripts Mapping
+
+| Paper Table | Script | Data | Seed |
+|-------------|--------|------|------|
+| Tab 3: Synthetic P/R/F1 | `generate_all_paper_tables.py` | `SyntheticGenerator` | 42 |
+| Tab 4: False positive rates | `generate_all_paper_tables.py` | `SyntheticGenerator` (null) | 42 |
+| Tab 5: Sensitivity analysis | `generate_all_paper_tables.py` | `SensitivitySweep` | 42 |
+| Tab 6: CheXpert results | `run_chexpert_benchmark.py` | `data/chest_embeddings.npy` | 42 |
+| Tab 7: MIMIC-CXR cross-val | `run_mimic_benchmark.py` | `data/mimic_cxr/*.npy` | 42 |
+| Tab 8: CelebA validation | `run_celeba_real_benchmark.py` | `data/celeba/celeba_real_embeddings.npy` | 42 |
+| Tab 9: Risk conditions | `generate_all_paper_tables.py` | `SyntheticGenerator` | 42 |
+| Fig 2: Convergence matrix | `generate_paper_figures.py` | Synthetic + CheXpert | 42 |
+
+See `docs/reproducibility.md` for full details.
+
+## GPU Support
+
+The library auto-selects the best available device. PyTorch components (probes, VAE, GroupDRO, adversarial debiasing, etc.) use the standard `torch.device` fallback:
+
+| Platform | Backend | Auto-detected |
+|----------|---------|---------------|
+| Linux/Windows with NVIDIA GPU | CUDA | Yes (`torch.cuda.is_available()`) |
+| macOS Apple Silicon | MPS | Partial -- pass `device="mps"` explicitly |
+| CPU (any platform) | CPU | Yes (default fallback) |
+
+> **Note:** Most detection methods (HBAC, statistical, geometric, etc.) run on CPU via NumPy/scikit-learn and do not require GPU. GPU acceleration benefits the torch-based probe, VAE, GroupDRO, and mitigation methods. MPS support depends on PyTorch operator coverage; if you encounter errors on Apple Silicon, fall back to `device="cpu"`.
+
+## Interactive Dashboard
+
+```bash
+python app.py
+# Opens at http://127.0.0.1:7860
+```
+
+Features: sample CheXpert data, custom CSV upload, PDF/HTML reports, model comparison tab, multi-attribute analysis.
+
+**CSV Format:**
+```csv
+embedding_0,embedding_1,...,task_label,group_label,attr_race,attr_gender
+0.123,0.456,...,1,group_a,Black,Male
+```
+
+> See [Dashboard Guide](docs/getting-started/dashboard.md) for detailed usage.
+
+## Testing
+
+```bash
+pytest tests/ -v
+pytest --cov=shortcut_detect --cov-report=html
+```
+
+**638 tests passing** across all detection and mitigation methods.
+
+## Contributing
+
+```bash
+pip install -e ".[dev]"
+pre-commit install
+```
+
+- **Black** for formatting (line length: 100), **Ruff** for linting, **MyPy** for types
+- Pre-commit hooks run automatically; CI tests on Python 3.10, 3.11, 3.12
+- New detectors must implement `DetectorBase`. See `docs/contributing.md` and `shortcut_detect/detector_template.py`
+
+## Project Structure
+
+```
+shortcut_detect/
+├── probes/           # Probe-based detection (sklearn + torch)
+├── clustering/       # HBAC detector
+├── statistical/      # Statistical testing
+├── geometric/        # Geometric & bias direction analysis
+├── fairness/         # Equalized Odds, Demographic Parity, Intersectional
+├── frequency/        # Frequency shortcut detector
+├── causal/           # Causal effect detector
+├── gce/              # Generalized cross-entropy detector
+├── training/         # Early epoch clustering (SPARE)
+├── vae/              # VAE latent disentanglement
+├── xai/              # CAV, SpRAy, GradCAM mask overlap, SIS
+├── ssa/              # Semi-supervised spectral analysis
+├── groupdro/         # GroupDRO worst-group robustness
+├── conditions/       # Pluggable risk aggregation conditions
+│   ├── base.py, registry.py, indicator_count.py, majority_vote.py
+│   ├── weighted_risk.py, multi_attribute.py, meta_classifier.py
+│   └── meta_model.joblib  # Trained meta-classifier (bundled)
+├── benchmark/        # Paper benchmark infrastructure
+│   ├── runner.py, paper_runner.py, synthetic_generator.py
+│   ├── measurement.py, fp_analysis.py, sensitivity.py
+│   ├── convergence_viz.py, baseline_comparison.py, figures.py
+├── comparison/       # Model comparison runner
+├── mitigation/       # Debiasing & masking methods (M01-M07)
+├── reporting/        # HTML/PDF/CSV reports & visualizations
+├── unified.py        # ShortcutDetector unified API
+└── detector_base.py  # DetectorBase ABC with results_ schema
+
+docs/                 # MkDocs documentation site
+examples/             # Notebooks and benchmark configs
+app.py                # Gradio dashboard
+Dockerfile            # Reproducible environment
+scripts/              # Paper reproduction scripts
+tests/                # Test suite (475+ tests)
+```
+
+## Documentation
+
+```bash
+pip install mkdocs mkdocs-material "mkdocstrings[python]" pymdown-extensions
+mkdocs serve  # http://127.0.0.1:8000
+```
+
+- [Getting Started](docs/getting-started/installation.md)
+- [Detection Methods](docs/methods/overview.md) -- all 20+ methods with guides
+- [API Reference](docs/api/shortcut-detector.md)
+- [Contributing](docs/contributing.md)
+
+## Citation
+
+```bibtex
+@software{shortkit_ml2025,
+  title={ShortKit-ML: Tools for Identifying Biases in Embedding Spaces},
+  author={Sebastian Cajas, Aldo Marzullo, Sahil Kapadia, Qingpeng Kong, Filipe Santos, Alessandro Quarta, Leo Celi},
+  year={2025},
+  url={https://github.com/criticaldata/ShortKit-ML}
+}
+```
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file
+
+## Contact
+
+- **GitHub**: [criticaldata/ShortKit-ML](https://github.com/criticaldata/ShortKit-ML)
+- **Issues**: [GitHub Issues](https://github.com/criticaldata/ShortKit-ML/issues)