elastic / elastic/elastic-evals-sdk-python
[kbn-evals] Add IR evaluators with rank-based metrics (HitRate@K, MRR@K, NDCG@K, MAP@K)
- Lingua principale
- Python
- Stelle
- 2
- Fork
- 0
- Merge medio
- 1g 13h
- PR unite (30g)
- 18
Descrizione
### Summary
The SDK has no information retrieval evaluators in the installed package. `create_document_recall_evaluator` in `examples/` covers plain recall only and is not exported.
`@kbn/evals` (TypeScript) ships seven IR metrics under `create_ir_evaluators`. Reference PR: elastic/kibana#288639 (waiting for approval). The Python SDK needs a matching implementation for local CODE evaluators.
### Proposed approach
Add `src/elastic_evals/evaluators/ir/` with:
- `RetrievedDoc`: `{ index: str, id: str }`: rank implied by list order
- `GroundTruth`: `dict[str, dict[str, float]]`: `{ index_name: { doc_id: relevance_score } }`
- `create_ir_evaluators(config)` → `list[Evaluator]`: all seven metrics, one set per K value
- Per-metric factories: `create_precision_at_k_evaluator`, `create_recall_at_k_evaluator`, etc.
- `IR_EVAL_K` env var (comma-separated) to override configured K at runtime
Metric formulas mirror elastic/kibana#288639 exactly:
- NDCG: graded relevance, linear DCG $Σ gain_i / log2(i + 2)$, ideal gains from full ground truth
- MAP denominator: `min(K, total_relevant)`
- Deduplicate retrieved docs before top-K cutoff
Export all public symbols from `elastic_evals.evaluators`.
### Done when
- [ ] All 7 metrics implemented and formula-verified against elastic/kibana#288639
- [ ] `create_ir_evaluators` exported from `elastic_evals.evaluators`
- [ ] `IR_EVAL_K` env var supported
- [ ] Unit tests cover all metrics and edge cases (no ground truth, duplicates, multi-K)
Guida per i contributori
Nessuna guida per i contributori indicizzata per questo repository
Direzione di ricerca
Inizia leggendo examples/create_document_recall_evaluator e le esportazioni pubbliche in elastic_evals.evaluators, poi confronta le formule delle metriche con elastic/kibana#288639. Parti dalla struttura proposta src/elastic_evals/evaluators/ir/ e verifica le sette metriche, il comportamento di IR_EVAL_K, i duplicati, la ground truth mancante e i casi con più valori di K tramite test unitari.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Valutazione
- Stack tecnologico
- python
- Ambito
- search
- Tipo di issue
- Funzionalità
- Difficoltà
- 4/5
- Tempo stimato
- 3-5 giorni
- Stato di attività
- Attiva
- Chiarezza
- Abbastanza chiara
- Idoneità per principianti
- 50/100