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

src/services/llm/telemetry.py

@@ -0,0 +1,40 @@
+"""
+LLM Telemetry
+=============
+
+Basic telemetry tracking for LLM calls.
+"""
+
+import functools
+import logging
+from typing import Any, Callable
+
+logger = logging.getLogger(__name__)
+
+
+def track_llm_call(provider_name: str):
+    """
+    Decorator to track LLM calls for telemetry.
+
+    Args:
+        provider_name: Name of the provider being called
+
+    Returns:
+        Decorator function
+    """
+
+    def decorator(func: Callable) -> Callable:
+        @functools.wraps(func)
+        async def wrapper(*args, **kwargs) -> Any:
+            logger.debug(f"LLM call to {provider_name}: {func.__name__}")
+            try:
+                result = await func(*args, **kwargs)
+                logger.debug(f"LLM call to {provider_name} completed successfully")
+                return result
+            except Exception as e:
+                logger.warning(f"LLM call to {provider_name} failed: {e}")
+                raise
+
+        return wrapper
+
+    return decorator

src/services/llm/types.py

@@ -0,0 +1,27 @@
+from typing import Any, AsyncGenerator, Dict, Optional
+
+from pydantic import BaseModel, Field
+
+
+class TutorResponse(BaseModel):
+    content: str
+    raw_response: Dict[str, Any]
+    usage: Dict[str, int] = Field(
+        default_factory=lambda: {"prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 0}
+    )
+    provider: str
+    model: str
+    finish_reason: Optional[str] = None
+    cost_estimate: float = 0.0
+
+
+class TutorStreamChunk(BaseModel):
+    content: str
+    delta: str
+    provider: str
+    model: str
+    is_complete: bool = False
+    usage: Optional[Dict[str, int]] = None
+
+
+AsyncStreamGenerator = AsyncGenerator[TutorStreamChunk, None]

src/services/llm/utils.py

@@ -0,0 +1,333 @@
+"""
+LLM Utilities
+=============
+
+Utility functions for LLM service:
+- URL handling for local and cloud servers
+- Response content extraction
+- Thinking tags cleaning
+"""
+
+import re
+from typing import Any, Optional
+
+# Known cloud provider domains (should never be treated as local)
+CLOUD_DOMAINS = [
+    ".openai.com",
+    ".anthropic.com",
+    ".deepseek.com",
+    ".openrouter.ai",
+    ".azure.com",
+    ".googleapis.com",
+    ".cohere.ai",
+    ".mistral.ai",
+    ".together.ai",
+    ".fireworks.ai",
+    ".groq.com",
+    ".perplexity.ai",
+]
+
+# Common local server ports
+LOCAL_PORTS = [
+    ":1234",  # LM Studio
+    ":11434",  # Ollama
+    ":8000",  # vLLM
+    ":8080",  # llama.cpp
+    ":5000",  # Common dev port
+    ":3000",  # Common dev port
+    ":8001",  # Alternative vLLM
+    ":5001",  # Alternative dev port
+]
+
+# Local hostname indicators
+LOCAL_HOSTS = [
+    "localhost",
+    "127.0.0.1",
+    "0.0.0.0",
+]
+
+# Ports that need /v1 suffix for OpenAI compatibility
+V1_SUFFIX_PORTS = {
+    ":11434",  # Ollama
+    ":1234",  # LM Studio
+    ":8000",  # vLLM
+    ":8001",  # Alternative vLLM
+    ":8080",  # llama.cpp
+}
+
+
+def is_local_llm_server(base_url: str) -> bool:
+    """
+    Check if the given URL points to a local LLM server.
+
+    Detects local servers by:
+    1. Checking for local hostnames (localhost, 127.0.0.1, 0.0.0.0)
+    2. Checking for common local LLM server ports
+    3. Excluding known cloud provider domains
+
+    Args:
+        base_url: The base URL to check
+
+    Returns:
+        True if the URL appears to be a local LLM server
+    """
+    if not base_url:
+        return False
+
+    base_url_lower = base_url.lower()
+
+    # First, exclude known cloud providers
+    for domain in CLOUD_DOMAINS:
+        if domain in base_url_lower:
+            return False
+
+    # Check for local hostname indicators
+    for host in LOCAL_HOSTS:
+        if host in base_url_lower:
+            return True
+
+    # Check for common local server ports
+    for port in LOCAL_PORTS:
+        if port in base_url_lower:
+            return True
+
+    return False
+
+
+def _needs_v1_suffix(url: str) -> bool:
+    """
+    Check if the URL needs /v1 suffix for OpenAI compatibility.
+
+    Most local LLM servers (Ollama, LM Studio, vLLM, llama.cpp) expose
+    OpenAI-compatible endpoints at /v1.
+
+    Args:
+        url: The URL to check
+
+    Returns:
+        True if /v1 should be appended
+    """
+    if not url:
+        return False
+
+    url_lower = url.lower()
+
+    # Skip if already has /v1
+    if url_lower.endswith("/v1"):
+        return False
+
+    # Only add /v1 for local servers with known ports that need it
+    if not is_local_llm_server(url):
+        return False
+
+    # Check if URL contains any port that needs /v1 suffix
+    # Also check for "ollama" in URL (but not ollama.com cloud service)
+    is_ollama = "ollama" in url_lower and "ollama.com" not in url_lower
+    if is_ollama:
+        return True
+
+    return any(port in url_lower for port in V1_SUFFIX_PORTS)
+
+
+def sanitize_url(base_url: str, model: str = "") -> str:
+    """
+    Sanitize base URL for OpenAI-compatible APIs, with special handling for local LLM servers.
+
+    Handles:
+    - Ollama (port 11434)
+    - LM Studio (port 1234)
+    - vLLM (port 8000)
+    - llama.cpp (port 8080)
+    - Other localhost OpenAI-compatible servers
+
+    Args:
+        base_url: The base URL to sanitize
+        model: Optional model name (unused, kept for API compatibility)
+
+    Returns:
+        Sanitized URL string
+    """
+    if not base_url:
+        return base_url
+
+    url = base_url.rstrip("/")
+
+    # Ensure URL has a protocol (default to http for local servers)
+    if url and not url.startswith(("http://", "https://")):
+        url = "http://" + url
+
+    # Standard OpenAI client library is strict about URLs:
+    # - No trailing slashes
+    # - No /chat/completions or /completions/messages/embeddings suffixes
+    #   (it adds these automatically)
+    for suffix in ["/chat/completions", "/completions", "/messages", "/embeddings"]:
+        if url.endswith(suffix):
+            url = url[: -len(suffix)]
+            url = url.rstrip("/")
+
+    # For local LLM servers, ensure /v1 is present for OpenAI compatibility
+    if _needs_v1_suffix(url):
+        url = url.rstrip("/") + "/v1"
+
+    return url
+
+
+def clean_thinking_tags(
+    content: str,
+    binding: Optional[str] = None,
+    model: Optional[str] = None,
+) -> str:
+    """
+    Remove thinking tags from model output.
+
+    Some reasoning models (DeepSeek, Qwen, etc.) include <think>...</think> blocks
+    that should be stripped from the final response.
+
+    Args:
+        content: Raw model output
+        binding: Provider binding name (optional, for capability check)
+        model: Model name (optional, for capability check)
+
+    Returns:
+        Cleaned content without thinking tags
+    """
+    if not content:
+        return content
+
+    # Check if model produces thinking tags (if binding/model provided)
+    if binding:
+        # Lazy import to avoid circular dependency
+        from .capabilities import has_thinking_tags
+
+        if not has_thinking_tags(binding, model):
+            return content
+
+    # Remove <think>...</think> blocks
+    if "<think>" in content:
+        content = re.sub(r"<think>.*?</think>", "", content, flags=re.DOTALL)
+
+    return content.strip()
+
+
+def build_chat_url(
+    base_url: str,
+    api_version: Optional[str] = None,
+    binding: Optional[str] = None,
+) -> str:
+    """
+    Build the full chat completions endpoint URL.
+
+    Handles:
+    - Adding /chat/completions suffix for OpenAI-compatible endpoints
+    - Adding /messages suffix for Anthropic endpoints
+    - Adding api-version query parameter for Azure OpenAI
+
+    Args:
+        base_url: Base URL (should be sanitized first)
+        api_version: API version for Azure OpenAI (optional)
+        binding: Provider binding name (optional, for Anthropic detection)
+
+    Returns:
+        Full endpoint URL
+    """
+    if not base_url:
+        return base_url
+
+    url = base_url.rstrip("/")
+
+    # Anthropic uses /messages endpoint
+    binding_lower = (binding or "").lower()
+    if binding_lower in ["anthropic", "claude"]:
+        if not url.endswith("/messages"):
+            url += "/messages"
+    else:
+        # OpenAI-compatible endpoints use /chat/completions
+        if not url.endswith("/chat/completions"):
+            url += "/chat/completions"
+
+    # Add api-version for Azure OpenAI
+    if api_version:
+        separator = "&" if "?" in url else "?"
+        url += f"{separator}api-version={api_version}"
+
+    return url
+
+
+def extract_response_content(message: dict[str, Any]) -> str:
+    """
+    Extract content from LLM response message.
+
+    Handles different response formats from various models:
+    - Standard content field
+    - Reasoning models that use reasoning_content, reasoning, or thought fields
+
+    Args:
+        message: Message dict from LLM response (e.g., choices[0].message)
+
+    Returns:
+        Extracted content string
+    """
+    if not message:
+        return ""
+
+    content = message.get("content", "")
+
+    # Handle reasoning models that return content in different fields
+    if not content:
+        content = (
+            message.get("reasoning_content")
+            or message.get("reasoning")
+            or message.get("thought")
+            or ""
+        )
+
+    return content
+
+
+def build_auth_headers(
+    api_key: Optional[str],
+    binding: Optional[str] = None,
+) -> dict[str, str]:
+    """
+    Build authentication headers for LLM API requests.
+
+    Args:
+        api_key: API key
+        binding: Provider binding name (for provider-specific headers)
+
+    Returns:
+        Headers dict
+    """
+    headers = {"Content-Type": "application/json"}
+
+    if not api_key:
+        return headers
+
+    binding_lower = (binding or "").lower()
+
+    if binding_lower in ["anthropic", "claude"]:
+        headers["x-api-key"] = api_key
+        headers["anthropic-version"] = "2023-06-01"
+    elif binding_lower == "azure_openai":
+        headers["api-key"] = api_key
+    else:
+        headers["Authorization"] = f"Bearer {api_key}"
+
+    return headers
+
+
+__all__ = [
+    # URL utilities
+    "sanitize_url",
+    "is_local_llm_server",
+    "build_chat_url",
+    "build_auth_headers",
+    # Content utilities
+    "clean_thinking_tags",
+    "extract_response_content",
+    # Constants
+    "CLOUD_DOMAINS",
+    "LOCAL_PORTS",
+    "LOCAL_HOSTS",
+    "V1_SUFFIX_PORTS",
+]

src/services/prompt/__init__.py

@@ -0,0 +1,25 @@
+"""
+Prompt Service
+==============
+
+Unified prompt management for all DeepTutor modules.
+
+Usage:
+    from src.services.prompt import get_prompt_manager, PromptManager
+
+    # Get singleton manager
+    pm = get_prompt_manager()
+
+    # Load prompts for an agent
+    prompts = pm.load_prompts("guide", "tutor_agent", language="en")
+
+    # Get specific prompt
+    system_prompt = pm.get_prompt(prompts, "system", "base")
+"""
+
+from .manager import PromptManager, get_prompt_manager
+
+__all__ = [
+    "PromptManager",
+    "get_prompt_manager",
+]

src/services/prompt/manager.py

@@ -0,0 +1,206 @@
+#!/usr/bin/env python
+"""
+Unified Prompt Manager - Single source of truth for all prompt loading.
+Supports multi-language, caching, and language fallbacks.
+"""
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from src.services.config import PROJECT_ROOT, parse_language
+
+
+class PromptManager:
+    """Unified prompt manager with singleton pattern and global caching."""
+
+    _instance: "PromptManager | None" = None
+    _cache: dict[str, dict[str, Any]] = {}
+
+    # Language fallback chain: if primary language not found, try alternatives
+    LANGUAGE_FALLBACKS = {
+        "zh": ["zh", "en"],
+        "en": ["en", "zh"],
+    }
+
+    # Supported modules
+    MODULES = ["research", "solve", "guide", "question", "ideagen", "co_writer"]
+
+    def __new__(cls) -> "PromptManager":
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def load_prompts(
+        self,
+        module_name: str,
+        agent_name: str,
+        language: str = "zh",
+        subdirectory: str | None = None,
+    ) -> dict[str, Any]:
+        """
+        Load prompts for an agent.
+
+        Args:
+            module_name: Module name (research, solve, guide, question, ideagen, co_writer)
+            agent_name: Agent name (filename without .yaml)
+            language: Language code ('zh' or 'en')
+            subdirectory: Optional subdirectory (e.g., 'solve_loop' for solve module)
+
+        Returns:
+            Loaded prompt configuration dictionary
+        """
+        lang_code = parse_language(language)
+        cache_key = self._build_cache_key(module_name, agent_name, lang_code, subdirectory)
+
+        if cache_key in self._cache:
+            return self._cache[cache_key]
+
+        prompts = self._load_with_fallback(module_name, agent_name, lang_code, subdirectory)
+        self._cache[cache_key] = prompts
+        return prompts
+
+    def _build_cache_key(
+        self,
+        module_name: str,
+        agent_name: str,
+        lang_code: str,
+        subdirectory: str | None,
+    ) -> str:
+        """Build unique cache key."""
+        subdir_part = f"_{subdirectory}" if subdirectory else ""
+        return f"{module_name}_{agent_name}_{lang_code}{subdir_part}"
+
+    def _load_with_fallback(
+        self,
+        module_name: str,
+        agent_name: str,
+        lang_code: str,
+        subdirectory: str | None,
+    ) -> dict[str, Any]:
+        """Load prompt file with language fallback."""
+        prompts_dir = PROJECT_ROOT / "src" / "agents" / module_name / "prompts"
+        fallback_chain = self.LANGUAGE_FALLBACKS.get(lang_code, ["en"])
+
+        for lang in fallback_chain:
+            prompt_file = self._resolve_prompt_path(prompts_dir, lang, agent_name, subdirectory)
+            if prompt_file and prompt_file.exists():
+                try:
+                    with open(prompt_file, encoding="utf-8") as f:
+                        return yaml.safe_load(f) or {}
+                except Exception as e:
+                    print(f"Warning: Failed to load {prompt_file}: {e}")
+                    continue
+
+        print(f"Warning: No prompt file found for {module_name}/{agent_name}")
+        return {}
+
+    def _resolve_prompt_path(
+        self,
+        prompts_dir: Path,
+        lang: str,
+        agent_name: str,
+        subdirectory: str | None,
+    ) -> Path | None:
+        """Resolve prompt file path, supporting subdirectory and recursive search."""
+        lang_dir = prompts_dir / lang
+
+        if not lang_dir.exists():
+            return None
+
+        # If subdirectory specified, look there first
+        if subdirectory:
+            direct_path = lang_dir / subdirectory / f"{agent_name}.yaml"
+            if direct_path.exists():
+                return direct_path
+
+        # Try direct path
+        direct_path = lang_dir / f"{agent_name}.yaml"
+        if direct_path.exists():
+            return direct_path
+
+        # Recursive search in subdirectories
+        found = list(lang_dir.rglob(f"{agent_name}.yaml"))
+        if found:
+            return found[0]
+
+        return None
+
+    def get_prompt(
+        self,
+        prompts: dict[str, Any],
+        section: str,
+        field: str | None = None,
+        fallback: str = "",
+    ) -> str:
+        """
+        Safely get prompt from loaded configuration.
+
+        Args:
+            prompts: Loaded prompt dictionary
+            section: Top-level section name
+            field: Optional nested field name
+            fallback: Default value if not found
+
+        Returns:
+            Prompt string or fallback
+        """
+        if section not in prompts:
+            return fallback
+
+        value = prompts[section]
+
+        if field is None:
+            return value if isinstance(value, str) else fallback
+
+        if isinstance(value, dict) and field in value:
+            result = value[field]
+            return result if isinstance(result, str) else fallback
+
+        return fallback
+
+    def clear_cache(self, module_name: str | None = None) -> None:
+        """
+        Clear cached prompts.
+
+        Args:
+            module_name: If provided, only clear cache for this module
+        """
+        if module_name:
+            keys_to_remove = [k for k in self._cache if k.startswith(f"{module_name}_")]
+            for key in keys_to_remove:
+                del self._cache[key]
+        else:
+            self._cache.clear()
+
+    def reload_prompts(
+        self,
+        module_name: str,
+        agent_name: str,
+        language: str = "zh",
+        subdirectory: str | None = None,
+    ) -> dict[str, Any]:
+        """Force reload prompts, bypassing cache."""
+        lang_code = parse_language(language)
+        cache_key = self._build_cache_key(module_name, agent_name, lang_code, subdirectory)
+
+        if cache_key in self._cache:
+            del self._cache[cache_key]
+
+        return self.load_prompts(module_name, agent_name, language, subdirectory)
+
+
+# Global singleton instance
+_prompt_manager: PromptManager | None = None
+
+
+def get_prompt_manager() -> PromptManager:
+    """Get the global PromptManager instance."""
+    global _prompt_manager
+    if _prompt_manager is None:
+        _prompt_manager = PromptManager()
+    return _prompt_manager
+
+
+__all__ = ["PromptManager", "get_prompt_manager"]

src/services/rag/__init__.py

@@ -0,0 +1,64 @@
+"""
+RAG Service
+===========
+
+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)
+- Modular components (parsers, chunkers, embedders, indexers, retrievers)
+- Factory for pipeline creation
+
+Usage:
+    # Recommended: Use RAGService for all operations
+    from src.services.rag import RAGService
+
+    service = RAGService(provider="llamaindex")
+    await service.initialize("kb_name", ["doc1.txt", "doc2.txt"])
+    result = await service.search("query", "kb_name")
+
+    # Alternative: Use factory directly
+    from src.services.rag import get_pipeline
+
+    pipeline = get_pipeline("raganything")
+    await pipeline.initialize("kb_name", ["doc1.pdf"])
+    result = await pipeline.search("query", "kb_name")
+
+    # Or build custom pipeline
+    from src.services.rag import RAGPipeline
+    from src.services.rag.components import TextParser, SemanticChunker
+
+    custom = (
+        RAGPipeline("custom")
+        .parser(TextParser())
+        .chunker(SemanticChunker())
+    )
+"""
+
+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
+
+__all__ = [
+    # Service (recommended entry point)
+    "RAGService",
+    # Types
+    "Document",
+    "Chunk",
+    "SearchResult",
+    # Pipeline
+    "RAGPipeline",
+    # Factory
+    "get_pipeline",
+    "list_pipelines",
+    "register_pipeline",
+    "has_pipeline",
+    # Pipeline implementations
+    "RAGAnythingPipeline",
+]