# Contributing to agenticraft-types

## Quick Start

```bash
git clone https://github.com/agenticraft/agenticraft-types.git
cd agenticraft-types
uv sync --group dev
uv run pytest tests/ -v
```

## Code Style

- **Formatter/linter**: [Ruff](https://docs.astral.sh/ruff/) (line-length 100, target `py310`)
- **Type checker**: pyright in basic mode
- **Docstrings**: Google style
- **Imports**: Always use `from __future__ import annotations` at the top of every module

Standard import order:

```python
from __future__ import annotations

import logging
from typing import TYPE_CHECKING, Any

if TYPE_CHECKING:
    from some_module import SomeType
```

## Testing

- **Framework**: pytest
- **Coverage minimum**: 90%
- **Test naming**: `test_<module>_<function>_<scenario>`

```bash
# Full test suite
uv run pytest tests/ -v

# With coverage report
uv run pytest tests/ --cov=agenticraft_types --cov-report=html
```

## Linting

```bash
# Check for lint errors
uv run ruff check src/ tests/

# Auto-format
uv run ruff format src/ tests/

# Type check
uv run pyright src/
```

## Pre-Commit Hooks

Install pre-commit to run checks automatically before each commit:

```bash
uv run pre-commit install
```

This runs ruff (lint + format) and standard file checks on every `git commit`.

## PR Process

### Branch Naming

- `feat/<name>` -- new features
- `fix/<name>` -- bug fixes
- `docs/<name>` -- documentation changes

### Commit Messages

Use conventional commit format:

```
feat(models): add new response model
fix(enums): correct provider name variant
docs(readme): update usage examples
test(protocols): add protocol conformance tests
```

### Checklist

Before submitting a PR:

- [ ] All tests pass (`uv run pytest tests/ -v`)
- [ ] Linter is clean (`uv run ruff check src/ tests/`)
- [ ] Code is formatted (`uv run ruff format --check src/ tests/`)
- [ ] Type checker passes (`uv run pyright src/`)
- [ ] Security check passes (`uvx bandit -r src/agenticraft_types/ -ll`)
- [ ] New functionality has tests
- [ ] Docstrings follow Google style

## Module Structure

```
src/agenticraft_types/
    enums.py       # Shared enumerations (ProviderName, FailureType, etc.)
    models.py      # Pydantic v2 request/response models
    errors.py      # Exception hierarchy
    protocols.py   # typing.Protocol classes for structural typing
    config.py      # Configuration schemas
```

### Adding a New Type

1. Determine which module the type belongs to (enums, models, errors, protocols, or config).
2. Add the type definition following existing patterns in that module.
3. Export from `__init__.py`.
4. Add type annotations to all public fields and methods.
5. Write tests in the `tests/` directory.
6. Keep business logic out -- this package is pure data definitions.
