deeptutor-knowledge 1.7.0__py3-none-any.whl

deeptutor/services/rag/eval/runner.py

@@ -0,0 +1,309 @@
+"""Run an evaluation set against a knowledge base and score its retrieval.
+
+The runner drives the same search path a chat turn uses (``rag_search`` →
+:class:`~deeptutor.services.rag.service.RAGService` → the KB's bound pipeline),
+so a score reflects production retrieval rather than a re-implementation of it.
+One case is one search; the ranked citations it returns are matched against the
+case's gold passages and scored at the configured cutoff.
+
+A case that cannot be scored — the engine raised, or it answered with an error
+envelope (a missing index, a credentials failure) — is recorded as failed with
+its message. Failed cases are excluded from the aggregate so an unreachable
+engine reports "0 of 8 scored" instead of a misleadingly low quality score.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass
+import logging
+import time
+from typing import TYPE_CHECKING, Any
+
+from .dataset import EvalCase, EvalDataset
+from .matching import MatchPolicy, RelevanceMatcher, source_text
+from .metrics import QueryMetrics, evaluate_hits
+
+if TYPE_CHECKING:  # ``report`` imports this module's result type.
+    from .report import EvalReport
+
+logger = logging.getLogger(__name__)
+
+#: Search callable shaped like :func:`deeptutor.tools.rag_tool.rag_search`.
+SearchFn = Callable[..., Awaitable[dict[str, Any]]]
+#: Progress hook: ``(index, total, evaluation)`` after each case.
+ProgressFn = Callable[[int, int, "QueryEvaluation"], None]
+
+#: The engine returned ranked citations.
+SOURCE_MODE_CITATIONS = "sources"
+#: The engine returned context but no citations; the context is scored as one span.
+SOURCE_MODE_CONTEXT = "content"
+
+
+@dataclass(frozen=True)
+class QueryEvaluation:
+    """One case's retrieval result, its ranked hits, and its metrics."""
+
+    case_id: str
+    query: str
+    k: int
+    gold_count: int
+    hits: tuple[frozenset[int], ...]
+    metrics: QueryMetrics
+    source_mode: str = SOURCE_MODE_CITATIONS
+    provider: str = ""
+    error: str = ""
+    sources: tuple[dict[str, Any], ...] = ()
+    query_rewrite: dict[str, Any] | None = None
+
+    @property
+    def failed(self) -> bool:
+        """True when the case could not be scored (error or failed engine)."""
+        return bool(self.error)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Serializable form, including which gold passages were covered."""
+        return {
+            "case_id": self.case_id,
+            "query": self.query,
+            "error": self.error,
+            "provider": self.provider,
+            "source_mode": self.source_mode,
+            "matched_gold": [sorted(indices) for indices in self.hits],
+            "query_rewrite": self.query_rewrite,
+            **self.metrics.to_dict(),
+        }
+
+
+def _extract_sources(result: Mapping[str, Any]) -> tuple[list[dict[str, Any]], str]:
+    """Pull the ranked citations out of a search result.
+
+    Engines that offload retrieval (LightRAG server, WeKnora, IMA) and the local
+    ones all normalize to ``sources``. An engine that answers with context but no
+    citations is scored on that context as a single span, so the case still says
+    whether the material came back at all.
+    """
+    raw = result.get("sources")
+    if isinstance(raw, list):
+        records = [item for item in raw if isinstance(item, Mapping)]
+        if records:
+            return [dict(record) for record in records], SOURCE_MODE_CITATIONS
+
+    content = result.get("content") or result.get("answer") or ""
+    if isinstance(content, str) and content.strip():
+        return [{"content": content}], SOURCE_MODE_CONTEXT
+    return [], SOURCE_MODE_CITATIONS
+
+
+def _error_message(result: Mapping[str, Any]) -> str:
+    """The engine's own failure text, or an empty string when the search worked."""
+    if result.get("needs_reindex"):
+        message = (
+            result.get("answer") or result.get("content") or "Knowledge base needs re-indexing."
+        )
+        return str(message)
+    if result.get("error_type"):
+        message = result.get("answer") or result.get("content") or result["error_type"]
+        return str(message)
+    if result.get("error"):
+        return str(result["error"])
+    return ""
+
+
+async def _default_search(
+    query: str,
+    *,
+    kb_name: str,
+    kb_base_dir: str | None,
+    mode: str | None,
+    top_k: int,
+    rewrite: bool | None = None,
+) -> dict[str, Any]:
+    """Retrieve through the production path (``rag_search`` → the bound pipeline)."""
+    from deeptutor.tools.rag_tool import rag_search
+
+    kwargs: dict[str, Any] = {"top_k": top_k}
+    if mode:
+        kwargs["mode"] = mode
+    if rewrite is not None:
+        kwargs["rewrite"] = rewrite
+    return await rag_search(query=query, kb_name=kb_name, kb_base_dir=kb_base_dir, **kwargs)
+
+
+class RetrievalEvaluator:
+    """Score a knowledge base against an evaluation set.
+
+    Args:
+        kb_name: The knowledge base to search.
+        kb_base_dir: KB root to search; ``None`` resolves the caller's workspace.
+        k: Rank cutoff for every metric.
+        mode: Search mode for engines that support one (e.g. ``hybrid``);
+            ``None`` leaves each engine on its own default.
+        query_limit: Evaluate only the first N cases.
+        policy: Gold-matching thresholds; defaults to :class:`MatchPolicy`.
+        search_fn: Search callable override, for tests and embedders.
+        provider: Provider label for the report; a search result's own
+            ``provider`` still wins per case.
+        rewrite: Force the query-rewrite layer on (``True``), off (``False``),
+            or defer to the runtime ``query_rewrite`` setting (``None``, the
+            default). Passed through to :func:`deeptutor.tools.rag_tool.rag_search`.
+
+    Raises:
+        ValueError: ``kb_name`` is empty or ``k`` is below 1.
+    """
+
+    def __init__(
+        self,
+        *,
+        kb_name: str,
+        kb_base_dir: str | None = None,
+        k: int = 5,
+        mode: str | None = None,
+        query_limit: int | None = None,
+        policy: MatchPolicy | None = None,
+        search_fn: SearchFn | None = None,
+        provider: str = "",
+        rewrite: bool | None = None,
+    ) -> None:
+        self.kb_name = (kb_name or "").strip()
+        if not self.kb_name:
+            raise ValueError("kb_name must be a non-empty string")
+        self.k = int(k)
+        if self.k < 1:
+            raise ValueError("k must be >= 1")
+        self.kb_base_dir = kb_base_dir
+        self.mode = mode or None
+        self.query_limit = query_limit if query_limit and query_limit > 0 else None
+        self.policy = policy or MatchPolicy()
+        self.search_fn: SearchFn = search_fn or _default_search
+        self.provider = provider
+        self.rewrite = rewrite
+
+    async def evaluate(
+        self,
+        dataset: EvalDataset,
+        *,
+        progress: ProgressFn | None = None,
+    ) -> EvalReport:
+        """Score every case and return the report defined in ``...eval.report``."""
+        from .report import EvalReport
+
+        cases = dataset.limited(self.query_limit).cases
+        started = time.monotonic()
+        evaluations: list[QueryEvaluation] = []
+        for index, case in enumerate(cases, start=1):
+            evaluation = await self.evaluate_case(case)
+            evaluations.append(evaluation)
+            if evaluation.failed:
+                logger.warning(
+                    "Evaluation case %s could not be scored: %s", case.id, evaluation.error
+                )
+            if progress is not None:
+                progress(index, len(cases), evaluation)
+
+        return EvalReport(
+            dataset_name=dataset.name,
+            kb_name=self.kb_name,
+            provider=self.provider,
+            k=self.k,
+            mode=self.mode,
+            policy=self.policy,
+            evaluations=tuple(evaluations),
+            duration_seconds=time.monotonic() - started,
+        )
+
+    async def evaluate_case(self, case: EvalCase) -> QueryEvaluation:
+        """Search one case and score the citations it came back with."""
+        matcher = RelevanceMatcher(case.gold, self.policy)
+        try:
+            search_kwargs: dict[str, Any] = {
+                "query": case.query,
+                "kb_name": self.kb_name,
+                "kb_base_dir": self.kb_base_dir,
+                "mode": self.mode,
+                "top_k": self.k,
+            }
+            if self.rewrite is not None:
+                search_kwargs["rewrite"] = self.rewrite
+            result = await self.search_fn(**search_kwargs)
+        except Exception as exc:
+            return self._failure(case, matcher, f"{type(exc).__name__}: {exc}")
+
+        if not isinstance(result, Mapping):
+            kind = type(result).__name__
+            return self._failure(case, matcher, f"unexpected search result {kind}")
+
+        error = _error_message(result)
+        if error:
+            return self._failure(case, matcher, error)
+
+        sources, source_mode = _extract_sources(result)
+        hits = tuple(
+            frozenset(matcher.match(source_text(source)).indices) for source in sources[: self.k]
+        )
+        provenance = result.get("query_rewrite")
+        return QueryEvaluation(
+            case_id=case.id,
+            query=case.query,
+            k=self.k,
+            gold_count=matcher.gold_count,
+            hits=hits,
+            metrics=evaluate_hits(case.id, hits, matcher.gold_count, self.k),
+            source_mode=source_mode,
+            provider=str(result.get("provider") or self.provider),
+            sources=tuple(sources),
+            query_rewrite=dict(provenance) if isinstance(provenance, Mapping) else None,
+        )
+
+    def _failure(self, case: EvalCase, matcher: RelevanceMatcher, message: str) -> QueryEvaluation:
+        """Record a case that could not be scored, with zeroed metrics."""
+        return QueryEvaluation(
+            case_id=case.id,
+            query=case.query,
+            k=self.k,
+            gold_count=matcher.gold_count,
+            hits=(),
+            metrics=evaluate_hits(case.id, (), matcher.gold_count, self.k),
+            provider=self.provider,
+            error=message,
+        )
+
+
+async def evaluate_dataset(
+    dataset: EvalDataset,
+    *,
+    kb_name: str,
+    kb_base_dir: str | None = None,
+    k: int = 5,
+    mode: str | None = None,
+    query_limit: int | None = None,
+    policy: MatchPolicy | None = None,
+    search_fn: SearchFn | None = None,
+    provider: str = "",
+    rewrite: bool | None = None,
+    progress: ProgressFn | None = None,
+) -> EvalReport:
+    """Score one dataset against one knowledge base (see :class:`RetrievalEvaluator`)."""
+    evaluator = RetrievalEvaluator(
+        kb_name=kb_name,
+        kb_base_dir=kb_base_dir,
+        k=k,
+        mode=mode,
+        query_limit=query_limit,
+        policy=policy,
+        search_fn=search_fn,
+        provider=provider,
+        rewrite=rewrite,
+    )
+    return await evaluator.evaluate(dataset, progress=progress)
+
+
+__all__ = [
+    "ProgressFn",
+    "QueryEvaluation",
+    "RetrievalEvaluator",
+    "SearchFn",
+    "SOURCE_MODE_CITATIONS",
+    "SOURCE_MODE_CONTEXT",
+    "evaluate_dataset",
+]

