README.md

metadata

title: BiasGuard Pro
emoji: 🛡️
colorFrom: purple
colorTo: pink
sdk: gradio
sdk_version: 6.2.0
python_version: '3.10'
app_file: app.py
pinned: false

An Explainable Text Bias Auditing & Counterfactual Suggestion Toolkit

🚀 Live Demo | ✨ Features | 🎯 Usage Guide | 🧠 Technical Details | 🤝 Contributing

---

🌟 Overview

BiasXplainer (a.k.a. BiasGuard Pro) is an interactive and programmatic toolkit for:

• 🔍 Detecting potential bias (e.g. gendered language) in short text inputs
• 🧪 Explaining classifier outputs via token-level SHAP attributions (with graceful fallbacks)
• 🔁 Generating neutral counterfactual rewrites while preserving semantics
• 📊 Running batch analyses with aggregation statistics & comparative subgroup views
• 🛠 Exporting structured outputs (JSON/CSV) for downstream pipelines

This toolkit is designed as an exploratory auditing aid—ideal for rapid experimentation, prototype fairness evaluation, educational demonstrations, and workflow integration proof-of-concepts.

⚠️ Important: This is not a definitive bias measurement instrument. For production or compliance use:

• Apply validated, domain-appropriate bias and fairness metrics
• Use diverse, representative corpora (not isolated sentences)
• Incorporate human review and domain expertise
• Follow established AI ethics & governance frameworks

---

🎯 Purpose & Scope

BiasXplainer helps you:

• Understand why a sentence may be flagged: token impacts clearly visualized
• Explore neutral alternatives via structured counterfactual suggestions
• Analyze variability across groups in batch mode (substring-based comparative lens)
• Export artifacts for integration with other auditing pipelines

---

🎭 Why This Toolkit?

Goal	How It's Achieved
Transparency	Token-level impact via SHAP + heuristic fallback
Counterfactual Exploration	Template + semantic replacements + FLAN‑T5 polish
Batch Insight	Aggregated stats: mean bias, class distribution, top impactful terms
Fairness Prototyping	Simple comparative view (e.g., “women” vs “men” substring focus)
Extensibility	Modular architecture for adding models / exporters / fairness metrics
Developer Friendliness	Clean Python modules + minimal dependency surface

---

✨ Features

🔬 Core Capabilities

• Single Text Analysis: Bias score + classification + SHAP impact chart + highlighted tokens
• Counterfactual Suggestions: Structured rewrite candidates (neutralization focus)
• Batch Mode: Accepts .txt, .csv, .json and runs background jobs
• Comparative View: Substring-based group comparison (basic fairness proxy)
• Exports: JSON & CSV from UI or programmatic API
• Model Override: Auto-load local fine-tuned DistilBERT if present under ./models/
• Profiling Panel: Inline latency breakdown (tokenization, SHAP, rewrite phases)

🧩 Extended Features

• ⚡ Parallel bias + SHAP computation
• 🧪 Resilient fallback keyword scoring if SHAP fails
• 🔁 FLAN‑T5-backed grammar polishing for counterfactuals
• 🧱 Batched inference APIs (predict_batch_batched)
• 🧪 Hooks for future fairness metrics (equalized odds, subgroup performance gaps)

---

🚀 Live Demo

Try it instantly on Hugging Face Spaces:

👉 Launch Interactive Demo

---

🗂 Project Structure

BiasXplainer/
│
├── main.py                      # Gradio entrypoint (BiasGuardDashboard)
├── requirements.txt             # Python dependencies
├── README.md                    # This file
│
├── core/
│   ├── bias_detector.py         # DistilBERT classifier logic
│   ├── explainer.py             # SHAP integration + fallback heuristic
│   ├── counterfactuals.py       # Rewrite engine + FLAN‑T5 polishing
│   ├── utils.py                 # Helpers (token merging, formatting, etc.)
│
├── export/
│   ├── json_export.py           # JSON serialization helper
│   ├── csv_export.py            # CSV serialization helper
│
├── models/                      # (Optional) Local fine-tuned model artifacts
├── tests/                       # Pytest suite (add fairness & stability tests)
├── docs/
│   ├── usage.md                 # Advanced usage patterns
│   ├── api.md                   # Programmatic interface reference
│   └── roadmap.md               # Extended roadmap details
│
├── assets/                      # (Optional) Screenshots / banners
├── results/
│   └── latency_before_after.csv # Placeholder performance metrics file
└── LICENSE                      # MIT license (add full text)

---

🎯 Usage Guide

Quick Start (Local)

git clone https://github.com/dyra-12/BiasXplainer.git
cd BiasXplainer
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python main.py

Open the printed local URL to start auditing text.

GUI Workflows

1. Single Analysis – Paste text → Analyze → View bias score, class, SHAP token chart, highlighted impacts, and counterfactual suggestions.
2. Batch & Compare – Paste multi-line text OR upload .txt / .csv / .json → Start job → Poll status → Download results. Optionally specify two substrings (e.g., women, men).
3. Export – Use Export buttons (JSON/CSV) or programmatic API calls. Files saved under ./export/.

Supported Input Formats

Format	Structure
.txt	Newline-separated sentences
.csv	Must include a text column (fallback to first column)
.json	List of strings OR list of objects with text field

Minimal Programmatic API

from main import BiasGuardDashboard

dashboard = BiasGuardDashboard()
texts = [
    "Women should be nurses because they are compassionate.",
    "Men are naturally better at engineering roles.",
    "This is a neutral sentence."
]

results = dashboard.analyzer.detector.predict_batch_batched(texts)
print(results)  # [{'bias_probability': ..., 'classification': ..., 'confidence': ...}, ...]

