README_HF.md

---
title: Semantic Document Retrieval API
emoji: 🔬
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false
---

# 🔬 Calibrated Entropy-Weighted Hybrid Retrieval API

A research-oriented hybrid retrieval system deployed on Hugging Face Spaces. Combines BM25 sparse retrieval, FAISS dense retrieval, corpus-level CDF score calibration, entropy-weighted adaptive fusion, and cross-encoder reranking behind a FastAPI service.

## 📡 API Endpoints

- `GET /` — Root API status & route map
- `GET /health` — Service health & index state
- `GET /modes` — List all 7 retrieval modes
- `POST /query` — Query indexed documents
- `POST /upload` — Upload PDF/TXT/MD files to index
- `GET /documents` — List all indexed source documents