CONTRIBUTING.md

# Contributing

Thanks for wanting to contribute! This repository uses a strict CI and formatting policy to keep code consistent, with special emphasis on memory-efficient development for cloud deployment.

## 🧠 Memory-Constrained Development Guidelines

This project is optimized for deployment on Render's free tier (512MB RAM limit). All contributions must consider memory usage as a primary constraint.

### Memory Development Principles

1. **Memory-First Design**: Consider memory impact of every code change
2. **Lazy Loading**: Initialize services only when needed
3. **Resource Cleanup**: Always clean up resources in finally blocks or context managers
4. **Memory Testing**: Test changes in memory-constrained environments
5. **Monitoring Integration**: Add memory tracking to new services

### Memory-Aware Code Guidelines

**✅ DO - Memory Efficient Patterns:**

```python
# Use context managers for resource cleanup
from src.utils.memory_utils import MemoryManager

with MemoryManager() as mem:
    # Memory-intensive operations
    embeddings = process_large_dataset(data)
    # Automatic cleanup on exit

# Implement lazy loading for expensive services
@lru_cache(maxsize=1)
def get_expensive_service():
    return ExpensiveService()  # Only created once

# Use generators for large data processing
def process_documents(documents):
    for doc in documents:
        yield process_single_document(doc)  # Memory efficient iteration
```

**❌ DON'T - Memory Wasteful Patterns:**

```python
# Don't load all data into memory at once
all_embeddings = [embed(doc) for doc in all_documents]  # Memory spike

# Don't create multiple instances of expensive services
service1 = ExpensiveMLModel()
service2 = ExpensiveMLModel()  # Duplicates memory usage

# Don't keep large objects in global scope
GLOBAL_LARGE_DATA = load_entire_dataset()  # Always consumes memory
```

## 🛠️ Recommended Local Setup

We recommend using `pyenv` + `venv` to create a reproducible development environment. A helper script `dev-setup.sh` is included to automate the steps:

```bash
# Run the helper script (default Python version can be overridden)
./dev-setup.sh 3.11.4
source venv/bin/activate

# Install pre-commit hooks
pip install -r dev-requirements.txt
pre-commit install
```

### Memory-Constrained Testing Environment

**Test your changes in a memory-limited environment:**

```bash
# Limit Python process memory to simulate Render constraints (macOS/Linux)
ulimit -v 524288  # 512MB limit in KB

# Run your development server
flask run

# Test memory usage
curl http://localhost:5000/health | jq '.memory_usage_mb'
```

## 🧪 Development Workflow

### Before Opening a PR

**Required Checks:**

1. **Code Quality**: `make format` and `make ci-check`
2. **Test Suite**: `pytest` (all 138 tests must pass)
3. **Pre-commit**: `pre-commit run --all-files`
4. **Memory Testing**: Verify memory usage stays within limits

**Memory-Specific Testing:**

```bash
# Test memory usage during development
python -c "
from src.app_factory import create_app
from src.utils.memory_utils import MemoryManager
app = create_app()
with app.app_context():
    mem = MemoryManager()
    print(f'App startup memory: {mem.get_memory_usage():.1f}MB')
    # Should be ~50MB or less
"

# Test first request memory loading
curl -X POST http://localhost:5000/chat -H "Content-Type: application/json" \
  -d '{"message": "test"}' && \
curl http://localhost:5000/health | jq '.memory_usage_mb'
# Should be ~200MB or less
```

### Memory Optimization Development Process

1. **Profile Before Changes**: Measure baseline memory usage
2. **Implement Changes**: Follow memory-efficient patterns
3. **Profile After Changes**: Verify memory impact is acceptable
4. **Load Test**: Validate performance under memory constraints
5. **Document Changes**: Update memory-related documentation

### New Feature Development Guidelines

**When Adding New ML Services:**

```python
# Example: Adding a new ML service with memory management
class NewMLService:
    def __init__(self):
        self._model = None  # Lazy loading

    @property
    def model(self):
        if self._model is None:
            with MemoryManager() as mem:
                logger.info(f"Loading model, current memory: {mem.get_memory_usage():.1f}MB")
                self._model = load_expensive_model()
                logger.info(f"Model loaded, current memory: {mem.get_memory_usage():.1f}MB")
        return self._model

    def process(self, data):
        # Use the lazily-loaded model
        return self.model.predict(data)
```

