Updated readme file

.github/workflows/ci.yml

@@ -0,0 +1,111 @@
+name: CI/CD Pipeline
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main, develop ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.8', '3.9', '3.10', '3.11']
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v3
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v4
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Cache pip dependencies
+      uses: actions/cache@v3
+      with:
+        path: ~/.cache/pip
+        key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
+        restore-keys: |
+          ${{ runner.os }}-pip-
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -r requirements.txt
+        pip install pytest pytest-cov flake8 black
+
+    - name: Lint with flake8
+      run: |
+        # Stop the build if there are Python syntax errors or undefined names
+        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
+        # Exit-zero treats all errors as warnings
+        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=100 --statistics
+
+    - name: Check code formatting with Black
+      run: |
+        black --check src/ tests/ app.py || echo "Code formatting check completed"
+
+    - name: Run tests with pytest
+      run: |
+        pytest tests/ -v --cov=src --cov-report=xml --cov-report=html
+
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v3
+      with:
+        file: ./coverage.xml
+        flags: unittests
+        name: codecov-umbrella
+
+  build-docker:
+    runs-on: ubuntu-latest
+    needs: test
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v3
+
+    - name: Set up Docker Buildx
+      uses: docker/setup-buildx-action@v2
+
+    - name: Build Docker image
+      run: |
+        docker build -t vit-auditing-toolkit:latest .
+
+    - name: Test Docker image
+      run: |
+        docker run -d --name test-container -p 7860:7860 vit-auditing-toolkit:latest
+        sleep 30
+        curl -f http://localhost:7860/ || exit 1
+        docker stop test-container
+        docker rm test-container
+
+  lint:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v3
+
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: '3.10'
+
+    - name: Install linting tools
+      run: |
+        pip install flake8 black mypy
+
+    - name: Run flake8
+      run: |
+        flake8 src/ tests/ app.py --max-line-length=100
+
+    - name: Run Black
+      run: |
+        black --check src/ tests/ app.py
+
+    - name: Run mypy
+      run: |
+        mypy src/ --ignore-missing-imports || echo "Type checking completed"

CHANGELOG.md

