Development

Setup

Requires Python 3.12+ and (for PostgreSQL) Docker.

pip install -e ".[dev]"

The test suite uses SQLite and needs no external services:

make test          # or: python -m pytest -q

It runs in about a second and covers configuration, logging, the schema, session handling, and migrations.

make lint          # ruff check .

Auto-generated Alembic migrations are excluded from linting.

Start a local PostgreSQL (host port 5433) and create the schema:

make db-up
cp .env.example .env
make migrate

Inspect it:

docker compose -f deploy/docker-compose.yml exec db psql -U agentwatch -d agentwatch -c "\dt"

Stop it:

make db-down

Autogenerate a migration:

alembic revision --autogenerate -m "describe the change"

Review the generated file in migrations/versions/. If it references a custom type (such as the portable JSONB), make sure the corresponding import is present.
Apply it:
```
make migrate
```
Confirm the test suite still passes on SQLite:
```
make test
```

Path	Responsibility
`agentwatch/config.py`	Typed settings from the environment
`agentwatch/logging.py`	Structured JSON logging
`agentwatch/db/base.py`	SQLAlchemy declarative base
`agentwatch/db/types.py`	Portable `JSONB` column type
`agentwatch/db/models.py`	The five ORM models
`agentwatch/db/session.py`	Engine and `session_scope()`
`migrations/`	Alembic environment and versions
`deploy/`	Docker Compose services
`tests/`	Test suite

Each module has one clear responsibility, which keeps files small and easy to test in isolation.