Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
41 lines (30 loc) · 1.98 KB

CONTRIBUTING.md

File metadata and controls

41 lines (30 loc) · 1.98 KB

Contributing

Thanks for improving VisoRAG. This repository is intentionally strict about source-of-truth and runtime contracts.

Source of Truth

VisoRAG_v8_Final (1).ipynb is the authoritative implementation. The package in src/visorag/ is a maintainable extraction of that behavior. Behavior changes must update both the notebook contract and package tests unless the pull request is docs-only.

Do not reintroduce stale derived files at the repository root, including api_app.py, streamlit_app.py, visorag_core.py, README_STREAMLIT.md, old duplicate notebooks, or stale requirements.txt.

Local Checks

python -m pip install -e ".[dev]"
python scripts/check_notebook_contract.py
python scripts/smoke_import.py
python -m ruff format --check .
python -m ruff check .
python -m pytest

These checks do not download or run GPU models. Real ColQwen2 and Qwen2.5-VL verification should be done separately on a CUDA machine and marked clearly in the pull request.

Behavior Changes

  • Edit the notebook when changing the authoritative workflow.
  • Edit src/visorag/ when changing the maintainable package surface.
  • Update tests whenever public request validation, response contracts, supported file types, query types, or lazy-loading behavior changes.
  • If the package intentionally diverges from the notebook, document the migration in docs/source-of-truth.md and the pull request.

Pull Request Checklist

  • Notebook JSON parses and code cells AST-parse without executing GPU models.
  • No stored notebook error outputs.
  • Package import does not load ColQwen2 or Qwen2.5-VL.
  • process_request() signature and response contracts remain compatible.
  • Extraction mode still returns flat JSON.
  • top_k remains limited to 1..20.
  • The 25 MB default upload limit remains documented if changed.
  • No real secrets, private documents, model weights, uploads, or cache artifacts are committed.
  • Security-sensitive behavior is documented in SECURITY.md or docs/security-model.md.