Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
257 lines (195 loc) · 7.42 KB

CONTRIBUTING.md

File metadata and controls

257 lines (195 loc) · 7.42 KB
Raw

Contributing to VKRA Protocol

Thank you for your interest in contributing to VKRA Protocol! This document provides guidelines and instructions for contributing to this open source project.

Code of Conduct

By participating in this project, you agree to abide by our Code of Conduct. Please read it before contributing.

How to Contribute

Reporting Bugs

  1. Check if the bug has already been reported in GitHub Issues
  2. If not, create a new issue with:
    • Clear title and description
    • Steps to reproduce
    • Expected vs actual behavior
    • Environment details (Python version, OS, etc.)
    • Error messages or logs (sanitized, no API keys)

Suggesting Features

  1. Check if the feature has already been suggested
  2. Open an issue with the "feature request" label
  3. Include:
    • Use case description
    • Proposed API changes (if applicable)
    • Benefits to developers
    • Example implementation (if possible)

Pull Requests

  1. Fork the repository

  2. Create a feature branch

    git checkout -b feature/amazing-feature

  3. Follow the architecture patterns

    • Keep core logic separate from adapters (Ports & Adapters pattern)
    • Follow interface-first design
    • Keep features modular and testable
    • Add proper type hints

  4. Write tests (see Testing Guidelines below)

    • Add unit tests for new features
    • Add integration tests for vertical slices
    • Ensure all tests pass

  5. Update documentation

    • Update README if needed
    • Add/update docstrings
    • Update CHANGELOG.md for user-facing changes

  6. Run code quality checks

    uv run ruff format .
uv run ruff check .
uv run mypy src/
uv run pytest

  7. Commit your changes

    git commit -m 'Add amazing feature'
    • Use clear, descriptive commit messages
    • Reference issue numbers if applicable

  8. Push to your fork

    git push origin feature/amazing-feature

  9. Open a Pull Request

    • Provide clear description
    • Reference related issues
    • Request review from maintainers

Development Setup

Prerequisites

  • Python 3.11 or higher
  • uv package manager (recommended) or pip
  • Git

Setup

  1. Clone your fork:

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

  2. Install dependencies:

    # With uv (recommended)
uv sync --dev

# Or with pip
pip install -e ".[dev]"

  3. Verify installation:

    python -c "from vkra_protocol import LLMAOrchestrator; print('✅ Installation successful!')"

Code Style

Python

  • Follow PEP 8 style guide
  • Use type hints for all functions and methods
  • Use async/await for all I/O operations
  • Keep functions focused and small
  • Add docstrings for public functions and classes
  • Maximum line length: 100 characters (configured in ruff)

Architecture Principles

  • Interface First: All modules use abstract base classes
  • Database Agnostic: No hardcoded database dependencies
  • Core Isolation: Core business logic should be testable without external dependencies
  • Ports & Adapters: Separate core logic from infrastructure adapters
  • Modular Design: Each module is independently testable

File Structure

src/vkra_protocol/
├── __init__.py           # Public API exports
├── interfaces.py         # Abstract interfaces (VectorDatabase, UserProfileStore)
├── orchestrator.py       # Main orchestrator
├── schemas.py            # Pydantic models
└── modules/              # Pluggable modules
    ├── base.py           # Abstract base classes
    ├── presentation/     # Presentation modules
    ├── commission/       # Commission modules
    ├── prediction/       # Prediction modules
    ├── ranking/          # Ranking modules
    └── user_preferences/ # User preference modules

Testing Guidelines

VKRA Protocol follows a Core + Vertical Slice Architecture with Ports & Adapters pattern. Our testing strategy reflects this architecture:

Unit Tests (Core Logic Isolation)

  • Purpose: Test business logic in total isolation
  • Strategy: Mock only outbound ports/interfaces (adapters), not internal code
  • Mocked Interfaces:
    • VectorDatabase interface
    • UserProfileStore interface
    • OpenAI client (for embeddings)
  • What's Real: All core logic (orchestrator, modules) runs with real implementations
  • Location: tests/unit/

Example:

# Mock the adapter interface, test real core logic
mock_vector_db = MockVectorDatabase()
orchestrator = LLMAOrchestrator(
    vector_db=mock_vector_db,  # Mock adapter
    profile_store=mock_profile_store,  # Mock adapter
    openai_client=mock_openai,  # Mock adapter
    generate_embedding=mock_embedding,
)
# Test real orchestrator logic
response = await orchestrator.execute_search(request)

Integration Tests (Vertical Slices)

  • Purpose: Test entire features from top to bottom
  • Strategy: "Sociable" unit tests - real core logic, mock only final adapters
  • Approach:
    • Use real LLMAOrchestrator and all module implementations
    • Mock only the final adapters that touch external services
    • Test complete feature flows (e.g., search request → response)
  • Location: tests/integration/

Testing Principles

  • Don't Mock Your Own Code: Only mock outbound ports (interfaces) that connect to external services
  • Isolate Core: Core business logic should be testable without any external dependencies
  • Test Vertical Slices: Integration tests should test complete feature flows with real core logic
  • Separate Adapter Tests: Adapter implementations are tested separately in the private API repo

Running Tests

# Run all tests
uv run pytest

# Run only unit tests
uv run pytest tests/unit/

# Run only integration tests
uv run pytest tests/integration/

# Run with coverage
uv run pytest --cov=src/vkra_protocol --cov-report=html

# Run specific test file
uv run pytest tests/unit/test_orchestrator.py

Documentation

  • README.md: User-facing documentation, installation, quick start
  • CONTRIBUTING.md: This file - contributor guidelines
  • CODE_OF_CONDUCT.md: Community standards
  • CHANGELOG.md: Version history and changes
  • Docstrings: All public functions and classes should have docstrings

Docstring Format

Use Google-style docstrings:

async def execute_search(
    self,
    request: SearchRequest,
) -> tuple[SearchResponse, float, float, bool]:
    """Execute the complete LLMA pipeline.
    
    Args:
        request: Search request with query and context
        
    Returns:
        Tuple of (SearchResponse, embedding_time_ms, search_time_ms, cache_hit)
    """

Review Process

  1. Maintainers will review your PR
  2. Address any feedback or requested changes
  3. Once approved, your PR will be merged
  4. Thank you for contributing!

Questions?

License

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

Note: For AdAPI-specific integration details (private API repository), see .github/CONTRIBUTING.md.