Contributing to Ondine

Thank you for your interest in contributing to Ondine!

Quick Start

1. Fork and Clone

   git clone https://github.com/YOUR_USERNAME/Ondine.git
   cd Ondine
   

2. Set Up Development Environment

   # Install uv (if not already installed)
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # Install dependencies
   uv sync --extra dev --extra observability
   
   # Install pre-commit hooks
   uv run pre-commit install
   

3. Create a Branch

   git checkout -b feature/your-feature-name
   

Development Workflow

Running Tests

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=ondine --cov-report=html

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

# Run with verbose output
uv run pytest -v

Code Quality

# Format code
uv run ruff format ondine/ tests/

# Lint code
uv run ruff check ondine/ tests/

# Type check
uv run mypy ondine/

# Run all quality checks
just lint

Using Justfile

We provide a justfile for common tasks:

# Run tests
just test

# Run tests with coverage
just test-coverage

# Format and lint
just format
just lint

# Run all checks
just check

# View all available commands
   just --list

Code Guidelines

Style

• Follow PEP 8 and the Zen of Python
• Use type hints for all function signatures
• Keep functions small and focused (KISS principle)
• Write self-documenting code with clear variable names

Testing

• Write tests for all new features (TDD encouraged)
• Maintain or improve test coverage (currently 95%+)
• Include both unit and integration tests where appropriate
• Use descriptive test names: test_<what>_<when>_<expected>

Documentation

• Update README.md if adding user-facing features
• Add docstrings to all public functions and classes
• Include examples for new features in examples/ directory
• Update CHANGELOG.md following Keep a Changelog

Commits

• Write clear, descriptive commit messages
• Use conventional commits format:
• feat: - New feature
• fix: - Bug fix
• docs: - Documentation changes
• test: - Test additions or changes
• refactor: - Code refactoring
• chore: - Maintenance tasks

Example:

feat: add support for custom retry strategies

- Implement RetryStrategy interface
- Add exponential backoff with jitter
- Update documentation

Architecture

Ondine follows a 5-layer clean architecture:

1. Core - Domain models and business logic
2. Adapters - External integrations (LLM clients, I/O)
3. Stages - Pipeline processing stages
4. Orchestration - Execution strategies and state management
5. API - Public interfaces (builders, composers)

Plugin System

Ondine uses decorators for extensibility:

• @provider - Register custom LLM providers
• @stage - Register custom pipeline stages

See examples/15_custom_llm_provider.py and examples/16_custom_pipeline_stage.py for details.

Adding New Features

Adding a New LLM Provider

1. Create a new class inheriting from BaseLLMProvider
2. Implement invoke() and estimate_tokens() methods
3. Register with @provider("your_provider_name")
4. Add tests in tests/unit/test_providers.py
5. Add example in examples/
6. Update README.md

Adding a New Pipeline Stage

1. Create a new class inheriting from PipelineStage
2. Implement execute() method
3. Register with @stage("your_stage_name")
4. Add tests in tests/unit/test_stages.py
5. Add example in examples/
6. Update documentation

Reporting Bugs

1. Check if the bug is already reported in Issues
2. If not, create a new issue with:
3. Clear title and description
4. Steps to reproduce
5. Expected vs actual behavior
6. Environment details (OS, Python version, Ondine version)
7. Minimal reproducible example

Suggesting Features

1. Check existing feature requests
2. Open a new issue with:
3. Clear use case description
4. Proposed API or interface
5. Example usage
6. Why this would benefit users

Pull Request Process

1. Before submitting:
2. Ensure all tests pass: just test
3. Run code quality checks: just check
4. Update documentation if needed

5. Add entry to CHANGELOG.md

6. Submit PR:

7. Write a clear title and description
8. Reference related issues (e.g., "Fixes #123")
9. Ensure CI passes (tests, linting, security)

10. Respond to code review feedback

11. After approval:

12. Maintainers will merge your PR
13. Your contribution will be included in the next release!

Good First Issues

Look for issues labeled good first issue - these are great for newcomers!

Getting Help

• Questions? Open a Discussion
• Bugs? Open an Issue
• Chat? Join our community (link coming soon)

Code of Conduct

• Be respectful and inclusive
• Welcome newcomers
• Focus on constructive feedback
• Help others learn and grow

Thank You!

Every contribution, no matter how small, makes Ondine better. We appreciate your time and effort!

---

Happy coding!