Developer Documentation
Resources for contributing to Claif and developing custom providers.
Development Environment
Setup Requirements
- Python 3.8+ (3.12+ recommended)
- uv package manager
- Git for version control
- Pre-commit hooks for code quality
Local Development Setup
# Clone the repository
git clone https://github.com/twardoch/claif.git
cd claif
# Install development dependencies
uv pip install -e ".[dev]"
# Set up pre-commit hooks
pre-commit install
# Run tests
uvx hatch test
Contributing Guidelines
Code Standards
- PEP 8 compliance with 120-character line limit
- Type hints for all public APIs
- Docstrings in imperative mood (PEP 257)
- Modern Python features (f-strings, pattern matching)
- Loguru for all logging needs
Testing Requirements
- 80%+ test coverage for all new code
- Unit tests for individual components
- Integration tests for provider interactions
- Mocked dependencies for reliable testing
- Cross-platform compatibility verified
Code Quality Tools
# Format code
fd -e py -x ruff format {}
# Lint code
fd -e py -x ruff check --fix {}
# Type checking
mypy src/
# Run all checks
pre-commit run --all-files
Architecture Principles
Core Design Patterns
- Plugin Architecture - Modular provider system
- Abstract Base Classes - Consistent provider interface
- Async-First - Non-blocking operations by default
- Configuration-Driven - TOML-based settings
- Error Hierarchy - Structured exception handling
Provider Development
- Minimal Interface - Implement only required methods
- Error Handling - Map provider errors to Claif types
- Testing Strategy - Mock external dependencies
- Documentation - Comprehensive usage examples
Release Process
Versioning Strategy
- Semantic Versioning (MAJOR.MINOR.PATCH)
- Coordinated Releases across all packages
- Dependency Management between core and providers
- Migration Guides for breaking changes
Release Workflow
- Test all providers in clean environments
- Update version numbers in all packages
- Generate changelogs from commit history
- Create release tags with v{version} format
- Publish to PyPI in dependency order
Navigation
- Setup Guide - Development environment
- Contributing - Contribution guidelines
- Architecture - Design decisions
- Provider Development - Creating providers
- Release Process - Version management
- Testing Guide - Testing strategies