realtimex-deeptutor 0.5.0.post1__py3-none-any.whl → 0.5.0.post3__py3-none-any.whl

src/services/llm/realtimex_provider.py

@@ -0,0 +1,240 @@
+"""
+RealTimeX LLM Provider
+======================
+
+Provides LLM capabilities through RealTimeX SDK proxy.
+Used when running as a local app within RealTimeX desktop.
+
+This provider maps DeepTutor's LLM API to the RealTimeX SDK's ChatMessage format
+and handles error translation from SDK exceptions to DeepTutor exception hierarchy.
+"""
+
+from typing import TYPE_CHECKING, AsyncGenerator, Dict, List, Optional
+
+from src.logging import get_logger
+from src.utils.realtimex import get_realtimex_sdk
+
+from .exceptions import LLMAPIError, LLMRateLimitError, RealTimeXError, RealTimeXPermissionError
+
+if TYPE_CHECKING:
+    from realtimex_sdk import ChatMessage
+
+logger = get_logger("RealTimeXProvider")
+
+
+def _build_messages(
+    prompt: str,
+    system_prompt: str = "You are a helpful assistant.",
+    messages: Optional[List[Dict[str, str]]] = None,
+) -> List["ChatMessage"]:
+    """
+    Build ChatMessage array from DeepTutor's API parameters.
+
+    Args:
+        prompt: User message
+        system_prompt: System role instruction
+        messages: Optional pre-built messages array
+
+    Returns:
+        List[ChatMessage]: Messages formatted for SDK
+    """
+    from realtimex_sdk import ChatMessage
+
+    if messages:
+        # Convert dict format to ChatMessage objects
+        return [ChatMessage(role=m["role"], content=m["content"]) for m in messages]
+    else:
+        # Build from prompt and system_prompt
+        return [
+            ChatMessage(role="system", content=system_prompt),
+            ChatMessage(role="user", content=prompt),
+        ]
+
+
+def _map_sdk_error(e: Exception) -> Exception:
+    """
+    Map SDK exceptions to DeepTutor exception hierarchy.
+
+    Args:
+        e: SDK exception
+
+    Returns:
+        Exception: Mapped DeepTutor exception
+    """
+    try:
+        from realtimex_sdk import LLMPermissionError, LLMProviderError
+
+        if isinstance(e, LLMPermissionError):
+            return RealTimeXPermissionError(
+                permission=e.permission, message=f"RealTimeX permission required: {e.permission}"
+            )
+
+        if isinstance(e, LLMProviderError):
+            if e.code == "RATE_LIMIT":
+                return LLMRateLimitError(str(e), provider="realtimex")
+            if e.code in ("LLM_STREAM_ERROR", "LLM_ERROR"):
+                return RealTimeXError(str(e), error_code=e.code)
+
+            # Generic provider error
+            return RealTimeXError(str(e), error_code=e.code)
+
+    except ImportError:
+        pass
+
+    # Fallback for unknown errors
+    return LLMAPIError(f"RealTimeX SDK error: {str(e)}", provider="realtimex")
+
+
+async def complete(
+    prompt: str,
+    system_prompt: str = "You are a helpful assistant.",
+    model: Optional[str] = None,
+    temperature: float = 0.7,
+    max_tokens: int = 1000,
+    messages: Optional[List[Dict[str, str]]] = None,
+    response_format: Optional[Dict[str, str]] = None,
+    **kwargs,
+) -> str:
+    """
+    Complete request via RealTimeX SDK.
+
+    Maps DeepTutor's API to SDK's ChatMessage format and handles error translation.
+
+    Args:
+        prompt: User message
+        system_prompt: System role instruction (default: "You are a helpful assistant.")
+        model: Optional model override
+        temperature: Sampling temperature (0.0-2.0)
+        max_tokens: Maximum tokens to generate
+        messages: Optional pre-built messages array
+        response_format: Optional response format config (e.g., {"type": "json_object"})
+        **kwargs: Additional parameters (ignored for now)
+
+    Returns:
+        str: Generated completion text
+
+    Raises:
+        RealTimeXPermissionError: If permission is required/denied
+        RealTimeXError: If SDK request fails
+        LLMRateLimitError: If rate limited
+    """
+    from realtimex_sdk import ChatOptions
+
+    sdk = get_realtimex_sdk()
+
+    # Build messages array
+    chat_messages = _build_messages(prompt, system_prompt, messages)
+
+    # Build options
+    options = ChatOptions(
+        model=model,
+        temperature=temperature,
+        max_tokens=max_tokens,
+        response_format=response_format,  # Pass through to SDK
+    )
+
+    # Log request
+    logger.debug(
+        f"RealTimeX complete: model={model or 'default'}, "
+        f"temp={temperature}, max_tokens={max_tokens}, "
+        f"messages_count={len(chat_messages)}, "
+        f"response_format={response_format}"
+    )
+
+    try:
+        response = await sdk.llm.chat(chat_messages, options)
+
+        if not response.success:
+            logger.error(f"RealTimeX request failed: {response.error}")
+            raise RealTimeXError(response.error or "SDK request failed", error_code=response.code)
+
+        # Log response metadata
+        logger.debug(
+            f"RealTimeX response: success={response.success}, "
+            f"provider={response.provider}, model={response.model}"
+        )
+
+        if response.metrics:
+            logger.debug(
+                f"Tokens: {response.metrics.total_tokens} "
+                f"(prompt={response.metrics.prompt_tokens}, "
+                f"completion={response.metrics.completion_tokens})"
+            )
+
+        return response.content or ""
+
+    except Exception as e:
+        # Map SDK errors to DeepTutor exceptions
+        mapped_error = _map_sdk_error(e)
+        logger.error(f"RealTimeX error: {mapped_error}")
+        raise mapped_error
+
+
+async def stream(
+    prompt: str,
+    system_prompt: str = "You are a helpful assistant.",
+    model: Optional[str] = None,
+    temperature: float = 0.7,
+    max_tokens: int = 1000,
+    messages: Optional[List[Dict[str, str]]] = None,
+    response_format: Optional[Dict[str, str]] = None,
+    **kwargs,
+) -> AsyncGenerator[str, None]:
+    """
+    Stream response via RealTimeX SDK.
+
+    Args:
+        prompt: User message
+        system_prompt: System role instruction
+        model: Optional model override
+        temperature: Sampling temperature (0.0-2.0)
+        max_tokens: Maximum tokens to generate
+        messages: Optional pre-built messages array
+        response_format: Optional response format config
+        **kwargs: Additional parameters (ignored)
+
+    Yields:
+        str: Text chunks as they arrive
+
+    Raises:
+        RealTimeXPermissionError: If permission is required/denied
+        RealTimeXError: If SDK request fails
+        LLMRateLimitError: If rate limited
+    """
+    from realtimex_sdk import ChatOptions
+
+    sdk = get_realtimex_sdk()
+
+    # Build messages array
+    chat_messages = _build_messages(prompt, system_prompt, messages)
+
+    # Build options
+    options = ChatOptions(
+        model=model,
+        temperature=temperature,
+        max_tokens=max_tokens,
+        response_format=response_format,  # Pass through to SDK
+    )
+
+    # Log request
+    logger.debug(
+        f"RealTimeX stream: model={model or 'default'}, "
+        f"temp={temperature}, max_tokens={max_tokens}, "
+        f"messages_count={len(chat_messages)}, "
+        f"response_format={response_format}"
+    )
+
+    try:
+        async for chunk in sdk.llm.chat_stream(chat_messages, options):
+            if chunk.error:
+                logger.error("RealTimeX stream error detected")
+                raise RealTimeXError("Stream error", error_code="LLM_STREAM_ERROR")
+
+            if chunk.text:
+                yield chunk.text
+
+    except Exception as e:
+        # Map SDK errors to DeepTutor exceptions
+        mapped_error = _map_sdk_error(e)
+        logger.error(f"RealTimeX stream error: {mapped_error}")
+        raise mapped_error

