Skip to content

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

16.2 KB
Raw Blame
"""Bridge DeepTutor runtime configuration into the LightRAG 1.5 native SDK.

This module is the decoupling seam: it exposes availability + mode helpers and
builds the three adapters LightRAG needs from DeepTutor's already-resolved LLM,
vision, and embedding clients. LightRAG imports remain lazy so every other RAG
provider can import without the optional extra installed.

Decoupling notes:
* ``llm_model_func`` / ``vision_model_func`` wrap DeepTutor's unified model
  callables and DROP LightRAG's internal kwargs (``hashing_kv``,
  ``keyword_extraction``, …) so they never leak into ``factory.complete``.
* ``embedding_func`` reuses DeepTutor's embedding client, wrapped in LightRAG's
  ``EmbeddingFunc`` with the active model's dimension.
"""

from __future__ import annotations

import asyncio
from collections.abc import Awaitable, Callable
from copy import deepcopy
import importlib.util
import inspect
import logging
import re
from typing import TYPE_CHECKING, Any, TypeVar

if TYPE_CHECKING:
    from lightrag.utils import EmbeddingFunc

    from deeptutor.multi_user.models import CurrentUser
    from deeptutor.services.embedding.config import EmbeddingConfig
    from deeptutor.services.llm.config import LLMConfig

    from .worker import OwnerLoopBridge

logger = logging.getLogger(__name__)

_T = TypeVar("_T")

# LightRAG's native retrieval modes. ``hybrid`` (KG + vector) is the safest
# general default and matches the shared per-KB ``search_mode`` default.
SUPPORTED_MODES = ("naive", "local", "global", "hybrid", "mix")
DEFAULT_MODE = "hybrid"

# Conservative cap for the embedding wrapper when the model doesn't advertise one.
_DEFAULT_MAX_TOKEN_SIZE = 8192

# Keep retries at the LightRAG adapter boundary so the SDK receives one
# predictable policy for both text and vision calls. Provider retries are disabled
# on every attempt to prevent the two retry layers from multiplying.
_ADAPTER_MAX_ATTEMPTS = 3
_ADAPTER_RETRY_DELAYS_SECONDS = (1.0, 2.0)
_ADAPTER_MAX_RETRY_DELAY_SECONDS = 60.0
_RETRYABLE_HTTP_STATUS_CODES = frozenset({408, 429, 500, 502, 503, 504, 529})
_HTTP_STATUS_PATTERN = re.compile(
    r"\b(?:http(?: status)?|status(?: code)?|error code)\s*[:=-]?\s*(\d{3})\b",
    re.I,
)


class LightRagNotAvailableError(RuntimeError):
    """Raised when the optional ``lightrag-hku`` dependency is not installed."""


class LightRagNotConfiguredError(RuntimeError):
    """Raised when DeepTutor's LLM / embedding config can't back LightRAG."""


def _http_status_code(exc: Exception) -> int | None:
    """Return a structured or safely normalized HTTP status for an LLM error."""
    status_code = getattr(exc, "status_code", None)
    if isinstance(status_code, int) and not isinstance(status_code, bool):
        return status_code

    response = getattr(exc, "response", None)
    response_status = getattr(response, "status_code", None)
    if isinstance(response_status, int) and not isinstance(response_status, bool):
        return response_status

    # The Codex provider currently returns a safe, normalized ``HTTP NNN``
    # message through LLMAPIError instead of preserving the status attribute.
    is_llm_api_error = any(cls.__name__ == "LLMAPIError" for cls in type(exc).__mro__)
    message = getattr(exc, "message", None)
    if is_llm_api_error and isinstance(message, str):
        match = _HTTP_STATUS_PATTERN.search(message)
        if match is not None:
            return int(match.group(1))
    return None


