---
description: Code style and conventions
alwaysApply: true
---

# Code Style

## Formatting

- 100-character line length (enforced by ruff and `.editorconfig`)
- 4-space indentation for Python
- 2-space indentation for YAML, JSON, TOML
- Tabs for Makefiles

## Python Conventions

- Use `from __future__ import annotations` for forward references
- Absolute imports only: `from tools.base import BaseTool`
- Type hints on all function parameters and return types
- `TypedDict` for graph state, Pydantic `StrictConfigModel` for configs
- One clear purpose per file (separation of concerns)

## Tooling

- **Linter:** ruff (rules: E, W, F, I, B, C4, UP, ARG, SIM)
- **Type checker:** mypy (Python 3.13 target, `warn_return_any`)
- **Formatter:** ruff format (Black-compatible)
- **Python version:** >=3.12 (tooling targets 3.13)

## Quality Commands

Ruff and mypy run over the source packages (`config core gateway integrations
platform surfaces tools`) plus `tests/`; the Makefile keeps the canonical path
list in `PYTHON_SOURCE_PATHS`.

```bash
make lint            # ruff check
make format-check    # ruff format --check (read-only; CI enforces this)
make format          # ruff format (write fixes locally)
make typecheck       # mypy
make test-cov        # pytest with coverage
make check           # lint + format-check + typecheck + test-full
```

Before opening a PR, run `make format-check` (or `make check`) in addition to `make lint`.