doc: update

Author: Bingxi Zhao

.github/workflows/linting.yaml

@@ -38,7 +38,8 @@ jobs:
       - name: Install pre-commit
         run: |
           python -m pip install --upgrade pip
-          pip install pre-commit
+          # Install pre-commit and tomli (required for bandit to read pyproject.toml)
+          pip install pre-commit tomli
 
       - name: Run pre-commit on Python files
         run: |

.github/workflows/tests.yml

@@ -73,13 +73,14 @@ jobs:
       - name: Check module imports
         run: |
           echo "🐍 Testing with Python ${{ matrix.python-version }}"
-          python -c "from src.services.llm import complete, stream, fetch_models, sanitize_url; print('✅ LLM service imports OK')"
+          # Core service imports (no heavy RAG dependencies)
           python -c "from src.services.llm.config import get_llm_config; print('✅ LLM config imports OK')"
+          python -c "from src.services.llm.factory import complete, stream; print('✅ LLM factory imports OK')"
+          python -c "from src.services.llm.utils import sanitize_url; print('✅ LLM utils imports OK')"
           python -c "from src.services.config.loader import load_config_with_main; print('✅ Config loader imports OK')"
           python -c "from src.services.config.unified_config import UnifiedConfigManager; print('✅ Unified config imports OK')"
           python -c "from src.logging import get_logger; print('✅ Logging imports OK')"
-          python -c "from src.services.prompt import get_prompt_manager; print('✅ Prompt service imports OK')"
-          python -c "from src.services.search import web_search; print('✅ Search service imports OK')"
+          python -c "from src.services.prompt.manager import PromptManager; print('✅ Prompt manager imports OK')"
         env:
           PYTHONPATH: ${{ github.workspace }}
 

.pre-commit-config.yaml

@@ -87,6 +87,7 @@ repos:
       - id: bandit
         args: [-c, pyproject.toml, -q]
         exclude: ^tests/
+        additional_dependencies: ["bandit[toml]"]
 
   # ============================================
   # Type checking

README.md

@@ -45,7 +45,7 @@
 
 ### 📦 Releases
 
-> **[2026.1.18]** Release [v0.5.1](https://github.com/HKUDS/DeepTutor/releases/tag/v0.5.1) - Enhance RAG pipeline with Docling support and improve CI/CD workflows with several minor bugs fixed -- Thanks to all the feedbacks!
+> **[2026.1.18]** Release [v0.5.2](https://github.com/HKUDS/DeepTutor/releases/tag/v0.5.1) - Enhance RAG pipeline with Docling support and improve CI/CD workflows with several minor bugs fixed -- Thanks to all the feedbacks!
 
 <details>
 <summary>History releases</summary>

src/services/__init__.py

@@ -43,7 +43,9 @@
     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",
@@ -55,3 +57,16 @@
     "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/llm/__init__.py

@@ -48,8 +48,8 @@
     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,
@@ -140,7 +140,7 @@
     "DEFAULT_MAX_RETRIES",
     "DEFAULT_RETRY_DELAY",
     "DEFAULT_EXPONENTIAL_BACKOFF",
-    # Providers
+    # Providers (lazy loaded)
     "cloud_provider",
     "local_provider",
     # Utils
@@ -151,3 +151,16 @@
     "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}")

src/services/llm/cloud_provider.py

@@ -12,13 +12,26 @@
 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")
 
+# 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 supports_response_format
 from .config import get_token_limit_kwargs
 from .exceptions import LLMAPIError, LLMAuthenticationError, LLMConfigError
@@ -183,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)

src/services/rag/__init__.py

@@ -40,12 +40,20 @@
 
 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
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
 __all__ = [
     # Service (recommended entry point)
     "RAGService",
@@ -60,6 +68,6 @@
     "list_pipelines",
     "register_pipeline",
     "has_pipeline",
-    # Pipeline implementations
+    # Pipeline implementations (lazy loaded)
     "RAGAnythingPipeline",
 ]

src/services/rag/factory.py

@@ -4,22 +4,38 @@
 ================
 
 Factory for creating and managing RAG pipelines.
+
+Note: Pipeline imports are lazy to avoid importing heavy dependencies (lightrag, llama_index, etc.)
+at module load time. This allows the core services to be imported without RAG dependencies.
 """
 
 from typing import Callable, Dict, List, Optional
 import warnings
 
-from .pipelines import lightrag, llamaindex
-from .pipelines.raganything import RAGAnythingPipeline
-from .pipelines.raganything_docling import RAGAnythingDoclingPipeline
+# Pipeline registry - populated lazily
+_PIPELINES: Dict[str, Callable] = {}
+_PIPELINES_INITIALIZED = False
+
+
+def _init_pipelines():
+    """Lazily initialize pipeline registry to avoid import errors when RAG deps not installed."""
+    global _PIPELINES, _PIPELINES_INITIALIZED
+    if _PIPELINES_INITIALIZED:
+        return
 
-# Pipeline registry
-_PIPELINES: Dict[str, Callable] = {
-    "raganything": RAGAnythingPipeline,  # Full multimodal: MinerU parser, deep analysis (slow, thorough)
-    "raganything_docling": RAGAnythingDoclingPipeline,  # Docling parser: Office/HTML friendly, easier setup
-    "lightrag": lightrag.LightRAGPipeline,  # Knowledge graph: PDFParser, fast text-only (medium speed)
-    "llamaindex": llamaindex.LlamaIndexPipeline,  # Vector-only: Simple chunking, fast (fastest)
-}
+    from .pipelines import lightrag, llamaindex
+    from .pipelines.raganything import RAGAnythingPipeline
+    from .pipelines.raganything_docling import RAGAnythingDoclingPipeline
+
+    _PIPELINES.update(
+        {
+            "raganything": RAGAnythingPipeline,  # Full multimodal: MinerU parser, deep analysis (slow, thorough)
+            "raganything_docling": RAGAnythingDoclingPipeline,  # Docling parser: Office/HTML friendly, easier setup
+            "lightrag": lightrag.LightRAGPipeline,  # Knowledge graph: PDFParser, fast text-only (medium speed)
+            "llamaindex": llamaindex.LlamaIndexPipeline,  # Vector-only: Simple chunking, fast (fastest)
+        }
+    )
+    _PIPELINES_INITIALIZED = True
 
 
 def get_pipeline(name: str = "raganything", kb_base_dir: Optional[str] = None, **kwargs):
@@ -37,6 +53,7 @@ def get_pipeline(name: str = "raganything", kb_base_dir: Optional[str] = None, *
     Raises:
         ValueError: If pipeline name is not found
     """
+    _init_pipelines()
     if name not in _PIPELINES:
         available = list(_PIPELINES.keys())
         raise ValueError(f"Unknown pipeline: {name}. Available: {available}")
@@ -98,6 +115,7 @@ def register_pipeline(name: str, factory: Callable):
         name: Pipeline name
         factory: Factory function or class that creates the pipeline
     """
+    _init_pipelines()
     _PIPELINES[name] = factory
 
 
@@ -111,6 +129,7 @@ def has_pipeline(name: str) -> bool:
     Returns:
         True if pipeline exists
     """
+    _init_pipelines()
     return name in _PIPELINES