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

src/services/llm/capabilities.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 Provider Capabilities
 =====================
@@ -120,6 +121,14 @@ PROVIDER_CAPABILITIES: dict[str, dict[str, Any]] = {
         "supports_tools": False,
         "system_in_messages": True,
     },
+    # RealTimeX SDK (proxy to configured providers)
+    "realtimex": {
+        "supports_response_format": True,  # Proxied to underlying provider
+        "supports_streaming": True,  # SDK supports chat_stream()
+        "supports_tools": True,  # Depends on underlying provider
+        "system_in_messages": True,  # SDK uses messages array format
+        "is_proxy": True,  # SDK proxies to actual LLM providers
+    },
 }
 
 # Default capabilities for unknown providers (assume OpenAI-compatible)
@@ -129,6 +138,7 @@ DEFAULT_CAPABILITIES: dict[str, Any] = {
     "supports_tools": False,
     "system_in_messages": True,
     "has_thinking_tags": False,
+    "forced_temperature": None,  # None means no forced value, use requested temperature
 }
 
 # Model-specific overrides
@@ -161,6 +171,17 @@ MODEL_OVERRIDES: dict[str, dict[str, Any]] = {
         "supports_response_format": False,
         "system_in_messages": False,
     },
+    # Reasoning models - only support temperature=1.0
+    # See: https://github.com/HKUDS/DeepTutor/issues/141
+    "gpt-5": {
+        "forced_temperature": 1.0,
+    },
+    "o1": {
+        "forced_temperature": 1.0,
+    },
+    "o3": {
+        "forced_temperature": 1.0,
+    },
 }
 
 
@@ -299,6 +320,31 @@ def requires_api_version(binding: str, model: Optional[str] = None) -> bool:
     return get_capability(binding, "requires_api_version", model, default=False)
 
 
