Skip to content

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

test: cover query rewrite layer and RAGService integration

Kunga14c1a512694
diff --git a/tests/services/rag/test_query_rewrite.py b/tests/services/rag/test_query_rewrite.py
new file mode 100644
index 000000000..e2a5308eb
--- /dev/null
+++ b/tests/services/rag/test_query_rewrite.py
@@ -0,0 +1,297 @@
+"""Tests for the RAG query rewrite layer (``deeptutor.services.rag.query_rewrite``)."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+
+import pytest
+
+from deeptutor.services.rag.query_rewrite import (
+ STRATEGY_OFF,
+ STRATEGY_STANDALONE,
+ RewriteOutcome,
+ maybe_rewrite,
+ rewrite_query,
+)
+
+
+def _ok_complete(text: str = "rewritten keywords") -> Callable[..., Awaitable[str]]:
+ async def _fn(query: str, system_prompt: str | None = None, model: str | None = None) -> str:
+ return text
+
+ return _fn
+
+
+def _fail_complete() -> Callable[..., Awaitable[str]]:
+ async def _fn(query: str, system_prompt: str | None = None, model: str | None = None) -> str:
+ raise RuntimeError("LLM down")
+
+ return _fn
+
+
+def _slow_complete() -> Callable[..., Awaitable[str]]:
+ async def _fn(query: str, system_prompt: str | None = None, model: str | None = None) -> str:
+ await asyncio.sleep(10)
+ return "too late"
+
+ return _fn
+
+
+def _enabled_settings(**overrides) -> dict:
+ base = {
+ "enabled": True,
+ "strategy": STRATEGY_STANDALONE,
+ "min_query_chars": 1,
+ "timeout_seconds": 5,
+ }
+ base.update(overrides)
+ return base
+
+
+# --------------------------------------------------------------------------- #
+# rewrite_query — the single-strategy core (always returns an outcome)
+# --------------------------------------------------------------------------- #
+
+
+def test_rewrite_query_success_strips_and_records_metadata():
+ """A successful rewrite strips quotes/whitespace and records provenance."""
+ out = asyncio.run(
+ rewrite_query(
+ "what is x",
+ settings=_enabled_settings(model="gpt-4o-mini"),
+ complete_fn=_ok_complete(' "clean query" '),
+ )
+ )
+ assert isinstance(out, RewriteOutcome)
+ assert out.original == "what is x"
+ assert out.rewritten == "clean query"
+ assert out.strategy == STRATEGY_STANDALONE
+ assert out.error == ""
+ assert out.latency_ms >= 0
+ assert out.applied is True
+
+
+def test_rewrite_query_disabled_returns_off_outcome():
+ """enabled=False short-circuits with an 'off' outcome, no LLM call."""
+ called = {"n": 0}
+
+ async def _fn(query, system_prompt=None, model=None):
+ called["n"] += 1
+ return "x"
+
+ out = asyncio.run(
+ rewrite_query(
+ "what is x",
+ settings=_enabled_settings(enabled=False),
+ complete_fn=_fn,
+ )
+ )
+ assert out.strategy == STRATEGY_OFF
+ assert out.rewritten == "what is x"
+ assert out.applied is False
+ assert called["n"] == 0
+
+
+def test_rewrite_query_strategy_off_skips_llm():
+ """strategy='off' behaves like disabled even if enabled=True."""
+ out = asyncio.run(
+ rewrite_query(
+ "what is x",
+ settings=_enabled_settings(strategy=STRATEGY_OFF),
+ complete_fn=_ok_complete(),
+ )
+ )
+ assert out.strategy == STRATEGY_OFF
+ assert out.rewritten == "what is x"
+
+
+def test_rewrite_query_short_query_skips():
+ """Queries under min_query_chars are passed through untouched."""
+ out = asyncio.run(
+ rewrite_query(
+ "hi",
+ settings=_enabled_settings(min_query_chars=12),
+ complete_fn=_ok_complete(),
+ )
+ )
+ assert out.rewritten == "hi"
+ assert out.strategy == STRATEGY_STANDALONE
+ assert out.applied is False
+
+
+def test_rewrite_query_exception_falls_back_with_error():
+ """An LLM exception keeps the original query and records the error."""
+ out = asyncio.run(
+ rewrite_query(
+ "what is x",
+ settings=_enabled_settings(),
+ complete_fn=_fail_complete(),
+ )
+ )
+ assert out.rewritten == "what is x"
+ assert out.applied is False
+ assert out.error != ""
+
+
+def test_rewrite_query_timeout_falls_back():
+ """A slow LLM is cut off by the timeout and falls back to the original."""
+ out = asyncio.run(
+ rewrite_query(
+ "what is x",
+ settings=_enabled_settings(timeout_seconds=0.1),
+ complete_fn=_slow_complete(),
+ )
+ )
+ assert out.rewritten == "what is x"
+ assert out.error != ""
+
+
+def test_rewrite_query_empty_output_falls_back():
+ """Whitespace-only LLM output is treated as a failure (empty_rewrite)."""
+ out = asyncio.run(
+ rewrite_query(
+ "what is x",
+ settings=_enabled_settings(),
+ complete_fn=_ok_complete(" \n "),
+ )
+ )
+ assert out.rewritten == "what is x"
+ assert out.error == "empty_rewrite"
+
+
+def test_rewrite_query_passes_system_prompt_and_model():
+ """The LLM is called with the system prompt and configured model."""
+ seen = {}
+
+ async def _fn(query, system_prompt=None, model=None):
+ seen["query"] = query
+ seen["system_prompt"] = system_prompt
+ seen["model"] = model
+ return "rewritten"
+
+ asyncio.run(
+ rewrite_query(
+ "what is x",
+ settings=_enabled_settings(model="gpt-4o-mini"),
+ complete_fn=_fn,
+ )
+ )
+ assert seen["query"] == "what is x"
+ assert seen["system_prompt"] and "self-contained" in seen["system_prompt"]
+ assert seen["model"] == "gpt-4o-mini"
+
+
+# --------------------------------------------------------------------------- #
+# maybe_rewrite — the settings/call-override gate used by RAGService.search
+# --------------------------------------------------------------------------- #
+
+
+def test_maybe_rewrite_off_returns_original_and_none():
+ """rewrite=False is an explicit override: original query, no outcome."""
+ q, out = asyncio.run(
+ maybe_rewrite(
+ "what is x",
+ rewrite=False,
+ settings=_enabled_settings(),
+ complete_fn=_ok_complete(),
+ )
+ )
+ assert q == "what is x"
+ assert out is None
+
+
+def test_maybe_rewrite_none_disabled_settings_skips():
+ """rewrite=None with enabled=False follows settings: skipped, outcome None."""
+ q, out = asyncio.run(
+ maybe_rewrite(
+ "what is x",
+ rewrite=None,
+ settings=_enabled_settings(enabled=False),
+ complete_fn=_ok_complete(),
+ )
+ )
+ assert q == "what is x"
+ assert out is None
+
+
+def test_maybe_rewrite_none_enabled_settings_rewrites():
+ """rewrite=None with enabled=True follows settings: query is rewritten."""
+ q, out = asyncio.run(
+ maybe_rewrite(
+ "what is x",
+ rewrite=None,
+ settings=_enabled_settings(),
+ complete_fn=_ok_complete(),
+ )
+ )
+ assert q == "rewritten keywords"
+ assert out is not None
+ assert out.rewritten == "rewritten keywords"
+ assert out.applied is True
+
+
+def test_maybe_rewrite_true_overrides_disabled_settings():
+ """rewrite=True forces the rewrite on even when settings say disabled."""
+ q, out = asyncio.run(
+ maybe_rewrite(
+ "what is x",
+ rewrite=True,
+ settings=_enabled_settings(enabled=False),
+ complete_fn=_ok_complete(),
+ )
+ )
+ assert q == "rewritten keywords"
+ assert out is not None
+
+
+def test_maybe_rewrite_false_overrides_enabled_settings():
+ """rewrite=False forces the rewrite off even when settings say enabled."""
+ q, out = asyncio.run(
+ maybe_rewrite(
+ "what is x",
+ rewrite=False,
+ settings=_enabled_settings(enabled=True),
+ complete_fn=_ok_complete(),
+ )
+ )
+ assert q == "what is x"
+ assert out is None
+
+
+def test_maybe_rewrite_short_query_skips():
+ """Short queries pass through: query unchanged, outcome records no-op.
+
+ When the layer is on but the query is under ``min_query_chars``, the query
+ is returned unchanged and a provenance outcome with ``applied=False`` is
+ still attached (so callers can see the rewrite was considered).
+ """
+ q, out = asyncio.run(
+ maybe_rewrite(
+ "hi",
+ rewrite=True,
+ settings=_enabled_settings(min_query_chars=12),
+ complete_fn=_ok_complete(),
+ )
+ )
+ assert q == "hi"
+ assert out is not None
+ assert out.rewritten == "hi"
+ assert out.applied is False
+
+
+def test_maybe_rewrite_failure_still_returns_original_with_outcome():
+ """On LLM failure the original query is kept but provenance is recorded."""
+ q, out = asyncio.run(
+ maybe_rewrite(
+ "what is x",
+ rewrite=True,
+ settings=_enabled_settings(),
+ complete_fn=_fail_complete(),
+ )
+ )
+ assert q == "what is x"
+ assert out is not None
+ assert out.rewritten == "what is x"
+ assert out.error != ""
+ assert out.applied is False
diff --git a/tests/services/rag/test_rag_service_rewrite.py b/tests/services/rag/test_rag_service_rewrite.py
new file mode 100644
index 000000000..46714905b
--- /dev/null
+++ b/tests/services/rag/test_rag_service_rewrite.py
@@ -0,0 +1,151 @@
+"""RAGService query-rewrite integration tests (with a fake pipeline).
+
+These verify that :meth:`RAGService.search` threads the rewrite layer through
+the production path: the rewritten query reaches the pipeline, the ``rewrite``
+control kwarg never leaks to the engine, and provenance is attached to the
+result only when a rewrite actually ran.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Dict
+
+import pytest
+
+import deeptutor.services.rag.service as rag_service_module
+from deeptutor.services.rag.service import RAGService
+
+
+class _RecordingPipeline:
+ """Pipeline stub that records the exact query/kwargs it receives."""
+
+ def __init__(self, search_result: Dict[str, Any] | None = None) -> None:
+ self.calls: list[dict] = []
+ self.search_result = search_result or {
+ "answer": "fake answer",
+ "sources": [{"id": 1}],
+ "provider": "llamaindex",
+ }
+
+ async def initialize(self, kb_name: str, file_paths, **kwargs) -> bool:
+ return True
+
+ async def add_documents(self, kb_name: str, file_paths, **kwargs) -> bool:
+ return True
+
+ async def search(self, query: str, kb_name: str, **kwargs) -> Dict[str, Any]:
+ self.calls.append({"query": query, "kb_name": kb_name, "kwargs": kwargs})
+ return dict(self.search_result)
+
+ async def delete(self, kb_name: str) -> bool:
+ return True
+
+
+def service_with_pipeline(tmp_path, monkeypatch) -> tuple[RAGService, _RecordingPipeline]:
+ """An RAGService whose default provider resolves to a recording stub."""
+ from deeptutor.services.rag import index_probe
+
+ monkeypatch.setattr(
+ index_probe, "latest_ready_provider_version", lambda *args: {"version": "fake"}
+ )
+ pipeline = _RecordingPipeline()
+ service = RAGService(kb_base_dir=str(tmp_path))
+ service._pipelines["llamaindex"] = pipeline # type: ignore[attr-defined]
+ return service, pipeline
+
+
+def _patch_rewrite(monkeypatch, effective_query: str, outcome: Any):
+ """Replace the service's maybe_rewrite with a deterministic stub."""
+ import deeptutor.services.rag.query_rewrite as qr
+
+ async def _fake(query, *, rewrite=None, settings=None, complete_fn=None):
+ return effective_query, outcome
+
+ monkeypatch.setattr(qr, "maybe_rewrite", _fake)
+
+
+async def test_search_passes_rewritten_query_to_pipeline(service_with_pipeline, monkeypatch):
+ """When a rewrite runs, the pipeline receives the rewritten query."""
+ from deeptutor.services.rag.query_rewrite import RewriteOutcome
+
+ service, pipeline = service_with_pipeline
+ outcome = RewriteOutcome(
+ original="what is x", rewritten="explicit keyword query", strategy="standalone"
+ )
+ _patch_rewrite(monkeypatch, "explicit keyword query", outcome)
+
+ result = await service.search(query="what is x", kb_name="kb", rewrite=True)
+
+ assert pipeline.calls[-1]["query"] == "explicit keyword query"
+ assert result["query_rewrite"] == outcome.to_dict()
+ assert result["query_rewrite"]["rewritten"] == "explicit keyword query"
+
+
+async def test_search_does_not_leak_rewrite_kwarg_to_pipeline(service_with_pipeline, monkeypatch):
+ """The ``rewrite`` control kwarg must never reach the engine."""
+ from deeptutor.services.rag.query_rewrite import RewriteOutcome
+
+ service, pipeline = service_with_pipeline
+ outcome = RewriteOutcome(original="q", rewritten="q2", strategy="standalone")
+ _patch_rewrite(monkeypatch, "q2", outcome)
+
+ await service.search(query="q", kb_name="kb", rewrite=True, top_k=5, mode="hybrid")
+
+ kwargs = pipeline.calls[-1]["kwargs"]
+ assert "rewrite" not in kwargs
+ # Unrelated kwargs still forward untouched.
+ assert kwargs.get("top_k") == 5
+ assert kwargs.get("mode") == "hybrid"
+
+
+async def test_search_no_rewrite_omits_provenance(service_with_pipeline, monkeypatch):
+ """When the layer is off (outcome None), no query_rewrite is attached."""
+ service, pipeline = service_with_pipeline
+ _patch_rewrite(monkeypatch, "original query", None)
+
+ result = await service.search(query="original query", kb_name="kb", rewrite=False)
+
+ assert pipeline.calls[-1]["query"] == "original query"
+ assert "query_rewrite" not in result
+
+
+async def test_search_emits_rewrite_status_event(service_with_pipeline, monkeypatch):
+ """A rewrite emits a status event carrying the provenance dict."""
+ from deeptutor.services.rag.query_rewrite import RewriteOutcome
+
+ service, pipeline = service_with_pipeline
+ outcome = RewriteOutcome(original="what is x", rewritten="kw query", strategy="standalone")
+ _patch_rewrite(monkeypatch, "kw query", outcome)
+
+ events: list[tuple[str, dict]] = []
+
+ async def _sink(event_type, message, metadata=None):
+ events.append((event_type, metadata or {}))
+
+ await service.search(query="what is x", kb_name="kb", rewrite=True, event_sink=_sink)
+
+ rewrite_events = [m for (t, m) in events if "rewrite_outcome" in m]
+ assert rewrite_events, "expected a status event carrying rewrite_outcome"
+ assert rewrite_events[0]["rewrite_outcome"]["rewritten"] == "kw query"
+
+
+async def test_search_error_path_keeps_rewrite_provenance(service_with_pipeline, monkeypatch):
+ """If the engine errors after a rewrite, provenance is still attached."""
+ from deeptutor.services.rag.query_rewrite import RewriteOutcome
+
+ service, pipeline = service_with_pipeline
+ pipeline.search_result = {"error_type": "index_missing", "answer": "reindex needed"}
+ outcome = RewriteOutcome(original="q", rewritten="q2", strategy="standalone")
+ _patch_rewrite(monkeypatch, "q2", outcome)
+
+ result = await service.search(query="q", kb_name="kb", rewrite=True)
+
+ assert result.get("error_type") == "index_missing"
+ assert result["query_rewrite"] == outcome.to_dict()