CONTRIBUTING.md

# Contributing to Numbskull

Thank you for your interest in contributing to Numbskull! This document provides guidelines and information for contributors.

## 🚀 Getting Started

### Prerequisites

- Python 3.8 or higher
- Git
- Basic understanding of embedding systems and machine learning

### Development Setup

1. **Fork the repository**
   ```bash
   git clone https://github.com/your-username/numbskull.git
   cd numbskull
   ```

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

3. **Install dependencies**
   ```bash
   pip install -r requirements.txt
   pip install -e .  # Install in development mode
   ```

4. **Install development dependencies**
   ```bash
   pip install pytest black flake8 mypy
   ```

5. **Run tests**
   ```bash
   cd advanced_embedding_pipeline
   python simple_test.py
   ```

## 🎯 How to Contribute

### Types of Contributions

1. **Bug Reports**: Report issues you find
2. **Feature Requests**: Suggest new features
3. **Code Contributions**: Fix bugs or add features
4. **Documentation**: Improve documentation
5. **Testing**: Add tests or improve test coverage

### Contribution Workflow

1. **Create an Issue**
   - Describe the problem or feature request
   - Provide context and examples
   - Assign appropriate labels

2. **Fork and Branch**
   ```bash
   git checkout -b feature/your-feature-name
   # or
   git checkout -b bugfix/your-bug-fix
   ```

3. **Make Changes**
   - Write clean, documented code
   - Add tests for new functionality
   - Update documentation as needed

4. **Test Your Changes**
   ```bash
   # Run basic tests
   python simple_test.py
   
   # Run full integration tests (if applicable)
   python integration_test.py
   
   # Run linting
   flake8 .
   black --check .
   ```

5. **Commit and Push**
   ```bash
   git add .
   git commit -m "Add: brief description of changes"
   git push origin feature/your-feature-name
   ```

6. **Create Pull Request**
   - Provide clear description
   - Link to related issues
   - Request reviews from maintainers

## 📝 Coding Standards

### Python Code Style

- Follow PEP 8 guidelines
- Use type hints where possible
- Write docstrings for all functions and classes
- Keep functions small and focused

### Example Code Style

```python
from typing import List, Dict, Any, Optional
import logging

logger = logging.getLogger(__name__)


class ExampleEmbedder:
    """
    Example embedder following coding standards.
    
    Args:
        config: Configuration for the embedder
    """
    
    def __init__(self, config: Dict[str, Any]):
        self.config = config
        self.logger = logger
    
    async def embed_text(self, text: str) -> List[float]:
        """
        Embed a single text.
        
        Args:
            text: Input text to embed
            
        Returns:
            Embedding vector
            
        Raises:
            ValueError: If text is empty
        """
        if not text:
            raise ValueError("Text cannot be empty")
        
        # Implementation here
        return [0.1, 0.2, 0.3]  # Example return
```

### Documentation Standards

- Use clear, concise language
- Provide examples for complex features
- Update README.md for user-facing changes
- Add docstrings for all public APIs

### Testing Standards

- Write tests for new functionality
- Aim for >80% test coverage
- Test both success and failure cases
- Use descriptive test names

```python
import pytest
from advanced_embedding_pipeline import ExampleEmbedder


class TestExampleEmbedder:
    """Test suite for ExampleEmbedder."""
    
    def test_embed_text_success(self):
        """Test successful text embedding."""
        embedder = ExampleEmbedder({})
        result = embedder.embed_text("test text")
        assert len(result) > 0
        assert all(isinstance(x, (int, float)) for x in result)
    
    def test_embed_text_empty_input(self):
        """Test embedding with empty input."""
        embedder = ExampleEmbedder({})
        with pytest.raises(ValueError):
            embedder.embed_text("")
```

## 🧪 Testing

### Running Tests

```bash
# Basic functionality test
python simple_test.py

# Full integration test (requires external services)
python integration_test.py

# Comprehensive demo
python demo.py

# Unit tests (when available)
pytest tests/
```

### Adding New Tests

1. Create test files in the `tests/` directory
2. Use descriptive test names
3. Test both positive and negative cases
4. Mock external dependencies when possible

## 📚 Documentation

### Types of Documentation

1. **README.md**: Main project documentation
2. **Code Comments**: Inline code documentation
3. **Docstrings**: Function and class documentation
4. **Examples**: Usage examples and tutorials

### Writing Documentation

- Use clear, simple language
- Provide practical examples
- Keep documentation up-to-date
- Use consistent formatting

## 🐛 Bug Reports

### Before Reporting

1. Check existing issues
2. Try the latest version
3. Reproduce the issue
4. Gather relevant information

### Bug Report Template

```markdown
**Bug Description**
A clear description of the bug.

**Steps to Reproduce**
1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error

**Expected Behavior**
What you expected to happen.

**Actual Behavior**
What actually happened.

**Environment**
- OS: [e.g., Ubuntu 20.04]
- Python Version: [e.g., 3.9]
- Numbskull Version: [e.g., 1.0.0]

**Additional Context**
Any other relevant information.
```

## 💡 Feature Requests

### Feature Request Template

```markdown
**Feature Description**
A clear description of the feature.

**Use Case**
Why is this feature needed?

**Proposed Solution**
How should this feature work?

**Alternatives Considered**
Other solutions you've considered.

**Additional Context**
Any other relevant information.
```

## 🔍 Code Review Process

### For Contributors

- Respond to review feedback promptly
- Make requested changes
- Ask questions if feedback is unclear
- Test changes after addressing feedback

### For Reviewers

- Be constructive and respectful
- Focus on code quality and correctness
- Provide specific, actionable feedback
- Approve when changes meet standards

## 📋 Pull Request Guidelines

### PR Description Template

```markdown
## Description
Brief description of changes.

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] Tests pass locally
- [ ] New tests added (if applicable)
- [ ] Documentation updated

## Checklist
- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Comments added for complex code
- [ ] No unnecessary debug code
```

## 🏷️ Labels and Milestones

### Issue Labels

- `bug`: Something isn't working
- `enhancement`: New feature or request
- `documentation`: Improvements to documentation
- `good first issue`: Good for newcomers
- `help wanted`: Extra attention needed
- `question`: Further information is requested

### PR Labels

- `ready for review`: Ready for code review
- `work in progress`: Still being worked on
- `needs testing`: Requires additional testing
- `breaking change`: Changes existing behavior

## 🚀 Release Process

1. **Version Bumping**: Update version in `setup.py` and `__init__.py`
2. **Changelog**: Update CHANGELOG.md with new features/fixes
3. **Testing**: Ensure all tests pass
4. **Tagging**: Create git tag for release
5. **Documentation**: Update documentation if needed

## 📞 Getting Help

- **Issues**: [GitHub Issues](https://github.com/9x25dillon/numbskull/issues)
- **Discussions**: [GitHub Discussions](https://github.com/9x25dillon/numbskull/discussions)
- **Email**: [Your contact information]

## 📄 License

By contributing to Numbskull, you agree that your contributions will be licensed under the MIT License.

## 🙏 Recognition

Contributors will be recognized in:
- CONTRIBUTORS.md file
- Release notes
- Project documentation

Thank you for contributing to Numbskull! 🎉