**Memory Testing for New Features:**

```python
# Add to your test file
def test_new_feature_memory_usage():
    """Test that new feature doesn't exceed memory limits"""
    import psutil
    import os

    # Measure before
    process = psutil.Process(os.getpid())
    memory_before = process.memory_info().rss / 1024 / 1024  # MB

    # Execute new feature
    result = your_new_feature()

    # Measure after
    memory_after = process.memory_info().rss / 1024 / 1024  # MB
    memory_increase = memory_after - memory_before

    # Assert memory increase is reasonable
    assert memory_increase < 50, f"Memory increase {memory_increase:.1f}MB exceeds 50MB limit"
    assert memory_after < 300, f"Total memory {memory_after:.1f}MB exceeds 300MB limit"
```

## 🔧 CI Expectations

**Automated Checks:**

- **Code Quality**: Pre-commit hooks (black, isort, flake8)
- **Test Suite**: All 138 tests must pass
- **Memory Validation**: Memory usage checks during CI
- **Performance Regression**: Response time validation
- **Python Version**: Enforces Python >=3.10

**Memory-Specific CI Checks:**

```bash
# CI pipeline includes memory validation
pytest tests/test_memory_constraints.py  # Memory usage tests
pytest tests/test_performance.py         # Response time validation
pytest tests/test_resource_cleanup.py    # Resource leak detection
```

## 🚀 Deployment Considerations

### Render Platform Constraints

**Resource Limits:**

- **RAM**: 512MB total (200MB steady state, 312MB headroom)
- **CPU**: 0.1 vCPU (I/O bound workload)
- **Storage**: 1GB (current usage ~100MB)
- **Network**: Unmetered (external API calls)

**Performance Requirements:**

- **Startup Time**: <30 seconds (lazy loading)
- **Response Time**: <3 seconds for chat requests
- **Memory Stability**: No memory leaks over 24+ hours
- **Concurrent Users**: Support 20-30 simultaneous requests

### Production Testing

**Before Production Deployment:**

```bash
# Test with production configuration
export FLASK_ENV=production
gunicorn -c gunicorn.conf.py app:app &

# Load test with memory monitoring
artillery run load-test.yml  # Simulate concurrent users
curl http://localhost:5000/health | jq '.memory_usage_mb'

# Memory leak detection (run for 1+ hours)
while true; do
  curl -s http://localhost:5000/health | jq '.memory_usage_mb'
  sleep 300  # Check every 5 minutes
done
```

## 📚 Additional Resources

### Memory Optimization References

- **[Memory Utils Documentation](./src/utils/memory_utils.py)**: Comprehensive memory management utilities
- **[App Factory Pattern](./src/app_factory.py)**: Lazy loading implementation
- **[Gunicorn Configuration](./gunicorn.conf.py)**: Production server optimization
- **[Design Documentation](./design-and-evaluation.md)**: Memory architecture decisions

### Development Tools

```bash
# Memory profiling during development
pip install memory-profiler
python -m memory_profiler your_script.py

# Real-time memory monitoring
pip install psutil
python -c "
import psutil
process = psutil.Process()
print(f'Memory: {process.memory_info().rss / 1024 / 1024:.1f}MB')
"
```

## 🎯 Code Review Guidelines

### Memory-Focused Code Review

**Review Checklist:**

- [ ] Does the code follow lazy loading patterns?
- [ ] Are expensive resources properly cleaned up?
- [ ] Is memory usage tested and validated?
- [ ] Are there any potential memory leaks?
- [ ] Does the change impact startup memory?
- [ ] Is caching used appropriately?

**Memory Review Questions:**

1. "What is the memory impact of this change?"
2. "Could this cause a memory leak in long-running processes?"
3. "Is this resource initialized only when needed?"
4. "Are all expensive objects properly cleaned up?"
5. "How does this scale with concurrent users?"

Thank you for contributing to memory-efficient, production-ready RAG development! Please open issues or PRs against `main` and follow these memory-conscious development practices.