def _retry_classification(exc: Exception) -> tuple[bool, str]:
    """Classify retryability without inspecting or logging provider payloads."""
    from deeptutor.services.llm.request_compat import is_transient_transport_error

    status_code = _http_status_code(exc)
    if status_code is not None:
        return status_code in _RETRYABLE_HTTP_STATUS_CODES, f"http_{status_code}"
    if is_transient_transport_error(exc):
        return True, "transport"
    return False, "non_retryable"


def _retry_delay_seconds(exc: Exception, scheduled_delay: float) -> float:
    """Honor a safe Retry-After value without allowing unbounded sleeps."""
    from deeptutor.services.llm.error_mapping import retry_after_seconds

    requested_delay = retry_after_seconds(exc)
    if requested_delay is None:
        return scheduled_delay
    return min(requested_delay, _ADAPTER_MAX_RETRY_DELAY_SECONDS)


async def _run_adapter_with_retry(
    request: Callable[[], Awaitable[_T]],
    *,
    io_bridge: OwnerLoopBridge | None,
) -> _T:
    """Run one adapter request with bounded, non-multiplying retries."""
    for attempt in range(1, _ADAPTER_MAX_ATTEMPTS + 1):
        try:
            if io_bridge is not None:
                return await io_bridge.run(request)
            return await request()
        except Exception as exc:
            should_retry, status = _retry_classification(exc)
            if not should_retry or attempt == _ADAPTER_MAX_ATTEMPTS:
                raise
            logger.warning(
                "LightRAG adapter retry attempt=%d exception=%s status=%s",
                attempt,
                type(exc).__name__,
                status,
            )
            delay = _retry_delay_seconds(exc, _ADAPTER_RETRY_DELAYS_SECONDS[attempt - 1])
            await asyncio.sleep(delay)

    raise AssertionError("unreachable")


def is_lightrag_available() -> bool:
    """True when the native LightRAG SDK can be imported.

    Opt-in extra: ``pip install 'deeptutor[rag-lightrag]'``. Until installed the
    provider is hidden / blocked in the UI.
    """
    return importlib.util.find_spec("lightrag") is not None


def normalize_mode(mode: str | None) -> str:
    """Coerce a stored ``search_mode`` to a valid LightRAG query mode.

    The per-KB ``search_mode`` field is shared across engines; anything that
    isn't a LightRAG mode falls back to :data:`DEFAULT_MODE`.
    """
    candidate = (mode or "").strip().lower()
    return candidate if candidate in SUPPORTED_MODES else DEFAULT_MODE


def query_kwargs_from_settings() -> dict:
    """``QueryParam`` values from runtime settings."""
    try:
        from deeptutor.services.config import load_lightrag_settings

        settings = load_lightrag_settings()
        return {
            "top_k": int(settings.get("top_k", 60)),
            "response_type": str(settings.get("response_type") or "Multiple Paragraphs"),
        }
    except Exception:
        return {}


def indexing_kwargs_from_settings() -> dict:
    """Native parser-pool knobs from runtime settings."""
    try:
        from deeptutor.services.config import load_lightrag_settings

        settings = load_lightrag_settings()
        return {"max_parallel_parse_native": int(settings.get("max_concurrent_files", 1))}
    except Exception:
        return {}


def constructor_kwargs_from_settings() -> dict:
    """Direct LightRAG constructor knobs from runtime settings."""
    try:
        from deeptutor.services.config import load_lightrag_settings

        settings = load_lightrag_settings()
        return {
            "llm_model_max_async": int(settings.get("llm_model_max_async", 4)),
            "entity_extract_max_gleaning": int(settings.get("entity_extract_max_gleaning", 1)),
            "default_llm_timeout": int(settings.get("llm_timeout", 240)),
        }
    except Exception:
        return {}


