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

src/services/llm/config.py

@@ -0,0 +1,200 @@
+# -*- coding: utf-8 -*-
+"""
+LLM Configuration
+=================
+
+Configuration management for LLM services.
+Simplified version - loads from unified config service or falls back to .env.
+"""
+
+from dataclasses import dataclass
+import logging
+import os
+from pathlib import Path
+import re
+from typing import Optional
+
+from dotenv import load_dotenv
+
+from .exceptions import LLMConfigError
+
+logger = logging.getLogger(__name__)
+
+# Load environment variables
+PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent.parent
+load_dotenv(PROJECT_ROOT / "DeepTutor.env", override=False)
+load_dotenv(PROJECT_ROOT / ".env", override=False)
+
+
+@dataclass
+class LLMConfig:
+    """LLM configuration dataclass."""
+
+    model: str
+    api_key: str
+    base_url: Optional[str] = None
+    binding: str = "openai"
+    api_version: Optional[str] = None
+    max_tokens: int = 4096
+    temperature: float = 0.7
+
+
+def _strip_value(value: Optional[str]) -> Optional[str]:
+    """Remove leading/trailing whitespace and quotes from string."""
+    if value is None:
+        return None
+    return value.strip().strip("\"'")
+
+
+def _get_llm_config_from_env() -> LLMConfig:
+    """Get LLM configuration from environment variables."""
+    binding = _strip_value(os.getenv("LLM_BINDING", "openai"))
+    model = _strip_value(os.getenv("LLM_MODEL"))
+    api_key = _strip_value(os.getenv("LLM_API_KEY"))
+    base_url = _strip_value(os.getenv("LLM_HOST"))
+    api_version = _strip_value(os.getenv("LLM_API_VERSION"))
+
+    # Validate required configuration
+    if not model:
+        raise LLMConfigError(
+            "LLM_MODEL not set, please configure it in .env file or add a configuration in Settings"
+        )
+    if not base_url:
+        raise LLMConfigError(
+            "LLM_HOST not set, please configure it in .env file or add a configuration in Settings"
+        )
+
+    return LLMConfig(
+        binding=binding,
+        model=model,
+        api_key=api_key or "",
+        base_url=base_url,
+        api_version=api_version,
+    )
+
+
+def get_llm_config() -> LLMConfig:
+    """
+    Load LLM configuration.
+
+    Priority:
+    1. Active configuration from unified config service
+    2. Environment variables (.env)
+
+    Returns:
+        LLMConfig: Configuration dataclass
+
+    Raises:
+        LLMConfigError: If required configuration is missing
+    """
+    # 1. Try to get active config from unified config service
+    try:
+        from src.services.config import get_active_llm_config
+
+        config = get_active_llm_config()
+        if config:
+            return LLMConfig(
+                binding=config.get("provider", "openai"),
+                model=config["model"],
+                api_key=config.get("api_key", ""),
+                base_url=config.get("base_url"),
+                api_version=config.get("api_version"),
+            )
+    except ImportError:
+        # Unified config service not yet available, fall back to env
+        pass
+    except Exception as e:
+        logger.warning(f"Failed to load from unified config: {e}")
+
+    # 2. Fallback to environment variables
+    return _get_llm_config_from_env()
+
+
+async def get_llm_config_async() -> LLMConfig:
+    """
+    Async version of get_llm_config for non-blocking configuration loading.
+
+    Returns:
+        LLMConfig: Configuration dataclass
+
+    Raises:
+        LLMConfigError: If required configuration is missing
+    """
+    # 1. Try to get active config from unified config service
+    try:
+        from src.services.config import get_active_llm_config
+
+        config = get_active_llm_config()
+        if config:
+            return LLMConfig(
+                binding=config.get("provider", "openai"),
+                model=config["model"],
+                api_key=config.get("api_key", ""),
+                base_url=config.get("base_url"),
+                api_version=config.get("api_version"),
+            )
+    except ImportError:
+        pass
+    except Exception as e:
+        logger.warning(f"Failed to load from unified config: {e}")
+
+    # 2. Fallback to environment variables
+    return _get_llm_config_from_env()
+
+
+def uses_max_completion_tokens(model: str) -> bool:
+    """
+    Check if the model uses max_completion_tokens instead of max_tokens.
+
+    Newer OpenAI models (o1, o3, gpt-4o, gpt-5.x, etc.) require max_completion_tokens
+    while older models use max_tokens.
+
+    Args:
+        model: The model name
+
+    Returns:
+        True if the model requires max_completion_tokens, False otherwise
+    """
+    model_lower = model.lower()
+
+    # Models that require max_completion_tokens:
+    # - o1, o3 series (reasoning models)
+    # - gpt-4o series
+    # - gpt-5.x and later
+    patterns = [
+        r"^o[13]",  # o1, o3 models
+        r"^gpt-4o",  # gpt-4o models
+        r"^gpt-[5-9]",  # gpt-5.x and later
+        r"^gpt-\d{2,}",  # gpt-10+ (future proofing)
+    ]
+
+    for pattern in patterns:
+        if re.match(pattern, model_lower):
+            return True
+
+    return False
+
+
+def get_token_limit_kwargs(model: str, max_tokens: int) -> dict:
+    """
+    Get the appropriate token limit parameter for the model.
+
+    Args:
+        model: The model name
+        max_tokens: The desired token limit
+
+    Returns:
+        Dictionary with either {"max_tokens": value} or {"max_completion_tokens": value}
+    """
+    if uses_max_completion_tokens(model):
+        return {"max_completion_tokens": max_tokens}
+    return {"max_tokens": max_tokens}
+
+
+__all__ = [
+    "LLMConfig",
+    "get_llm_config",
+    "get_llm_config_async",
+    "uses_max_completion_tokens",
+    "get_token_limit_kwargs",
+]

