# rag-bm25-hybrid Specification

## Purpose
TBD - created by archiving change rag-bm25-hybrid-drop-sdk. Update Purpose after archive.
## Requirements
### Requirement: Knowledge vector backend SHALL be a single Milvus V2 store

Knowledge indexing and retrieval SHALL use one MilvusClientV2-backed store. Legacy MilvusServiceClient SDK search modes (`sdk`, `auto` fallback to SDK) SHALL NOT be used for `lookup_knowledge`.

#### Scenario: No SDK search mode

- **WHEN** knowledge retrieval executes
- **THEN** it SHALL NOT call legacy SDK `search` APIs for candidate generation

### Requirement: Hybrid mode SHALL fuse dense ANN and BM25 sparse ANN

When search mode is hybrid, the store SHALL query dense vectors and BM25 sparse vectors and fuse results with RRF (or equivalent ranker) before returning hits.

#### Scenario: Hybrid uses BM25 text query

- **WHEN** hybrid search runs with a text query
- **THEN** one search leg SHALL use the BM25/sparse field with the raw query text
- **AND** another leg SHALL use the dense embedding of the query

### Requirement: Write path SHALL populate BM25 input text and dense vectors

Document chunk indexing SHALL write original content, BM25 input text, dense embedding, and metadata required for chunk identity.

#### Scenario: Index writes search_text and vector

- **WHEN** a chunk is indexed
- **THEN** the store row SHALL include searchable text for BM25 and a dense vector field