Vector Storage & Retrieval (04_vectoredb)

Handles semantic search across documents, conversation memory, and related chunks with modular retrieval strategies.

Quick Start — For LLM / Generation Integration

Your teammate's main entry point is get_unified_context_for_llm(). It handles retrieval, reranking, and memory in one call.

from CognitiveRAG.04_vectoredb import get_unified_context_for_llm

Choose a strategy: "dense", "sparse", or "hybrid"

context = get_unified_context_for_llm(
    query_embedding=embedding_vector,   # dense vector from 03_embedding
    query_text="user question here",    # raw query string
    strategy="hybrid",                  # "dense" | "sparse" | "hybrid"
)

# Feed to LLM ↓
chunks_for_llm = context["unified_context"]

What it returns

Optional parameters

[!NOTE] Reranking is automatic. When RERANKER_ENABLED=true (default), cross-encoder reranking runs
after retrieval and trims results to RERANKER_TOP_N (default 10). No extra code needed.

Strategy details

• Dense — Semantic similarity via NVIDIA NIM embeddings. Needs query_embedding.
• Sparse — BM25-style keyword retrieval via Pinecone sparse index. Needs query_text.
• Hybrid — Dense + Sparse merged with Reciprocal Rank Fusion (RRF). Needs both.

Features

• Multi-Namespace Retrieval: Query documents and conversation memory in parallel
• Modular Strategies: Dense, Sparse (BM25-style), and Hybrid (RRF) retrieval
• Cross-Encoder Reranking: Automatic reranking with cross-encoder/ms-marco-MiniLM-L6-v2
• LangSmith Tracing: Automatic tracing of all retrieval operations
• Relational Chunking: Fetch prev/next adjacent chunks for context continuity
• JSON Output: Export retrieval results for downstream integration
• NVIDIA NIM Embeddings: Uses nvidia/llama-3.2-nv-embedqa-1b-v2 (2048 dim)

Files

Indexes

Configuration (config.py)

Lower-Level API

If you only need raw retrieval without memory/reranking, use retrieve():

from CognitiveRAG.04_vectoredb import retrieve, RetrievalStrategy

result = retrieve(
    query_embedding=vec,
    query_text="query",
    strategy=RetrievalStrategy.HYBRID,  # .DENSE | .SPARSE | .HYBRID
    top_k=30,
)
chunks = result["retrieved_chunks"]

Or call individual functions directly:

from CognitiveRAG.04_vectoredb import retrieve_dense, retrieve_sparse, retrieve_hybrid

result = retrieve_hybrid(
    query_embedding=embedding,
    query_text="patient medications",
    top_k=30,
    rrf_k=60,
)

Upserting Documents

# Dense index (default)
python upsert_db.py

# Sparse index
python upsert_db.py --mode sparse --file "path/to/chunks.jsonl"

# Both indexes
python upsert_db.py --mode both

LangSmith Tracing

All retrieval functions are automatically traced. Traces appear in your LangSmith dashboard under project cognitive-rag-retrieval.

Functions traced:

• get_unified_context — Main retrieval with memories
• retrieve_dense / retrieve_sparse / retrieve_hybrid

JSON Output Format

{
  "query": "What meds is the patient on?",
  "retrieved_chunks": ["chunk text 1", "chunk text 2"],
  "chunk_metadata": [
    {"chunk_id": "...", "doc_id": "...", "score": 0.92, "source": "hybrid"}
  ],
  "memory_chunks": ["previous Q/A text"],
  "stats": {
    "document_count": 5,
    "memory_count": 2,
    "related_count": 10
  }
}

Environment Files