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

src/api/utils/task_id_manager.py

@@ -0,0 +1,100 @@
+"""
+Task ID Manager - Assigns unique IDs to each background task
+"""
+
+from datetime import datetime, timedelta
+import threading
+from typing import Optional
+import uuid
+
+
+class TaskIDManager:
+    """Singleton class for managing task IDs"""
+
+    _instance: Optional["TaskIDManager"] = None
+    _lock = threading.Lock()
+    _task_ids: dict[str, str] = {}  # task_key -> task_id
+    _task_metadata: dict[str, dict] = {}  # task_id -> metadata
+
+    @classmethod
+    def get_instance(cls) -> "TaskIDManager":
+        """Get singleton instance"""
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = cls()
+        return cls._instance
+
+    def generate_task_id(self, task_type: str, task_key: str) -> str:
+        """
+        Generate unique ID for task
+
+        Args:
+            task_type: Task type (e.g., 'kb_init', 'kb_upload', 'question_gen', 'solve', 'research')
+            task_key: Task unique identifier (e.g., knowledge base name, question ID, etc.)
+
+        Returns:
+            Task ID (format: {task_type}_{timestamp}_{uuid})
+        """
+        with self._lock:
+            # If task already exists, return existing ID
+            if task_key in self._task_ids:
+                return self._task_ids[task_key]
+
+            # Generate new ID
+            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+            unique_id = str(uuid.uuid4())[:8]
+            task_id = f"{task_type}_{timestamp}_{unique_id}"
+
+            # Save mapping and metadata
+            self._task_ids[task_key] = task_id
+            self._task_metadata[task_id] = {
+                "task_type": task_type,
+                "task_key": task_key,
+                "created_at": datetime.now().isoformat(),
+                "status": "running",
+            }
+
+            return task_id
+
+    def get_task_id(self, task_key: str) -> str | None:
+        """Get task ID"""
+        with self._lock:
+            return self._task_ids.get(task_key)
+
+    def update_task_status(self, task_id: str, status: str, **kwargs):
+        """Update task status"""
+        with self._lock:
+            if task_id in self._task_metadata:
+                self._task_metadata[task_id]["status"] = status
+                self._task_metadata[task_id].update(kwargs)
+                if status in ["completed", "error", "cancelled"]:
+                    self._task_metadata[task_id]["finished_at"] = datetime.now().isoformat()
+
+    def get_task_metadata(self, task_id: str) -> dict | None:
+        """Get task metadata"""
+        with self._lock:
+            return self._task_metadata.get(task_id, {}).copy()
+
+    def cleanup_old_tasks(self, max_age_hours: int = 24):
+        """Clean up old tasks (completed tasks older than specified hours)"""
+        with self._lock:
+            cutoff = datetime.now() - timedelta(hours=max_age_hours)
+
+            to_remove = []
+            for task_id, metadata in self._task_metadata.items():
+                if metadata.get("status") in ["completed", "error", "cancelled"]:
+                    finished_at = metadata.get("finished_at")
+                    if finished_at:
+                        try:
+                            finished_time = datetime.fromisoformat(finished_at)
+                            if finished_time < cutoff:
+                                to_remove.append(task_id)
+                        except:
+                            pass
+
+            for task_id in to_remove:
+                metadata = self._task_metadata.pop(task_id, {})
+                task_key = metadata.get("task_key")
+                if task_key:
+                    self._task_ids.pop(task_key, None)

src/config/accessors.py

@@ -0,0 +1,18 @@
+from typing import Callable
+
+
+class ConfigAccessor:
+    def __init__(self, loader: Callable[[], dict]):
+        self._loader = loader
+
+    def llm_model(self) -> str:
+        cfg = self._loader()
+        return str(cfg.get("llm", {}).get("model", "Pro/Flash"))
+
+    def llm_provider(self) -> str:
+        cfg = self._loader()
+        return str(cfg.get("llm", {}).get("provider", "openai"))
+
+    def user_data_dir(self) -> str:
+        cfg = self._loader()
+        return str(cfg.get("paths", {}).get("user_data_dir", "./data/user"))

src/config/constants.py

