Contributingstable

Development setup

Python 3.11+. The environment is built with `uv`; the repository expects the virtualenv at .venv in the root, because every documented invocation spells .venv/bin/python explicitly rather than relying on an activated shell.

bash

uv venv .venv --python 3.11

Dependency tiers

Install only the tier your change needs. The tiers exist because the standards-track suites must run in an environment with no torch, no Qdrant and no network — that constraint is load-bearing, not a convenience.

Tier 1 — standards track (validator, conformance corpus, CPNP determinism, record and wire models):

bash

uv pip install --python .venv/bin/python \
  ruff pytest jsonschema pydantic pydantic-settings \
  pillow numpy imagehash piexif rfc8785 cryptography

Tier 2 — federation, offline (adds the HTTP/API/atproto/index surfaces; the Qdrant-marked tests still skip without a running Qdrant):

bash

uv pip install --python .venv/bin/python \
  httpx websockets qdrant-client atproto fastapi typer uvicorn \
  python-multipart rich

Tier 3 — the full pipeline (adds ~2 GB of wheels and a ~1.5 GB weights download on first ingest):

bash

uv pip install --python .venv/bin/python torch transformers
docker compose up -d          # qdrant on :6333, pinned to v1.19.0

tests/conftest.py deselects the suites whose imports are absent at collection time rather than letting them error, so a Tier 1 environment runs a green subset instead of a broken one. That means a missing dependency looks like a smaller test run, not a failure — check the collected count if a suite you expected to exercise appears to have passed instantly.

The exiftool binary

Some metadata tests shell out to exiftool, which is not a Python package:

bash

sudo apt-get install -y libimage-exiftool-perl     # Debian/Ubuntu
brew install exiftool                              # macOS

Tests that need it carry the exiftool marker (see pyproject.toml), alongside qdrant, model and network for the other external facts a test can depend on. Mark a new test that needs one of those four; do not silently assume it.