+def get_effective_temperature(
+    binding: str,
+    model: Optional[str] = None,
+    requested_temp: float = 0.7,
+) -> float:
+    """
+    Get the effective temperature value for a model.
+
+    Some models (e.g., o1, o3, gpt-5) only support a fixed temperature value (1.0).
+    This function returns the forced temperature if defined, otherwise the requested value.
+
+    Args:
+        binding: Provider binding name
+        model: Optional model name for model-specific overrides
+        requested_temp: The temperature value requested by the caller (default: 0.7)
+
+    Returns:
+        The effective temperature to use for the API call
+    """
+    forced_temp = get_capability(binding, "forced_temperature", model)
+    if forced_temp is not None:
+        return forced_temp
+    return requested_temp
+
+
 __all__ = [
     "PROVIDER_CAPABILITIES",
     "MODEL_OVERRIDES",
@@ -310,4 +356,5 @@ __all__ = [
     "has_thinking_tags",
     "supports_tools",
     "requires_api_version",
+    "get_effective_temperature",
 ]

src/services/llm/client.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 LLM Client
 ==========
@@ -31,9 +32,38 @@ class LLMClient:
         Args:
             config: LLM configuration. If None, loads from environment.
         """
+
         self.config = config or get_llm_config()
         self.logger = get_logger("LLMClient")
 
+        # Set environment variables for LightRAG compatibility
+        # LightRAG's internal functions (openai_complete_if_cache, etc.) read from
+        # os.environ["OPENAI_API_KEY"] even when api_key is passed as parameter.
+        # We must set these env vars early to ensure all LightRAG operations work.
+        self._setup_openai_env_vars()
+
+    def _setup_openai_env_vars(self):
+        """
+        Set OpenAI environment variables for LightRAG compatibility.
+
+        LightRAG's internal functions read from os.environ["OPENAI_API_KEY"]
+        even when api_key is passed as parameter. This method ensures the
+        environment variables are set for all LightRAG operations.
+        """
+        import os
+
+        binding = getattr(self.config, "binding", "openai")
+
+        # Only set env vars for OpenAI-compatible bindings
+        if binding in ("openai", "azure_openai", "gemini"):
+            if self.config.api_key:
+                os.environ["OPENAI_API_KEY"] = self.config.api_key
+                self.logger.debug("Set OPENAI_API_KEY env var for LightRAG compatibility")
+
+            if self.config.base_url:
+                os.environ["OPENAI_BASE_URL"] = self.config.base_url
+                self.logger.debug(f"Set OPENAI_BASE_URL env var to {self.config.base_url}")
+
     async def complete(
         self,
         prompt: str,
@@ -128,6 +158,7 @@ class LLMClient:
             return llm_model_func_via_factory
 
         # OpenAI-compatible bindings use lightrag (has caching)
+        # Note: Environment variables are already set in __init__ via _setup_openai_env_vars()
         from lightrag.llm.openai import openai_complete_if_cache
 
         def llm_model_func(
@@ -196,6 +227,7 @@ class LLMClient:
             return vision_model_func_via_factory
 
         # OpenAI-compatible bindings
+        # Note: Environment variables are already set in __init__ via _setup_openai_env_vars()
         from lightrag.llm.openai import openai_complete_if_cache
 
         # Get api_version once for reuse

src/services/llm/cloud_provider.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 Cloud LLM Provider
 ==================
@@ -11,14 +12,27 @@ import os
 from typing import AsyncGenerator, Dict, List, Optional
 
 import aiohttp
-from lightrag.llm.openai import openai_complete_if_cache
 
 # Get loggers for suppression during fallback scenarios
 # (lightrag logs errors internally before raising exceptions)
 _lightrag_logger = logging.getLogger("lightrag")
 _openai_logger = logging.getLogger("openai")
 
-from .capabilities import supports_response_format
+# Lazy import for lightrag to avoid import errors when not installed
+_openai_complete_if_cache = None
+
+
+def _get_openai_complete_if_cache():
+    """Lazy load openai_complete_if_cache from lightrag."""
+    global _openai_complete_if_cache
+    if _openai_complete_if_cache is None:
+        from lightrag.llm.openai import openai_complete_if_cache
+
+        _openai_complete_if_cache = openai_complete_if_cache
+    return _openai_complete_if_cache
+
+
+from .capabilities import get_effective_temperature, supports_response_format
 from .config import get_token_limit_kwargs
 from .exceptions import LLMAPIError, LLMAuthenticationError, LLMConfigError
 from .utils import (
@@ -182,6 +196,7 @@ async def _openai_complete(
         _openai_logger.setLevel(logging.CRITICAL)
         try:
             # model and prompt must be positional arguments
+            openai_complete_if_cache = _get_openai_complete_if_cache()
             content = await openai_complete_if_cache(model, prompt, **lightrag_kwargs)
         finally:
             _lightrag_logger.setLevel(original_lightrag_level)
@@ -203,7 +218,9 @@ async def _openai_complete(
                 {"role": "system", "content": system_prompt},
                 {"role": "user", "content": prompt},
             ],
-            "temperature": kwargs.get("temperature", 0.7),
+            "temperature": get_effective_temperature(
+                binding, model, kwargs.get("temperature", 0.7)
+            ),
         }
 
         # Handle max_tokens / max_completion_tokens based on model
@@ -279,7 +296,7 @@ async def _openai_stream(
     data = {
         "model": model,
         "messages": msg_list,
-        "temperature": kwargs.get("temperature", 0.7),
+        "temperature": get_effective_temperature(binding, model, kwargs.get("temperature", 0.7)),
         "stream": True,
     }
 

src/services/llm/config.py

@@ -26,6 +26,37 @@ load_dotenv(PROJECT_ROOT / "DeepTutor.env", override=False)
 load_dotenv(PROJECT_ROOT / ".env", override=False)
 
 
+def _setup_openai_env_vars_early():
+    """
+    Set OPENAI_API_KEY environment variable early for LightRAG compatibility.
+
+    LightRAG's internal functions (e.g., create_openai_async_client) read directly
+    from os.environ["OPENAI_API_KEY"] instead of using the api_key parameter.
+    This function ensures the environment variable is set as soon as this module
+    is imported, before any LightRAG operations can occur.
+
+    This is called at module load time to ensure env vars are set before any
+    RAG operations, including those in worker threads/processes.
+    """
+    binding = os.getenv("LLM_BINDING", "openai")
+    api_key = os.getenv("LLM_API_KEY")
+    base_url = os.getenv("LLM_HOST")
+
+    # Only set env vars for OpenAI-compatible bindings
+    if binding in ("openai", "azure_openai", "gemini"):
+        if api_key and not os.getenv("OPENAI_API_KEY"):
+            os.environ["OPENAI_API_KEY"] = api_key
+            logger.debug("Set OPENAI_API_KEY env var for LightRAG compatibility (early init)")
+
+        if base_url and not os.getenv("OPENAI_BASE_URL"):
+            os.environ["OPENAI_BASE_URL"] = base_url
+            logger.debug(f"Set OPENAI_BASE_URL env var to {base_url} (early init)")
+
+
+# Execute early setup at module import time
+_setup_openai_env_vars_early()
+
+
 @dataclass
 class LLMConfig:
     """LLM configuration dataclass."""
@@ -37,6 +68,7 @@ class LLMConfig:
     api_version: Optional[str] = None
     max_tokens: int = 4096
     temperature: float = 0.7
+    source: Optional[str] = None  # "realtimex" when using RTX SDK
 
 
 def _strip_value(value: Optional[str]) -> Optional[str]:
@@ -95,10 +127,11 @@ def get_llm_config() -> LLMConfig:
         if config:
             return LLMConfig(
                 binding=config.get("provider", "openai"),
-                model=config["model"],
+                model=config.get("model", ""),
                 api_key=config.get("api_key", ""),
                 base_url=config.get("base_url"),
                 api_version=config.get("api_version"),
+                source=config.get("source"),  # "realtimex" when using RTX
             )
     except ImportError:
         # Unified config service not yet available, fall back to env
@@ -128,10 +161,11 @@ async def get_llm_config_async() -> LLMConfig:
         if config:
             return LLMConfig(
                 binding=config.get("provider", "openai"),
-                model=config["model"],
+                model=config.get("model", ""),
                 api_key=config.get("api_key", ""),
                 base_url=config.get("base_url"),
                 api_version=config.get("api_version"),
+                source=config.get("source"),  # "realtimex" when using RTX
             )
     except ImportError:
         pass

src/services/llm/error_mapping.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 Error Mapping - Map provider-specific errors to unified exceptions.
 """

src/services/llm/exceptions.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 LLM Service Exceptions
 ======================
@@ -137,6 +138,33 @@ class ProviderContextWindowError(LLMAPIError):
     pass
 
 
+# RealTimeX-specific exceptions (for SDK integration)
+class RealTimeXError(LLMAPIError):
+    """
+    Base exception for RealTimeX SDK errors.
+
+    Raised when interacting with RealTimeX SDK proxy fails.
+    """
+
+    def __init__(self, message: str, error_code: Optional[str] = None):
+        super().__init__(message, error_code)
+
+
+class RealTimeXPermissionError(LLMAuthenticationError):
+    """
+    Exception raised when RealTimeX SDK permission is required or denied.
+
+    Args:
+        permission: The permission that was required (e.g., 'llm.chat', 'llm.embed')
+        message: Optional custom error message
+    """
+
+    def __init__(self, permission: str, message: Optional[str] = None):
+        self.permission = permission
+        msg = message or f"RealTimeX permission required: {permission}"
+        super().__init__(msg)
+
+
 __all__ = [
     "LLMError",
     "LLMConfigError",
@@ -149,4 +177,6 @@ __all__ = [
     "LLMParseError",
     "ProviderQuotaExceededError",
     "ProviderContextWindowError",
+    "RealTimeXError",
+    "RealTimeXPermissionError",
 ]

src/services/llm/factory.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 LLM Factory - Central Hub for LLM Calls
 =======================================
@@ -20,9 +21,10 @@ CloudProvider      LocalProvider
               ↓                   ↓
 OpenAI/DeepSeek/etc    LM Studio/Ollama/etc
 
-Routing:
-- Automatically routes to local_provider for local URLs (localhost, 127.0.0.1, etc.)
-- Routes to cloud_provider for all other URLs
+Routing (Priority Order):
+1. RealTimeX SDK (if RTX_APP_ID detected)
+2. Local Provider (for localhost/127.0.0.1 URLs)
+3. Cloud Provider (default)
 
 Retry Mechanism:
 - Automatic retry with exponential backoff for transient errors
@@ -36,6 +38,7 @@ from typing import Any, AsyncGenerator, Dict, List, Optional
 import tenacity
 
 from src.logging.logger import get_logger
+from src.utils.realtimex import should_use_realtimex_sdk
 
 from . import cloud_provider, local_provider
 from .config import get_llm_config
@@ -51,8 +54,8 @@ from .utils import is_local_llm_server
 logger = get_logger("LLMFactory")
 
 # Default retry configuration
-DEFAULT_MAX_RETRIES = 3
-DEFAULT_RETRY_DELAY = 1.0  # seconds
+DEFAULT_MAX_RETRIES = 5  # Increased for complex agents like Research
+DEFAULT_RETRY_DELAY = 2.0  # seconds
 DEFAULT_EXPONENTIAL_BACKOFF = True
 
 
@@ -141,8 +144,8 @@ async def complete(
         api_version: API version for Azure OpenAI (optional)
         binding: Provider binding type (optional)
         messages: Pre-built messages array (optional)
-        max_retries: Maximum number of retry attempts (default: 3)
-        retry_delay: Initial delay between retries in seconds (default: 1.0)
+        max_retries: Maximum number of retry attempts (default: 5)
+        retry_delay: Initial delay between retries in seconds (default: 2.0)
         exponential_backoff: Whether to use exponential backoff (default: True)
         **kwargs: Additional parameters (temperature, max_tokens, etc.)
 
@@ -150,6 +153,7 @@ async def complete(
         str: The LLM response
     """
     # Get config if parameters not provided
+    config = None
     if not model or not base_url:
         config = get_llm_config()
         model = model or config.model
@@ -158,7 +162,17 @@ async def complete(
         api_version = api_version or config.api_version
         binding = binding or config.binding or "openai"
 
-    # Determine which provider to use
+    # ROUTING LOGIC (Priority order):
+
+    # 1. RealTimeX SDK (when active config has source="realtimex")
+    if config and getattr(config, "source", None) == "realtimex" and should_use_realtimex_sdk():
+        from . import realtimex_provider
+
+        return await realtimex_provider.complete(
+            prompt=prompt, system_prompt=system_prompt, model=model, messages=messages, **kwargs
+        )
+
+    # 2. Determine which provider to use (local vs cloud)
     use_local = _should_use_local(base_url)
 
     # Define helper to determine if a generic LLMAPIError is retriable
@@ -189,6 +203,9 @@ async def complete(
 
         return False
 
+    # Calculate total attempts for logging (1 initial + max_retries)
+    total_attempts = max_retries + 1
+
     # Define the actual completion function with tenacity retry
     @tenacity.retry(
         retry=(
@@ -196,10 +213,10 @@ async def complete(
             | tenacity.retry_if_exception_type(LLMTimeoutError)
             | tenacity.retry_if_exception(_is_retriable_llm_api_error)
         ),
-        wait=tenacity.wait_exponential(multiplier=retry_delay, min=retry_delay, max=60),
-        stop=tenacity.stop_after_attempt(max_retries + 1),
+        wait=tenacity.wait_exponential(multiplier=retry_delay, min=retry_delay, max=120),
+        stop=tenacity.stop_after_attempt(total_attempts),
         before_sleep=lambda retry_state: logger.warning(
-            f"LLM call failed (attempt {retry_state.attempt_number}/{max_retries + 1}), "
+            f"LLM call failed (attempt {retry_state.attempt_number}/{total_attempts}), "
             f"retrying in {retry_state.upcoming_sleep:.1f}s... Error: {str(retry_state.outcome.exception())}"
         ),
     )
@@ -268,8 +285,8 @@ async def stream(
         api_version: API version for Azure OpenAI (optional)
         binding: Provider binding type (optional)
         messages: Pre-built messages array (optional)
-        max_retries: Maximum number of retry attempts (default: 3)
-        retry_delay: Initial delay between retries in seconds (default: 1.0)
+        max_retries: Maximum number of retry attempts (default: 5)
+        retry_delay: Initial delay between retries in seconds (default: 2.0)
         exponential_backoff: Whether to use exponential backoff (default: True)
         **kwargs: Additional parameters (temperature, max_tokens, etc.)
 
@@ -277,6 +294,7 @@ async def stream(
         str: Response chunks
     """
     # Get config if parameters not provided
+    config = None
     if not model or not base_url:
         config = get_llm_config()
         model = model or config.model
@@ -285,7 +303,19 @@ async def stream(
         api_version = api_version or config.api_version
         binding = binding or config.binding or "openai"
 
-    # Determine which provider to use
+    # ROUTING LOGIC (Priority order):
+
+    # 1. RealTimeX SDK (when active config has source="realtimex")
+    if config and getattr(config, "source", None) == "realtimex" and should_use_realtimex_sdk():
+        from . import realtimex_provider
+
+        async for chunk in realtimex_provider.stream(
+            prompt=prompt, system_prompt=system_prompt, model=model, messages=messages, **kwargs
+        ):
+            yield chunk
+        return
+
+    # 2. Determine which provider to use (local vs cloud)
     use_local = _should_use_local(base_url)
 
     # Build call kwargs
@@ -305,10 +335,13 @@ async def stream(
         call_kwargs["binding"] = binding or "openai"
 
     # Retry logic for streaming (retry on connection errors)
+    # Total attempts = 1 initial + max_retries
+    total_attempts = max_retries + 1
     last_exception = None
     delay = retry_delay
+    max_delay = 120  # Cap maximum delay at 120 seconds (consistent with complete())
 
-    for attempt in range(max_retries + 1):
+    for attempt in range(total_attempts):
         try:
             # Route to appropriate provider
             if use_local:
@@ -328,7 +361,7 @@ async def stream(
 
             # Calculate delay for next attempt
             if exponential_backoff:
-                current_delay = delay * (2**attempt)
+                current_delay = min(delay * (2**attempt), max_delay)
             else:
                 current_delay = delay
 
@@ -336,6 +369,12 @@ async def stream(
             if isinstance(e, LLMRateLimitError) and e.retry_after:
                 current_delay = max(current_delay, e.retry_after)
 
+            # Log retry attempt (consistent with complete() function)
+            logger.warning(
+                f"LLM streaming failed (attempt {attempt + 1}/{total_attempts}), "
+                f"retrying in {current_delay:.1f}s... Error: {str(e)}"
+            )
+
             # Wait before retrying
             await asyncio.sleep(current_delay)
 

src/services/llm/local_provider.py

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

src/services/llm/providers/anthropic.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 import anthropic
 
 from ..registry import register_provider

src/services/llm/providers/base_provider.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 Base LLM Provider - Unified interface and configuration.
 """

src/services/llm/providers/open_ai.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 import os
 
 import httpx