CONTRIBUTING.md

Contributing to MediGuard AI RAG-Helper

First off, thank you for considering contributing to MediGuard AI! It's people like you that make this project better for everyone.

📋 Table of Contents

• Code of Conduct
• Getting Started
• How Can I Contribute?
• Development Setup
• Style Guidelines
• Commit Messages
• Pull Request Process

Code of Conduct

This project adheres to a code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers.

Our Standards

• Be Respectful: Treat everyone with respect
• Be Collaborative: Work together effectively
• Be Professional: Maintain professionalism at all times
• Be Inclusive: Welcome diverse perspectives and backgrounds

Getting Started

Prerequisites

• Python 3.11+
• Git
• A GitHub account
• FREE API key from Groq or Google Gemini

First Contribution

1. Fork the repository
2. Clone your fork

   git clone https://github.com/your-username/RagBot.git
   cd RagBot
   

3. Set up development environment (see below)
4. Create a new branch

   git checkout -b feature/your-feature-name
   

How Can I Contribute?

🐛 Reporting Bugs

Before submitting a bug report:

• Check the existing issues
• Ensure you're using the latest version
• Collect relevant information (Python version, OS, error messages)

How to submit a good bug report:

• Use a clear and descriptive title
• Describe the exact steps to reproduce
• Provide specific examples
• Describe the behavior you observed and what you expected
• Include screenshots if applicable
• Include your environment details

Template:

## Bug Description
[Clear description of the bug]

## Steps to Reproduce
1. 
2. 
3. 

## Expected Behavior
[What should happen]

## Actual Behavior
[What actually happens]

## Environment
- OS: [e.g., Windows 11, macOS 14, Ubuntu 22.04]
- Python Version: [e.g., 3.11.5]
- MediGuard Version: [e.g., 1.0.0]

## Additional Context
[Any other relevant information]

💡 Suggesting Enhancements

Before submitting an enhancement suggestion:

• Check if it's already been suggested
• Determine which part of the project it relates to
• Consider if it aligns with the project's goals

How to submit a good enhancement suggestion:

• Use a clear and descriptive title
• Provide a detailed description of the proposed enhancement
• Explain why this enhancement would be useful
• List potential benefits and drawbacks
• Provide examples or mockups if applicable

🔨 Pull Requests

Good first issues:

• Look for issues labeled good first issue
• Documentation improvements
• Test coverage improvements
• Bug fixes

Areas needing contribution:

• Additional biomarker support
• Disease model improvements
• Performance optimizations
• Documentation enhancements
• Test coverage
• UI/UX improvements

Development Setup

1. Fork and Clone

# Fork via GitHub UI, then:
git clone https://github.com/your-username/RagBot.git
cd RagBot

2. Create Virtual Environment

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install Dependencies

# Core dependencies
pip install -r requirements.txt

# Development dependencies
pip install pytest pytest-cov black flake8 mypy

4. Configure Environment

cp .env.template .env
# Edit .env with your API keys

5. Run Tests

# Run unit tests (30 tests)
.venv\Scripts\python.exe -m pytest tests/ -q \
  --ignore=tests/test_basic.py \
  --ignore=tests/test_diabetes_patient.py \
  --ignore=tests/test_evolution_loop.py \
  --ignore=tests/test_evolution_quick.py \
  --ignore=tests/test_evaluation_system.py

# Run with coverage
.venv\Scripts\python.exe -m pytest --cov=src tests/

# Run specific test file
.venv\Scripts\python.exe -m pytest tests/test_codebase_fixes.py -v

Style Guidelines

Python Code Style

We follow PEP 8 with some modifications:

• Line length: 100 characters maximum
• Imports: Organized with isort
• Formatting: Automated with black
• Type hints: Required for function signatures
• Docstrings: Google style

Code Formatting

Before committing, run:

# Auto-format code
black src/ scripts/ tests/

# Check style compliance
flake8 src/ scripts/ tests/

# Type checking
mypy src/

# Import sorting
isort src/ scripts/ tests/

Docstring Example

