Skip to content

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

14.3 KB
Raw Blame
"""Unified RAG service entry point."""

from __future__ import annotations

import contextlib
import importlib
import logging
import os
from pathlib import Path
import shutil
from typing import Any, Dict, List, Optional

from deeptutor.runtime.home import get_runtime_data_root

from .embedding_binding import with_kb_embedding
from .factory import DEFAULT_PROVIDER, get_pipeline, list_pipelines, normalize_provider_name
from .provider_binding import resolve_bound_provider

DEFAULT_KB_BASE_DIR = str(get_runtime_data_root() / "knowledge_bases")


class RAGService:
    """Unified RAG service that routes to a KB's bound pipeline.

    The provider is resolved per knowledge base: an explicit ``provider`` passed
    to the constructor wins (used at create time); otherwise it is read from
    DeepTutor's authoritative KB config, with metadata as a legacy fallback.
    """

    def __init__(
        self,
        kb_base_dir: Optional[str] = None,
        provider: Optional[str] = None,
    ):
        self.logger = logging.getLogger(__name__)
        if kb_base_dir is None:
            try:
                from deeptutor.services.path_service import get_path_service

                kb_base_dir = str(get_path_service().get_knowledge_bases_root())
            except Exception:
                self.logger.warning(
                    "RAGService falling back to DEFAULT_KB_BASE_DIR (%s); "
                    "this should only happen in single-user / CLI mode. "
                    "Multi-user requests must reach this path with an explicit kb_base_dir.",
                    DEFAULT_KB_BASE_DIR,
                )
                kb_base_dir = DEFAULT_KB_BASE_DIR
        self.kb_base_dir = kb_base_dir
        self._provider_override = normalize_provider_name(provider) if provider else None
        # ``self.provider`` kept for callers that read it directly; the real
        # selection happens per kb_name in ``_resolve_provider``.
        self.provider = self._provider_override or DEFAULT_PROVIDER
        self._pipelines: dict[str, Any] = {}

    def _resolve_provider(self, kb_name: Optional[str]) -> str:
        """Pick the provider for ``kb_name`` from DeepTutor's binding."""
        if self._provider_override:
            return self._provider_override
        return resolve_bound_provider(self.kb_base_dir, kb_name)

    def _get_pipeline(self, provider: str):
        if provider not in self._pipelines:
            self._pipelines[provider] = get_pipeline(name=provider, kb_base_dir=self.kb_base_dir)
        return self._pipelines[provider]

    @with_kb_embedding
    async def initialize(self, kb_name: str, file_paths: List[str], **kwargs) -> bool:
        return await self._index(kb_name, file_paths, "initialize", kwargs)

    @with_kb_embedding
    async def add_documents(self, kb_name: str, file_paths: List[str], **kwargs) -> bool:
        return await self._index(kb_name, file_paths, "add_documents", kwargs)

    async def _index(self, kb_name, file_paths, method, kwargs):
        from deeptutor.knowledge.indexing_run import IndexingRun, current_run

        from .index_probe import latest_ready_provider_version
        from .kb_paths import resolve_kb_dir

        provider = self._resolve_provider(kb_name)
        pipeline = self._get_pipeline(provider)
        operation = getattr(pipeline, method, None) or pipeline.initialize
        if current_run() is not None:
            return await operation(kb_name=kb_name, file_paths=file_paths, **kwargs)
        task_id = kwargs.pop("task_id", "")
        async with IndexingRun(
            resolve_kb_dir(self.kb_base_dir, kb_name),
            file_paths,
            task_id=task_id,
            action="upload" if method == "add_documents" else "rebuild",
            provider=provider,
        ) as run:
            receipt_callback = kwargs.get("indexed_file_callback")

            def indexed(paths):
                for path in paths:
                    run.document(Path(path), "completed")
                if receipt_callback:
                    receipt_callback(paths)

            kwargs["indexed_file_callback"] = indexed
            callback = kwargs.get("progress_callback")

            def progress(current, total):
                run.phase("embedding", current=current, total=total)
                if callback:
                    callback(current, total)

            kwargs["progress_callback"] = progress
            success = await operation(kb_name=kb_name, file_paths=file_paths, **kwargs)
            if not run.data.get("usable_version"):
                run.check()
            if not success:
                return False
            version = latest_ready_provider_version(run.kb_dir, provider)
            if version is None:
                raise RuntimeError("Index output did not pass the provider readiness check.")
            partial = any(
                doc.get("status") in {"failed", "unknown", "pending", "parsing"}
                for doc in run.data["documents"].values()
            )
            run.finish("partial" if partial else "completed", version=version.get("version"))
            return True

    @with_kb_embedding
    async def search(
        self,
        query: str,
        kb_name: str,
        event_sink=None,
        rewrite: bool | None = None,
        **kwargs,
    ) -> Dict[str, Any]:
        provider = self._resolve_provider(kb_name)
        from .factory import PAGEINDEX_OSS_PROVIDER, PAGEINDEX_PROVIDER

        if provider in {PAGEINDEX_PROVIDER, PAGEINDEX_OSS_PROVIDER}:
            message = (
                "PageIndex uses Reasoning as Retrieval. Read this knowledge base with "
                "its PageIndex tools inside an agent loop instead of RAGService.search()."
            )
            return {
                "query": query,
                "answer": message,
                "content": "",
                "sources": [],
                "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,
                "status",
                f"Query: {query}",
                {"query": query, "kb_name": kb_name, "trace_layer": "summary"},
            )

            self.logger.info(f"Searching KB '{kb_name}' with query: {query[:50]}...")
            pipeline = self._get_pipeline(provider)

            await self._emit_tool_event(
                event_sink,
                "status",
                f"Retrieving from knowledge base '{kb_name}'...",
                {"provider": provider, "trace_layer": "summary"},
            )

            result = await pipeline.search(query=effective_query, kb_name=kb_name, **kwargs)

            if "query" not in result:
                result["query"] = query
            if "answer" not in result and "content" in result:
                result["answer"] = result["content"]
            if "content" not in result and "answer" in result:
                result["content"] = result["answer"]
            # 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(
                    event_sink,
                    "status",
                    result.get("answer") or result.get("content") or "RAG search failed.",
                    {
                        "provider": provider,
                        "kb_name": kb_name,
                        "trace_layer": "summary",
                        "call_state": "error",
                        "error_type": result.get("error_type"),
                        "needs_reindex": bool(result.get("needs_reindex")),
                    },
                )
                return result

            answer = result.get("answer") or result.get("content") or ""
            await self._emit_tool_event(
                event_sink,
                "status",
                f"Retrieved {len(answer)} characters of grounded context.",
                {
                    "provider": provider,
                    "kb_name": kb_name,
                    "trace_layer": "summary",
                },
            )

            # L1 memory trace — best-effort, never blocks the search path.
            try:
                from deeptutor.services.memory import get_memory_store
                from deeptutor.services.memory.trace import TraceEvent

                await get_memory_store().emit(
                    TraceEvent.new(
                        "kb",
                        "query",
                        {
                            "query": query,
                            "kb_name": kb_name,
                            "answer_chars": len(answer),
                        },
                    )
                )
            except Exception:
                pass

            return result

    async def _emit_tool_event(
        self,
        event_sink,
        event_type: str,
        message: str,
        metadata: Optional[dict[str, Any]] = None,
    ) -> None:
        if event_sink is None:
            return
        await event_sink(event_type, message, metadata or {})

    def _capture_raw_logs(self, event_sink):
        if event_sink is None:
            return contextlib.nullcontext()

        from deeptutor.logging import ProcessLogEvent, capture_process_logs
        from deeptutor.logging.process_stream import ProcessLogHandler

        def should_skip_noisy_retrieve_log(event: ProcessLogEvent) -> bool:
            if event.level != "INFO":
                return False
            message = event.message.strip()
            logger_name = event.logger
            if logger_name == "nano-vectordb" and (
                message.startswith("Load ") or message.startswith("Init ")
            ):
                return True
            if (
                logger_name.startswith("deeptutor.services.embedding.")
                and (
                    message.startswith("Successfully generated ")
                    or message.startswith("Generated ")
                )
                and "embedding" in message.lower()
            ):
                return True
            return False

        def emit(event):
            if should_skip_noisy_retrieve_log(event):
                return None
            return self._emit_tool_event(
                event_sink,
                "raw_log",
                event.message,
                {
                    "level": event.level,
                    "logger": event.logger,
                    "timestamp": event.timestamp,
                    "trace_layer": "raw",
                    **event.context,
                },
            )

        @contextlib.contextmanager
        def capture_non_propagating_logs():
            handlers: list[tuple[logging.Logger, logging.Handler]] = []
            for logger_name in ("lightrag", "graphrag", "graphrag_llm"):
                if logger_name == "lightrag":
                    with contextlib.suppress(Exception):
                        importlib.import_module("lightrag.utils")
                source_logger = logging.getLogger(logger_name)
                if source_logger.propagate:
                    continue
                handler = ProcessLogHandler(emit, min_level=logging.INFO)
                source_logger.addHandler(handler)
                handlers.append((source_logger, handler))
            try:
                yield
            finally:
                for source_logger, handler in handlers:
                    if handler in source_logger.handlers:
                        source_logger.removeHandler(handler)
                    handler.close()

        @contextlib.contextmanager
        def capture_all_raw_logs():
            with capture_process_logs(emit, min_level=logging.INFO):
                with capture_non_propagating_logs():
                    yield

        return capture_all_raw_logs()

    async def delete(self, kb_name: str) -> bool:
        provider = self._resolve_provider(kb_name)
        self.logger.info(f"Deleting KB '{kb_name}' (provider={provider})")
        pipeline = self._get_pipeline(provider)

        if hasattr(pipeline, "delete"):
            return await pipeline.delete(kb_name=kb_name)

        kb_dir = Path(self.kb_base_dir) / kb_name
        if kb_dir.exists():
            shutil.rmtree(kb_dir)
            self.logger.info(f"Deleted KB directory: {kb_dir}")
            return True
        return False

    async def smart_retrieve(
        self,
        context: str,
        kb_name: str,
        query_hints: Optional[List[str]] = None,
        max_queries: int = 3,
    ) -> Dict[str, Any]:
        from .smart_retriever import SmartRetriever

        return await SmartRetriever(self.search).retrieve(
            context=context,
            kb_name=kb_name,
            query_hints=query_hints,
            max_queries=max_queries,
        )

    @staticmethod
    def list_providers() -> List[Dict[str, str]]:
        return list_pipelines()

    @staticmethod
    def get_current_provider() -> str:
        # Global default; per-KB selection happens in ``_resolve_provider``.
        return normalize_provider_name(os.getenv("RAG_PROVIDER"))

    @staticmethod
    def has_provider(name: str) -> bool:
        from .factory import KNOWN_PROVIDERS

        return (name or "").strip().lower() in KNOWN_PROVIDERS