@@ -0,0 +1,34 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""
+Constants for DeepTutor
+"""
+
+from pathlib import Path
+
+# Project root directory - central location for all path calculations
+PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent
+
+# Valid tools for investigate agent
+VALID_INVESTIGATE_TOOLS = ["rag_naive", "rag_hybrid", "web_search", "query_item", "none"]
+
+# Valid tools for solve agent
+VALID_SOLVE_TOOLS = [
+    "web_search",
+    "code_execution",
+    "rag_naive",
+    "rag_hybrid",
+    "query_item",
+    "none",
+    "finish",
+]
+
+# Logging symbols for different log levels
+LOG_SYMBOLS = {
+    "DEBUG": "·",
+    "INFO": "●",
+    "SUCCESS": "✓",
+    "WARNING": "⚠",
+    "ERROR": "✗",
+    "CRITICAL": "✗",
+}

src/config/defaults.py

@@ -0,0 +1,18 @@
+"""
+Default configuration values for DeepTutor.
+"""
+
+from pathlib import Path
+
+# Get project root
+_project_root = Path(__file__).parent.parent.parent
+
+# Default configuration
+DEFAULTS = {
+    "llm": {"model": "gpt-4o-mini", "provider": "openai"},
+    "paths": {
+        "user_data_dir": str(_project_root / "data" / "user"),
+        "knowledge_bases_dir": str(_project_root / "data" / "knowledge_bases"),
+        "user_log_dir": str(_project_root / "logs"),
+    },
+}

src/config/schema.py

@@ -0,0 +1,38 @@
+from typing import Any, Dict
+
+from pydantic import BaseModel, field_validator
+
+
+class LLMConfig(BaseModel):
+    model: str
+    provider: str = "openai"
+
+
+class PathsConfig(BaseModel):
+    user_data_dir: str
+    knowledge_bases_dir: str
+    user_log_dir: str
+
+
+class AppConfig(BaseModel):
+    llm: LLMConfig
+    paths: PathsConfig
+
+    @field_validator("llm", mode="before")
+    @classmethod
+    def ensure_llm(cls, v: Any) -> Dict[str, Any]:
+        if not isinstance(v, dict):
+            raise ValueError("llm section must be a mapping")
+        if "model" not in v:
+            raise ValueError("llm.model is required")
+        return v
+
+
+CURRENT_SCHEMA_VERSION = 1
+
+
+def migrate_config(cfg: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    No-op migration for now; placeholder for future versioned changes.
+    """
+    return cfg

src/config/settings.py

@@ -0,0 +1,50 @@
+"""
+Configuration Settings for DeepTutor
+
+Environment Variables:
+    LLM_RETRY__MAX_RETRIES: Maximum retry attempts for LLM calls (default: 3)
+    LLM_RETRY__BASE_DELAY: Base delay between retries in seconds (default: 1.0)
+    LLM_RETRY__EXPONENTIAL_BACKOFF: Whether to use exponential backoff (default: True)
+
+Examples:
+    export LLM_RETRY__MAX_RETRIES=5
+    export LLM_RETRY__BASE_DELAY=2.0
+    export LLM_RETRY__EXPONENTIAL_BACKOFF=false
+"""
+
+from pydantic import BaseModel, Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class LLMRetryConfig(BaseModel):
+    max_retries: int = Field(default=3, description="Maximum retry attempts for LLM calls")
+    base_delay: float = Field(default=1.0, description="Base delay between retries in seconds")
+    exponential_backoff: bool = Field(
+        default=True, description="Whether to use exponential backoff"
+    )
+
+
+class Settings(BaseSettings):
+    # LLM retry configuration
+    retry: LLMRetryConfig = Field(default_factory=LLMRetryConfig)
+
+    # Deprecated: use retry instead
+    @property
+    def llm_retry(self):
+        import warnings
+
+        warnings.warn(
+            "settings.llm_retry is deprecated, use settings.retry instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.retry
+
+    model_config = SettingsConfigDict(
+        env_prefix="LLM_",
+        env_nested_delimiter="__",
+    )
+
+
+# Global settings instance
+settings = Settings()

src/core/errors.py

@@ -0,0 +1,62 @@
+"""
+Base exception classes for consistent error handling across the application.
+Provides a standardized way to distinguish between bugs, recoverable errors,
+and configuration issues.
+"""
+
+from typing import Any, Dict, Optional
+
+
+class DeepTutorError(Exception):
+    """Base class for all application errors in DeepTutor."""
+
+    def __init__(self, message: str, details: Optional[Dict[str, Any]] = None):
+        super().__init__(message)
+        self.message = message
+        self.details = details or {}
+
+    def __str__(self) -> str:
+        if self.details:
+            return f"{self.message} (details: {self.details})"
+        return self.message
+
+
+class ConfigurationError(DeepTutorError):
+    """Raised when there's a configuration-related error."""
+
+    pass
+
+
+class ValidationError(DeepTutorError):
+    """Raised when input validation fails."""
+
+    pass
+
+
+class ServiceError(DeepTutorError):
+    """Base class for service layer errors."""
+
+    pass
+
+
+class LLMServiceError(ServiceError):
+    """Base class for LLM service-related errors."""
+
+    pass
+
+
+class LLMContextError(LLMServiceError):
+    """Raised when prompt exceeds model context window."""
+
+    pass
+
+
+class EnvironmentConfigError(ConfigurationError):
+    """Raised when there's an environment-related configuration error."""
+
+    pass
+
+
+# Aliases for backward compatibility
+ConfigError = ConfigurationError
+EnvError = EnvironmentConfigError

src/knowledge/__init__.py

@@ -0,0 +1,23 @@
+#!/usr/bin/env python
+"""
+Knowledge Base Initialization Module
+
+Includes:
+- init_knowledge_base: Knowledge base initializer
+- add_documents: Incremental document addition (new feature)
+- kb_manager: Knowledge base manager
+- extract_numbered_items: Extract numbered items
+- config: Path configuration
+"""
+
+from . import config
+from .add_documents import DocumentAdder
+from .initializer import KnowledgeBaseInitializer
+from .manager import KnowledgeBaseManager
+
+__all__ = [
+    "DocumentAdder",
+    "KnowledgeBaseInitializer",
+    "KnowledgeBaseManager",
+    "config",
+]