CONTRIBUTING.md

Contributing

Thanks for your interest in contributing! This project is a research-oriented retrieval system, so contributions that improve evaluation rigor, retrieval quality, or code clarity are especially welcome.

Getting Started

# Clone and set up
git clone https://github.com/ayushmath07/Semantic-Document-Retrieval-API.git
cd Semantic-Document-Retrieval-API

python -m venv venv
venv\Scripts\activate        # Windows
# source venv/bin/activate   # macOS/Linux

pip install -r requirements.txt

Development Workflow

Run Tests

pytest tests/ -v

All tests must pass before submitting a PR.

Lint and Format

This project uses Ruff for linting and formatting:

ruff check .          # lint
ruff format --check . # verify formatting
ruff format .         # auto-format

Build the Index

python scripts/build_index.py --dataset scifact

Run Evaluation

python scripts/evaluate.py

Project Structure

app/              Core retrieval modules (calibration, fusion, reranking, API)
scripts/          Index building and evaluation runners
tests/            pytest test suite
eval/             Golden set labels and generated results
data/             Sample documents and FAISS/BM25 index artifacts

Pull Request Guidelines

1. One concern per PR. Don't mix refactors with feature additions.
2. Include tests for new functionality.
3. Run the full test suite before opening the PR.
4. Update the README if your change affects the API, retrieval modes, or evaluation.

Code Style

• Python 3.11+
• Type hints on all function signatures
• Docstrings on all public functions (Google style)
• Ruff-clean (ruff check . produces zero warnings)

Reporting Issues

Open a GitHub issue with:

• What you expected to happen
• What actually happened
• Steps to reproduce
• Python version and OS