src/services/llm/registry.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 LLM Provider Registry
 ====================

src/services/llm/telemetry.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 LLM Telemetry
 =============

src/services/llm/types.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 from typing import Any, AsyncGenerator, Dict, Optional
 
 from pydantic import BaseModel, Field

src/services/llm/utils.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 LLM Utilities
 =============

src/services/prompt/__init__.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 Prompt Service
 ==============

src/services/prompt/manager.py

@@ -1,4 +1,5 @@
 #!/usr/bin/env python
+# -*- coding: utf-8 -*-
 """
 Unified Prompt Manager - Single source of truth for all prompt loading.
 Supports multi-language, caching, and language fallbacks.
@@ -20,8 +21,8 @@ class PromptManager:
 
     # Language fallback chain: if primary language not found, try alternatives
     LANGUAGE_FALLBACKS = {
-        "zh": ["zh", "en"],
-        "en": ["en", "zh"],
+        "zh": ["zh", "cn", "en"],
+        "en": ["en", "zh", "cn"],
     }
 
     # Supported modules

src/services/rag/__init__.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 RAG Service
 ===========
@@ -7,7 +8,7 @@ Unified RAG pipeline service for DeepTutor.
 Provides:
 - RAGService: Unified entry point for all RAG operations
 - Composable RAG pipelines
-- Pre-configured pipelines (RAGAnything, LightRAG, LlamaIndex, Academic)
+- Pre-configured pipelines (RAGAnything, LightRAG, LlamaIndex)
 - Modular components (parsers, chunkers, embedders, indexers, retrievers)
 - Factory for pipeline creation
 
@@ -39,12 +40,33 @@ Usage:
 
 from .factory import get_pipeline, has_pipeline, list_pipelines, register_pipeline
 from .pipeline import RAGPipeline
-
-# Import pipeline classes for convenience
-from .pipelines.raganything import RAGAnythingPipeline
 from .service import RAGService
 from .types import Chunk, Document, SearchResult
 
+
+# Lazy import for RAGAnythingPipeline to avoid importing heavy dependencies at module load time
+def __getattr__(name: str):
+    """Lazy import for pipeline classes that depend on heavy libraries."""
+    if name == "RAGAnythingPipeline":
+        from .pipelines.raganything import RAGAnythingPipeline
+
+        return RAGAnythingPipeline
+    if name == "RAGAnythingDoclingPipeline":
+        from .pipelines.raganything_docling import RAGAnythingDoclingPipeline
+
+        return RAGAnythingDoclingPipeline
+    if name == "LlamaIndexPipeline":
+        # Optional dependency: llama_index
+        from .pipelines.llamaindex import LlamaIndexPipeline
+
+        return LlamaIndexPipeline
+    if name == "LightRAGPipeline":
+        from .pipelines.lightrag import LightRAGPipeline
+
+        return LightRAGPipeline
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
 __all__ = [
     # Service (recommended entry point)
     "RAGService",
@@ -59,6 +81,6 @@ __all__ = [
     "list_pipelines",
     "register_pipeline",
     "has_pipeline",
-    # Pipeline implementations
+    # Pipeline implementations (lazy loaded)
     "RAGAnythingPipeline",
 ]

src/services/rag/components/__init__.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 RAG Components
 ==============

src/services/rag/components/base.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 Base Component
 ==============

src/services/rag/components/chunkers/__init__.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 Document Chunkers
 =================

src/services/rag/components/chunkers/base.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 Base Chunker
 ============

src/services/rag/components/chunkers/fixed.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 Fixed Size Chunker
 ==================

src/services/rag/components/chunkers/numbered_item.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 Numbered Item Extractor
 =======================

src/services/rag/components/chunkers/semantic.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 Semantic Chunker
 ================

src/services/rag/components/embedders/__init__.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 Document Embedders
 ==================

src/services/rag/components/embedders/base.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 Base Embedder
 =============

src/services/rag/components/embedders/openai.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 OpenAI Embedder
 ===============

src/services/rag/components/indexers/__init__.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 Document Indexers
 =================

src/services/rag/components/indexers/base.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 Base Indexer
 ============

src/services/rag/components/indexers/graph.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 Graph Indexer
 =============
@@ -51,58 +52,18 @@ class GraphIndexer(BaseComponent):
             sys.path.insert(0, str(raganything_path))
 
         try:
-            from openai import AsyncOpenAI
             from raganything import RAGAnything, RAGAnythingConfig
 
             from src.services.embedding import get_embedding_client
             from src.services.llm import get_llm_client
 
+            # Use unified LLM client from src/services/llm
             llm_client = get_llm_client()
             embed_client = get_embedding_client()
 
-            # Create AsyncOpenAI client directly
-            openai_client = AsyncOpenAI(
-                api_key=llm_client.config.api_key,
-                base_url=llm_client.config.base_url,
-            )
-
-            # LLM function using services (ASYNC - LightRAG expects async functions)
-            async def llm_model_func(prompt, system_prompt=None, history_messages=None, **kwargs):
-                """Custom async LLM function that bypasses LightRAG's openai_complete_if_cache."""
-                if history_messages is None:
-                    history_messages = []
-
-                # Build messages
-                messages = []
-                if system_prompt:
-                    messages.append({"role": "system", "content": system_prompt})
-                messages.extend(history_messages)
-                messages.append({"role": "user", "content": prompt})
-
-                # Whitelist only valid OpenAI parameters
-                valid_params = {
-                    "temperature",
-                    "top_p",
-                    "n",
-                    "stream",
-                    "stop",
-                    "max_tokens",
-                    "presence_penalty",
-                    "frequency_penalty",
-                    "logit_bias",
-                    "user",
-                    "seed",
-                }
-                clean_kwargs = {k: v for k, v in kwargs.items() if k in valid_params}
-
-                # Call OpenAI API directly (async)
-                response = await openai_client.chat.completions.create(
-                    model=llm_client.config.model,
-                    messages=messages,
-                    **clean_kwargs,
-                )
-
-                return response.choices[0].message.content
+            # Get model function from unified LLM client
+            # This handles all provider differences and env var setup for LightRAG
+            llm_model_func = llm_client.get_model_func()
 
             config = RAGAnythingConfig(
                 working_dir=working_dir,

src/services/rag/components/indexers/lightrag.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 LightRAG Indexer
 ================
@@ -53,57 +54,17 @@ class LightRAGIndexer(BaseComponent):
 
         try:
             from lightrag import LightRAG
-            from openai import AsyncOpenAI
 
             from src.services.embedding import get_embedding_client
             from src.services.llm import get_llm_client
 
+            # Use unified LLM client from src/services/llm
             llm_client = get_llm_client()
             embed_client = get_embedding_client()
 
-            # Create AsyncOpenAI client directly
-            openai_client = AsyncOpenAI(
-                api_key=llm_client.config.api_key,
-                base_url=llm_client.config.base_url,
-            )
-
-            # LLM function using services (ASYNC - LightRAG expects async functions)
-            async def llm_model_func(prompt, system_prompt=None, history_messages=None, **kwargs):
-                """Custom async LLM function that bypasses LightRAG's openai_complete_if_cache."""
-                if history_messages is None:
-                    history_messages = []
-
-                # Build messages
-                messages = []
-                if system_prompt:
-                    messages.append({"role": "system", "content": system_prompt})
-                messages.extend(history_messages)
-                messages.append({"role": "user", "content": prompt})
-
-                # Whitelist only valid OpenAI parameters
-                valid_params = {
-                    "temperature",
-                    "top_p",
-                    "n",
-                    "stream",
-                    "stop",
-                    "max_tokens",
-                    "presence_penalty",
-                    "frequency_penalty",
-                    "logit_bias",
-                    "user",
-                    "seed",
-                }
-                clean_kwargs = {k: v for k, v in kwargs.items() if k in valid_params}
-
-                # Call OpenAI API directly (async)
-                response = await openai_client.chat.completions.create(
-                    model=llm_client.config.model,
-                    messages=messages,
-                    **clean_kwargs,
-                )
-
-                return response.choices[0].message.content
+            # Get model function from unified LLM client
+            # This handles all provider differences and env var setup for LightRAG
+            llm_model_func = llm_client.get_model_func()
 
             # Create pure LightRAG instance (no multimodal)
             rag = LightRAG(

src/services/rag/components/indexers/vector.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 Vector Indexer
 ==============

src/services/rag/components/parsers/__init__.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 Document Parsers
 ================

src/services/rag/components/parsers/base.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 Base Parser
 ===========

src/services/rag/components/parsers/markdown.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 Markdown Parser
 ===============

src/services/rag/components/parsers/pdf.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 PDF Parser
 ==========

src/services/rag/components/parsers/text.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 Text Parser
 ===========

src/services/rag/components/retrievers/__init__.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 Document Retrievers
 ===================

src/services/rag/components/retrievers/base.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 Base Retriever
 ==============

src/services/rag/components/retrievers/dense.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 Dense Retriever
 ===============

src/services/rag/components/retrievers/hybrid.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 Hybrid Retriever
 ================
@@ -50,58 +51,18 @@ class HybridRetriever(BaseComponent):
             sys.path.insert(0, str(raganything_path))
 
         try:
-            from openai import AsyncOpenAI
             from raganything import RAGAnything, RAGAnythingConfig
 
             from src.services.embedding import get_embedding_client
             from src.services.llm import get_llm_client
 
+            # Use unified LLM client from src/services/llm
             llm_client = get_llm_client()
             embed_client = get_embedding_client()
 
-            # Create AsyncOpenAI client directly
-            openai_client = AsyncOpenAI(
-                api_key=llm_client.config.api_key,
-                base_url=llm_client.config.base_url,
-            )
-
-            # LLM function using services (ASYNC - LightRAG expects async functions)
-            async def llm_model_func(prompt, system_prompt=None, history_messages=None, **kwargs):
-                """Custom async LLM function that bypasses LightRAG's openai_complete_if_cache."""
-                if history_messages is None:
-                    history_messages = []
-
-                # Build messages
-                messages = []
-                if system_prompt:
-                    messages.append({"role": "system", "content": system_prompt})
-                messages.extend(history_messages)
-                messages.append({"role": "user", "content": prompt})
-
-                # Whitelist only valid OpenAI parameters
-                valid_params = {
-                    "temperature",
-                    "top_p",
-                    "n",
-                    "stream",
-                    "stop",
-                    "max_tokens",
-                    "presence_penalty",
-                    "frequency_penalty",
-                    "logit_bias",
-                    "user",
-                    "seed",
-                }
-                clean_kwargs = {k: v for k, v in kwargs.items() if k in valid_params}
-
-                # Call OpenAI API directly (async)
-                response = await openai_client.chat.completions.create(
-                    model=llm_client.config.model,
-                    messages=messages,
-                    **clean_kwargs,
-                )
-
-                return response.choices[0].message.content
+            # Get model function from unified LLM client
+            # This handles all provider differences and env var setup for LightRAG
+            llm_model_func = llm_client.get_model_func()
 
             config = RAGAnythingConfig(
                 working_dir=working_dir,