DeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.
Python ai-agentsai-tutorclawbotcli-tooldeepresearchinteractive-learninglearningmulti-agent-systemsrag
feat(rag): add pluggable query rewrite layer for retrieval quality
Kung08ba2d9074ed
diff --git a/deeptutor/services/config/__init__.py b/deeptutor/services/config/__init__.pyindex 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.pyindex 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.pynew file mode 100644index 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.pyindex 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(