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

src/services/__init__.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 Services Layer
 ==============
@@ -42,7 +43,9 @@ Usage:
     result = web_search("What is AI?")
 """
 
-from . import config, embedding, llm, prompt, rag, search, setup, tts
+# Note: rag and embedding modules are lazy-loaded via __getattr__
+# to avoid importing heavy dependencies (lightrag, llama_index) at module load time
+from . import config, llm, prompt, search, setup, tts
 
 __all__ = [
     "llm",
@@ -54,3 +57,16 @@ __all__ = [
     "setup",
     "config",
 ]
+
+
+def __getattr__(name: str):
+    """Lazy import for modules that depend on heavy libraries."""
+    if name == "rag":
+        from . import rag
+
+        return rag
+    if name == "embedding":
+        from . import embedding
+
+        return embedding
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

src/services/config/__init__.py

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

src/services/config/knowledge_base_config.py

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

src/services/config/loader.py

@@ -191,7 +191,7 @@ def parse_language(language: Any) -> str:
         lang_lower = language.lower()
         if lang_lower in ["en", "english"]:
             return "en"
-        if lang_lower in ["zh", "chinese"]:
+        if lang_lower in ["zh", "chinese", "cn"]:
             return "zh"
 
     return "zh"  # Default Chinese

src/services/config/unified_config.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 Unified Configuration Manager
 =============================
@@ -133,6 +134,68 @@ class UnifiedConfigManager:
         # Ensure default configs exist and are synced with env on startup
         self._ensure_default_configs()
 
+        # Auto-activate RealTimeX if available (unless user has explicitly chosen another config)
+        self._auto_activate_rtx_if_available()
+
+    def _auto_activate_rtx_if_available(self) -> None:
+        """
+        Auto-activate RealTimeX for LLM and Embedding when SDK is detected.
+
+        Sets default provider (realtimexai) and models if no RTX selection exists yet.
+        Only activates RTX if:
+        1. SDK is available
+        2. User hasn't explicitly chosen a different config (active_id is still 'default')
+        """
+        try:
+            from src.utils.realtimex import (
+                get_rtx_active_config,
+                set_rtx_active_config,
+                should_use_realtimex_sdk,
+            )
+
+            if not should_use_realtimex_sdk():
+                return
+
+            # Auto-activate for LLM
+            llm_data = self._load_configs(ConfigType.LLM)
+            llm_active_id = llm_data.get("active_id", "default")
+
+            # Only auto-activate if still using default
+            if llm_active_id == "default":
+                rtx_llm_config = get_rtx_active_config("llm")
+                if not rtx_llm_config:
+                    # Set default RTX LLM config
+                    set_rtx_active_config("llm", "realtimexai", "gpt-4o-mini")
+                    logger.info("Auto-configured RealTimeX LLM with default model: gpt-4o-mini")
+
+                # Activate RTX for LLM
+                self.set_active_config(ConfigType.LLM, "rtx")
+                logger.info("Auto-activated RealTimeX for LLM")
+
+            # Auto-activate for Embedding
+            emb_data = self._load_configs(ConfigType.EMBEDDING)
+            emb_active_id = emb_data.get("active_id", "default")
+
+            # Only auto-activate if still using default
+            if emb_active_id == "default":
+                rtx_emb_config = get_rtx_active_config("embedding")
+                if not rtx_emb_config:
+                    # Set default RTX Embedding config
+                    set_rtx_active_config("embedding", "realtimexai", "text-embedding-3-small")
+                    logger.info(
+                        "Auto-configured RealTimeX Embedding with default model: text-embedding-3-small"
+                    )
+
+                # Activate RTX for Embedding
+                self.set_active_config(ConfigType.EMBEDDING, "rtx")
+                logger.info("Auto-activated RealTimeX for Embedding")
+
+        except ImportError:
+            # RTX utilities not available
+            pass
+        except Exception as e:
+            logger.warning(f"Failed to auto-activate RealTimeX: {e}")
+
     def _ensure_default_configs(self) -> None:
         """
         Ensure default configurations exist in storage files and sync with env.
