[aminbigdeli]

Description

Adds HyDE from Precise Zero-Shot Dense Retrieval without Relevance Labels (Gao et al., 2022) as a new reformulation method ("hyde").

The original HyDE averages the embeddings of the query and 8 LLM-generated hypothetical documents. Like every other QueryGym method, this version emits text instead: the reformulated query is the original query followed by the 8 generated documents (query + doc_1 + … + doc_8). That way it works with any retriever (BM25, SPLADE++, BGE). The query appears once, matching its 1-in-9 weight in the original embedding average.

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to change)
• 📚 Documentation update
• 🔧 Refactoring (no functional changes)
• 🧪 Test update

Related Issues

None.

Changes Made

• Method (querygym/methods/hyde.py): HyDE makes n_docs (default 8) LLM calls per query, then concatenates the query and the documents. Empty generations are dropped; if all are empty, the original query is returned. Metadata: task, n_docs, hypothetical_docs.
• Prompts (prompt_bank.yaml): the 7 task prompts copied verbatim from the original implementation: web search, scifact, arguana, trec-covid, fiqa, dbpedia-entity, trec-news. The task param selects one (default web search). An unknown or misspelled task raises ValueError instead of silently falling back. The Mr. TyDi (multilingual) prompt is not included.
• Dataset → prompt mapping: task_for_dataset() maps the 6 BEIR datasets to their own prompt. Everything else uses web search: MS MARCO, DL-HARD, BRIGHT, custom query files and unknown dataset names. The example pipeline (reformulate_queries.py) applies it when task isn't set; an explicit task always wins. The chosen task is recorded in method_params, so it's part of params_hash.
• Defaults: paper sampling settings (temperature 0.7, max_tokens 512, top_p 1.0, stop ["\n\n\n"]) in querygym/config/defaults.yaml and examples/querygym_pyserini/reformulation_config.yaml.
• CLI: querygym run --method hyde --output-format plain writes one column per document.
• Registration: methods/__init__.py, core/runner.py, and the querygym package exports.
• Docs: methods reference section, reformulation guide, API reference, quickstart list, changelog (Unreleased), README methods table, and web/site/src/data/methods.json (marketing site; also supplies the leaderboard's paper link).

Testing

• Unit tests pass (pytest): 137 passed, including 35 new tests in tests/test_methods_hyde.py
• Manual testing performed (with a stubbed LLM, see below)
• New tests added for new functionality

The new tests use a fake LLM and cover:

• 8 calls per query and the concatenation order
• the n_docs and repeat_query_weight params
• every task's prompt, plus the error on an unknown task
• the sampling params passed to the LLM and their overrides
• empty and newline handling
• the dataset → task mapping
• registration
• the CLI defaults and both output formats

I also ran the example pipeline with the LLM and searcher stubbed out:

Run	Task used
beir-v1.0.0-scifact	scifact
bright-biology	web search
custom .tsv	web search
explicit task: fiqa	fiqa (overrides the mapping)

Not yet tested against a real LLM endpoint.

Checklist

• My code follows the project's style guidelines (black and ruff clean on the new files)
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have updated the documentation accordingly
• My changes generate no new warnings
• Any dependent changes have been merged and published

Additional Notes

• Expected retrieval behavior: with about 4k tokens of generated text, the original query terms count for little under BM25 and SPLADE++, so HyDE may score below methods that repeat the query (Query2Doc, MuGI). repeat_query_weight can raise the query's weight. BGE truncates at 512 tokens, so it effectively sees the query plus about the first document.
• create_reformulator defaults: qg.create_reformulator("hyde") without llm_config gets the factory's temperature=0.8 and max_tokens=256, as every method does. The docs say to pass the paper settings explicitly. querygym run and the example pipeline already use them.
• Prompt license field: the HyDE prompts use license: "CC-BY-4.0" like the rest of the prompt bank. The original HyDE repo doesn't include a license file.
• No leaderboard runs are included; those will come in a separate PR.