Skip to content

DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.

feat(rag): add pluggable query rewrite layer for retrieval quality

Kung08ba2d9074ed
diff --git a/deeptutor/services/config/__init__.py b/deeptutor/services/config/__init__.py
index 312f753e2..eaea44e84 100644
--- a/deeptutor/services/config/__init__.py
+++ b/deeptutor/services/config/__init__.py
@@ -43,6 +43,7 @@ from .runtime_settings import (
load_lightrag_settings,
load_llamaindex_settings,
load_mineru_settings,
+ load_query_rewrite_settings,
load_system_settings,
)
@@ -109,6 +110,7 @@ __all__ = [
"load_lightrag_server_settings",
"load_llamaindex_settings",
"load_mineru_settings",
+ "load_query_rewrite_settings",
"load_system_settings",
]
diff --git a/deeptutor/services/config/runtime_settings.py b/deeptutor/services/config/runtime_settings.py
index 4e001bac6..1ab0ddd14 100644
--- a/deeptutor/services/config/runtime_settings.py
+++ b/deeptutor/services/config/runtime_settings.py
@@ -277,6 +277,21 @@ DEFAULT_PAGEINDEX_SETTINGS: dict[str, Any] = {
"api_key": "",
}
+# Query-rewrite layer for retrieval (``RAGService.search``). Disabled by
+# default so behaviour is unchanged until an operator opts in; ``strategy``
+# reserves the ``multi_query`` slot for a follow-up PR.
+DEFAULT_QUERY_REWRITE_SETTINGS: dict[str, Any] = {
+ "version": 1,
+ "enabled": False,
+ "strategy": "standalone",
+ "model": "",
+ "timeout_seconds": 5.0,
+ "min_query_chars": 12,
+}
+
+#: Strategies the query-rewrite layer accepts.
+QUERY_REWRITE_STRATEGIES = ("off", "standalone")
+
# Tencent IMA. The credential pair (``client_id`` + ``api_key``, issued at
# https://ima.qq.com/agent-interface) identifies one IMA account, and every
# library in that account is reachable with it — so it belongs here, beside the
@@ -621,6 +636,21 @@ class RuntimeSettingsService:
_atomic_write_json(self.path_for("pageindex"), payload)
return payload
+ def load_query_rewrite(self, *, include_process_overrides: bool = True) -> dict[str, Any]:
+ payload = self._load_or_create(
+ "query_rewrite",
+ DEFAULT_QUERY_REWRITE_SETTINGS,
+ self._normalize_query_rewrite,
+ )
+ if include_process_overrides:
+ payload = self._apply_query_rewrite_process_overrides(payload)
+ return payload
+
+ def save_query_rewrite(self, settings: dict[str, Any]) -> dict[str, Any]:
+ payload = self._normalize_query_rewrite({**DEFAULT_QUERY_REWRITE_SETTINGS, **settings})
+ _atomic_write_json(self.path_for("query_rewrite"), payload)
+ return payload
+
def load_ima(self, *, include_process_overrides: bool = True) -> dict[str, Any]:
payload = self._load_or_create("ima", DEFAULT_IMA_SETTINGS, self._normalize_ima)
if include_process_overrides:
@@ -697,6 +727,7 @@ class RuntimeSettingsService:
self.load_pageindex(include_process_overrides=False)
self.load_ima(include_process_overrides=False)
self.load_llamaindex(include_process_overrides=False)
+ self.load_query_rewrite(include_process_overrides=False)
self.load_graphrag()
self.load_lightrag()
self.load_lightrag_server()
@@ -955,6 +986,43 @@ class RuntimeSettingsService:
"api_key": _string(settings.get("api_key")),
}
+ def _apply_query_rewrite_process_overrides(self, settings: dict[str, Any]) -> dict[str, Any]:
+ payload = dict(settings)
+ if value := self._process_env_value("DEEPTUTOR_QUERY_REWRITE_ENABLED"):
+ payload["enabled"] = value
+ if value := self._process_env_value("DEEPTUTOR_QUERY_REWRITE_STRATEGY"):
+ payload["strategy"] = value
+ if value := self._process_env_value("DEEPTUTOR_QUERY_REWRITE_MODEL"):
+ payload["model"] = value
+ if value := self._process_env_value("DEEPTUTOR_QUERY_REWRITE_TIMEOUT_SECONDS"):
+ payload["timeout_seconds"] = value
+ if value := self._process_env_value("DEEPTUTOR_QUERY_REWRITE_MIN_QUERY_CHARS"):
+ payload["min_query_chars"] = value
+ return self._normalize_query_rewrite(payload)
+
+ def _normalize_query_rewrite(self, settings: dict[str, Any]) -> dict[str, Any]:
+ strategy = str(settings.get("strategy") or "standalone").strip().lower()
+ if strategy not in QUERY_REWRITE_STRATEGIES:
+ strategy = "standalone"
+ try:
+ timeout = float(settings.get("timeout_seconds", 5.0))
+ except (TypeError, ValueError):
+ timeout = 5.0
+ timeout = min(max(timeout, 0.5), 60.0)
+ try:
+ min_chars = int(settings.get("min_query_chars", 12))
+ except (TypeError, ValueError):
+ min_chars = 12
+ min_chars = min(max(min_chars, 0), 500)
+ return {
+ "version": 1,
+ "enabled": _coerce_bool(settings.get("enabled"), False),
+ "strategy": strategy,
+ "model": str(settings.get("model") or "").strip(),
+ "timeout_seconds": timeout,
+ "min_query_chars": min_chars,
+ }
+
def _apply_ima_process_overrides(self, settings: dict[str, Any]) -> dict[str, Any]:
payload = dict(settings)
if value := self._process_env_value("IMA_CLIENT_ID"):
@@ -1488,6 +1556,10 @@ def load_graphrag_settings() -> dict[str, Any]:
return get_runtime_settings_service().load_graphrag()
+def load_query_rewrite_settings() -> dict[str, Any]:
+ return get_runtime_settings_service().load_query_rewrite()
+
+
def load_lightrag_settings() -> dict[str, Any]:
return get_runtime_settings_service().load_lightrag()
@@ -1518,6 +1590,7 @@ __all__ = [
"DEFAULT_LLAMAINDEX_SETTINGS",
"DEFAULT_MINERU_SETTINGS",
"DEFAULT_PAGEINDEX_SETTINGS",
+ "DEFAULT_QUERY_REWRITE_SETTINGS",
"DEFAULT_SYSTEM_SETTINGS",
"DOCUMENT_PARSING_ENGINE_DOCLING",
"DOCUMENT_PARSING_ENGINE_LITEPARSE",
@@ -1531,6 +1604,7 @@ __all__ = [
"LITEPARSE_IMAGE_MODES",
"MINERU_MODE_CLOUD",
"MINERU_MODE_LOCAL",
+ "QUERY_REWRITE_STRATEGIES",
"SETTINGS_DERIVED_ENV_KEYS",
"ChatAttachmentLimits",
"RuntimeSettingsService",
@@ -1548,5 +1622,6 @@ __all__ = [
"load_lightrag_server_settings",
"load_llamaindex_settings",
"load_mineru_settings",
+ "load_query_rewrite_settings",
"load_system_settings",
]
diff --git a/deeptutor/services/rag/query_rewrite.py b/deeptutor/services/rag/query_rewrite.py
new file mode 100644
index 000000000..21be05cfb
--- /dev/null
+++ b/deeptutor/services/rag/query_rewrite.py
@@ -0,0 +1,174 @@
+"""Single-query rewrite for retrieval.
+
+Rewrites a conversational or anaphoric user query into one self-contained,
+keyword-leaning search query before it reaches the KB pipeline. The layer is
+fail-open by design: any LLM error, timeout, or empty output falls back to
+the original query so retrieval never fails because of a rewrite.
+
+Only the ``standalone`` strategy exists in v1 (one LLM call, one query).
+``multi_query`` is reserved for a follow-up PR; the settings schema already
+carries the ``strategy`` field so no migration is needed later.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+import time
+from typing import Any, Optional
+
+#: Rewrite is disabled / was forced off.
+STRATEGY_OFF = "off"
+#: Single self-contained query produced by one LLM call.
+STRATEGY_STANDALONE = "standalone"
+
+#: Strategies ``maybe_rewrite`` accepts (``off`` forces the pass-through).
+KNOWN_STRATEGIES = (STRATEGY_OFF, STRATEGY_STANDALONE)
+
+_SYSTEM_PROMPT = (
+ "You rewrite a user question into a single self-contained search query "
+ "for a document retrieval engine. Keep the original language (never "
+ "translate). Resolve pronouns and conversational context into explicit "
+ "keywords. Output ONLY the rewritten query, no quotes, no explanation."
+)
+
+
+@dataclass(frozen=True)
+class RewriteOutcome:
+ """What the rewrite layer did to one query."""
+
+ original: str
+ rewritten: str
+ strategy: str
+ latency_ms: float = 0.0
+ error: str = ""
+
+ @property
+ def applied(self) -> bool:
+ """True when the query sent to the engine differs from the input."""
+ return bool(self.rewritten) and self.rewritten != self.original
+
+ def to_dict(self) -> dict[str, Any]:
+ """Serializable form attached to search results and eval reports."""
+ return {
+ "original": self.original,
+ "rewritten": self.rewritten,
+ "strategy": self.strategy,
+ "latency_ms": round(self.latency_ms, 1),
+ "error": self.error,
+ }
+
+
+def _clean_rewritten(raw: str) -> str:
+ """Take the first non-empty line of LLM output, minus wrapping quotes."""
+ for line in (raw or "").splitlines():
+ text = line.strip().strip("\"'“”‘’")
+ if text:
+ return text
+ return ""
+
+
+async def rewrite_query(
+ query: str,
+ *,
+ settings: dict[str, Any] | None = None,
+ complete_fn: Callable[..., Awaitable[str]] | None = None,
+) -> RewriteOutcome:
+ """Rewrite ``query`` per ``settings``; always fail open to the original."""
+ original = query if isinstance(query, str) else ""
+ cfg = settings or {}
+ strategy = str(cfg.get("strategy") or STRATEGY_STANDALONE)
+ if not bool(cfg.get("enabled", False)) or strategy == STRATEGY_OFF:
+ return RewriteOutcome(original=original, rewritten=original, strategy=STRATEGY_OFF)
+
+ min_chars = int(cfg.get("min_query_chars") or 0)
+ if len(original.strip()) < max(0, min_chars):
+ return RewriteOutcome(original=original, rewritten=original, strategy=strategy)
+
+ timeout = float(cfg.get("timeout_seconds") or 5.0)
+ model = str(cfg.get("model") or "").strip() or None
+
+ started = time.monotonic()
+ try:
+ complete = complete_fn
+ if complete is None:
+ from deeptutor.services.llm import complete as _default_complete
+
+ complete = _default_complete
+ if model is not None:
+ raw = await asyncio.wait_for(
+ complete(query, system_prompt=_SYSTEM_PROMPT, model=model),
+ timeout=timeout,
+ )
+ else:
+ raw = await asyncio.wait_for(
+ complete(query, system_prompt=_SYSTEM_PROMPT),
+ timeout=timeout,
+ )
+ except Exception as exc:
+ return RewriteOutcome(
+ original=original,
+ rewritten=original,
+ strategy=strategy,
+ latency_ms=(time.monotonic() - started) * 1000.0,
+ error=f"{type(exc).__name__}: {exc}",
+ )
+
+ latency_ms = (time.monotonic() - started) * 1000.0
+ rewritten = _clean_rewritten(raw)
+ if not rewritten:
+ return RewriteOutcome(
+ original=original,
+ rewritten=original,
+ strategy=strategy,
+ latency_ms=latency_ms,
+ error="empty_rewrite",
+ )
+ return RewriteOutcome(
+ original=original,
+ rewritten=rewritten,
+ strategy=strategy,
+ latency_ms=latency_ms,
+ )
+
+
+async def maybe_rewrite(
+ query: str,
+ *,
+ rewrite: bool | None = None,
+ settings: dict[str, Any] | None = None,
+ complete_fn: Callable[..., Awaitable[str]] | None = None,
+) -> tuple[str, Optional[RewriteOutcome]]:
+ """Return ``(effective_query, outcome)`` for :meth:`RAGService.search`.
+
+ ``rewrite`` is the per-call override: True forces the rewrite on, False
+ forces it off, None follows the runtime settings. Returns ``(query, None)``
+ when the layer is off so callers only attach provenance when active.
+ """
+ cfg = settings
+ if cfg is None and rewrite is None:
+ from deeptutor.services.config import get_runtime_settings_service
+
+ cfg = get_runtime_settings_service().load_query_rewrite()
+ elif cfg is None:
+ cfg = {"enabled": bool(rewrite), "strategy": STRATEGY_STANDALONE}
+ else:
+ cfg = dict(cfg)
+ if rewrite is not None:
+ cfg["enabled"] = bool(rewrite)
+
+ if not bool(cfg.get("enabled", False)):
+ return query, None
+ outcome = await rewrite_query(query, settings=cfg, complete_fn=complete_fn)
+ return outcome.rewritten, outcome
+
+
+__all__ = [
+ "KNOWN_STRATEGIES",
+ "STRATEGY_OFF",
+ "STRATEGY_STANDALONE",
+ "RewriteOutcome",
+ "maybe_rewrite",
+ "rewrite_query",
+]
diff --git a/deeptutor/services/rag/service.py b/deeptutor/services/rag/service.py
index 49da9488d..627da317f 100644
--- a/deeptutor/services/rag/service.py
+++ b/deeptutor/services/rag/service.py
@@ -129,6 +129,7 @@ class RAGService:
query: str,
kb_name: str,
event_sink=None,
+ rewrite: bool | None = None,
**kwargs,
) -> Dict[str, Any]:
provider = self._resolve_provider(kb_name)
@@ -147,6 +148,26 @@ class RAGService:
"provider": provider,
"error_type": "reasoning_as_retrieval_required",
}
+
+ # Query rewrite layer (fail-open). ``maybe_rewrite`` reads runtime
+ # settings when ``rewrite`` is None, honors an explicit True/False
+ # override, and returns ``(original, None)`` when the layer is off, so
+ # provenance is only attached when a rewrite actually ran.
+ from deeptutor.services.rag.query_rewrite import maybe_rewrite
+
+ effective_query, rewrite_outcome = await maybe_rewrite(query, rewrite=rewrite)
+ if rewrite_outcome is not None:
+ await self._emit_tool_event(
+ event_sink,
+ "status",
+ f"Rewritten query: {rewrite_outcome.rewritten}",
+ {
+ "query": query,
+ "rewrite_outcome": rewrite_outcome.to_dict(),
+ "trace_layer": "summary",
+ },
+ )
+
with self._capture_raw_logs(event_sink):
await self._emit_tool_event(
event_sink,
@@ -165,7 +186,7 @@ class RAGService:
{"provider": provider, "trace_layer": "summary"},
)
- result = await pipeline.search(query=query, kb_name=kb_name, **kwargs)
+ result = await pipeline.search(query=effective_query, kb_name=kb_name, **kwargs)
if "query" not in result:
result["query"] = query
@@ -176,6 +197,8 @@ class RAGService:
# The service is authoritative about which engine ran (resolved from
# the KB's binding), so it overwrites whatever the pipeline reports.
result["provider"] = provider
+ if rewrite_outcome is not None:
+ result["query_rewrite"] = rewrite_outcome.to_dict()
if result.get("error_type") or result.get("needs_reindex"):
await self._emit_tool_event(