From 003459f90f2741a0374d993262adc557d7507344 Mon Sep 17 00:00:00 2001 From: Olaiwonismail Date: Thu, 8 Jan 2026 00:07:32 +0000 Subject: [PATCH] docs: add contributing guidelines and project documentation --- CONTRIBUTING.md | 328 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 328 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..71636f9e --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,328 @@ +# Contributing to Celeste AI + +Thank you for your interest in contributing to Celeste AI! We welcome contributions from the community and are excited to have you on board. + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [Getting Started](#getting-started) + - [Prerequisites](#prerequisites) + - [Development Setup](#development-setup) +- [Project Structure](#project-structure) +- [Development Workflow](#development-workflow) + - [Making Changes](#making-changes) + - [Code Style](#code-style) + - [Type Checking](#type-checking) + - [Testing](#testing) + - [Security](#security) +- [Adding a New Provider](#adding-a-new-provider) +- [Pull Request Process](#pull-request-process) +- [Reporting Issues](#reporting-issues) + +## Code of Conduct + +Please be respectful and constructive in all interactions. We are committed to providing a welcoming and inclusive environment for everyone. + +## Getting Started + +### Prerequisites + +- **Python 3.12+** - Celeste requires Python 3.12 or higher +- **[uv](https://docs.astral.sh/uv/)** - We use `uv` for dependency management +- **Git** - For version control + +### Development Setup + +1. **Fork and clone the repository:** + + ```bash + git clone https://github.com/YOUR_USERNAME/celeste-python.git + cd celeste-python + ``` + +2. **Install dependencies:** + + ```bash + make sync + ``` + + This will install all dependencies including development tools and all capability packages. + +3. **Verify setup:** + + ```bash + make ci + ``` + + This runs the full CI pipeline locally to ensure everything is working. + +## Project Structure + +Celeste uses a monorepo structure with workspaces: + +``` +celeste-python/ +├── src/celeste/ # Core library +│ ├── client.py # Base client interface +│ ├── models.py # Core data models +│ ├── http.py # HTTP utilities +│ ├── streaming.py # Streaming support +│ └── ... +├── packages/ +│ ├── capabilities/ # Capability packages +│ │ ├── text-generation/ +│ │ ├── image-generation/ +│ │ ├── video-generation/ +│ │ └── speech-generation/ +│ └── providers/ # Provider-specific packages +│ ├── openai/ +│ ├── anthropic/ +│ ├── google/ +│ └── ... +├── tests/ +│ └── unit_tests/ # Core library tests +├── Makefile # Development commands +└── pyproject.toml # Project configuration +``` + +### Key Concepts + +- **Capabilities**: Abstract interfaces for AI functionalities (text generation, image generation, etc.) +- **Providers**: Concrete implementations for specific AI services (OpenAI, Anthropic, Google, etc.) +- **Core Library**: Shared utilities, base classes, and type definitions + +## Development Workflow + +### Making Changes + +1. **Create a feature branch:** + + ```bash + git checkout -b feature/your-feature-name + ``` + +2. **Make your changes** following the code style guidelines below. + +3. **Run the CI pipeline locally:** + + ```bash + make ci + ``` + +4. **Commit your changes** with clear, descriptive commit messages. + +### Code Style + +We use [Ruff](https://docs.astral.sh/ruff/) for linting and formatting. + +- **Run linting:** + + ```bash + make lint + ``` + +- **Auto-fix linting issues:** + + ```bash + make lint-fix + ``` + +- **Format code:** + + ```bash + make format + ``` + +#### Style Guidelines + +- Use type hints for all function parameters and return values +- Write docstrings for all public classes and functions +- Follow PEP 8 naming conventions +- Keep functions focused and single-purpose +- Prefer composition over inheritance where appropriate + +### Type Checking + +We use [mypy](https://mypy.readthedocs.io/) for static type checking. All code must pass type checking. + +```bash +make typecheck +``` + +### Testing + +We use [pytest](https://pytest.org/) for testing. Tests are organized into: + +- **Unit tests**: Fast, isolated tests in `tests/unit_tests/` and `packages/*/tests/unit_tests/` +- **Integration tests**: Tests requiring API keys in `packages/*/tests/integration_tests/` + +#### Running Tests + +- **Run unit tests with coverage:** + + ```bash + make test + ``` + + Unit tests must maintain **80% code coverage**. + +- **Run integration tests (requires API keys):** + + ```bash + make integration-test + ``` + +- **Run integration tests for a specific capability:** + + ```bash + make integration-test image-generation + ``` + +#### Writing Tests + +- Place unit tests in the appropriate `unit_tests/` directory +- Use `pytest.mark.integration` for integration tests +- Use `pytest.mark.slow` for slow-running tests +- Mock external API calls in unit tests +- Use `pytest-asyncio` for async test functions + +### Security + +We use [Bandit](https://bandit.readthedocs.io/) for security scanning. + +```bash +make security +``` + +## Adding a New Provider + +To add support for a new AI provider: + +### 1. Create Provider Package (if needed) + +If the provider doesn't exist yet, create a new package in `packages/providers/`: + +``` +packages/providers/your-provider/ +├── pyproject.toml +└── src/ + └── celeste_your_provider/ + ├── __init__.py + └── py.typed +``` + +### 2. Implement Capability Support + +Add the provider implementation to the relevant capability package(s). For example, to add text generation support: + +1. Create the provider directory: + + ``` + packages/capabilities/text-generation/src/celeste_text_generation/providers/your_provider/ + ├── __init__.py + ├── client.py + ├── parameters.py + └── streaming.py + ``` + +2. Implement the client by extending the appropriate base class: + + ```python + from celeste_text_generation.client import TextGenerationClient + + class YourProviderTextGenerationClient(TextGenerationClient): + """Your provider client for text generation.""" + + @classmethod + def parameter_mappers(cls) -> list[ParameterMapper]: + # Define parameter mappings + ... + + def _init_request(self, inputs: TextGenerationInput) -> dict[str, Any]: + # Initialize API request + ... + + def _parse_content(self, response_data: dict[str, Any], **parameters) -> StructuredOutput: + # Parse API response + ... + ``` + +3. Register the provider in the capability's `providers/__init__.py`: + + ```python + from celeste_text_generation.providers.your_provider.client import ( + YourProviderTextGenerationClient, + ) + + # Add to PROVIDERS list + (Provider.YOUR_PROVIDER, YourProviderTextGenerationClient), + ``` + +### 3. Add Models + +Register the provider's models in the appropriate models file so they can be resolved. + +### 4. Write Tests + +- Add unit tests for the client implementation +- Add integration tests (marked with `@pytest.mark.integration`) + +### 5. Update Documentation + +- Update the README if adding a major new provider +- Add any provider-specific configuration notes + +## Pull Request Process + +1. **Ensure all checks pass:** + + ```bash + make ci + ``` + +2. **Update documentation** if you've changed APIs or added features. + +3. **Write clear PR description:** + - What problem does this solve? + - How does it solve the problem? + - Any breaking changes? + +4. **Request review** from maintainers. + +5. **Address feedback** promptly and thoroughly. + +### PR Requirements + +- All CI checks must pass +- Unit test coverage must not decrease +- Type hints must be complete +- Code must be formatted with Ruff +- No security issues flagged by Bandit + +## Reporting Issues + +### Bug Reports + +Please include: +- Python version +- Celeste version +- Provider being used +- Minimal reproduction steps +- Expected vs actual behavior +- Error messages/stack traces + +### Feature Requests + +Please include: +- Use case description +- Proposed API/interface (if applicable) +- Any alternatives considered + +--- + +## Questions? + +- **GitHub Issues**: [celeste-python/issues](https://github.com/withceleste/celeste-python/issues) +- **Documentation**: [withceleste.ai/docs](https://withceleste.ai/docs) + +Thank you for contributing to Celeste AI! 🎉