Skip to content

feat(defaults): per_chunk contextual + slice reranker top-3

Jérôme Revillard requested to merge feat/better-reranker-contextual-defaults into main

What

Changes 4 proven defaults from el-salvador R&D testing:

Variable Old default New default Why
CONTEXTUAL_STRATEGY doc_level per_chunk Anthropic recipe — section-tailored context per chunk
DATAPREP_CONTEXTUAL_DOC_BUDGET 6000 100000 per_chunk needs full doc visible per call
RERANKING_STRATEGY adaptive slice Slice dominates adaptive on both recall AND precision (offline sweep)
RERANKER_TOP_N 1 3 Best recall/precision balance (top-2 = precision king, top-5 = recall king)

Adaptive's multiplicative novelty formula (relevance × sigmoid(novelty)) was structurally flawed — a high-relevance chunk could be zeroed by low novelty. Standard MMR is additive. Slice top-3 recall 0.91 vs adaptive 0.69.

Scope

  • Code: 4 files (reranker, chatqna, dataprep, reranking_microservice)
  • Ansible: all.yml, env.j2, README.md
  • Config template: env
  • CLAUDE.md: updated defaults + added RERANKING_STRATEGY/RERANKER_TOP_N
  • Site docs: 5 pages (contextual-retrieval, reranking, data-labeling, architecture, install-guide)
  • Tests: test_reranker.py defaults updated to match

Caveat

per_chunk is more expensive (1 LLM call/chunk vs 1/doc for doc_level) but produces better results. Deployments with existing doc_level ingests must re-ingest to benefit. Override CONTEXTUAL_STRATEGY=doc_level to keep the cheap path.

Merge request reports