def _lightrag_llm_selection_from_settings(*, strict: bool) -> dict[str, str] | None:
    try:
        from deeptutor.services.config import load_lightrag_settings

        settings = load_lightrag_settings()
        profile_id = str(settings.get("llm_profile_id") or "").strip()
        model_id = str(settings.get("llm_model_id") or "").strip()
        if not profile_id and not model_id:
            return None
        if not profile_id or not model_id:
            if strict:
                raise ValueError("The LightRAG LLM selection is incomplete.")
            logger.warning("Ignoring incomplete LightRAG LLM selection; using the active model")
            return None
        return {"profile_id": profile_id, "model_id": model_id}
    except Exception:
        if strict:
            raise
        logger.warning(
            "Could not read LightRAG LLM selection; using the active model",
            exc_info=True,
        )
        return None


def lightrag_llm_selection_from_settings() -> dict[str, str] | None:
    """Return the released query-model selection with its fallback semantics."""
    return _lightrag_llm_selection_from_settings(strict=False)


def lightrag_indexing_selection_from_settings() -> dict[str, str] | None:
    """Return the indexing default, rejecting unreadable or partial settings."""
    return _lightrag_llm_selection_from_settings(strict=True)


def resolve_lightrag_query_llm_config():
    """Resolve legacy settings, access-checking the active fallback as well."""
    from deeptutor.multi_user.model_access import apply_allowed_llm_selection
    from deeptutor.services.model_selection.runtime import resolve_llm_config_for_selection

    from .indexing_policy import _active_catalog_selection

    selection = lightrag_llm_selection_from_settings() or _active_catalog_selection()
    if selection is None:
        raise LightRagNotConfiguredError("Choose an accessible LightRAG model in engine settings.")
    apply_allowed_llm_selection(selection)
    try:
        return resolve_llm_config_for_selection(selection)
    except ValueError:
        fallback = _active_catalog_selection()
        if fallback is None or fallback == selection:
            raise
        apply_allowed_llm_selection(fallback)
        return resolve_llm_config_for_selection(fallback)


def build_llm_model_func(
    *,
    io_bridge: OwnerLoopBridge | None = None,
    llm_config: LLMConfig | None = None,
    owner: CurrentUser | None = None,
):
    """Wrap DeepTutor's unified LLM callable for LightRAG.

    Preserve provider-facing structured-output requests while keeping
    LightRAG's orchestration-only kwargs out of DeepTutor's provider layer.

    ``enable_cot`` is intentionally an output-formatting switch in LightRAG,
    not a request to enable provider reasoning. DeepTutor controls reasoning
    through the frozen role configuration and returns answer content without
    exposing provider reasoning text.
    """
    if llm_config is None:
        from deeptutor.services.llm import get_llm_client

        base = get_llm_client().get_model_func()
    else:
        from deeptutor.services.llm.client import build_model_func_for_config

        base = build_model_func_for_config(llm_config, allow_multimodal=False)

    async def llm_model_func(
        prompt="",
        system_prompt=None,
        history_messages=None,
        messages=None,
        response_format=None,
        enable_cot=False,
        **_ignored,
    ):
        del enable_cot

        async def request() -> Any:
            async def complete() -> Any:
                provider_kwargs = {}
                if response_format is not None:
                    provider_kwargs["response_format"] = response_format
                return await base(
                    prompt or "",
                    system_prompt=system_prompt,
                    history_messages=history_messages or [],
                    messages=messages,
                    max_retries=0,
                    allow_image_fallback=False,
                    **provider_kwargs,
                )

            if owner is None:
                return await complete()
            from deeptutor.multi_user.paths import user_context

            with user_context(owner):
                return await complete()

        return await _run_adapter_with_retry(request, io_bridge=io_bridge)

    return llm_model_func


