CONTRIBUTING.md

Contributing to ChronoQuant

Quick start

git clone https://github.com/your-org/chronoquant
cd chronoquant
poetry install
docker compose up -d
poetry run pytest -v

All 32 tests must pass before opening a PR.

What to work on

Good first issues:

• New DB adapter — implement MyDBAdapter following the interface in README.md (Pinecone, Weaviate, pgvector, Chroma, Milvus)
• Re-promotion — vectors accessed frequently should be able to move back up tiers
• Async PolarQuant — encode/decode in a thread pool to unblock the event loop
• Config file support — load tier thresholds from YAML/TOML instead of hardcoded constants

Adding a new vector DB adapter

1. Create chronoquant/adapters/<db_name>_adapter.py
2. Implement all 7 methods: upsert, search, get, delete, count, scroll, set_payload
3. search() must return objects with .id, .score (cosine similarity, 0–1), .payload, .vector
4. Add tests in tests/test_<db_name>_adapter.py — mock the DB client, test all 7 methods
5. Add a row to the adapter table in README

Pull request checklist

• poetry run pytest -v passes locally
• poetry run pytest benchmarks/recall_validation.py -v passes (if you touched polar_quant.py)
• New code has tests (aim for the existing ~80% coverage level)
• No hardcoded secrets or API keys
• PR description explains the why, not just the what

Code style

• black for formatting: poetry run black .
• ruff for linting: poetry run ruff check .
• Type annotations on all function signatures
• No comments explaining what the code does — only why when non-obvious

CI

Two jobs run on every PR:

Job	What it checks
test	Full pytest suite on Python 3.11 + 3.12, with live Qdrant + Redis
recall	PolarQuant recall thresholds (int8 ≥99%, 4-bit ≥97%, 3-bit ≥95%)

Both must be green to merge.

Architecture notes

• BGCompressor uses a shadow-write pattern: encode → upsert to target → verify recall ≥ 0.95 → delete from source. Never delete before verifying.
• QdrantAdapter hashes string IDs to UUID via uuid5(NAMESPACE_DNS, vec_id). Other adapters should do the same or store the original vec_id in payload for round-trip lookup.
• PolarQuant pads vectors to next power-of-2 before RHT. The stored byte blob is ceil(padded_dim * bits / 8) bytes. Seed must be consistent across encode/decode calls.
• WAL uses INSERT OR IGNORE — safe to call append() multiple times for the same vec_id.