src/services/llm/error_mapping.py

@@ -0,0 +1,103 @@
+"""
+Error Mapping - Map provider-specific errors to unified exceptions.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import logging
+from typing import Callable, List, Optional, Type
+
+# Import unified exceptions from exceptions.py
+from .exceptions import (
+    LLMAPIError,
+    LLMAuthenticationError,
+    LLMError,
+    LLMRateLimitError,
+    ProviderContextWindowError,
+)
+
+try:
+    import openai  # type: ignore
+
+    _HAS_OPENAI = True
+except ImportError:  # pragma: no cover
+    openai = None  # type: ignore
+    _HAS_OPENAI = False
+
+
+logger = logging.getLogger(__name__)
+
+
+ErrorClassifier = Callable[[Exception], bool]
+
+
+@dataclass(frozen=True)
+class MappingRule:
+    classifier: ErrorClassifier
+    factory: Callable[[Exception, Optional[str]], LLMError]
+
+
+def _instance_of(*types: Type[BaseException]) -> ErrorClassifier:
+    return lambda exc: isinstance(exc, types)
+
+
+def _message_contains(*needles: str) -> ErrorClassifier:
+    def _classifier(exc: Exception) -> bool:
+        msg = str(exc).lower()
+        return any(needle in msg for needle in needles)
+
+    return _classifier
+
+
+_GLOBAL_RULES: List[MappingRule] = [
+    MappingRule(
+        classifier=_message_contains("rate limit", "429", "quota"),
+        factory=lambda exc, provider: LLMRateLimitError(str(exc), provider=provider),
+    ),
+    MappingRule(
+        classifier=_message_contains("context length", "maximum context"),
+        factory=lambda exc, provider: ProviderContextWindowError(str(exc), provider=provider),
+    ),
+]
+
+if _HAS_OPENAI:
+    _GLOBAL_RULES[:0] = [
+        MappingRule(
+            classifier=_instance_of(openai.AuthenticationError),
+            factory=lambda exc, provider: LLMAuthenticationError(str(exc), provider=provider),
+        ),
+        MappingRule(
+            classifier=_instance_of(openai.RateLimitError),
+            factory=lambda exc, provider: LLMRateLimitError(str(exc), provider=provider),
+        ),
+    ]
+
+# Attempt to load Anthropic and Google rules if SDKs are present
+try:
+    import anthropic
+
+    _GLOBAL_RULES.append(
+        MappingRule(
+            classifier=_instance_of(anthropic.RateLimitError),
+            factory=lambda exc, provider: LLMRateLimitError(str(exc), provider=provider),
+        )
+    )
+except ImportError:
+    pass
+
+
+def map_error(exc: Exception, provider: Optional[str] = None) -> LLMError:
+    """Map provider-specific errors to unified internal exceptions."""
+    # Heuristic check for status codes before rules
+    status_code = getattr(exc, "status_code", None)
+    if status_code == 401:
+        return LLMAuthenticationError(str(exc), provider=provider)
+    if status_code == 429:
+        return LLMRateLimitError(str(exc), provider=provider)
+
+    for rule in _GLOBAL_RULES:
+        if rule.classifier(exc):
+            return rule.factory(exc, provider)
+
+    return LLMAPIError(str(exc), status_code=status_code, provider=provider)

src/services/llm/exceptions.py

@@ -0,0 +1,152 @@
+"""
+LLM Service Exceptions
+======================
+
+Custom exception classes for the LLM service.
+Provides a consistent exception hierarchy for better error handling.
+Maintains parity with upstream dev branch.
+"""
+
+from typing import Any, Dict, Optional
+
+
+class LLMError(Exception):
+    """Base exception for all LLM-related errors."""
+
+    def __init__(
+        self, message: str, details: Optional[Dict[str, Any]] = None, provider: Optional[str] = None
+    ):
+        super().__init__(message)
+        self.message = message
+        self.details = details or {}
+        self.provider = provider
+
+    def __str__(self) -> str:
+        provider_prefix = f"[{self.provider}] " if self.provider else ""
+        if self.details:
+            return f"{provider_prefix}{self.message} (details: {self.details})"
+        return f"{provider_prefix}{self.message}"
+
+
+class LLMConfigError(LLMError):
+    """Raised when there's an error in LLM configuration."""
+
+    pass
+
+
+class LLMProviderError(LLMError):
+    """Raised when there's an error with the LLM provider."""
+
+    pass
+
+
+class LLMAPIError(LLMError):
+    """
+    Raised when an API call to an LLM provider fails.
+    Standardizes status_code and provider name.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        provider: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(message, details, provider)
+        self.status_code = status_code
+
+    def __str__(self) -> str:
+        parts = []
+        if self.provider:
+            parts.append(f"[{self.provider}]")
+        if self.status_code:
+            parts.append(f"HTTP {self.status_code}")
+        parts.append(self.message)
+        return " ".join(parts)
+
+
+class LLMTimeoutError(LLMAPIError):
+    """Raised when an API call times out."""
+
+    def __init__(
+        self,
+        message: str = "Request timed out",
+        timeout: Optional[float] = None,
+        provider: Optional[str] = None,
+    ):
+        super().__init__(message, status_code=408, provider=provider)
+        self.timeout = timeout
+
+
+class LLMRateLimitError(LLMAPIError):
+    """Raised when rate limited by the API."""
+
+    def __init__(
+        self,
+        message: str = "Rate limit exceeded",
+        retry_after: Optional[float] = None,
+        provider: Optional[str] = None,
+    ):
+        super().__init__(message, status_code=429, provider=provider)
+        self.retry_after = retry_after
+
+
+class LLMAuthenticationError(LLMAPIError):
+    """Raised when authentication fails (invalid API key, etc.)."""
+
+    def __init__(
+        self,
+        message: str = "Authentication failed",
+        provider: Optional[str] = None,
+    ):
+        super().__init__(message, status_code=401, provider=provider)
+
+
+class LLMModelNotFoundError(LLMAPIError):
+    """Raised when the requested model is not found."""
+
+    def __init__(
+        self,
+        message: str = "Model not found",
+        model: Optional[str] = None,
+        provider: Optional[str] = None,
+    ):
+        super().__init__(message, status_code=404, provider=provider)
+        self.model = model
+
+
+class LLMParseError(LLMError):
+    """Raised when parsing LLM output fails."""
+
+    def __init__(
+        self,
+        message: str = "Failed to parse LLM output",
+        provider: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+    ):
+        super().__init__(message, details=details, provider=provider)
+
+
+# Multi-provider specific aliases for mapping rules
+class ProviderQuotaExceededError(LLMRateLimitError):
+    pass
+
+
+class ProviderContextWindowError(LLMAPIError):
+    pass
+
+
+__all__ = [
+    "LLMError",
+    "LLMConfigError",
+    "LLMProviderError",
+    "LLMAPIError",
+    "LLMTimeoutError",
+    "LLMRateLimitError",
+    "LLMAuthenticationError",
+    "LLMModelNotFoundError",
+    "LLMParseError",
+    "ProviderQuotaExceededError",
+    "ProviderContextWindowError",
+]