def build_vision_model_func(
    *,
    io_bridge: OwnerLoopBridge | None = None,
    llm_config: LLMConfig | None = None,
    owner: CurrentUser | None = None,
):
    """Map rc2 ``image_inputs`` to DeepTutor's vision callable."""
    if llm_config is None:
        from deeptutor.services.llm import get_llm_client

        base = get_llm_client().get_vision_model_func()
    else:
        from deeptutor.services.llm.client import build_model_func_for_config

        base = build_model_func_for_config(llm_config, allow_multimodal=True)

    async def vision_model_func(
        prompt="",
        system_prompt=None,
        history_messages=None,
        image_inputs=None,
        messages=None,
        response_format=None,
        **_ignored,
    ):
        if not isinstance(image_inputs, list) or len(image_inputs) != 1:
            raise ValueError("LightRAG vision requests must contain exactly one image input")
        payload = image_inputs[0]
        if not isinstance(payload, dict):
            raise ValueError("LightRAG vision image input must be an object")
        image_data = payload.get("base64")
        if not isinstance(image_data, str) or not image_data.strip():
            raise ValueError("LightRAG vision image input requires a non-empty base64 value")

        async def request() -> Any:
            async def complete() -> Any:
                provider_kwargs = {}
                if response_format is not None:
                    provider_kwargs["response_format"] = response_format
                return await base(
                    prompt or "",
                    system_prompt=system_prompt,
                    history_messages=history_messages or [],
                    image_data=image_data,
                    messages=messages,
                    max_retries=0,
                    allow_image_fallback=False,
                    **provider_kwargs,
                )

            if owner is None:
                return await complete()
            from deeptutor.multi_user.paths import user_context

            with user_context(owner):
                return await complete()

        return await _run_adapter_with_retry(request, io_bridge=io_bridge)

    return vision_model_func


def vision_model_available() -> bool:
    """Return whether the active DeepTutor model is explicitly vision-capable."""
    try:
        from deeptutor.services.llm import get_llm_client

        return bool(get_llm_client().supports_multimodal_images())
    except Exception:
        return False


def build_embedding_func(
    *,
    io_bridge: OwnerLoopBridge | None = None,
    embedding_config: EmbeddingConfig | None = None,
) -> EmbeddingFunc:
    """Wrap one captured embedding configuration in LightRAG's adapter."""
    from lightrag.utils import EmbeddingFunc

    from deeptutor.services.embedding import get_embedding_config
    from deeptutor.services.embedding.client import EmbeddingClient

    cfg = deepcopy(embedding_config if embedding_config is not None else get_embedding_config())
    dim = int(getattr(cfg, "dim", 0) or 0)
    if not dim:
        raise LightRagNotConfiguredError(
            "No active embedding model with a known dimension. Configure one under "
            "Settings → Catalog before using a LightRAG knowledge base."
        )

    client = EmbeddingClient(config=cfg)

    async def embedding_func(texts: list[str], context: str | None = None, **_ignored: Any) -> Any:
        import numpy as np

        # No context means no role. Defaulting to "document" would label
        # queries as passages.
        input_type = {
            "query": "search_query",
            "document": "search_document",
        }.get(str(context or "").strip().lower())

        async def request() -> Any:
            return await client.embed(texts, input_type=input_type)

        vectors = await io_bridge.run(request) if io_bridge is not None else await request()
        return np.asarray(vectors, dtype=np.float32)

    embedding_kwargs = {
        "embedding_dim": dim,
        "max_token_size": int(getattr(cfg, "max_tokens", 0) or _DEFAULT_MAX_TOKEN_SIZE),
        "func": embedding_func,
    }
    if "supports_asymmetric" in inspect.signature(EmbeddingFunc).parameters:
        embedding_kwargs["supports_asymmetric"] = True
    return EmbeddingFunc(**embedding_kwargs)


__all__ = [
    "SUPPORTED_MODES",
    "DEFAULT_MODE",
    "LightRagNotAvailableError",
    "LightRagNotConfiguredError",
    "is_lightrag_available",
    "normalize_mode",
    "query_kwargs_from_settings",
    "indexing_kwargs_from_settings",
    "constructor_kwargs_from_settings",
    "lightrag_llm_selection_from_settings",
    "resolve_lightrag_query_llm_config",
    "build_llm_model_func",
    "build_vision_model_func",
    "vision_model_available",
    "build_embedding_func",
]