CONTRIBUTING.md

# Contributing Guide

Thank you for your interest in contributing to the Multimodal Skin Lesion Explainability project! This guide will help you get started.

## Code of Conduct

Please follow [HuggingFace's Code of Conduct](https://huggingface.co/code-of-conduct) in all interactions.

## Getting Started

### 1. Fork & Clone
```bash
# Fork the repository at HuggingFace or GitHub
git clone https://huggingface.co/spaces/<your-username>/<your-fork>
cd GradCAMPlusPlus_SkinLesion
```

### 2. Set Up Environment
```bash
# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies with dev tools
pip install -r requirements.txt
pip install black flake8 pytest  # Optional: for code style
```

### 3. Verify Installation
```bash
python app.py  # Should launch Gradio without errors
```

## Development Workflow

### Making Changes

1. **Create a feature branch**
   ```bash
   git checkout -b feature/your-feature-name
   ```

2. **Make your changes**
   - Follow existing code style
   - Add type hints to new functions
   - Include docstrings for complex logic

3. **Test locally**
   ```bash
   python app.py
   # Test the UI thoroughly before pushing
   ```

4. **Format code** (optional but recommended)
   ```bash
   black src/ app.py
   flake8 src/ app.py
   ```

5. **Commit with clear messages**
   ```bash
   git add .
   git commit -m "feat: add new feature description"
   ```

6. **Push and create Pull Request**
   ```bash
   git push origin feature/your-feature-name
   ```

## Types of Contributions

### 🐛 Bug Reports
**Found an issue?** Check [Issues](../../issues) first, then report with:
- Describe the bug clearly
- Steps to reproduce
- Expected vs. actual behavior
- Screenshots if relevant
- Environment details (OS, Python version, GPU/CPU)

### ✨ Feature Requests
**Have an idea?** Create an issue with:
- Clear description of the feature
- Why it's useful
- Suggested implementation (if you have one)
- Examples of similar solutions

### 📚 Documentation
**Improve docs?** Edit:
- `README.md` - Main documentation
- `DEPLOYMENT.md` - Deployment guide
- Code docstrings - Inline documentation
- Create tutorials or examples

### 🔧 Code Improvements

#### Areas for Contribution:
- **Model Improvements**: Optimize attention mechanisms, add new architectures
- **UI/UX**: Enhance Gradio interface, add new visualizations
- **Performance**: Reduce inference time, optimize memory usage
- **Testing**: Add test cases, improve code coverage
- **Documentation**: Add docstrings, improve clarity

#### Code Standards:
```python
# Type hints required
from typing import Optional, Tuple, List

def process_metadata(values: dict, enabled_groups: List[str]) -> str:
    """
    Process metadata values and generate CSV format.
    
    Args:
        values: Dictionary of patient/lesion fields
        enabled_groups: List of active metadata groups
        
    Returns:
        CSV-formatted string
        
    Raises:
        ValueError: If required fields are missing
    """
    # Implementation...
```

## Project Structure Reference

```
src/
├── main.py                    # Gradio UI - Safe to modify
├── models/
│   ├── inference.py          # Model loading - Core logic
│   ├── model_loader.py       # PyTorch model setup
│   ├── cam.py                # GradCAM++ implementation
│   ├── preprocessing.py      # Image/metadata processing
│   ├── metadata_*.py         # Metadata handling
│   └── ...                   # Attention mechanism files
utils/
├── transforms.py             # Image transformations
└── load_local_variables.py   # Configuration loading

data/
├── weights/TO_BE_USED/       # Model files (do not commit large files)
└── preprocess_data/          # Encoders, scalers
```

## Areas to Avoid (Breaking Changes)

- **Do not modify**: Input/output format of `run_inference()` without coordination
- **Do not change**: Metadata CSV schema without updating documentation
- **Do not remove**: Core model classes without providing migration path
- **Do not alter**: Pre-trained model weights (they're frozen)

## Testing

### Manual Testing
```bash
# Run the app locally
python app.py

# Test scenarios:
1. Upload test image (try different formats)
2. Toggle metadata groups
3. Test all model options
4. Verify heatmap generation
5. Check metadata CSV output
```

### Automated Testing (Optional)
```bash
# Create tests/test_inference.py
import pytest
from src.models.inference import get_available_model_choices

def test_model_loading():
    choices = get_available_model_choices()
    assert len(choices) > 0, "No models available"
    assert all(isinstance(c, tuple) for c in choices)

# Run tests
pytest tests/
```

## Deployment Considerations

Before submitting PR with changes:
- [ ] Changes work locally with `python app.py`
- [ ] No new dependencies added without updating `requirements.txt`
- [ ] No hardcoded local paths
- [ ] All imports are available in requirements
- [ ] Code produces no warnings when run

## GPU/Performance Notes

- Models are cached after first load - don't reload unnecessarily
- Use `torch.no_grad()` for inference (already implemented)
- Profile code for bottlenecks: `python -m cProfile app.py`

## Documentation Standards

### For New Features
1. Update `README.md` with feature description
2. Add docstrings to functions
3. Include usage examples in docstrings
4. Update relevant guide (DEPLOYMENT.md, etc.)

### Example Docstring
```python
def generate_heatmap(image_tensor: torch.Tensor, metadata_tensor: torch.Tensor) -> np.ndarray:
    """
    Generate GradCAM++ heatmap for given inputs.
    
    This method computes class-weighted gradients and generates attention maps.
    The output can be overlaid on the original image for visualization.
    
    Args:
        image_tensor: Preprocessed image (1, 3, H, W)
        metadata_tensor: Encoded metadata (1, 20)
        
    Returns:
        Normalized heatmap (H, W) with values in [0, 1]
        
    Example:
        >>> image = torch.randn(1, 3, 224, 224)
        >>> metadata = torch.randn(1, 20)
        >>> heatmap = generate_heatmap(image, metadata)
        >>> assert heatmap.shape == (224, 224)
    """
```

## Commit Message Style

Follow conventional commits:
```
feat: add new attention mechanism
fix: resolve heatmap generation bug
docs: update README with new feature
style: format code with black
refactor: optimize inference pipeline
test: add unit tests for metadata builder
chore: update dependencies
```

## Getting Help

- **Questions**: Post in [Discussions](../../discussions)
- **Documentation**: Check README.md and DEPLOYMENT.md
- **Issues**: Search existing issues first
- **Code Review**: Tag maintainers in your PR

## Recognition

Contributors will be:
- Listed in project README
- Credited in git commits
- Thanked in release notes
- Considered for maintainer roles (for significant contributions)

## Legal

- By contributing, you agree your work may be used under the MIT License
- Ensure you have rights to any code you submit
- Respect intellectual property and attribution

## Review Process

1. **Automated Checks**: CI/CD runs automatically
   - Code format check
   - Import validation
   - Model loading verification

2. **Manual Review**: Maintainers review for:
   - Code quality and style
   - Alignment with project goals
   - Documentation completeness
   - Performance impact

3. **Merge**: Once approved, changes are merged to main

## Questions?

- Check existing [Issues](../../issues)
- Read [DEPLOYMENT.md](DEPLOYMENT.md) for deployment questions
- Open a [Discussion](../../discussions) for questions

---

**Thank you for contributing!** 🙏

Together we make skin lesion analysis more transparent and interpretable.

**Last Updated**: March 2026