Skip to content

feat: add --no-expand flag to qmd query#622

Open
kechol wants to merge 1 commit intotobi:mainfrom
kechol:feat/query-no-expand
Open

feat: add --no-expand flag to qmd query#622
kechol wants to merge 1 commit intotobi:mainfrom
kechol:feat/query-no-expand

Conversation

@kechol
Copy link
Copy Markdown

@kechol kechol commented May 4, 2026

#454

Summary

Add a --no-expand flag to qmd query that skips LLM query expansion and searches the original query verbatim.

Motivation

The built-in query expansion model (qmd-query-expansion-1.7B) is trained primarily on English. Given a non-English query — Chinese, Japanese, Korean — it translates the query into English before generating lex/vec/hyde variants. The vector search downstream then runs against English-translated text, and on a non-English corpus recall drops sharply.

A typed-query path ({ type: 'lex', query: ... } via SDK or MCP) bypasses expansion already, but for the simple ergonomic qmd query "..." CLI path there was no escape hatch. This PR adds one.

Changes

  • qmd query --no-expand skips expansion entirely and searches the original query verbatim. Mirrors --no-rerank.
  • SDK: search({ query, expand: false }) — analogous to the existing rerank: false.
  • HybridQueryOptions.skipExpansion plumbs through to hybridQuery(). When set, expandQuery() is not called and the lex/vec/hyde fan-out is empty — only the original query runs against BM25 and the vector index.
  • CLI hook output emits a single Expansion disabled (--no-expand) line on stderr so users see the flag took effect, instead of the misleading "Expanding query..." line.
  • MCP query tool already takes pre-expanded searches, so expansion is structurally absent there. No MCP changes needed.

Usage

# Skip expansion for non-English queries
qmd query "テレグラム 設定" --no-expand

# Same effect via SDK
const results = await store.search({ query: "テレグラム 設定", expand: false })

Notes

  • Default behavior is unchanged when --no-expand is absent (or expand is unset / true).
  • Strong-BM25-signal short-circuit still works on the default path; --no-expand just makes the bypass unconditional.
  • Pairs naturally with --no-rerank for the lowest-latency CPU path: qmd query "..." --no-expand --no-rerank runs only BM25 + vector + RRF, no LLM calls.

The built-in query expansion model is English-tuned. Given a CJK or
other non-English query, it tends to translate the query into English
before generating variants. The vector search then runs against
English-translated text — and on a non-English corpus, recall drops
sharply.

`qmd query --no-expand` skips expansion entirely and searches the
original query verbatim. Mirrors `--no-rerank`. Also exposed as
`expand: false` on the SDK `search()` method.

The MCP `query` tool already takes pre-expanded `searches`, so
expansion is structurally absent on that path; no MCP changes needed.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant