local-deep-research 0.4.3__py3-none-any.whl → 0.5.0__py3-none-any.whl

local_deep_research/defaults/default_settings.json

@@ -991,7 +991,7 @@
         "options": null,
         "step": null,
         "type": "SEARCH",
-        "ui_element": "text",
+        "ui_element": "json",
         "value": [
             "scientific papers",
             "academic research",
@@ -1014,7 +1014,7 @@
         "options": null,
         "step": null,
         "type": "SEARCH",
-        "ui_element": "text",
+        "ui_element": "json",
         "value": [
             "non-academic topics",
             "consumer products",
@@ -1159,7 +1159,7 @@
         "options": null,
         "step": null,
         "type": "SEARCH",
-        "ui_element": "text",
+        "ui_element": "json",
         "value": [
             "intelligent engine selection",
             "adaptable to query type",
@@ -1177,7 +1177,7 @@
         "options": null,
         "step": null,
         "type": "SEARCH",
-        "ui_element": "text",
+        "ui_element": "json",
         "value": [
             "slightly slower due to LLM analysis"
         ],
@@ -1375,7 +1375,7 @@
         "options": null,
         "step": null,
         "type": "SEARCH",
-        "ui_element": "text",
+        "ui_element": "json",
         "value": [
             "privacy-focused web search",
             "product information",
@@ -1410,7 +1410,7 @@
         "options": null,
         "step": null,
         "type": "SEARCH",
-        "ui_element": "text",
+        "ui_element": "json",
         "value": [
             "requires API key with usage limits",
             "smaller index than Google"
@@ -1640,7 +1640,7 @@
         "options": null,
         "step": null,
         "type": "SEARCH",
-        "ui_element": "text",
+        "ui_element": "json",
         "value": [
             "code repositories",
             "software documentation",
@@ -1675,7 +1675,7 @@
         "options": null,
         "step": null,
         "type": "SEARCH",
-        "ui_element": "text",
+        "ui_element": "json",
         "value": [
             "non-technical content",
             "content outside GitHub",
@@ -1861,7 +1861,7 @@
         "options": null,
         "step": null,
         "type": "SEARCH",
-        "ui_element": "text",
+        "ui_element": "json",
         "value": [
             "custom search scope",
             "high-quality results",
@@ -1895,7 +1895,7 @@
         "options": null,
         "step": null,
         "type": "SEARCH",
-        "ui_element": "text",
+        "ui_element": "json",
         "value": [
             "requires API key with usage limits",
             "limited to 10,000 queries/day on free tier",
@@ -2025,7 +2025,7 @@
         "options": null,
         "step": null,
         "type": "SEARCH",
-        "ui_element": "text",
+        "ui_element": "json",
         "value": [
             "searches all local collections",
             "personal documents",
@@ -2043,7 +2043,7 @@
         "options": null,
         "step": null,
         "type": "SEARCH",
-        "ui_element": "text",
+        "ui_element": "json",
         "value": [
             "may return too many results",
             "requires indexing"
@@ -2232,9 +2232,9 @@
         "options": null,
         "step": null,
         "type": "SEARCH",
-        "ui_element": "text",
+        "ui_element": "json",
         "value": [
-            "@format ${DOCS_DIR}/personal_notes"
+            "/local_collections/personal_notes"
         ],
         "visible": true
     },
@@ -2262,7 +2262,7 @@
         "options": null,
         "step": null,
         "type": "SEARCH",
-        "ui_element": "text",
+        "ui_element": "json",
         "value": [
             "personal knowledge",
             "notes",
@@ -2280,7 +2280,7 @@
         "options": null,
         "step": null,
         "type": "SEARCH",
-        "ui_element": "text",
+        "ui_element": "json",
         "value": [
             "subjective content",
             "informal information"
@@ -2469,9 +2469,9 @@
         "options": null,
         "step": null,
         "type": "SEARCH",
-        "ui_element": "text",
+        "ui_element": "json",
         "value": [
-            "@format ${DOCS_DIR}/project_documents"
+            "/local_collections/project_docs/"
         ],
         "visible": true
     },
@@ -2499,7 +2499,7 @@
         "options": null,
         "step": null,
         "type": "SEARCH",
-        "ui_element": "text",
+        "ui_element": "json",
         "value": [
             "project documentation",
             "specifications",
@@ -2517,7 +2517,7 @@
         "options": null,
         "step": null,
         "type": "SEARCH",
-        "ui_element": "text",
+        "ui_element": "json",
         "value": [
             "no external information",
             "limited to organizational knowledge"
@@ -2730,7 +2730,7 @@
         "options": null,
         "step": null,
         "type": "SEARCH",
-        "ui_element": "text",
+        "ui_element": "json",
         "value": [
             "biomedical literature",
             "medical research",
@@ -2751,7 +2751,7 @@
         "options": null,
         "step": null,
         "type": "SEARCH",
-        "ui_element": "text",
+        "ui_element": "json",
         "value": [
             "non-medical topics",
             "very recent papers may be missing",
@@ -2941,9 +2941,9 @@
         "options": null,
         "step": null,
         "type": "SEARCH",
-        "ui_element": "text",
+        "ui_element": "json",
         "value": [
-            "@format ${DOCS_DIR}/research_papers"
+            "/local_collections/research_papers/"
         ],
         "visible": true
     },
@@ -2971,7 +2971,7 @@
         "options": null,
         "step": null,
         "type": "SEARCH",
-        "ui_element": "text",
+        "ui_element": "json",
         "value": [
             "academic research",
             "scientific papers",
@@ -2989,7 +2989,7 @@
         "options": null,
         "step": null,
         "type": "SEARCH",
-        "ui_element": "text",
+        "ui_element": "json",
         "value": [
             "potentially outdated",
             "limited to collected papers"
@@ -3062,7 +3062,7 @@
         "options": null,
         "step": null,
         "type": "SEARCH",
-        "ui_element": "text",
+        "ui_element": "json",
         "value": [
             "general"
         ],
@@ -3231,7 +3231,7 @@
         "options": null,
         "step": null,
         "type": "SEARCH",
-        "ui_element": "text",
+        "ui_element": "json",
         "value": [
             "comprehensive general information",
             "current events and news",
@@ -3270,7 +3270,7 @@
         "options": null,
         "step": null,
         "type": "SEARCH",
-        "ui_element": "text",
+        "ui_element": "json",
         "value": [
             "requires self-hosting",
             "depends on other search engines",
@@ -3470,7 +3470,7 @@
         "options": null,
         "step": null,
         "type": "SEARCH",
-        "ui_element": "text",
+        "ui_element": "json",
         "value": [
             "comprehensive web search",
             "product information",
@@ -3505,7 +3505,7 @@
         "options": null,
         "step": null,
         "type": "SEARCH",
-        "ui_element": "text",
+        "ui_element": "json",
         "value": [
             "requires API key with usage limits",
             "not specialized for academic content"
@@ -3662,7 +3662,7 @@
         "options": null,
         "step": null,
         "type": "SEARCH",
-        "ui_element": "text",
+        "ui_element": "json",
         "value": [
             "historical web content",
             "archived websites",
@@ -3696,7 +3696,7 @@
         "options": null,
         "step": null,
         "type": "SEARCH",
-        "ui_element": "text",
+        "ui_element": "json",
         "value": [
             "limited to previously archived content",
             "may miss recent changes",
@@ -3868,7 +3868,7 @@
         "options": null,
         "step": null,
         "type": "SEARCH",
-        "ui_element": "text",
+        "ui_element": "json",
         "value": [
             "factual information",
             "general knowledge",
@@ -3889,7 +3889,7 @@
         "options": null,
         "step": null,
         "type": "SEARCH",
-        "ui_element": "text",
+        "ui_element": "json",
         "value": [
             "recent events",
             "specialized academic topics",

local_deep_research/metrics/__init__.py

@@ -0,0 +1,13 @@
+"""Metrics module for tracking LLM usage and token counts."""
+
+from .database import get_metrics_db
+from .db_models import ModelUsage, TokenUsage
+from .token_counter import TokenCounter, TokenCountingCallback
+
+__all__ = [
+    "TokenCounter",
+    "TokenCountingCallback",
+    "TokenUsage",
+    "ModelUsage",
+    "get_metrics_db",
+]

local_deep_research/metrics/database.py

@@ -0,0 +1,58 @@
+"""Database utilities for metrics module with SQLAlchemy."""
+
+from contextlib import contextmanager
+from typing import Generator
+
+from loguru import logger
+from sqlalchemy import create_engine
+from sqlalchemy.orm import Session, sessionmaker
+
+from ..utilities.db_utils import DB_PATH
+from .db_models import Base
+
+
+class MetricsDatabase:
+    """Database manager for metrics using SQLAlchemy."""
+
+    def __init__(self):
+        # Use the same database as the rest of the app
+        self.engine = create_engine(
+            f"sqlite:///{DB_PATH}", connect_args={"check_same_thread": False}
+        )
+        self.SessionLocal = sessionmaker(
+            bind=self.engine, autocommit=False, autoflush=False
+        )
+        self._init_database()
+
+    def _init_database(self):
+        """Initialize database tables for metrics."""
+        try:
+            Base.metadata.create_all(self.engine)
+            logger.info("Metrics tables initialized successfully")
+        except Exception as e:
+            logger.exception(f"Error initializing metrics tables: {e}")
+
+    @contextmanager
+    def get_session(self) -> Generator[Session, None, None]:
+        """Get a database session with automatic cleanup."""
+        session = self.SessionLocal()
+        try:
+            yield session
+            session.commit()
+        except Exception:
+            session.rollback()
+            raise
+        finally:
+            session.close()
+
+
+# Singleton instance
+_metrics_db = None
+
+
+def get_metrics_db() -> MetricsDatabase:
+    """Get the singleton metrics database instance."""
+    global _metrics_db
+    if _metrics_db is None:
+        _metrics_db = MetricsDatabase()
+    return _metrics_db

local_deep_research/metrics/db_models.py

@@ -0,0 +1,115 @@
+"""SQLAlchemy models for metrics."""
+
+from sqlalchemy import (
+    Column,
+    DateTime,
+    Integer,
+    String,
+    Text,
+    UniqueConstraint,
+    func,
+)
+from sqlalchemy.ext.declarative import declarative_base
+
+Base = declarative_base()
+
+
+class TokenUsage(Base):
+    """Model for tracking individual token usage events."""
+
+    __tablename__ = "token_usage"
+
+    id = Column(Integer, primary_key=True)
+    research_id = Column(
+        Integer
+    )  # Removed foreign key constraint to fix token tracking
+    model_name = Column(String)
+    provider = Column(
+        String
+    )  # Added provider column for accurate cost tracking
+    prompt_tokens = Column(Integer)
+    completion_tokens = Column(Integer)
+    total_tokens = Column(Integer)
+
+    # Phase 1 Enhancement: Research context
+    research_query = Column(Text)
+    research_mode = Column(String)  # 'quick' or 'detailed'
+    research_phase = Column(String)  # 'init', 'iteration_1', etc.
+    search_iteration = Column(Integer)
+
+    # Phase 1 Enhancement: Performance metrics
+    response_time_ms = Column(Integer)
+    success_status = Column(
+        String, default="success"
+    )  # 'success', 'error', 'timeout'
+    error_type = Column(String)
+
+    # Phase 1 Enhancement: Search engine context
+    search_engines_planned = Column(Text)  # JSON array as text
+    search_engine_selected = Column(String)
+
+    # Call stack tracking
+    calling_file = Column(String)  # File that made the LLM call
+    calling_function = Column(String)  # Function that made the LLM call
+    call_stack = Column(Text)  # Full call stack as JSON
+
+    timestamp = Column(DateTime, server_default=func.now())
+
+
+class ModelUsage(Base):
+    """Model for aggregated token usage by model and research."""
+
+    __tablename__ = "model_usage"
+    __table_args__ = (UniqueConstraint("research_id", "model_name"),)
+
+    id = Column(Integer, primary_key=True)
+    research_id = Column(
+        Integer
+    )  # Removed foreign key constraint to fix token tracking
+    model_name = Column(String)
+    provider = Column(String)
+    prompt_tokens = Column(Integer, default=0)
+    completion_tokens = Column(Integer, default=0)
+    total_tokens = Column(Integer, default=0)
+    calls = Column(Integer, default=0)
+    timestamp = Column(DateTime, server_default=func.now())
+
+
+class ResearchRating(Base):
+    """Model for storing user ratings of research sessions."""
+
+    __tablename__ = "research_ratings"
+
+    id = Column(Integer, primary_key=True)
+    research_id = Column(Integer, unique=True)  # References research session ID
+    rating = Column(Integer)  # 1-5 star rating
+    rated_at = Column(DateTime, server_default=func.now())
+    updated_at = Column(
+        DateTime, server_default=func.now(), onupdate=func.now()
+    )
+
+
+class SearchCall(Base):
+    """Model for individual search engine calls."""
+
+    __tablename__ = "search_calls"
+
+    id = Column(Integer, primary_key=True)
+    research_id = Column(Integer)
+    research_query = Column(Text)
+    research_mode = Column(String)
+    research_phase = Column(String)
+    search_iteration = Column(Integer)
+
+    # Search details
+    search_engine = Column(String)
+    query = Column(Text)
+    results_count = Column(Integer)
+    response_time_ms = Column(Integer)
+
+    # Status tracking
+    success_status = Column(String, default="success")
+    error_type = Column(String)
+    error_message = Column(Text)
+
+    timestamp = Column(DateTime, server_default=func.now())

local_deep_research/metrics/migrate_add_provider_to_token_usage.py

@@ -0,0 +1,148 @@
+"""
+Migration: Add provider column to TokenUsage table
+
+This migration adds the provider column to the TokenUsage table to enable
+accurate cost tracking based on both model and provider information.
+"""
+
+import logging
+from pathlib import Path
+
+from sqlalchemy import text
+
+from .database import get_metrics_db
+
+logger = logging.getLogger(__name__)
+
+
+def add_provider_column_to_token_usage():
+    """Add provider column to TokenUsage table."""
+    try:
+        db = get_metrics_db()
+
+        with db.get_session() as session:
+            # Check if provider column already exists
+            result = session.execute(
+                text(
+                    """
+                SELECT COUNT(*) as count
+                FROM pragma_table_info('token_usage')
+                WHERE name='provider'
+            """
+                )
+            )
+
+            provider_exists = result.fetchone()[0] > 0
+
+            if provider_exists:
+                logger.info(
+                    "Provider column already exists in token_usage table"
+                )
+                return True
+
+            logger.info("Adding provider column to token_usage table...")
+
+            # Add the provider column
+            session.execute(
+                text(
+                    """
+                ALTER TABLE token_usage
+                ADD COLUMN provider VARCHAR
+            """
+                )
+            )
+
+            # Try to populate provider info for existing records based on model name patterns
+            logger.info("Populating provider info for existing records...")
+
+            # Update known local model providers
+            local_model_updates = [
+                (
+                    "ollama",
+                    [
+                        "ollama",
+                        "llama",
+                        "mistral",
+                        "gemma",
+                        "qwen",
+                        "codellama",
+                        "vicuna",
+                        "alpaca",
+                    ],
+                ),
+                ("openai", ["gpt-", "davinci", "curie", "babbage", "ada"]),
+                ("anthropic", ["claude"]),
+                ("google", ["gemini", "bard"]),
+            ]
+
+            for provider, model_patterns in local_model_updates:
+                for pattern in model_patterns:
+                    session.execute(
+                        text(
+                            """
+                        UPDATE token_usage
+                        SET provider = :provider
+                        WHERE provider IS NULL
+                        AND (LOWER(model_name) LIKE :pattern OR LOWER(model_name) LIKE :pattern_percent)
+                    """
+                        ),
+                        {
+                            "provider": provider,
+                            "pattern": pattern,
+                            "pattern_percent": f"%{pattern}%",
+                        },
+                    )
+
+            # Set any remaining NULL providers to 'unknown'
+            session.execute(
+                text(
+                    """
+                UPDATE token_usage
+                SET provider = 'unknown'
+                WHERE provider IS NULL
+            """
+                )
+            )
+
+            session.commit()
+            logger.info(
+                "Successfully added provider column and populated existing data"
+            )
+            return True
+
+    except Exception as e:
+        logger.error(f"Error adding provider column to token_usage: {e}")
+        return False
+
+
+def run_migration():
+    """Run the provider column migration."""
+    logger.info("Starting migration: Add provider column to TokenUsage")
+
+    success = add_provider_column_to_token_usage()
+
+    if success:
+        logger.info("Migration completed successfully")
+    else:
+        logger.error("Migration failed")
+
+    return success
+
+
+if __name__ == "__main__":
+    # Allow running migration directly
+    import sys
+
+    # Add the project root to the path
+    project_root = Path(__file__).parent.parent.parent.parent
+    sys.path.insert(0, str(project_root))
+
+    logging.basicConfig(level=logging.INFO)
+    success = run_migration()
+
+    if success:
+        print("✅ Migration completed successfully")
+        sys.exit(0)
+    else:
+        print("❌ Migration failed")
+        sys.exit(1)