def analyze_biomarkers(
    biomarkers: Dict[str, float],
    patient_context: Optional[Dict[str, Any]] = None
) -> AnalysisResult:
    """
    Analyze patient biomarkers and generate clinical insights.
    
    Args:
        biomarkers: Dictionary of biomarker names to values
        patient_context: Optional patient demographic information
        
    Returns:
        AnalysisResult containing predictions and recommendations
        
    Raises:
        ValueError: If biomarkers dictionary is empty
        ValidationError: If biomarker values are invalid
        
    Example:
        >>> result = analyze_biomarkers({"Glucose": 185, "HbA1c": 8.2})
        >>> print(result.prediction.disease)
        'Diabetes'
    """
    pass

Testing Guidelines

• Write tests for all new features
• Maintain coverage above 80%
• Test edge cases and error conditions
• Use descriptive test names

Test Example:

def test_biomarker_validation_with_critical_high_glucose():
    """Test that critically high glucose values trigger safety alerts."""
    validator = BiomarkerValidator()
    biomarkers = {"Glucose": 400}  # Critically high
    
    flags, alerts = validator.validate_all(biomarkers)
    
    assert len(alerts) > 0
    assert any("critical" in alert.message.lower() for alert in alerts)

Commit Messages

Format

<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

# Good commit messages
git commit -m "feat(agents): add liver disease detection agent"
git commit -m "fix(validation): correct hemoglobin range for females"
git commit -m "docs: update API documentation with new endpoints"
git commit -m "test: add integration tests for workflow"

# Bad commit messages (avoid these)
git commit -m "fixed stuff"
git commit -m "updates"
git commit -m "WIP"

Pull Request Process

Before Submitting

1. ✅ Update your branch with latest main

   git checkout main
   git pull upstream main
   git checkout your-feature-branch
   git rebase main
   

2. ✅ Run all tests and ensure they pass

   pytest
   

3. ✅ Format your code

   black src/ scripts/ tests/
   flake8 src/ scripts/ tests/
   

4. ✅ Update documentation if needed

   • README.md
   • Docstrings
   • API documentation

5. ✅ Add/update tests for your changes

Submitting the PR

1. Push to your fork

   git push origin your-feature-branch
   

2. Create pull request via GitHub UI

3. Fill out the PR template completely

PR Template

## Description
[Clear description of what this PR does]

## Type of Change
- [ ] Bug fix (non-breaking change)
- [ ] New feature (non-breaking change)
- [ ] Breaking change
- [ ] Documentation update

## Related Issues
Fixes #[issue number]

## Testing
- [ ] All tests pass locally
- [ ] Added new tests for changes
- [ ] Updated existing tests

## Checklist
- [ ] Code follows project style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex code
- [ ] Documentation updated
- [ ] No new warnings generated

Review Process

1. Automated checks must pass (if configured)
2. Code review by maintainer(s)
3. Address feedback if requested
4. Approval from maintainer
5. Merge by maintainer

After Merge

• Delete your feature branch
• Update your fork's main branch
• Celebrate! 🎉

Project Structure

Understanding the codebase:

src/
├── agents/          # Specialist agent implementations
├── evaluation/      # Quality evaluation framework
├── evolution/       # Self-improvement engine
├── biomarker_validator.py  # Validation logic
├── config.py        # Configuration classes
├── llm_config.py    # LLM setup
├── pdf_processor.py # Vector store management
├── state.py         # State definitions
└── workflow.py      # Main workflow orchestration

Development Tips

Local Testing

# Test specific component
python -c "from src.biomarker_validator import BiomarkerValidator; v = BiomarkerValidator(); print('OK')"

# Test workflow initialization
python -c "from src.workflow import create_guild; guild = create_guild(); print('Guild OK')"

# Test chat interface
python scripts/chat.py

Debugging

• Use print() statements liberally during development
• Set LANGCHAIN_TRACING_V2="true" for LLM call tracing
• Check logs in the console output
• Use Python debugger: import pdb; pdb.set_trace()

Common Issues

Import errors:

• Ensure you're in the project root directory
• Check virtual environment is activated

API errors:

• Verify API keys in .env
• Check rate limits haven't been exceeded

Vector store errors:

• Ensure FAISS indices exist in data/vector_stores/
• Run python src/pdf_processor.py to rebuild if needed

Questions?

• General questions: Open a GitHub Discussion
• Bug reports: Open a GitHub Issue
• Security concerns: Email maintainers directly

Recognition

Contributors will be recognized in:

• Project README
• Release notes
• Special mentions for significant contributions

Thank you for contributing! 🙏