@@ -0,0 +1,86 @@
+# Changelog
+
+All notable changes to the ViT Auditing Toolkit will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Planned
+- Support for additional ViT variants (DeiT, BEiT, Swin Transformer)
+- Batch processing capabilities
+- Export functionality for reports
+- Custom model upload support
+- API endpoints for programmatic access
+
+## [1.0.0] - 2024-10-26
+
+### Added
+- Initial release of ViT Auditing Toolkit
+- Basic Explainability features:
+  - Attention Visualization with layer/head selection
+  - GradCAM implementation using Captum
+  - GradientSHAP for pixel-level attribution
+- Advanced Auditing features:
+  - Counterfactual Analysis with patch perturbation
+  - Confidence Calibration analysis
+  - Bias Detection across subgroups
+- Web interface using Gradio:
+  - Modern, responsive UI with custom styling
+  - Four-tab interface for different analysis types
+  - Real-time visualization of results
+- Model support:
+  - ViT-Base (google/vit-base-patch16-224)
+  - ViT-Large (google/vit-large-patch16-224)
+- Comprehensive documentation:
+  - Detailed README with usage guides
+  - Technical explanations of methods
+  - Installation instructions
+- Testing suite:
+  - Unit tests for core functionality
+  - Integration tests for advanced features
+- Docker support for easy deployment
+- CI/CD pipeline with GitHub Actions
+
+### Technical Details
+- PyTorch 2.2+ compatibility
+- Hugging Face Transformers integration
+- Captum for model interpretability
+- Gradio 4.19+ for web interface
+- Matplotlib for visualizations
+
+### Documentation
+- Comprehensive README.md
+- Contributing guidelines
+- MIT License
+- Code of conduct
+
+## [0.1.0] - 2024-10-15
+
+### Added
+- Project initialization
+- Basic project structure
+- Core module implementations
+- Initial model loading functionality
+
+---
+
+## Version History
+
+### Version Numbering
+- **Major version (X.0.0)**: Incompatible API changes
+- **Minor version (0.X.0)**: New functionality, backwards-compatible
+- **Patch version (0.0.X)**: Backwards-compatible bug fixes
+
+### Release Notes Format
+- **Added**: New features
+- **Changed**: Changes in existing functionality
+- **Deprecated**: Soon-to-be removed features
+- **Removed**: Removed features
+- **Fixed**: Bug fixes
+- **Security**: Vulnerability fixes
+
+---
+
+For more details on any version, see the [GitHub Releases](https://github.com/dyra-12/ViT-XAI-Dashboard/releases) page.

CONTRIBUTING.md

@@ -0,0 +1,306 @@
+# Contributing to ViT Auditing Toolkit
+
+First off, thank you for considering contributing to the ViT Auditing Toolkit! It's people like you that make this tool better for everyone.
+
+## 🌟 Ways to Contribute
+
+### 1. Reporting Bugs 🐛
+
+Before creating bug reports, please check existing issues to avoid duplicates. When creating a bug report, include:
+
+- **Clear title and description**
+- **Steps to reproduce** the behavior
+- **Expected vs actual behavior**
+- **Screenshots** if applicable
+- **Environment details** (OS, Python version, etc.)
+
+**Example:**
+```markdown
+**Bug**: GradCAM visualization fails with ViT-Large model
+
+**Steps to reproduce:**
+1. Select ViT-Large from dropdown
+2. Upload any image
+3. Select GradCAM method
+4. Click "Analyze Image"
+
+**Expected:** GradCAM heatmap visualization
+**Actual:** Error message "AttributeError: ..."
+
+**Environment:**
+- OS: Ubuntu 22.04
+- Python: 3.10.12
+- PyTorch: 2.2.0
+```
+
+### 2. Suggesting Features ✨
+
+Feature requests are welcome! Please provide:
+
+- **Clear use case**: Why is this feature needed?
+- **Proposed solution**: How should it work?
+- **Alternatives considered**: Other approaches you've thought about
+- **Additional context**: Screenshots, mockups, references
+
+### 3. Contributing Code 💻
+
+#### Development Setup
+
+```bash
+# 1. Fork the repository on GitHub
+# 2. Clone your fork
+git clone https://github.com/YOUR-USERNAME/ViT-XAI-Dashboard.git
+cd ViT-XAI-Dashboard
+
+# 3. Create a virtual environment
+python -m venv venv
+source venv/bin/activate  # Windows: venv\Scripts\activate
+
+# 4. Install dependencies
+pip install -r requirements.txt
+
+# 5. Install development dependencies
+pip install pytest black flake8 mypy
+
+# 6. Create a feature branch
+git checkout -b feature/amazing-feature
+```
+
+#### Code Style Guidelines
+
+**Python Style:**
+- Follow [PEP 8](https://pep8.org/)
+- Use 4 spaces for indentation
+- Maximum line length: 100 characters
+- Use meaningful variable names
+
+**Formatting:**
+```bash
+# Format code with Black
+black src/ tests/ app.py
+
+# Check style with flake8
+flake8 src/ tests/ app.py --max-line-length=100
+
+# Type checking with mypy
+mypy src/ --ignore-missing-imports
+```
+
+**Documentation:**
+- Add docstrings to all functions and classes
+- Use Google-style docstrings
+- Update README.md if adding new features
+
+**Example:**
+```python
+def explain_attention(model, processor, image, layer_index=6, head_index=0):
+    """
+    Extract and visualize attention weights from a specific layer and head.
+    
+    Args:
+        model: Pre-trained ViT model with attention outputs enabled.
+        processor: Image processor for model input preparation.
+        image (PIL.Image): Input image to analyze.
+        layer_index (int): Transformer layer index (0-11 for base model).
+        head_index (int): Attention head index (0-11 for base model).
+    
+    Returns:
+        matplotlib.figure.Figure: Visualization of attention patterns.
+    
+    Raises:
+        ValueError: If layer_index or head_index is out of range.
+        RuntimeError: If attention weights cannot be extracted.
+    
+    Example:
+        >>> from PIL import Image
+        >>> image = Image.open("cat.jpg")
+        >>> fig = explain_attention(model, processor, image, layer_index=6)
+        >>> fig.savefig("attention.png")
+    """
+    # Implementation...
+```
+
+#### Testing
+
+All new features must include tests:
+
+```bash
+# Run all tests
+pytest tests/
+
+# Run specific test file
+pytest tests/test_explainer.py
+
+# Run with coverage
+pytest --cov=src tests/
+```
+
+**Writing Tests:**
+```python
+import pytest
+from src.explainer import explain_attention
+
+def test_attention_visualization():
+    """Test attention visualization with valid inputs."""
+    # Setup
+    model, processor = load_test_model()
+    image = create_test_image()
+    
+    # Execute
+    fig = explain_attention(model, processor, image, layer_index=6)
+    
+    # Assert
+    assert fig is not None
+    assert len(fig.axes) > 0
+
+def test_attention_invalid_layer():
+    """Test attention visualization with invalid layer index."""
+    model, processor = load_test_model()
+    image = create_test_image()
+    
+    with pytest.raises(ValueError):
+        explain_attention(model, processor, image, layer_index=99)
+```
+
+#### Commit Messages
+
+Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+**Types:**
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation changes
+- `style`: Code style changes (formatting, etc.)
+- `refactor`: Code refactoring
+- `test`: Adding or updating tests
+- `chore`: Maintenance tasks
+
+**Examples:**
+```
+feat(explainer): add LIME explainability method
+
+- Implement LIME-based explanations
+- Add visualization function
+- Update documentation
+
+Closes #42
+```
+
+```
+fix(gradcam): resolve tensor dimension mismatch
+
+GradCAM was failing for batch size != 1 due to
+incorrect tensor reshaping. Now properly handles
+single image inputs.
+
+Fixes #38
+```
+
+#### Pull Request Process
+
+1. **Update documentation**: README, docstrings, etc.
+2. **Add tests**: Ensure your code is tested
+3. **Run tests locally**: All tests must pass
+4. **Update CHANGELOG**: Add your changes
+5. **Create PR**: Use a clear title and description
+
+**PR Template:**
+```markdown
+## Description
+Brief description of changes
+
+## Type of Change
+- [ ] Bug fix
+- [ ] New feature
+- [ ] Breaking change
+- [ ] Documentation update
+
+## Testing
+- [ ] All existing tests pass
+- [ ] New tests added for new functionality
+- [ ] Tested manually with various inputs
+
+## Checklist
+- [ ] Code follows style guidelines
+- [ ] Documentation updated
+- [ ] No new warnings or errors
+- [ ] Commit messages are clear
+```
+
+### 4. Improving Documentation 📝
+
+Documentation improvements are always welcome:
+
+- Fix typos or unclear explanations
+- Add examples and tutorials
+- Improve code comments
+- Create video demonstrations
+- Translate to other languages
+
+### 5. Reviewing Pull Requests 👀
+
+Help review open pull requests:
+
+- Test the changes locally
+- Provide constructive feedback
+- Check for potential issues
+- Verify documentation is updated
+
+## 🎯 Good First Issues
+
+Look for issues labeled `good first issue` or `help wanted` - these are great starting points!
+
+## 📋 Project Priorities
+
+Current focus areas:
+1. **Stability**: Bug fixes and error handling
+2. **Performance**: Optimization for large models
+3. **Features**: Additional explainability methods
+4. **Documentation**: More examples and tutorials
+5. **Testing**: Improved test coverage
+
+## 🤝 Code of Conduct
+
+### Our Pledge
+
+We are committed to providing a welcoming and inspiring community for all.
+
+### Our Standards
+
+**Positive behavior includes:**
+- Being respectful of differing viewpoints
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+**Unacceptable behavior includes:**
+- Harassment, trolling, or discriminatory comments
+- Personal or political attacks
+- Publishing others' private information
+- Other conduct which could reasonably be considered inappropriate
+
+### Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project maintainers. All complaints will be reviewed and investigated.
+
+## 📬 Getting Help
+
+- **Questions**: Use [GitHub Discussions](https://github.com/dyra-12/ViT-XAI-Dashboard/discussions)
+- **Bugs**: Open an [issue](https://github.com/dyra-12/ViT-XAI-Dashboard/issues)
+- **Chat**: Join our community (link coming soon)
+
+## 🙏 Thank You!
+
+Your contributions, large or small, make this project better. We appreciate your time and effort!
+
+---
+
+**Happy Contributing! 🎉**

Dockerfile

@@ -0,0 +1,34 @@
+# Use Python 3.10 slim image
+FROM python:3.10-slim
+
+# Set working directory
+WORKDIR /app
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    git \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy requirements first for better caching
+COPY requirements.txt .
+
+# Install Python dependencies
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application files
+COPY . .
+
+# Expose Gradio port
+EXPOSE 7860
+
+# Set environment variables
+ENV GRADIO_SERVER_NAME="0.0.0.0"
+ENV GRADIO_SERVER_PORT=7860
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
+    CMD curl -f http://localhost:7860/ || exit 1
+
+# Run the application
+CMD ["python", "app.py"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 ViT Auditing Toolkit 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, 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.

QUICKSTART.md

@@ -0,0 +1,348 @@
+# 🚀 Quick Start Guide
+
+Get up and running with the ViT Auditing Toolkit in under 5 minutes!
+
+## 📋 Prerequisites
+
+Before you begin, ensure you have:
+- Python 3.8 or higher installed
+- pip package manager
+- (Optional) CUDA-compatible GPU for faster inference
+
+Check your Python version:
+```bash
+python --version  # Should be 3.8+
+```
+
+## ⚡ Installation Options
+
+### Option 1: Quick Install (Recommended for Most Users)
+
+```bash
+# Clone the repository
+git clone https://github.com/dyra-12/ViT-XAI-Dashboard.git
+cd ViT-XAI-Dashboard
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Run the application
+python app.py
+```
+
+Open your browser to `http://localhost:7860` 🎉
+
+### Option 2: Virtual Environment (Recommended for Development)
+
+```bash
+# Clone the repository
+git clone https://github.com/dyra-12/ViT-XAI-Dashboard.git
+cd ViT-XAI-Dashboard
+
+# Create virtual environment
+python -m venv venv
+
+# Activate virtual environment
+# On macOS/Linux:
+source venv/bin/activate
+# On Windows:
+venv\Scripts\activate
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Run the application
+python app.py
+```
+
+### Option 3: Docker (Production Ready)
+
+```bash
+# Build the image
+docker build -t vit-auditing-toolkit .
+
+# Run the container
+docker run -p 7860:7860 vit-auditing-toolkit
+
+# Or use docker-compose
+docker-compose up
+```
+
+### Option 4: Google Colab (No Installation Required)
+
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/dyra-12/ViT-XAI-Dashboard/blob/main/notebooks/colab_demo.ipynb)
+
+Run directly in your browser with free GPU access!
+
+## 🎯 First-Time Usage
+
+### Step 1: Launch the Application
+
+```bash
+python app.py
+```
+
+You should see:
+```
+✅ Model and processor loaded successfully on cpu!
+Running on local URL:  http://localhost:7860
+```
+
+### Step 2: Open the Dashboard
+
+Open your web browser and navigate to:
+```
+http://localhost:7860
+```
+
+### Step 3: Load a Model
+
+1. In the **"Select Model"** dropdown, choose `ViT-Base`
+2. Click the **"🔄 Load Model"** button
+3. Wait for the confirmation: `✅ Model loaded: google/vit-base-patch16-224`
+
+### Step 4: Analyze Your First Image
+
+#### Option A: Use a Sample Image
+1. Download a sample image:
+   ```bash
+   curl -o sample.jpg https://images.unsplash.com/photo-1574158622682-e40e69881006
+   ```
+2. Or use any image from your computer
+
+#### Option B: Try the Demo Images
+We provide sample images in the `examples/` directory:
+- `examples/cat.jpg` - Cat portrait
+- `examples/dog.jpg` - Dog portrait  
+- `examples/bird.jpg` - Bird in flight
+- `examples/car.jpg` - Sports car
+
+### Step 5: Run Your First Analysis
+
+1. Go to the **"🔍 Basic Explainability"** tab
+2. Click **"📁 Upload Image"** and select your image
+3. Keep default settings (Attention Visualization, Layer 6, Head 0)
+4. Click **"🚀 Analyze Image"**
+5. View the results:
+   - **Processed Image**: Your input image
+   - **Top Predictions**: Bar chart of confidence scores
+   - **Explanation Visualization**: Attention heatmap
+
+## 🎓 Learning Path
+
+### Beginner: Understanding Predictions
+Start with **Basic Explainability** to see:
+- What objects the model recognizes
+- Which image regions are most important
+- How confident the model is
+
+**Try this:**
+```
+1. Upload a clear photo of a single object
+2. Use Attention Visualization (default)
+3. Try different layers (0-11) to see how features evolve
+4. Switch to GradCAM for a different perspective
+```
+
+### Intermediate: Testing Robustness
+Move to **Counterfactual Analysis** to explore:
+- How stable are predictions when parts of the image change?
+- Which regions are critical vs. irrelevant?
+
+**Try this:**
+```
+1. Upload the same image from before
+2. Start with patch_size=32, perturbation_type="blur"
+3. Click "Run Counterfactual Analysis"
+4. Try different perturbation types to see variations
+```
+
+### Advanced: Model Validation
+Use **Confidence Calibration** and **Bias Detection**:
+- Is the model overconfident?
+- Does performance vary across different image conditions?
+
+**Try this:**
+```
+1. Test calibration with various images
+2. Check if confidence matches actual reliability
+3. Use bias detection to compare subgroups
+```
+
+## 💡 Common Use Cases
+
+### Use Case 1: Debugging Misclassifications
+
+**Problem**: Model misclassifies your image  
+**Solution**: Use Basic Explainability to see what it's looking at
+
+```python
+# Steps:
+1. Upload misclassified image
+2. Check top predictions (might be close to correct class)
+3. View attention maps - is it focusing on the right region?
+4. Try GradCAM to see discriminative regions
+5. Use counterfactual analysis to find sensitive areas
+```
+
+### Use Case 2: Model Selection
+
+**Problem**: Choosing between ViT-Base and ViT-Large  
+**Solution**: Compare predictions and confidence
+
+```python
+# Steps:
+1. Load ViT-Base, analyze your image
+2. Note confidence scores and predictions
+3. Load ViT-Large, analyze same image
+4. Compare:
+   - Prediction accuracy
+   - Confidence levels
+   - Attention patterns
+   - Inference time
+```
+
+### Use Case 3: Dataset Quality Check
+
+**Problem**: Ensuring your dataset is suitable for ViT  
+**Solution**: Use bias detection and calibration
+
+```python
+# Steps:
+1. Sample random images from dataset
+2. Run bias detection to check for systematic issues
+3. Check calibration to see if model is overconfident
+4. Identify problematic image categories
+```
+
+## 🔧 Troubleshooting
+
+### Problem: Out of Memory Error
+
+**Solution:**
+```bash
+# Use ViT-Base instead of ViT-Large
+# Or reduce image batch size
+# Or close other applications
+
+# For programmatic use:
+import torch
+torch.cuda.empty_cache()  # Clear GPU memory
+```
+
+### Problem: Slow Inference
+
+**Solution:**
+```bash
+# Check if using GPU:
+python -c "import torch; print(torch.cuda.is_available())"
+
+# Install CUDA-enabled PyTorch:
+pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118
+```
+
+### Problem: Model Download Fails
+
+**Solution:**
+```bash
+# Set Hugging Face cache directory:
+export HF_HOME="/path/to/writable/directory"
+
+# Or download manually:
+python -c "from transformers import ViTImageProcessor; ViTImageProcessor.from_pretrained('google/vit-base-patch16-224')"
+```
+
+### Problem: Port Already in Use
+
+**Solution:**
+```bash
+# Use a different port:
+# Modify app.py, line: demo.launch(server_port=7861)
+
+# Or kill the process using port 7860:
+# Linux/Mac:
+lsof -ti:7860 | xargs kill -9
+
+# Windows:
+netstat -ano | findstr :7860
+taskkill /PID <PID> /F
+```
+
+## 📊 Example Workflows
+
+### Workflow 1: Quick Image Classification
+
+```bash
+# 1. Start application
+python app.py
+
+# 2. In browser (http://localhost:7860):
+#    - Load ViT-Base model
+#    - Upload image
+#    - Click "Analyze Image"
+#    - View top predictions
+
+# Total time: < 1 minute
+```
+
+### Workflow 2: Comprehensive Model Audit
+
+```bash
+# 1. Start application
+python app.py
+
+# 2. For each test image:
+#    Tab 1: Check predictions and attention
+#    Tab 2: Test robustness with perturbations
+#    Tab 3: Validate confidence calibration
+#    Tab 4: Check for bias across variations
+
+# 3. Document findings
+# 4. Iterate on model/data as needed
+
+# Total time: 5-10 minutes per image
+```
+
+### Workflow 3: Research Experiment
+
+```bash
+# 1. Collect dataset of test images
+# 2. For each explainability method:
+#    - Run on all test images
+#    - Export visualizations
+#    - Compute metrics
+# 3. Compare methods quantitatively
+# 4. Generate paper figures
+
+# Total time: Varies by dataset size
+```
+
+## 🎯 Next Steps
+
+After completing this quick start:
+
+1. **Explore Advanced Features**: Try all four tabs with different images
+2. **Read Technical Docs**: Understand the methods in detail
+3. **Customize Settings**: Adjust parameters for your use case
+4. **Integrate into Workflow**: Use programmatically or via API
+5. **Contribute**: Share improvements or report issues
+
+## 📚 Additional Resources
+
+- **Full Documentation**: [README.md](README.md)
+- **API Reference**: [docs/api.md](docs/api.md)
+- **Video Tutorials**: [YouTube Playlist](#)
+- **Example Notebooks**: [notebooks/](notebooks/)
+- **Community Forum**: [GitHub Discussions](https://github.com/dyra-12/ViT-XAI-Dashboard/discussions)
+
+## 🆘 Getting Help
+
+- **Issues**: [Report bugs](https://github.com/dyra-12/ViT-XAI-Dashboard/issues)
+- **Discussions**: [Ask questions](https://github.com/dyra-12/ViT-XAI-Dashboard/discussions)
+- **Email**: dyra12@example.com
+
+---
+
+**Ready to dive deeper?** Check out the [full documentation](README.md) or [contributing guidelines](CONTRIBUTING.md)!
+
+🎉 **Happy Exploring!** 🎉

README.md

@@ -0,0 +1,495 @@
+# 🎯 ViT Auditing Toolkit
+
+<div align="center">
+
+![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)
+![PyTorch](https://img.shields.io/badge/PyTorch-2.2+-ee4c2c.svg)
+![Transformers](https://img.shields.io/badge/🤗-Transformers-yellow.svg)
+![Gradio](https://img.shields.io/badge/Gradio-4.19+-orange.svg)
+![License](https://img.shields.io/badge/License-MIT-green.svg)
+
+**A Comprehensive Explainability and Validation Dashboard for Vision Transformers**
+
+[🚀 Live Demo](#) | [📖 Documentation](#features) | [💡 Examples](#usage-guide) | [🤝 Contributing](#contributing)
+
+<img src="https://via.placeholder.com/800x400/0f1419/6366f1?text=ViT+Auditing+Toolkit+Dashboard" alt="Dashboard Preview" width="800"/>
+
+</div>
+
+---
+
+## 🌟 Overview
+
+The **ViT Auditing Toolkit** is an advanced, interactive dashboard designed to help researchers, ML practitioners, and AI auditors understand, validate, and improve Vision Transformer (ViT) models. It provides a comprehensive suite of explainability techniques and auditing tools through an intuitive web interface.
+
+### 🎭 Why This Toolkit?
+
+- **🔍 Transparency**: Understand what your ViT models actually "see" and learn
+- **✅ Validation**: Verify model reliability through systematic testing
+- **⚖️ Fairness**: Detect potential biases across different data subgroups  
+- **🛡️ Robustness**: Test prediction stability under various perturbations
+- **📊 Calibration**: Ensure confidence scores reflect true prediction accuracy
+
+---
+
+## ✨ Features
+
+### 🔬 Basic Explainability
+Visualize and understand model predictions through multiple state-of-the-art techniques:
+
+- **🎨 Attention Visualization**: See which image patches the transformer focuses on at each layer and head
+- **🔥 GradCAM**: Gradient-weighted Class Activation Mapping for highlighting discriminative regions
+- **💫 GradientSHAP**: Shapley value-based attribution for pixel-level importance
+
+### 🔄 Counterfactual Analysis
+Test model robustness by systematically perturbing image regions:
+
+- **Patch Perturbation**: Apply blur, blackout, grayscale, or noise to image patches
+- **Sensitivity Mapping**: Identify which regions are critical for predictions
+- **Prediction Stability**: Measure confidence changes and prediction flip rates
+
+### 📊 Confidence Calibration
+Evaluate whether model confidence scores accurately reflect prediction reliability:
+
+- **Calibration Curves**: Visual assessment of confidence vs accuracy alignment
+- **Reliability Diagrams**: Binned analysis of prediction calibration
+- **Metrics Dashboard**: Mean confidence, overconfidence rate, and underconfidence rate
+
+### ⚖️ Bias Detection
+Identify performance disparities across different data subgroups:
+
+- **Subgroup Analysis**: Compare performance across demographic or environmental variations
+- **Fairness Metrics**: Detect systematic biases in model predictions
+- **Comparative Visualization**: Side-by-side analysis of confidence distributions
+
+---
+
+## 🚀 Live Demo
+
+Try the toolkit instantly on Hugging Face Spaces:
+
+### 👉 [Launch Interactive Demo](https://huggingface.co/spaces/YOUR-USERNAME/vit-auditing-toolkit)
+
+*No installation required! Upload an image and start exploring.*
+
+---
+
+## 📸 Screenshots
+
+<div align="center">
+
+### Basic Explainability Interface
+<img src="https://via.placeholder.com/700x400/1a1f2e/a5b4fc?text=Attention+Visualization+%26+Predictions" alt="Basic Explainability" width="700"/>
+
+### Counterfactual Analysis
+<img src="https://via.placeholder.com/700x400/1a1f2e/c4b5fd?text=Patch+Perturbation+Analysis" alt="Counterfactual Analysis" width="700"/>
+
+### Calibration & Bias Detection
+<img src="https://via.placeholder.com/700x400/1a1f2e/f9a8d4?text=Calibration+%26+Bias+Metrics" alt="Advanced Auditing" width="700"/>
+
+</div>
+
+---
+
+## 🎯 Usage Guide
+
+### Quick Start (3 Steps)
+
+1. **Select a Model**: Choose between ViT-Base or ViT-Large from the dropdown
+2. **Upload Your Image**: Any image you want to analyze (JPG, PNG, etc.)
+3. **Choose Analysis Type**: Select from 4 tabs based on your needs
+
+### Detailed Workflow
+
+#### 🔍 For Understanding Predictions:
+```
+1. Go to "Basic Explainability" tab
+2. Upload your image
+3. Select explanation method (Attention/GradCAM/SHAP)
+4. Adjust layer/head indices if needed
+5. Click "Analyze Image"
+6. View predictions and visual explanations
+```
+
+#### 🔄 For Testing Robustness:
+```
+1. Go to "Counterfactual Analysis" tab
+2. Upload your image
+3. Set patch size (16-64 pixels)
+4. Choose perturbation type (blur/blackout/gray/noise)
+5. Click "Run Analysis"
+6. Review sensitivity maps and metrics
+```
+
+#### 📊 For Validating Confidence:
+```
+1. Go to "Confidence Calibration" tab
+2. Upload a sample image
+3. Adjust number of bins for analysis
+4. Click "Analyze Calibration"
+5. Review calibration curves and metrics
+```
+
+#### ⚖️ For Detecting Bias:
+```
+1. Go to "Bias Detection" tab
+2. Upload a sample image
+3. Click "Detect Bias"
+4. Compare performance across generated subgroups
+5. Review fairness metrics
+```
+
+---
+
+## 💻 Local Installation
+
+### Prerequisites
+
+- Python 3.8 or higher
+- CUDA-compatible GPU (optional, but recommended for faster inference)
+- 8GB+ RAM
+
+### Step 1: Clone the Repository
+
+```bash
+git clone https://github.com/dyra-12/ViT-XAI-Dashboard.git
+cd ViT-XAI-Dashboard
+```
+
+### Step 2: Create Virtual Environment (Recommended)
+
+```bash
+# Using venv
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# OR using conda
+conda create -n vit-audit python=3.10
+conda activate vit-audit
+```
+
+### Step 3: Install Dependencies
+
+```bash
+pip install -r requirements.txt
+```
+
+### Step 4: Run the Application
+
+```bash
+python app.py
+```
+
+The dashboard will be available at `http://localhost:7860`
+
+### 🐳 Docker Installation (Alternative)
+
+```bash
+# Build the Docker image
+docker build -t vit-auditing-toolkit .
+
+# Run the container
+docker run -p 7860:7860 vit-auditing-toolkit
+```
+
+---
+
+## 🏗️ Project Structure
+
+```
+ViT-XAI-Dashboard/
+│
+├── app.py                      # Main Gradio application
+├── requirements.txt            # Python dependencies
+├── README.md                   # This file
+│
+├── src/
+│   ├── __init__.py
+│   ├── model_loader.py         # ViT model loading from Hugging Face
+│   ├── predictor.py            # Prediction and classification logic
+│   ├── explainer.py            # XAI methods (Attention, GradCAM, SHAP)
+│   ├── auditor.py              # Advanced auditing tools
+│   └── utils.py                # Helper functions and preprocessing
+│
+└── tests/
+    ├── test_phase1_complete.py # Basic functionality tests
+    └── test_advanced_features.py # Advanced auditing tests
+```
+
+---
+
+## 🧠 Technical Details
+
+### Vision Transformers (ViT)
+
+Vision Transformers apply the transformer architecture (originally designed for NLP) to computer vision tasks. Key concepts:
+
+- **Patch Embedding**: Images are split into fixed-size patches (e.g., 16×16 pixels)
+- **Self-Attention**: Each patch attends to all other patches to capture global context
+- **Layer Hierarchy**: Multiple transformer layers progressively refine representations
+- **Classification Token**: A special [CLS] token aggregates information for final prediction
+
+**Advantages:**
+- Strong performance on large-scale datasets
+- Captures long-range dependencies better than CNNs
+- More interpretable through attention mechanisms
+
+### Explainability Techniques
+
+#### 1. Attention Visualization
+**Method**: Direct visualization of transformer attention weights  
+**Purpose**: Shows which image patches the model focuses on  
+**Implementation**: Extracts attention matrices from specified layers/heads
+
+```python
+# Example: Layer 6, Head 0 typically captures semantic patterns
+attention_map = model.encoder.layer[6].attention.self.attention_weights
+```
+
+#### 2. GradCAM (Gradient-weighted Class Activation Mapping)
+**Method**: Uses gradients flowing into the final conv layer  
+**Purpose**: Highlights discriminative regions for target class  
+**Implementation**: Via Captum's `LayerGradCam`
+
+```python
+# Generates heatmap showing which regions support the prediction
+gradcam = LayerGradCam(model, target_layer)
+attribution = gradcam.attribute(input, target=predicted_class)
+```
+
+#### 3. GradientSHAP (Gradient-based Shapley Values)
+**Method**: Combines Shapley values with gradient information  
+**Purpose**: Pixel-level attribution with theoretical guarantees  
+**Implementation**: Via Captum's `GradientShap`
+
+```python
+# Computes fair attribution using random baselines
+gradient_shap = GradientShap(model)
+attributions = gradient_shap.attribute(input, baselines=random_baselines)
+```
+
+### Auditing Methodologies
+
+#### Counterfactual Analysis
+Systematically modifies image regions to test:
+- **Robustness**: Does the prediction remain stable?
+- **Feature Importance**: Which regions matter most?
+- **Adversarial Vulnerability**: How easy is it to fool the model?
+
+#### Confidence Calibration
+Measures alignment between predicted confidence and actual accuracy:
+- **Well-calibrated**: 80% confidence → 80% correct
+- **Overconfident**: 90% confidence → 60% correct (problem!)
+- **Underconfident**: 50% confidence → 80% correct (less critical)
+
+#### Bias Detection
+Compares performance across subgroups to identify:
+- **Demographic bias**: Different accuracy for different groups
+- **Environmental bias**: Performance varies with lighting, quality, etc.
+- **Systematic patterns**: Consistent over/under-performance
+
+---
+
+## 🔧 Supported Models
+
+Currently supported Vision Transformer models from Hugging Face:
+
+| Model | Parameters | Input Size | Accuracy (ImageNet) |
+|-------|-----------|------------|---------------------|
+| `google/vit-base-patch16-224` | 86M | 224×224 | ~81.3% |
+| `google/vit-large-patch16-224` | 304M | 224×224 | ~82.6% |
+
+**Easy to extend**: Add any Hugging Face ViT model to `src/model_loader.py`
+
+---
+
+## 📦 Dependencies
+
+### Core Libraries
+
+- **PyTorch** (≥2.2.0): Deep learning framework
+- **Transformers** (≥4.35.0): Hugging Face model hub
+- **Gradio** (≥4.19.0): Web interface framework
+- **Captum** (≥0.7.0): Model interpretability library
+
+### Supporting Libraries
+
+- **Pillow**: Image processing
+- **Matplotlib**: Visualization
+- **NumPy**: Numerical computations
+
+See `requirements.txt` for complete list with version constraints.
+
+---
+
+## 🎓 Use Cases
+
+### Research
+- **Interpretability Studies**: Analyze transformer attention patterns
+- **Benchmark Explainability**: Compare XAI methods systematically
+- **Model Auditing**: Validate models before deployment
+
+### Industry
+- **Model Validation**: Ensure reliability before production
+- **Bias Auditing**: Detect and mitigate fairness issues
+- **Regulatory Compliance**: Document model decision-making
+
+### Education
+- **Teaching Tool**: Demonstrate XAI concepts interactively
+- **Student Projects**: Foundation for ML course assignments
+- **Research Training**: Hands-on experience with modern techniques
+
+---
+
+## 🛣️ Roadmap
+
+### Upcoming Features
+- [ ] Support for additional ViT variants (DeiT, BEiT, Swin Transformer)
+- [ ] Batch processing for multiple images
+- [ ] Export functionality for reports and visualizations
+- [ ] Custom model upload support
+- [ ] Comparative analysis across multiple models
+- [ ] Integration with model monitoring platforms
+- [ ] Advanced bias metrics (demographic parity, equalized odds)
+- [ ] Adversarial robustness testing
+- [ ] API endpoint for programmatic access
+
+### Long-term Vision
+- Multi-modal transformer support (CLIP, ViLT)
+- Video analysis capabilities
+- Automated auditing pipelines
+- Integration with MLOps platforms
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Here's how you can help:
+
+### Ways to Contribute
+
+1. **🐛 Bug Reports**: Open an issue with detailed reproduction steps
+2. **✨ Feature Requests**: Suggest new explainability methods or auditing tools
+3. **📝 Documentation**: Improve guides, add examples, fix typos
+4. **💻 Code**: Submit pull requests for new features or fixes
+5. **🎨 UI/UX**: Enhance the dashboard design and user experience
+
+### Development Setup
+
+```bash
+# Fork and clone the repository
+git clone https://github.com/YOUR-USERNAME/ViT-XAI-Dashboard.git
+cd ViT-XAI-Dashboard
+
+# Create a feature branch
+git checkout -b feature/your-feature-name
+
+# Make changes and test
+python -m pytest tests/
+
+# Commit and push
+git commit -m "Add: your feature description"
+git push origin feature/your-feature-name
+
+# Open a pull request
+```
+
+### Code Style
+- Follow PEP 8 guidelines
+- Add docstrings to all functions
+- Include type hints where applicable
+- Write unit tests for new features
+
+---
+
+## 📄 License
+
+This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.
+
+```
+MIT License
+
+Copyright (c) 2024 ViT Auditing Toolkit 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, 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:
+
+[Full license text...]
+```
+
+---
+
+## 📚 References & Citations
+
+### Academic Papers
+
+1. **Vision Transformers**  
+   Dosovitskiy, A., et al. (2021). "An Image is Worth 16x16 Words: Transformers for Image Recognition at Scale." *ICLR 2021*.
+
+2. **GradCAM**  
+   Selvaraju, R. R., et al. (2017). "Grad-CAM: Visual Explanations from Deep Networks via Gradient-based Localization." *ICCV 2017*.
+
+3. **SHAP**  
+   Lundberg, S. M., & Lee, S. I. (2017). "A Unified Approach to Interpreting Model Predictions." *NeurIPS 2017*.
+
+4. **Model Calibration**  
+   Guo, C., et al. (2017). "On Calibration of Modern Neural Networks." *ICML 2017*.
+
+### Related Tools
+
+- [Captum](https://captum.ai/): Model interpretability for PyTorch
+- [Hugging Face Transformers](https://huggingface.co/transformers/): State-of-the-art NLP and Vision models
+- [Gradio](https://gradio.app/): Fast ML demo creation
+
+### Citation
+
+If you use this toolkit in your research, please cite:
+
+```bibtex
+@software{vit_auditing_toolkit_2024,
+  title={ViT Auditing Toolkit: Comprehensive Explainability for Vision Transformers},
+  author={dyra-12},
+  year={2024},
+  url={https://github.com/dyra-12/ViT-XAI-Dashboard}
+}
+```
+
+---
+
+## 🙏 Acknowledgments
+
+- **Hugging Face** for providing pre-trained ViT models and the Transformers library
+- **Captum Team** for the excellent interpretability library
+- **Gradio Team** for the intuitive ML interface framework
+- **PyTorch Community** for the robust deep learning ecosystem
+- All contributors and users who provide feedback and improvements
+
+---
+
+## 📧 Contact & Support
+
+- **GitHub Issues**: [Report bugs or request features](https://github.com/dyra-12/ViT-XAI-Dashboard/issues)
+- **Discussions**: [Ask questions or share ideas](https://github.com/dyra-12/ViT-XAI-Dashboard/discussions)
+- **Email**: dyra12@example.com
+
+---
+
+## 🌟 Star History
+
+If you find this project useful, please consider giving it a ⭐️ on GitHub!
+
+[![Star History Chart](https://api.star-history.com/svg?repos=dyra-12/ViT-XAI-Dashboard&type=Date)](https://star-history.com/#dyra-12/ViT-XAI-Dashboard&Date)
+
+---
+
+<div align="center">
+
+**Built with ❤️ by the community**
+
+[⬆ Back to Top](#-vit-auditing-toolkit)
+
+</div>

docker-compose.yml

@@ -0,0 +1,21 @@
+version: '3.8'
+
+services:
+  vit-auditing-toolkit:
+    build: .
+    container_name: vit-auditing-toolkit
+    ports:
+      - "7860:7860"
+    environment:
+      - GRADIO_SERVER_NAME=0.0.0.0
+      - GRADIO_SERVER_PORT=7860
+    volumes:
+      - ./models:/app/models  # Cache downloaded models
+      - ./examples:/app/examples  # Mount example images
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:7860/"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 60s