deeptutor/services/rag/factory.py

@@ -0,0 +1,369 @@
+"""RAG pipeline factory.
+
+Selects a KB's index/retrieve engine by provider name. Three pipelines ship
+today:
+
+* ``llamaindex`` (default) — local vector retrieval with hybrid BM25 fusion.
+* ``pageindex``           — PageIndex Cloud (deployment credential + MCP tools).
+* ``pageindex-oss``       — local PageIndex library using the active chat LLM.
+* ``graphrag``            — local knowledge-graph retrieval (microsoft/graphrag);
+                            optional dependency, ``pip install 'deeptutor[graphrag]'``.
+* ``lightrag``            — graph + vector retrieval (HKUDS/LightRAG, multimodal
+                            via the LightRAG native pipeline); optional dependency,
+                            ``pip install 'deeptutor[rag-lightrag]'``.
+* ``lightrag-server``     — retrieval offloaded to an external, standalone
+                            LightRAG server the user runs. No local index: each
+                            KB is a connection pointer queried over HTTP.
+* ``ima``                 — retrieval offloaded to a Tencent IMA knowledge base
+                            the user curates in IMA. No local index: each KB is
+                            a connection pointer queried over IMA's OpenAPI.
+* ``weknora``             — retrieval offloaded to a knowledge base in a
+                            self-hosted Tencent WeKnora deployment. No local
+                            index or document copy; each KB is a connection
+                            pointer queried over WeKnora's REST API.
+* ``kiwix``               — retrieval from one ZIM already served by
+                            kiwix-serve. Only matched articles are fetched;
+                            no local archive or index copy is made.
+
+A KB is bound to one provider at creation time; later adds and retrieval always
+go through that same pipeline (enforced upstream in the knowledge router).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+DEFAULT_PROVIDER = "llamaindex"
+PAGEINDEX_PROVIDER = "pageindex"
+PAGEINDEX_OSS_PROVIDER = "pageindex-oss"
+GRAPHRAG_PROVIDER = "graphrag"
+LIGHTRAG_PROVIDER = "lightrag"
+LIGHTRAG_SERVER_PROVIDER = "lightrag-server"
+IMA_PROVIDER = "ima"
+WEKNORA_PROVIDER = "weknora"
+KIWIX_PROVIDER = "kiwix"
+
+# Providers the factory can instantiate. Unknown / legacy strings fall back to
+# the default with a re-index hint upstream.
+KNOWN_PROVIDERS = frozenset(
+    {
+        DEFAULT_PROVIDER,
+        PAGEINDEX_PROVIDER,
+        PAGEINDEX_OSS_PROVIDER,
+        GRAPHRAG_PROVIDER,
+        LIGHTRAG_PROVIDER,
+        LIGHTRAG_SERVER_PROVIDER,
+        IMA_PROVIDER,
+        WEKNORA_PROVIDER,
+        KIWIX_PROVIDER,
+    }
+)
+
+# Cached pipeline instances keyed by (kb_base_dir, provider).
+_PIPELINE_CACHE: Dict[Tuple[Optional[str], str], Any] = {}
+
+
+def normalize_provider_name(name: Optional[str] = None) -> str:
+    """Return a known provider name, falling back to the default.
+
+    Unknown / removed provider strings collapse to the default so a stale config
+    never selects a pipeline that no longer exists.
+    """
+    candidate = (name or "").strip().lower()
+    return candidate if candidate in KNOWN_PROVIDERS else DEFAULT_PROVIDER
+
+
+def provider_uses_embedding_versions(provider: Optional[str]) -> bool:
+    """Whether this provider's index versions are keyed by embedding signature.
+
+    Today only the LlamaIndex pipeline uses DeepTutor's active embedding
+    signature to select/read index versions. PageIndex, GraphRAG and LightRAG
+    write synthetic provider signatures (``pageindex``/``graphrag``/``lightrag``)
+    and should not be marked stale merely because the active embedding profile
+    changed.
+    """
+    return normalize_provider_name(provider) == DEFAULT_PROVIDER
+
+
+def version_matches_provider(entry: dict[str, Any], provider: Optional[str]) -> bool:
+    """Return True when a version-list entry belongs to ``provider``."""
+    resolved = normalize_provider_name(provider)
+    entry_provider = str(entry.get("provider") or "").strip().lower()
+    signature = str(entry.get("signature") or "").strip().lower()
+
+    if resolved == DEFAULT_PROVIDER:
+        return entry_provider in {"", DEFAULT_PROVIDER} and signature not in {
+            PAGEINDEX_PROVIDER,
+            PAGEINDEX_OSS_PROVIDER,
+            GRAPHRAG_PROVIDER,
+            LIGHTRAG_PROVIDER,
+            LIGHTRAG_SERVER_PROVIDER,
+            IMA_PROVIDER,
+            WEKNORA_PROVIDER,
+            KIWIX_PROVIDER,
+        }
+
+    return entry_provider == resolved or signature == resolved
+
+
+def has_ready_provider_index(kb_dir: str | Path, provider: Optional[str]) -> bool:
+    """Return whether ``kb_dir`` has a ready index for ``provider``."""
+    from .index_probe import has_ready_provider_index as _has_ready_provider_index
+
+    return _has_ready_provider_index(kb_dir, provider)
+
+
+def version_has_provider_output(entry: dict[str, Any], provider: Optional[str]) -> bool:
+    """Return True when a version entry is ready and has real provider output."""
+    from .index_probe import inspect_provider_version
+
+    return inspect_provider_version(entry, provider).ready
+
+
+def provider_failure_summary(
+    kb_dir: str | Path,
+    provider: Optional[str],
+    *,
+    limit: int = 3,
+) -> str:
+    """Return a short provider-specific failure summary, when available."""
+    from .index_probe import provider_failure_summary as _provider_failure_summary
+
+    return _provider_failure_summary(kb_dir, provider, limit=limit)
+
+
+def _build_pipeline(provider: str, kb_base_dir: Optional[str], **kwargs: Any):
+    if provider in {PAGEINDEX_PROVIDER, PAGEINDEX_OSS_PROVIDER}:
+        from .pipelines.pageindex.pipeline import PageIndexPipeline
+
+        if kb_base_dir is not None:
+            kwargs.setdefault("kb_base_dir", kb_base_dir)
+        return PageIndexPipeline(provider=provider, **kwargs)
+
+    if provider == GRAPHRAG_PROVIDER:
+        from .pipelines.graphrag.pipeline import GraphRagPipeline
+
+        if kb_base_dir is not None:
+            kwargs.setdefault("kb_base_dir", kb_base_dir)
+        return GraphRagPipeline(**kwargs)
+
+    if provider == LIGHTRAG_PROVIDER:
+        from .pipelines.lightrag.pipeline import LightRagPipeline
+
+        if kb_base_dir is not None:
+            kwargs.setdefault("kb_base_dir", kb_base_dir)
+        return LightRagPipeline(**kwargs)
+
+    if provider == LIGHTRAG_SERVER_PROVIDER:
+        from .pipelines.lightrag_server.pipeline import LightRagServerPipeline
+
+        if kb_base_dir is not None:
+            kwargs.setdefault("kb_base_dir", kb_base_dir)
+        return LightRagServerPipeline(**kwargs)
+
+    if provider == IMA_PROVIDER:
+        from .pipelines.ima.pipeline import ImaPipeline
+
+        if kb_base_dir is not None:
+            kwargs.setdefault("kb_base_dir", kb_base_dir)
+        return ImaPipeline(**kwargs)
+
+    if provider == WEKNORA_PROVIDER:
+        from .pipelines.weknora.pipeline import WeKnoraPipeline
+
+        if kb_base_dir is not None:
+            kwargs.setdefault("kb_base_dir", kb_base_dir)
+        return WeKnoraPipeline(**kwargs)
+
+    if provider == KIWIX_PROVIDER:
+        from .pipelines.kiwix.pipeline import KiwixPipeline
+
+        if kb_base_dir is not None:
+            kwargs.setdefault("kb_base_dir", kb_base_dir)
+        return KiwixPipeline(**kwargs)
+
+    from .pipelines.llamaindex.pipeline import LlamaIndexPipeline
+
+    if kb_base_dir is not None:
+        kwargs.setdefault("kb_base_dir", kb_base_dir)
+    return LlamaIndexPipeline(**kwargs)
+
+
+def get_pipeline(
+    name: str = DEFAULT_PROVIDER,
+    kb_base_dir: Optional[str] = None,
+    **kwargs: Any,
+):
+    """Return a pipeline instance for ``name`` (cached when no custom kwargs)."""
+    provider = normalize_provider_name(name)
+
+    if kwargs:
+        # Custom kwargs (e.g. an injected client/loader): build a fresh instance
+        # and skip the cache so overrides are honoured.
+        return _build_pipeline(provider, kb_base_dir, **kwargs)
+
+    cache_key = (kb_base_dir, provider)
+    if cache_key not in _PIPELINE_CACHE:
+        _PIPELINE_CACHE[cache_key] = _build_pipeline(provider, kb_base_dir)
+    return _PIPELINE_CACHE[cache_key]
+
+
+def list_pipelines() -> List[Dict[str, Any]]:
+    """Describe the available pipelines for the UI provider picker."""
+    try:
+        from .pipelines.pageindex.config import is_pageindex_configured
+
+        pageindex_ready = is_pageindex_configured()
+    except Exception:
+        pageindex_ready = False
+
+    try:
+        from .pipelines.pageindex.client import resolve_oss_sdk_config
+
+        resolve_oss_sdk_config()
+        pageindex_oss_ready, pageindex_oss_reason = True, ""
+    except Exception as exc:
+        pageindex_oss_ready = False
+        pageindex_oss_reason = str(exc)
+
+    try:
+        from .pipelines.ima.config import is_ima_configured
+
+        ima_ready = is_ima_configured()
+    except Exception:
+        ima_ready = False
+
+    try:
+        from .pipelines.graphrag import config as graphrag_config
+
+        graphrag_ready = graphrag_config.is_graphrag_available()
+        graphrag_modes = list(graphrag_config.SUPPORTED_MODES)
+        graphrag_default_mode = graphrag_config.DEFAULT_MODE
+    except Exception:
+        graphrag_ready, graphrag_modes, graphrag_default_mode = False, [], ""
+
+    try:
+        from .pipelines.lightrag import config as lightrag_config
+
+        lightrag_ready = lightrag_config.is_lightrag_available()
+        lightrag_modes = list(lightrag_config.SUPPORTED_MODES)
+        lightrag_default_mode = lightrag_config.DEFAULT_MODE
+    except Exception:
+        lightrag_ready, lightrag_modes, lightrag_default_mode = False, [], ""
+
+    try:
+        from deeptutor.services.config import load_lightrag_server_settings
+
+        from .pipelines.lightrag_server import config as lightrag_server_config
+
+        lightrag_server_modes = list(lightrag_server_config.SUPPORTED_MODES)
+        lightrag_server_default_mode = lightrag_server_config.DEFAULT_MODE
+        lightrag_server_defaults_ready = bool(load_lightrag_server_settings().get("server_url"))
+    except Exception:
+        lightrag_server_modes, lightrag_server_default_mode = [], ""
+        lightrag_server_defaults_ready = False
+
+    return [
+        {
+            "id": DEFAULT_PROVIDER,
+            "name": "LlamaIndex",
+            "description": "Local vector retrieval with hybrid BM25/vector fusion. Works out of the box.",
+            "configured": True,
+            "requires_api_key": False,
+        },
+        {
+            "id": PAGEINDEX_PROVIDER,
+            "name": "PageIndex Cloud",
+            "description": "Hosted, vectorless engine: the chat agent reads documents through PageIndex SDK tools. Requires an API key; PDF, Office, text and Markdown formats.",
+            "configured": pageindex_ready,
+            "requires_api_key": True,
+        },
+        {
+            "id": PAGEINDEX_OSS_PROVIDER,
+            "name": "PageIndex OSS",
+            "description": "Local, chunkless and vectorless document indexing. Uses the active LLM and accepts PDF files.",
+            "configured": pageindex_oss_ready,
+            "requires_api_key": False,
+            "readiness_reason": pageindex_oss_reason,
+        },
+        {
+            "id": GRAPHRAG_PROVIDER,
+            "name": "GraphRAG",
+            "description": "Local knowledge-graph retrieval (global/local/drift/basic). Needs `pip install 'deeptutor[graphrag]'`; indexing is LLM-heavy.",
+            "configured": graphrag_ready,
+            "requires_api_key": False,
+            "modes": graphrag_modes,
+            "default_mode": graphrag_default_mode,
+        },
+        {
+            "id": LIGHTRAG_PROVIDER,
+            "name": "LightRAG",
+            "description": "Graph + vector retrieval with multimodal parsing (naive/local/global/hybrid/mix). Needs `pip install 'deeptutor[rag-lightrag]'`; indexing is LLM-heavy.",
+            "configured": lightrag_ready,
+            "requires_api_key": False,
+            "modes": lightrag_modes,
+            "default_mode": lightrag_default_mode,
+        },
+        {
+            "id": LIGHTRAG_SERVER_PROVIDER,
+            "name": "LightRAG Server",
+            "description": "Retrieval offloaded to an external, standalone LightRAG server you run. No local index — connect a KB to its URL and query it over HTTP (naive/local/global/hybrid/mix).",
+            # Always available: it's a thin HTTP client with no install or global
+            # credential. The endpoint is configured per-KB at connect time.
+            "configured": True,
+            "requires_api_key": False,
+            "setup_required": not lightrag_server_defaults_ready,
+            "modes": lightrag_server_modes,
+            "default_mode": lightrag_server_default_mode,
+        },
+        {
+            "id": IMA_PROVIDER,
+            "name": "Tencent IMA",
+            "description": (
+                "Retrieval offloaded to a knowledge base you keep in Tencent IMA. "
+                "No local index and no copy — connect a KB to its IMA library and "
+                "query it over IMA's OpenAPI. Chat can also browse the library's "
+                "documents, read a full source, search your IMA notes, and (when "
+                "you ask) collect a web page or save a note. Uploading files still "
+                "happens in IMA itself. Requires an IMA Client ID and API key."
+            ),
+            # A thin HTTPS client with no install; readiness is only about the
+            # account credentials. The library id stays per-KB, set at connect
+            # time, and a KB may pin its own credentials to reach another account.
+            "configured": ima_ready,
+            "requires_api_key": True,
+        },
+        {
+            "id": WEKNORA_PROVIDER,
+            "name": "WeKnora",
+            "description": (
+                "Retrieval offloaded to a knowledge base in your self-hosted "
+                "WeKnora deployment. No local index or document copy; connect "
+                "to its API URL, API key, and knowledge-base ID."
+            ),
+            "configured": True,
+            "requires_api_key": True,
+        },
+    ]
+
+
+__all__ = [
+    "DEFAULT_PROVIDER",
+    "PAGEINDEX_PROVIDER",
+    "PAGEINDEX_OSS_PROVIDER",
+    "GRAPHRAG_PROVIDER",
+    "LIGHTRAG_PROVIDER",
+    "LIGHTRAG_SERVER_PROVIDER",
+    "IMA_PROVIDER",
+    "WEKNORA_PROVIDER",
+    "KNOWN_PROVIDERS",
+    "get_pipeline",
+    "has_ready_provider_index",
+    "list_pipelines",
+    "normalize_provider_name",
+    "provider_failure_summary",
+    "provider_uses_embedding_versions",
+    "version_has_provider_output",
+    "version_matches_provider",
+]

deeptutor/services/rag/file_routing.py

@@ -0,0 +1,5 @@
+"""Compatibility import for shared document classification."""
+
+from deeptutor.utils.file_types import DocumentType, FileClassification, FileTypeRouter
+
+__all__ = ["DocumentType", "FileClassification", "FileTypeRouter"]