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

src/logging/stats/__init__.py

@@ -0,0 +1,16 @@
+"""
+Statistics Tracking
+===================
+
+Utilities for tracking LLM usage, costs, and performance metrics.
+"""
+
+from .llm_stats import MODEL_PRICING, LLMCall, LLMStats, estimate_tokens, get_pricing
+
+__all__ = [
+    "LLMStats",
+    "LLMCall",
+    "get_pricing",
+    "estimate_tokens",
+    "MODEL_PRICING",
+]

src/logging/stats/llm_stats.py

@@ -0,0 +1,179 @@
+# -*- coding: utf-8 -*-
+"""
+LLM Stats Tracker
+=================
+
+Simple utility for tracking LLM token usage and costs across all modules.
+Outputs summary to terminal at the end of processing.
+
+Usage:
+    from src.logging import LLMStats
+
+    stats = LLMStats()
+
+    # After each LLM call:
+    stats.add_call(
+        model="gpt-4o-mini",
+        prompt_tokens=100,
+        completion_tokens=50
+    )
+
+    # At the end:
+    stats.print_summary()
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Optional
+
+# Model pricing per 1K tokens (USD)
+MODEL_PRICING = {
+    "gpt-4o": {"input": 0.0025, "output": 0.010},
+    "gpt-4o-mini": {"input": 0.00015, "output": 0.0006},
+    "gpt-4-turbo": {"input": 0.01, "output": 0.03},
+    "gpt-4": {"input": 0.03, "output": 0.06},
+    "gpt-3.5-turbo": {"input": 0.0005, "output": 0.0015},
+    "deepseek-chat": {"input": 0.00014, "output": 0.00028},
+    "claude-3-5-sonnet": {"input": 0.003, "output": 0.015},
+    "claude-3-opus": {"input": 0.015, "output": 0.075},
+    "claude-3-haiku": {"input": 0.00025, "output": 0.00125},
+}
+
+
+def get_pricing(model: str) -> dict[str, float]:
+    """Get pricing for a model (fuzzy match)."""
+    model_lower = model.lower()
+    for key, pricing in MODEL_PRICING.items():
+        if key in model_lower or model_lower in key:
+            return pricing
+    return MODEL_PRICING.get("gpt-4o-mini", {"input": 0.00015, "output": 0.0006})
+
+
+def estimate_tokens(text: str) -> int:
+    """Rough estimate of tokens (1.3 tokens per word)."""
+    return int(len(text.split()) * 1.3)
+
+
+@dataclass
+class LLMCall:
+    """Single LLM call record."""
+
+    model: str
+    prompt_tokens: int
+    completion_tokens: int
+    cost: float
+    timestamp: str = field(default_factory=lambda: datetime.now().isoformat())
+
+
+class LLMStats:
+    """
+    LLM usage statistics tracker.
+    Tracks token usage and costs, outputs summary to terminal.
+    """
+
+    def __init__(self, module_name: str = "Module"):
+        """
+        Initialize stats tracker.
+
+        Args:
+            module_name: Name of the module (for display)
+        """
+        self.module_name = module_name
+        self.calls: list[LLMCall] = []
+        self.total_prompt_tokens = 0
+        self.total_completion_tokens = 0
+        self.total_cost = 0.0
+        self.model_used: Optional[str] = None
+
+    def add_call(
+        self,
+        model: str,
+        prompt_tokens: Optional[int] = None,
+        completion_tokens: Optional[int] = None,
+        # Alternative: estimate from text
+        system_prompt: Optional[str] = None,
+        user_prompt: Optional[str] = None,
+        response: Optional[str] = None,
+    ):
+        """
+        Add an LLM call to the stats.
+
+        Args:
+            model: Model name
+            prompt_tokens: Number of prompt tokens (if known)
+            completion_tokens: Number of completion tokens (if known)
+            system_prompt: System prompt text (for estimation)
+            user_prompt: User prompt text (for estimation)
+            response: Response text (for estimation)
+        """
+        # Estimate tokens if not provided
+        if prompt_tokens is None and (system_prompt or user_prompt):
+            prompt_text = (system_prompt or "") + "\n" + (user_prompt or "")
+            prompt_tokens = estimate_tokens(prompt_text)
+
+        if completion_tokens is None and response:
+            completion_tokens = estimate_tokens(response)
+
+        prompt_tokens = prompt_tokens or 0
+        completion_tokens = completion_tokens or 0
+
+        # Calculate cost
+        pricing = get_pricing(model)
+        cost = (prompt_tokens / 1000.0) * pricing["input"] + (completion_tokens / 1000.0) * pricing[
+            "output"
+        ]
+
+        # Record call
+        call = LLMCall(
+            model=model, prompt_tokens=prompt_tokens, completion_tokens=completion_tokens, cost=cost
+        )
+        self.calls.append(call)
+
+        # Update totals
+        self.total_prompt_tokens += prompt_tokens
+        self.total_completion_tokens += completion_tokens
+        self.total_cost += cost
+
+        # Track primary model
+        if self.model_used is None:
+            self.model_used = model
+
+    def get_summary(self) -> dict[str, Any]:
+        """Get summary as dictionary."""
+        return {
+            "module": self.module_name,
+            "model": self.model_used or "Unknown",
+            "calls": len(self.calls),
+            "prompt_tokens": self.total_prompt_tokens,
+            "completion_tokens": self.total_completion_tokens,
+            "total_tokens": self.total_prompt_tokens + self.total_completion_tokens,
+            "cost_usd": self.total_cost,
+        }
+
+    def print_summary(self):
+        """Print summary to terminal."""
+        if len(self.calls) == 0:
+            return
+
+        total_tokens = self.total_prompt_tokens + self.total_completion_tokens
+
+        print()
+        print("=" * 60)
+        print(f"📊 [{self.module_name}] LLM Usage Summary")
+        print("=" * 60)
+        print(f"  Model       : {self.model_used or 'Unknown'}")
+        print(f"  API Calls   : {len(self.calls)}")
+        print(
+            f"  Tokens      : {total_tokens:,} (Input: {self.total_prompt_tokens:,}, Output: {self.total_completion_tokens:,})"
+        )
+        print(f"  Cost        : ${self.total_cost:.6f} USD")
+        print("=" * 60)
+        print()
+
+    def reset(self):
+        """Reset all statistics."""
+        self.calls.clear()
+        self.total_prompt_tokens = 0
+        self.total_completion_tokens = 0
+        self.total_cost = 0.0
+        self.model_used = None

src/services/__init__.py

@@ -0,0 +1,56 @@
+"""
+Services Layer
+==============
+
+Unified service layer for DeepTutor providing:
+- LLM client and configuration
+- Embedding client and configuration
+- RAG pipelines and components
+- Prompt management
+- TTS configuration
+- Web Search providers
+- System setup utilities
+- Configuration loading
+
+Usage:
+    from src.services.llm import get_llm_client
+    from src.services.embedding import get_embedding_client
+    from src.services.rag import get_pipeline
+    from src.services.prompt import get_prompt_manager
+    from src.services.tts import get_tts_config
+    from src.services.search import web_search
+    from src.services.setup import init_user_directories
+    from src.services.config import load_config_with_main
+
+    # LLM
+    llm = get_llm_client()
+    response = await llm.complete("Hello, world!")
+
+    # Embedding
+    embed = get_embedding_client()
+    vectors = await embed.embed(["text1", "text2"])
+
+    # RAG
+    pipeline = get_pipeline("raganything")
+    result = await pipeline.search("query", "kb_name")
+
+    # Prompt
+    pm = get_prompt_manager()
+    prompts = pm.load_prompts("guide", "tutor_agent")
+
+    # Search
+    result = web_search("What is AI?")
+"""
+
+from . import config, embedding, llm, prompt, rag, search, setup, tts
+
+__all__ = [
+    "llm",
+    "embedding",
+    "rag",
+    "prompt",
+    "tts",
+    "search",
+    "setup",
+    "config",
+]

src/services/config/__init__.py

@@ -0,0 +1,61 @@
+"""
+Configuration Service
+=====================
+
+Provides three types of configuration:
+
+1. **YAML Configuration (loader.py)** - For application settings from config/*.yaml
+   - PROJECT_ROOT, load_config_with_main, get_path_from_config, parse_language, get_agent_params
+
+2. **Unified Config Service (unified_config.py)** - For service configurations (LLM, Embedding, TTS, Search)
+   - ConfigType, UnifiedConfigManager, get_config_manager
+   - get_active_llm_config, get_active_embedding_config, get_active_tts_config, get_active_search_config
+
+3. **Knowledge Base Config Service (knowledge_base_config.py)** - For KB-specific settings
+   - KnowledgeBaseConfigService, get_kb_config_service
+"""
+
+# Re-export everything from loader.py (existing functionality)
+# Export knowledge base config service
+from .knowledge_base_config import (
+    KnowledgeBaseConfigService,
+    get_kb_config_service,
+)
+from .loader import (
+    PROJECT_ROOT,
+    get_agent_params,
+    get_path_from_config,
+    load_config_with_main,
+    parse_language,
+)
+
+# Export new unified config service
+from .unified_config import (
+    ConfigType,
+    UnifiedConfigManager,
+    get_active_embedding_config,
+    get_active_llm_config,
+    get_active_search_config,
+    get_active_tts_config,
+    get_config_manager,
+)
+
+__all__ = [
+    # From loader.py
+    "PROJECT_ROOT",
+    "load_config_with_main",
+    "get_path_from_config",
+    "parse_language",
+    "get_agent_params",
+    # From unified_config.py
+    "ConfigType",
+    "UnifiedConfigManager",
+    "get_config_manager",
+    "get_active_llm_config",
+    "get_active_embedding_config",
+    "get_active_tts_config",
+    "get_active_search_config",
+    # From knowledge_base_config.py
+    "KnowledgeBaseConfigService",
+    "get_kb_config_service",
+]

src/services/config/knowledge_base_config.py

@@ -0,0 +1,210 @@
+"""
+Knowledge Base Configuration Service
+=====================================
+
+Centralized configuration management for knowledge bases.
+Stores KB-specific settings like RAG provider, search mode, etc.
+"""
+
+import json
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from src.logging import get_logger
+
+logger = get_logger("KBConfigService")
+
+# Default config file path
+DEFAULT_CONFIG_PATH = (
+    Path(__file__).parent.parent.parent.parent
+    / "data"
+    / "user"
+    / "settings"
+    / "knowledge_base_configs.json"
+)
+
+
+class KnowledgeBaseConfigService:
+    """
+    Service for managing knowledge base configurations.
+
+    Provides a centralized way to store and retrieve KB-specific settings,
+    separate from the per-KB metadata.json files.
+    """
+
+    _instance: Optional["KnowledgeBaseConfigService"] = None
+
+    def __init__(self, config_path: Optional[Path] = None):
+        self.config_path = config_path or DEFAULT_CONFIG_PATH
+        self._config: Dict[str, Any] = self._load_config()
+
+    @classmethod
+    def get_instance(cls, config_path: Optional[Path] = None) -> "KnowledgeBaseConfigService":
+        """Get singleton instance."""
+        if cls._instance is None:
+            cls._instance = cls(config_path)
+        return cls._instance
+
+    def _load_config(self) -> Dict[str, Any]:
+        """Load configuration from file."""
+        if self.config_path.exists():
+            try:
+                with open(self.config_path, "r", encoding="utf-8") as f:
+                    return json.load(f)
+            except Exception as e:
+                logger.warning(f"Failed to load KB config: {e}")
+
+        # Return default config
+        return {
+            "configs": {},
+            "default_kb": None,
+            "global_defaults": {"rag_provider": "llamaindex", "search_mode": "hybrid"},
+        }
+
+    def _save_config(self):
+        """Save configuration to file."""
+        try:
+            self.config_path.parent.mkdir(parents=True, exist_ok=True)
+            with open(self.config_path, "w", encoding="utf-8") as f:
+                json.dump(self._config, f, indent=2, ensure_ascii=False)
+        except Exception as e:
+            logger.error(f"Failed to save KB config: {e}")
+
+    def get_kb_config(self, kb_name: str) -> Dict[str, Any]:
+        """
+        Get configuration for a specific knowledge base.
+
+        Args:
+            kb_name: Knowledge base name
+
+        Returns:
+            KB configuration dict with defaults applied
+        """
+        kb_config = self._config.get("configs", {}).get(kb_name, {})
+        defaults = self._config.get("global_defaults", {})
+
+        # Merge with defaults
+        return {
+            "rag_provider": kb_config.get("rag_provider")
+            or defaults.get("rag_provider", "llamaindex"),
+            "search_mode": kb_config.get("search_mode") or defaults.get("search_mode", "hybrid"),
+            **kb_config,
+        }
+
+    def set_kb_config(self, kb_name: str, config: Dict[str, Any]):
+        """
+        Set configuration for a specific knowledge base.
+
+        Args:
+            kb_name: Knowledge base name
+            config: Configuration dict
+        """
+        if "configs" not in self._config:
+            self._config["configs"] = {}
+
+        # Merge with existing config
+        existing = self._config["configs"].get(kb_name, {})
+        existing.update(config)
+        self._config["configs"][kb_name] = existing
+
+        self._save_config()
+        logger.info(f"Updated config for KB '{kb_name}': {config}")
+
+    def get_rag_provider(self, kb_name: str) -> str:
+        """Get RAG provider for a knowledge base."""
+        return self.get_kb_config(kb_name).get("rag_provider", "llamaindex")
+
+    def set_rag_provider(self, kb_name: str, provider: str):
+        """Set RAG provider for a knowledge base."""
+        self.set_kb_config(kb_name, {"rag_provider": provider})
+
+    def get_search_mode(self, kb_name: str) -> str:
+        """Get search mode for a knowledge base."""
+        return self.get_kb_config(kb_name).get("search_mode", "hybrid")
+
+    def set_search_mode(self, kb_name: str, mode: str):
+        """Set search mode for a knowledge base."""
+        self.set_kb_config(kb_name, {"search_mode": mode})
+
+    def delete_kb_config(self, kb_name: str):
+        """Delete configuration for a knowledge base."""
+        if "configs" in self._config and kb_name in self._config["configs"]:
+            del self._config["configs"][kb_name]
+            self._save_config()
+            logger.info(f"Deleted config for KB '{kb_name}'")
+
+    def get_all_configs(self) -> Dict[str, Any]:
+        """Get all knowledge base configurations."""
+        return self._config
+
+    def set_global_defaults(self, defaults: Dict[str, Any]):
+        """Set global default values."""
+        if "global_defaults" not in self._config:
+            self._config["global_defaults"] = {}
+
+        self._config["global_defaults"].update(defaults)
+        self._save_config()
+        logger.info(f"Updated global defaults: {defaults}")
+
+    def set_default_kb(self, kb_name: Optional[str]):
+        """Set the default knowledge base."""
+        self._config["default_kb"] = kb_name
+        self._save_config()
+        logger.info(f"Set default KB: {kb_name}")
+
+    def get_default_kb(self) -> Optional[str]:
+        """Get the default knowledge base name."""
+        return self._config.get("default_kb")
+
+    def sync_from_metadata(self, kb_name: str, kb_base_dir: Path):
+        """
+        Sync configuration from a KB's metadata.json file.
+
+        Useful for migrating existing KBs to the centralized config.
+
+        Args:
+            kb_name: Knowledge base name
+            kb_base_dir: Base directory for knowledge bases
+        """
+        metadata_file = kb_base_dir / kb_name / "metadata.json"
+
+        if not metadata_file.exists():
+            return
+
+        try:
+            with open(metadata_file, "r", encoding="utf-8") as f:
+                metadata = json.load(f)
+
+            # Extract relevant config from metadata
+            config = {}
+            if "rag_provider" in metadata and metadata["rag_provider"]:
+                config["rag_provider"] = metadata["rag_provider"]
+
+            if config:
+                self.set_kb_config(kb_name, config)
+                logger.info(f"Synced config for KB '{kb_name}' from metadata.json")
+
+        except Exception as e:
+            logger.warning(f"Failed to sync config from metadata for '{kb_name}': {e}")
+
+    def sync_all_from_metadata(self, kb_base_dir: Path):
+        """
+        Sync configurations from all KBs' metadata.json files.
+
+        Args:
+            kb_base_dir: Base directory for knowledge bases
+        """
+        if not kb_base_dir.exists():
+            return
+
+        for kb_dir in kb_base_dir.iterdir():
+            if kb_dir.is_dir() and kb_dir.name != "__pycache__":
+                metadata_file = kb_dir / "metadata.json"
+                if metadata_file.exists():
+                    self.sync_from_metadata(kb_dir.name, kb_base_dir)
+
+
+# Convenience function
+def get_kb_config_service() -> KnowledgeBaseConfigService:
+    """Get the knowledge base config service instance."""
+    return KnowledgeBaseConfigService.get_instance()