# Contributing to KOAN

## Development Setup

### Prerequisites

- Python 3.11+
- [uv](https://docs.astral.sh/uv/) package manager

### Getting Started

```bash
# Clone the repository
git clone https://github.com/koan-framework/koan.git
cd koan

# Install all dependencies (including dev tools)
uv sync --group dev

# Verify setup
uv run koan verify
```

### Running Tests

```bash
# Unit tests (no external dependencies required)
uv run pytest

# With coverage
uv run pytest --cov=koan --cov-report=term-missing

# Integration tests (requires API keys in .env)
uv run pytest -m integration

# Graph database tests (requires Docker)
docker compose -f docker/docker-compose.graph.yml --profile falkordb up -d
uv run pytest -m graph
```

### Code Quality

```bash
# Lint
uv run ruff check src/ tests/

# Auto-fix lint issues
uv run ruff check src/ tests/ --fix

# Type checking
uv run pyright src/
```

## Project Conventions

- **Python 3.11 compatibility** -- No `type` alias syntax or generic class syntax (3.12+). Use `TypeVar` + `Generic[T]`.
- **`from __future__ import annotations`** in all source files (but not in test files that use `@tool` decorator with local classes).
- **Ruff TCH rules** -- Move stdlib/third-party imports to `TYPE_CHECKING` blocks when `from __future__ import annotations` is active.
- **pytest-asyncio** with `asyncio_mode = "auto"` -- No need to decorate async tests with `@pytest.mark.asyncio`.
- **Streaming everywhere** -- Every agent/orchestrator that has `run()` must also have `run_stream()`.

## Project Structure

```
src/koan/           # Source code
tests/              # Unit tests (mirrors src/ structure)
tests/integration/  # Integration tests (real APIs, marked)
examples/           # Working example scripts
docker/             # Docker Compose files for graph databases
schema/             # Cypher schema scripts
```

## Pull Request Guidelines

1. Create a feature branch from `main`
2. Write tests for new functionality
3. Ensure `uv run pytest` passes
4. Ensure `uv run ruff check src/` and `uv run pyright src/` are clean
5. Keep PRs focused -- one feature or fix per PR