@@ -392,6 +455,58 @@ class UnifiedConfigManager:
 
         return resolved
 
+    def _build_rtx_virtual_config(self, config_type: ConfigType) -> Optional[Dict[str, Any]]:
+        """
+        Build a virtual RTX config entry for display in the config list.
+
+        This config represents the RealTimeX SDK integration and is shown
+        when the SDK is connected. It reads the user's active selection
+        from rtx_active.json.
+
+        Returns:
+            Dict with RTX config for display, or None if RTX not available
+        """
+        try:
+            from src.utils.realtimex import get_rtx_active_config, should_use_realtimex_sdk
+
+            if not should_use_realtimex_sdk():
+                return None
+
+            # Only LLM and Embedding are supported via RTX
+            if config_type not in (ConfigType.LLM, ConfigType.EMBEDDING):
+                return None
+
+            # Get user's active selection (or use defaults)
+            active = get_rtx_active_config(config_type.value)
+
+            if active:
+                provider = active.get("provider", "realtimexai")
+                model = active.get("model", "")
+            else:
+                # Use defaults
+                provider = "realtimexai"
+                if config_type == ConfigType.LLM:
+                    model = "gpt-4o-mini"
+                else:  # Embedding
+                    model = "text-embedding-3-small"
+
+            return {
+                "id": "rtx",
+                "name": "RealTimeX",
+                "is_default": False,
+                "provider": provider,
+                "model": model,
+                "source": "realtimex",  # Flag for services to route through SDK
+                "api_key": "—",  # No API key needed
+                "base_url": "—",  # Uses SDK proxy
+            }
+
+        except ImportError:
+            return None
+        except Exception as e:
+            logger.warning(f"Failed to build RTX virtual config: {e}")
+            return None
+
     def get_provider_options(self, config_type: ConfigType) -> List[str]:
         """Get available provider options for a config type."""
         return PROVIDER_OPTIONS.get(config_type, [])
@@ -404,6 +519,9 @@ class UnifiedConfigManager:
         For display purposes, the default config shows:
         - Current model/provider from env (dynamically refreshed)
         - base_url/api_key as "***" (hidden for security)
+
+        When RealTimeX SDK is connected, a virtual "RealTimeX" config
+        is prepended to the list for LLM and Embedding types.
         """
         data = self._load_configs(config_type)
         configs = data.get("configs", [])
@@ -416,6 +534,12 @@ class UnifiedConfigManager:
         result = []
         has_default = False
 
+        # Prepend RTX virtual config if available
+        rtx_config = self._build_rtx_virtual_config(config_type)
+        if rtx_config:
+            rtx_config["is_active"] = active_id == "rtx"
+            result.append(rtx_config)
+
         for cfg in configs:
             if cfg.get("id") == "default":
                 # Use the dynamically built display config for default
@@ -437,7 +561,9 @@ class UnifiedConfigManager:
         # If no default config found in file, prepend the display default
         if not has_default:
             display_default["is_active"] = active_id == "default"
-            result.insert(0, display_default)
+            # Insert after RTX config if present, otherwise at the beginning
+            insert_pos = 1 if rtx_config else 0
+            result.insert(insert_pos, display_default)
 
         return result
 
@@ -456,10 +582,46 @@ class UnifiedConfigManager:
         """
         Get the currently active configuration with all values resolved.
         This is used internally when services need actual configuration values.
