How to enable semantic search

How-to: enable semantic search

Hybrid retrieval (lexical + dense + graph, weights 0.45/0.45/0.10 in in_memory_repository.py:695) over the same store. Measured 2026-08-31: file-level recall@8 = 1.0 on all 16 hand-labeled questions across requests + urllib3 (raw artifacts in docs/).

The no-accidental-network rule

Embeddings are optional and off by default. The env fallback enables only when BOTH are set:

export CIE_EMBED_DSN="https://integrate.api.nvidia.com/v1"   # explicit opt-in
export CIE_EMBED_API_KEY="nvapi-..."                          # or NVIDIA_API_KEY

A bare provider key (NVIDIA_API_KEY alone) never turns network on — pinned by tests. No key? Everything still works; semantic_search and the dense leg of hybrid_search degrade to the lexical+graph signals, and supports_embeddings() reports false.

Tier order (cie.embed)

host core.llm › registered override (register_embed_functions) › env-gated fallback › raise. Vectors are computed at index time and persisted — queries don't re-embed the corpus.

Measured (not claimed)

• Model used in the benchmark: nvidia/nemotron-3-embed-1b (dim 2048)
• recall@8 = 1.0 on 16/16 questions; hybrid MRR 0.854 (requests) / 0.781 (urllib3); semantic alone 0.754/0.823 — neither retriever dominates; hybrid's floor is higher
• Index overhead ≈ free at this scale (+0.03s @ 665 nodes)
• Misses are published in the benchmarks doc, not hidden