Contributing

Thanks for helping make document extraction safer and easier to audit. The project supports Python 3.10 and later and uses a src/ package layout.

Set up a development checkout

git clone https://github.com/BEASTSHRIRAM/docgate.git
cd docgate
python -m pip install -e ".[dev,office,docs]"
python -m pytest -q

Preserve the product boundary

docgate owns safe rasterization, planning, cost and budget controls, cache correctness, provenance, and receipts. It does not host models, transmit telemetry, interpret documents, or make business decisions.

Changes must preserve these invariants:

• plan() remains local-only: no provider call, network request, or credential access.
• Unread pages remain explicit Unknown records, never ambiguous empty strings.
• Raster output stays bounded and every clamp is recorded.
• Budgets are hard ceilings based on provider estimates; cache hits cost zero.
• Cache keys derive from exact provider bytes plus non-secret provider/model identity, never a filename or path.
• Failed, malformed, and empty provider responses are not cached.
• Provider failures remain visible as Degradation entries, even after fallback.

Before opening a pull request

Run the relevant checks, update user-facing documentation for behavior changes, and add tests for new failure states or receipt fields.

python -m pytest -q
python -m mkdocs build --strict

Keep public result records frozen and backward-compatible. Never commit a real API key or private document.