+
+        When active_id is 'rtx', returns a config with source='realtimex'
+        to signal services to route through the RealTimeX SDK.
         """
         data = self._load_configs(config_type)
         active_id = data.get("active_id", "default")
 
+        # Handle RTX virtual config
+        if active_id == "rtx":
+            try:
+                from src.utils.realtimex import get_rtx_active_config, should_use_realtimex_sdk
+
+                if should_use_realtimex_sdk():
+                    rtx_active = get_rtx_active_config(config_type.value)
+
+                    if rtx_active:
+                        return {
+                            "id": "rtx",
+                            "provider": rtx_active.get("provider", "realtimexai"),
+                            "model": rtx_active.get("model", ""),
+                            "source": "realtimex",  # This tells services to use SDK
+                        }
+                    else:
+                        # Return defaults when no selection exists yet
+                        default_model = (
+                            "gpt-4o-mini"
+                            if config_type == ConfigType.LLM
+                            else "text-embedding-3-small"
+                        )
+                        return {
+                            "id": "rtx",
+                            "provider": "realtimexai",
+                            "model": default_model,
+                            "source": "realtimex",
+                        }
+            except ImportError:
+                pass
+            # Fallback to default if RTX not available
+            return self._get_default_config_resolved(config_type)
+
         if active_id == "default":
             return self._get_default_config_resolved(config_type)
 
@@ -530,14 +692,59 @@ class UnifiedConfigManager:
         """Set a configuration as active."""
         data = self._load_configs(config_type)
 
-        # Verify config exists
-        if config_id != "default":
+        # Verify config exists (rtx is a special virtual config)
+        if config_id not in ("default", "rtx"):
             found = any(c.get("id") == config_id for c in data.get("configs", []))
             if not found:
                 return False
 
         data["active_id"] = config_id
-        return self._save_configs(config_type, data)
+        success = self._save_configs(config_type, data)
+
+        # Update environment variables for LightRAG compatibility when LLM config changes
+        if success and config_type == ConfigType.LLM:
+            self._update_openai_env_vars_for_lightrag()
+
+        return success
+
+    def _update_openai_env_vars_for_lightrag(self):
+        """
+        Update OPENAI_API_KEY and OPENAI_BASE_URL environment variables for LightRAG.
+
+        LightRAG's internal functions read directly from os.environ["OPENAI_API_KEY"]
+        instead of using passed parameters. This method ensures the environment
+        variables are updated when the active LLM configuration changes.
+        """
+        try:
+            config = self.get_active_config(ConfigType.LLM)
+            if not config:
+                return
+
+            provider = config.get("provider", "openai")
+            api_key = config.get("api_key", "")
+            base_url = config.get("base_url", "")
+
+            # Only set env vars for OpenAI-compatible providers
+            if provider in ("openai", "azure_openai", "gemini", "deepseek"):
+                if api_key:
+                    os.environ["OPENAI_API_KEY"] = api_key
+                    logger.debug("Updated OPENAI_API_KEY env var for LightRAG compatibility")
+
+                if base_url:
+                    os.environ["OPENAI_BASE_URL"] = base_url
+                    logger.debug(f"Updated OPENAI_BASE_URL env var to {base_url}")
+
+            # Reset LLM client singleton to pick up new configuration
+            try:
+                from src.services.llm import reset_llm_client
+
+                reset_llm_client()
+                logger.debug("Reset LLM client singleton after config change")
+            except ImportError:
+                pass
+
+        except Exception as e:
+            logger.warning(f"Failed to update OpenAI env vars: {e}")
 
     def get_env_status(self, config_type: ConfigType) -> Dict[str, bool]:
         """Check which environment variables are configured for a service type."""

src/services/embedding/__init__.py

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

src/services/embedding/adapters/__init__.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 Adapters Package
 ================
@@ -10,6 +11,7 @@ from .cohere import CohereEmbeddingAdapter
 from .jina import JinaEmbeddingAdapter
 from .ollama import OllamaEmbeddingAdapter
 from .openai_compatible import OpenAICompatibleEmbeddingAdapter
+from .realtimex import RealTimeXEmbeddingAdapter
 
 __all__ = [
     "BaseEmbeddingAdapter",
@@ -19,4 +21,5 @@ __all__ = [
     "JinaEmbeddingAdapter",
     "CohereEmbeddingAdapter",
     "OllamaEmbeddingAdapter",
+    "RealTimeXEmbeddingAdapter",
 ]

src/services/embedding/adapters/base.py

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

src/services/embedding/adapters/cohere.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """Cohere Embedding Adapter for v1 and v2 API."""
 
 import logging

src/services/embedding/adapters/jina.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """Jina AI embedding adapter with task-aware embeddings and late chunking."""
 
 import logging

src/services/embedding/adapters/ollama.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """Ollama Embedding Adapter for local embeddings."""
 
 import logging

src/services/embedding/adapters/openai_compatible.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """OpenAI-compatible embedding adapter for OpenAI, Azure, HuggingFace, LM Studio, etc."""
 
 import logging

src/services/embedding/adapters/realtimex.py

@@ -0,0 +1,125 @@
+# -*- coding: utf-8 -*-
+"""
+RealTimeX Embedding Adapter
+============================
+
+Provides embedding capabilities through RealTimeX SDK proxy.
+Used when running as a local app within RealTimeX desktop.
+"""
+
+from typing import Any, Dict
+
+from realtimex_sdk import LLMPermissionError, LLMProviderError
+
+from src.logging import get_logger
+from src.utils.realtimex import get_realtimex_sdk
+
+from .base import BaseEmbeddingAdapter, EmbeddingRequest, EmbeddingResponse
+
+logger = get_logger("RealTimeXEmbeddingAdapter")
+
+
+class RealTimeXEmbeddingAdapter(BaseEmbeddingAdapter):
+    """
+    Embedding adapter for RealTimeX SDK.
+
+    Provides embeddings through the RealTimeX Main App proxy.
+    No API key or base_url needed - uses RTX_APP_ID for authentication.
+    """
+
+    def __init__(self, config: Dict[str, Any]):
+        """
+        Initialize RealTimeX embedding adapter.
+
+        Args:
+            config: Adapter config (SDK doesn't need api_key/base_url)
+                   - model: Model name (optional, uses active provider default)
+                   - dimensions: Expected embedding dimensions
+        """
+        # Call parent init (though most fields not needed for RealTimeX)
+        super().__init__(config)
+
+        # SDK is initialized lazily on first request
+        logger.debug(
+            f"RealTimeX embedding adapter configured: "
+            f"model={self.model or 'default'}, dimensions={self.dimensions}"
+        )
+
+    async def embed(self, request: EmbeddingRequest) -> EmbeddingResponse:
+        """
+        Generate embeddings via RealTimeX SDK.
+
+        Args:
+            request: EmbeddingRequest with texts
+
+        Returns:
+            EmbeddingResponse with embeddings
+
+        Raises:
+            Exception: If SDK request fails or permission denied
+        """
+        sdk = get_realtimex_sdk()
+
+        # Use model from request, fallback to adapter config
+        model = request.model or self.model
+
+        logger.debug(
+            f"RealTimeX embed: texts_count={len(request.texts)}, model={model or 'default'}"
+        )
+
+        try:
+            # Call SDK embed function
+            result = await sdk.llm.embed(input_text=request.texts, model=model)
+
+            if not result.success:
+                error_msg = result.error or "SDK request failed"
+                logger.error(f"RealTimeX embed failed: {error_msg}")
+                raise Exception(f"RealTimeX embedding error: {error_msg}")
+
+            # Validate dimensions match if specified
+            if self.dimensions and result.dimensions != self.dimensions:
+                logger.warning(
+                    f"Dimension mismatch: expected {self.dimensions}, "
+                    f"got {result.dimensions} from {result.model}"
+                )
+
+            # Log success
+            logger.debug(
+                f"RealTimeX embed success: provider={result.provider}, "
+                f"model={result.model}, dimensions={result.dimensions}, "
+                f"embeddings_count={len(result.embeddings)}"
+            )
+
+            return EmbeddingResponse(
+                embeddings=result.embeddings,
+                model=result.model or model or "unknown",
+                dimensions=result.dimensions,
+                usage={},  # SDK doesn't currently expose usage metrics
+            )
+
+        except LLMPermissionError as e:
+            logger.error(f"RealTimeX permission error: {e}")
+            raise PermissionError(
+                "RealTimeX embedding permission required. "
+                "Ensure 'llm.embed' is in your SDK permissions."
+            ) from e
+        except LLMProviderError as e:
+            logger.error(f"RealTimeX provider error: {e}")
+            raise Exception(f"RealTimeX embedding provider error: {e}") from e
+        except Exception as e:
+            logger.error(f"RealTimeX embedding error: {e}")
+            raise Exception(f"RealTimeX embedding failed: {e}") from e
+
+    def get_model_info(self) -> Dict[str, Any]:
+        """
+        Return information about the configured model.
+
+        Returns:
+            Dictionary with model metadata
+        """
+        return {
+            "provider": "realtimex",
+            "model": self.model or "default",
+            "dimensions": self.dimensions,
+            "description": "RealTimeX SDK embedding proxy",
+        }

src/services/embedding/client.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 Embedding Client
 ================
@@ -34,6 +35,32 @@ class EmbeddingClient:
         self.logger = get_logger("EmbeddingClient")
         self.manager: EmbeddingProviderManager = get_embedding_provider_manager()
 
+        # ROUTING LOGIC: Use RealTimeX adapter when source is "realtimex"
+        if getattr(self.config, "source", None) == "realtimex":
+            try:
+                from src.utils.realtimex import should_use_realtimex_sdk
+
+                if should_use_realtimex_sdk():
+                    from .adapters.realtimex import RealTimeXEmbeddingAdapter
+
+                    adapter = RealTimeXEmbeddingAdapter(
+                        {
+                            "model": self.config.model,
+                            "dimensions": self.config.dim,
+                        }
+                    )
+
+                    self.manager.set_adapter(adapter)
+
+                    self.logger.info(
+                        f"Using RealTimeX embedding adapter (model: {self.config.model}, "
+                        f"dimensions: {self.config.dim})"
+                    )
+                    return
+            except ImportError:
+                self.logger.warning("RealTimeX SDK not available, falling back to env config")
+                pass
+
         # Initialize adapter based on binding configuration
         try:
             adapter = self.manager.get_adapter(

src/services/embedding/config.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 Embedding Configuration
 =======================
@@ -35,6 +36,7 @@ class EmbeddingConfig:
     max_tokens: int = 8192
     request_timeout: int = 30
     input_type: Optional[str] = None  # For task-aware embeddings (Cohere, Jina)
+    source: Optional[str] = None  # "realtimex" when using RTX SDK
 
     # Optional provider-specific settings
     encoding_format: str = "float"
@@ -92,6 +94,7 @@ def get_embedding_config() -> EmbeddingConfig:
                 base_url=config.get("base_url"),
                 api_version=config.get("api_version"),
                 dim=config.get("dimensions", 3072),
+                source=config.get("source"),  # "realtimex" when using RTX
             )
     except ImportError:
         # Unified config service not yet available, fall back to env

src/services/embedding/provider.py

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

src/services/llm/__init__.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 """
 LLM Service
 ===========
@@ -47,8 +48,8 @@ Usage:
     from src.services.llm import sanitize_url, is_local_llm_server
 """
 
-# Also expose the providers for direct access if needed
-from . import cloud_provider, local_provider
+# Note: cloud_provider and local_provider are lazy-loaded via __getattr__
+# to avoid importing lightrag at module load time
 from .capabilities import (
     DEFAULT_CAPABILITIES,
     MODEL_OVERRIDES,
@@ -139,7 +140,7 @@ __all__ = [
     "DEFAULT_MAX_RETRIES",
     "DEFAULT_RETRY_DELAY",
     "DEFAULT_EXPONENTIAL_BACKOFF",
-    # Providers
+    # Providers (lazy loaded)
     "cloud_provider",
     "local_provider",
     # Utils
@@ -150,3 +151,16 @@ __all__ = [
     "clean_thinking_tags",
     "extract_response_content",
 ]
+
+
+def __getattr__(name: str):
+    """Lazy import for provider modules that depend on heavy libraries."""
+    if name == "cloud_provider":
+        from . import cloud_provider
+
+        return cloud_provider
+    if name == "local_provider":
+        from . import local_provider
+
+        return local_provider
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")