---

🧪 Example Analysis Flow

1. User enters text
2. BiasDetector.predict_bias(text) → {probability, class, confidence}
3. Explainer.get_shap_values(text) → token-level impacts
4. CounterfactualGenerator.generate_counterfactuals(text, shap) → neutral rewrite candidates
5. UI renders gauge + impact bar + highlighted text + suggestions + profiling

Batch Flow

• Batched DistilBERT inference
• Async background job collects: mean bias probability, class distribution counts, top impactful tokens
• Optional simple substring comparison overlay

---

🧠 Technical Details

Core Modules

Module	Responsibility
core/bias_detector.py	DistilBERT-based classification (single + batched + efficient batching)
core/explainer.py	SHAP token attribution + fallback keyword heuristic
core/counterfactuals.py	Template-driven neutralization + FLAN‑T5 grammar refinement
export/json_export.py	Structured JSON serialization
export/csv_export.py	CSV export with impact flattening
main.py	Gradio composition, UI orchestration, profiling

Models

• Classifier: DistilBERT (distilbert-base-uncased or local fine-tune under ./models)
• Polisher: google/flan-t5-small (light rewrite improvements)

Performance Strategy

• Parallel futures for classifier + SHAP tasks
• Batching reduces tokenizer & forward overhead
• Token merging converts subword fragments into user-friendly units
• Inline profiling block surfaces latency bottlenecks

Counterfactual Strategy

1. Extract high-impact tokens (SHAP or fallback keyword list)
2. Apply neutral replacements or paraphrase templates
3. Polish grammar & semantics via FLAN‑T5 Small
4. Return ranked suggestions (preserving original intent)

---

📊 Performance

Record metrics in results/latency_before_after.csv (create if missing).

The project stores per-step latency measurements with the CSV schema: step,before_s,after_s,improvement_pct.

Step	Before (s)	After (s)	Improvement (%)
predict_bias	0.90	0.35	61.11
get_shap_values	24.00	6.60	72.50
generate_counterfactuals	2.50	1.00	60.00
create_shap_chart	0.80	0.50	37.50
create_bias_meter	0.20	0.15	25.00
highlight_biased_words	0.60	0.40	33.33
total	29.00	9.00	68.97

---

✅ Testing

pytest -q

Recommended test categories:

• Neutral vs biased fixtures (classification stability)
• SHAP fallback path when primary explainer errors
• Export correctness (headers + row counts)
• Deterministic counterfactual generation for controlled inputs

---

🗺 Roadmap

Short-Term:

• Live progress streaming (websocket / SSE)
• Extended fairness metrics (e.g., equalized odds, subgroup delta charts)
• Persistent job queue (Celery / RQ + Redis)
• Confidence calibration & uncertainty indicators
• Pluggable backbone registry (RoBERTa, DeBERTa, ALBERT)

Long-Term:

• Embedding-based semantic group comparison
• Multi-lingual model support
• Explanation fusion (SHAP + Integrated Gradients comparison)
• Audit session export bundles (results + metadata + configuration hash)

---

🎓 Use Cases

Research

• Rapid prototyping of bias detection workflows
• Comparing attribution stability across variants

Industry

• Early-stage content moderation tool exploration
• Internal fairness experimentation sandbox

Education

• Teaching interpretability concepts interactively
• Student projects on ethical AI + XAI

---

🤝 Contributing

We welcome improvements!

Ways to Contribute

1. 🐛 Bug Reports: Open an issue with reproduction steps
2. ✨ Feature Requests: Suggest metrics, exporters, or model options
3. 📝 Documentation: Improve guides, add examples
4. 💻 Code: Submit well-scoped PRs with tests
5. 📊 Performance: Optimize latency & update benchmarking CSV

Development Setup

# Fork the repo, then:
git clone https://github.com/YOUR-USERNAME/BiasXplainer.git
cd BiasXplainer

# Create a branch
git checkout -b feat/your-feature-name

# Install & test
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
pytest -q

# Commit & push
git commit -m "Feat: descriptive summary"
git push origin feat/your-feature-name

Code Style

• Follow PEP 8
• Use type hints where practical
• Add docstrings to public functions
• Include tests for new logic paths
• Avoid large, multi-purpose PRs

---

⚖️ Ethical Use & Disclaimer

This toolkit provides heuristic insights into potential linguistic bias patterns. It does not guarantee:

• Fairness across real-world demographic groups
• Complete coverage of subtle stereotypes
• Context-aware ethical judgments

Always complement automated signals with:

• Human expert review
• Diverse, representative evaluation sets
• Formal fairness metrics and governance policies

---

🔒 Security Notes

• Avoid submitting PII or confidential corpora to public hosted demos.
• For enterprise usage: run locally, restrict model paths, audit dependencies.
• Consider dependency pinning & vulnerability scanning (e.g., pip-audit, safety).

---

📄 License

This project is licensed under the MIT License — see the LICENSE file.

MIT License

Copyright (c) 2024 BiasXplainer Contributors

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...
[Full license text here]

---

🛟 Additional Resources

• docs/usage.md — Advanced usage & troubleshooting
• docs/api.md — Programmatic interface guide
• docs/roadmap.md — Expanded roadmap details (optional)
• Hugging Face Transformers Docs: https://huggingface.co/docs/transformers
• SHAP Documentation: https://shap.readthedocs.io/

---

📬 Contact & Support

• Email: dyutidasmahaptra@gmail.com
• Hugging Face Space: https://huggingface.co/spaces/Dyra1204/BiasGuard-Pro

Built with ❤️ by the community

⬆ Back to Top