Merge pull request #1931 from bluewave-labs/develop

Merging Develop into Master: August 18th 2025

Author: HarshP4585

BiasAndFairnessModule/.gitignore

@@ -0,0 +1,5 @@
+<<<<<<< HEAD
+*.zip
+=======
+/artifacts
+>>>>>>> upstream/develop

BiasAndFairnessModule/INSTALLATION.md

@@ -0,0 +1,208 @@
+# Installation Guide
+
+This guide covers how to install and set up the Bias and Fairness Module.
+
+## Prerequisites
+
+- Python 3.8 or higher (tested with Python 3.12)
+- pip package manager
+- Virtual environment (recommended)
+
+## Quick Start
+
+### 1. Clone the Repository
+
+```bash
+git clone <repository-url>
+cd BiasAndFairnessModule
+```
+
+### 2. Create and Activate Virtual Environment
+
+```bash
+# Create virtual environment
+python -m venv venv
+
+# Activate virtual environment
+# On macOS/Linux:
+source venv/bin/activate
+
+# On Windows:
+venv\Scripts\activate
+```
+
+### 3. Install Dependencies
+
+#### Option A: Install with Flexible Versions (Recommended)
+
+```bash
+pip install -r requirements.txt
+```
+
+#### Option B: Install with Exact Versions (Reproducible)
+
+```bash
+pip install -r requirements-exact.txt
+```
+
+#### Option C: Install Development Dependencies
+
+```bash
+pip install -r requirements-dev.txt
+```
+
+## Dependency Categories
+
+### Core Dependencies
+
+- **numpy**: Numerical computing (version 1.26.4, < 2.0.0 for compatibility)
+- **pandas**: Data manipulation and analysis
+- **pydantic**: Data validation and settings management
+- **pyyaml**: YAML configuration file parsing
+
+### Machine Learning and Fairness
+
+- **scikit-learn**: Machine learning algorithms and utilities
+- **fairlearn**: Fairness metrics and algorithms
+- **langfair**: Language model fairness evaluation
+
+### Deep Learning and Transformers
+
+- **torch**: PyTorch deep learning framework
+- **transformers**: Hugging Face transformers library
+- **sentence-transformers**: Sentence embedding models
+- **huggingface-hub**: Model and dataset hub integration
+
+### Data Handling
+
+- **datasets**: Hugging Face datasets library
+- **pyarrow**: Fast data serialization
+
+### Utilities
+
+- **tqdm**: Progress bars for long-running operations
+
+## Version Compatibility Notes
+
+### NumPy Version Constraint
+
+The module requires NumPy version **>= 1.26.4, < 2.0.0** due to:
+
+- Compatibility with `langfair` package
+- Stability with existing machine learning ecosystem
+- Avoidance of breaking changes in NumPy 2.x
+
+### PyTorch Installation
+
+For GPU support, you may need to install PyTorch with CUDA:
+
+```bash
+# For CUDA 11.8
+pip install torch>=2.7.0+cu118 --extra-index-url https://download.pytorch.org/whl/cu118
+
+# For CUDA 12.1
+pip install torch>=2.7.0+cu121 --extra-index-url https://download.pytorch.org/whl/cu121
+```
+
+## Development Setup
+
+### 1. Install Development Dependencies
+
+```bash
+pip install -r requirements-dev.txt
+```
+
+### 2. Install Pre-commit Hooks (Optional)
+
+```bash
+pre-commit install
+```
+
+### 3. Verify Installation
+
+```bash
+# Run tests
+make test
+
+# Run code quality checks
+make check
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### NumPy Version Conflicts
+
+If you encounter NumPy version conflicts:
+
+```bash
+pip uninstall numpy
+pip install "numpy>=1.26.4,<2.0.0"
+```
+
+#### Import Errors
+
+If you get import errors:
+
+1. Ensure you're in the virtual environment
+2. Check that all dependencies are installed
+3. Verify Python path includes the project directory
+
+#### CUDA Issues
+
+If PyTorch CUDA is not working:
+
+1. Check CUDA version: `nvidia-smi`
+2. Install matching PyTorch version
+3. Verify GPU drivers are up to date
+
+### Environment Variables
+
+Set these environment variables if needed:
+
+```bash
+export PYTHONPATH="${PYTHONPATH}:/path/to/BiasAndFairnessModule/src"
+export CUDA_VISIBLE_DEVICES=0  # For GPU usage
+```
+
+## Verification
+
+After installation, verify everything works:
+
+```bash
+# Run the test suite
+python run_tests.py
+
+# Test basic functionality
+python -c "from src import ConfigManager; print('✅ Installation successful!')"
+```
+
+## Updating Dependencies
+
+### Update All Dependencies
+
+```bash
+pip install --upgrade -r requirements.txt
+```
+
+### Update Specific Package
+
+```bash
+pip install --upgrade package_name
+```
+
+### Generate New Requirements Files
+
+```bash
+pip freeze > requirements-new.txt
+```
+
+## Support
+
+If you encounter issues:
+
+1. Check the troubleshooting section above
+2. Verify your Python and package versions
+3. Check the project's issue tracker
+4. Ensure you're using the recommended Python version (3.8+)

BiasAndFairnessModule/Makefile

@@ -1,10 +1,92 @@
+# Virtual environment setup
+venv:
+	python -m venv venv
+	. venv/bin/activate && pip install --upgrade pip
+
+# Install dependencies
+install: venv
+	. venv/bin/activate && pip install -r requirements.txt
+
+install-dev: venv
+	. venv/bin/activate && pip install -r requirements-dev.txt
+
+install-exact: venv
+	. venv/bin/activate && pip install -r requirements-exact.txt
+
+# Code formatting
 format:
+ifdef FILE
+	black $(FILE)
+	isort $(FILE)
+else
 	black . --exclude '(\.venv|venv)'
 	isort . --skip .venv
+endif
 
+# Code quality checks
 lint:
+ifdef FILE
+	flake8 $(FILE)
+	mypy $(FILE)
+	pylint $(FILE)
+else
 	flake8 . --exclude=.venv
 	mypy . --exclude .venv
 	pylint $(shell find . -type f -name "*.py" ! -path "./.venv/*")
+endif
+
+# Testing
+test:
+	. venv/bin/activate && python run_tests.py
+
+# Unit tests
+test-unit:
+	. venv/bin/activate && python src/tests/run_unit_tests.py
+
+test-metrics:
+	. venv/bin/activate && python src/tests/run_unit_tests.py src.tests.unit.test_metrics
+
+test-registry:
+	. venv/bin/activate && python src/tests/run_unit_tests.py src.tests.unit.test_metric_registry
+
+# Legacy test commands (for backward compatibility)
+test-evaluation:
+	. venv/bin/activate && python -m src.tests.run_all_tests evaluation
+
+test-config:
+	. venv/bin/activate && python -m src.tests.run_all_tests config
+
+test-compass:
+	. venv/bin/activate && python -m src.tests.run_all_tests compass
+
+test-coverage:
+	. venv/bin/activate && coverage run python run_tests.py
+	. venv/bin/activate && coverage report
+	. venv/bin/activate && coverage html
+
+# Development workflow
+check: format lint test
+
+# Environment status
+status:
+	@echo "Python version:"
+	@python --version
+	@echo "Python path:"
+	@which python
+	@echo "NumPy version:"
+	@python -c "import numpy; print(numpy.__version__)"
+	@echo "Virtual environment:"
+	@echo "$$VIRTUAL_ENV"
+
+# Environment check
+check-env:
+	. venv/bin/activate && python check_environment.py
 
-check: format lint
+# Clean up
+clean:
+	find . -type f -name "*.pyc" -delete
+	find . -type d -name "__pycache__" -delete
+	find . -type d -name "*.egg-info" -delete
+	rm -rf .pytest_cache
+	rm -rf htmlcov
+	rm -rf .coverage