Contributing to Orbiter

Thank you for your interest in contributing to Orbiter. This section covers everything you need to get started.

Quick Start

# Clone the repository
git clone https://github.com/Midsphere-AI/orbiter-ai.git
cd orbiter-ai

# Install dependencies (requires UV)
uv sync

# Run tests
uv run pytest

# Run linting
uv run ruff check packages/

# Run type checking
uv run pyright packages/orbiter-core/

Contribution Areas

Workflow

1. Find or create an issue describing the change you want to make
2. Create a feature branch from main
3. Make your changes following the code style and package structure guidelines
4. Write tests following the testing guide
5. Run quality checks — all of these must pass:
   bash

   uv run pytest                           # tests
   uv run ruff check packages/             # linting
   uv run pyright packages/orbiter-core/   # type checking

6. Commit with a descriptive message following conventional commits:
   code

   feat: add retry logic to tool execution
   fix: handle empty tool arguments in output parser
   docs: add migration guide for context engine

7. Open a pull request against main

Architecture Overview

Before contributing, read the Architecture Overview to understand:

• The 13-package monorepo structure
• The dependency DAG (orbiter-core at the bottom, everything depends on it)
• The execution flow (run -> call_runner -> agent.run -> tool loop)
• The design decisions (why single Agent class, why async-first, etc.)

Key Principles

• Max ~200 lines per source file. If a file grows beyond this, split it into _internal/ submodules.
• Async-first. All internal functions are async def. No sync/async duplication.
• Type-safe. Full pyright strict-mode compliance. All public functions must have type hints.
• Composition over inheritance. Max 2 levels of inheritance. Prefer tools, hooks, and processors.
• Zero heavy deps in core. orbiter-core depends only on pydantic. Provider SDKs live in orbiter-models.