local-deep-research 0.1.22__py3-none-any.whl → 0.1.24__py3-none-any.whl

local_deep_research/__init__.py

@@ -15,10 +15,19 @@ from .search_system import AdvancedSearchSystem
 from .report_generator import IntegratedReportGenerator
 from .config import get_llm, get_search
 
+# Import API functions
+from .api import quick_summary, generate_report, analyze_documents
+from .api import get_available_search_engines, get_available_collections
+
 # Export it
 __all__ = [
     "AdvancedSearchSystem", 
     "IntegratedReportGenerator",
     "get_llm",
-    "get_search"
+    "get_search",
+    "quick_summary",
+    "generate_report",
+    "analyze_documents",
+    "get_available_search_engines",
+    "get_available_collections"
 ]

local_deep_research/api/__init__.py

@@ -0,0 +1,20 @@
+# src/local_deep_research/api/__init__.py
+"""
+API module for programmatic access to Local Deep Research functionality.
+"""
+
+from .research_functions import (
+    quick_summary, 
+    generate_report, 
+    analyze_documents,
+    get_available_search_engines,
+    get_available_collections
+)
+
+__all__ = [
+    "quick_summary",
+    "generate_report",
+    "analyze_documents",
+    "get_available_search_engines",
+    "get_available_collections"
+]

local_deep_research/api/research_functions.py

@@ -0,0 +1,330 @@
+"""
+API module for Local Deep Research.
+Provides programmatic access to search and research capabilities.
+"""
+
+from typing import Dict, List, Optional, Union, Any, Callable
+import logging
+import os
+import traceback
+import toml
+from ..search_system import AdvancedSearchSystem
+from ..report_generator import IntegratedReportGenerator
+from ..config import get_llm, get_search, settings
+from ..utilties.search_utilities import remove_think_tags
+
+logger = logging.getLogger(__name__)
+
+def quick_summary(
+    query: str,
+    search_tool: Optional[str] = None,
+    iterations: int = 1,
+    questions_per_iteration: int = 1,
+    max_results: int = 20,
+    max_filtered_results: int = 5,
+    region: str = "us",
+    time_period: str = "y",
+    safe_search: bool = True,
+    temperature: float = 0.7,
+    progress_callback: Optional[Callable] = None,
+) -> Dict[str, Any]:
+    """
+    Generate a quick research summary for a given query.
+    
+    Args:
+        query: The research query to analyze
+        search_tool: Search engine to use (auto, wikipedia, arxiv, etc.). If None, uses default
+        iterations: Number of research cycles to perform
+        questions_per_iteration: Number of questions to generate per cycle
+        max_results: Maximum number of search results to consider
+        max_filtered_results: Maximum results after relevance filtering
+        region: Search region/locale
+        time_period: Time period for search results (d=day, w=week, m=month, y=year)
+        safe_search: Whether to enable safe search
+        temperature: LLM temperature for generation
+        progress_callback: Optional callback function to receive progress updates
+        
+    Returns:
+        Dictionary containing the research results with keys:
+        - 'summary': The generated summary text
+        - 'findings': List of detailed findings from each search
+        - 'iterations': Number of iterations performed
+        - 'questions': Questions generated during research
+    """
+    logger.info(f"Generating quick summary for query: {query}")
+    
+
+    # Get language model with custom temperature
+    llm = get_llm(temperature=temperature)
+    
+    # Create search system with custom parameters
+    system = AdvancedSearchSystem()
+    
+    # Override default settings with user-provided values
+    system.max_iterations = iterations 
+    system.questions_per_iteration = questions_per_iteration
+    system.model = llm  # Ensure the model is directly attached to the system
+    
+    # Set the search engine if specified
+    if search_tool:
+        search_engine = get_search(search_tool)
+        if search_engine:
+            system.search = search_engine
+        else:
+            logger.warning(f"Could not create search engine '{search_tool}', using default.")
+    
+    # Set progress callback if provided
+    if progress_callback:
+        system.set_progress_callback(progress_callback)
+    
+    # Perform the search and analysis
+    results = system.analyze_topic(query)
+    
+    # Extract the summary from the current knowledge
+    if results and "current_knowledge" in results:
+        summary = results["current_knowledge"]
+    else:
+        summary = "Unable to generate summary for the query."
+    
+    # Prepare the return value
+    return {
+        "summary": summary,
+        "findings": results.get("findings", []),
+        "iterations": results.get("iterations", 0),
+        "questions": results.get("questions", {}),
+        "formatted_findings": results.get("formatted_findings", ""),
+        "sources": results.get("all_links_of_system", [])
+    }
+
+
+def generate_report(
+    query: str,
+    search_tool: Optional[str] = None,
+    iterations: int = 2,
+    questions_per_iteration: int = 2,
+    searches_per_section: int = 2,
+    max_results: int = 50,
+    max_filtered_results: int = 5,
+    region: str = "us",
+    time_period: str = "y",
+    safe_search: bool = True,
+    temperature: float = 0.7,
+    output_file: Optional[str] = None,
+    progress_callback: Optional[Callable] = None,
+) -> Dict[str, Any]:
+    """
+    Generate a comprehensive, structured research report for a given query.
+    
+    Args:
+        query: The research query to analyze
+        search_tool: Search engine to use (auto, wikipedia, arxiv, etc.). If None, uses default
+        iterations: Number of research cycles to perform
+        questions_per_iteration: Number of questions to generate per cycle
+        searches_per_section: Number of searches to perform per report section
+        max_results: Maximum number of search results to consider
+        max_filtered_results: Maximum results after relevance filtering
+        region: Search region/locale
+        time_period: Time period for search results (d=day, w=week, m=month, y=year)
+        safe_search: Whether to enable safe search
+        temperature: LLM temperature for generation
+        output_file: Optional path to save report markdown file
+        progress_callback: Optional callback function to receive progress updates
+        
+    Returns:
+        Dictionary containing the research report with keys:
+        - 'content': The full report content in markdown format
+        - 'metadata': Report metadata including generated timestamp and query
+    """
+    logger.info(f"Generating comprehensive research report for query: {query}")
+    
+
+    # Get language model with custom temperature
+    llm = get_llm(temperature=temperature)
+    
+    # Create search system with custom parameters
+    system = AdvancedSearchSystem()
+    
+    # Override default settings with user-provided values
+    system.max_iterations = iterations
+    system.questions_per_iteration = questions_per_iteration
+    system.model = llm  # Ensure the model is directly attached to the system
+    
+    # Set the search engine if specified
+    if search_tool:
+        search_engine = get_search(
+            search_tool,
+            llm_instance=llm,
+            max_results=max_results,
+            max_filtered_results=max_filtered_results,
+            region=region,
+            time_period=time_period,
+            safe_search=safe_search
+        )
+        if search_engine:
+            system.search = search_engine
+        else:
+            logger.warning(f"Could not create search engine '{search_tool}', using default.")
+    
+    # Set progress callback if provided
+    if progress_callback:
+        system.set_progress_callback(progress_callback)
+    
+    # Perform the initial research
+    initial_findings = system.analyze_topic(query)
+    
+    # Generate the structured report
+    report_generator = IntegratedReportGenerator(searches_per_section=searches_per_section)
+    report_generator.model = llm  # Ensure the model is set on the report generator too
+    report = report_generator.generate_report(initial_findings, query)
+    
+    # Save report to file if path is provided
+    if output_file and report and "content" in report:
+            with open(output_file, "w", encoding="utf-8") as f:
+                f.write(report["content"])
+            logger.info(f"Report saved to {output_file}")
+            report["file_path"] = output_file
+    return report
+
+
+
+def analyze_documents(
+    query: str,
+    collection_name: str,
+    max_results: int = 10,
+    temperature: float = 0.7,
+    force_reindex: bool = False,
+    output_file: Optional[str] = None,
+) -> Dict[str, Any]:
+    """
+    Search and analyze documents in a specific local collection.
+    
+    Args:
+        query: The search query
+        collection_name: Name of the local document collection to search
+        max_results: Maximum number of results to return
+        temperature: LLM temperature for summary generation
+        force_reindex: Whether to force reindexing the collection
+        output_file: Optional path to save analysis results to a file
+        
+    Returns:
+        Dictionary containing:
+        - 'summary': Summary of the findings
+        - 'documents': List of matching documents with content and metadata
+    """
+    logger.info(f"Analyzing documents in collection '{collection_name}' for query: {query}")
+    
+
+    # Get language model with custom temperature
+    llm = get_llm(temperature=temperature)
+    
+    # Get search engine for the specified collection
+    search = get_search(collection_name, llm_instance=llm)
+    
+    if not search:
+        return {
+            "summary": f"Error: Collection '{collection_name}' not found or not properly configured.",
+            "documents": []
+        }
+    
+    # Set max results
+    search.max_results = max_results
+    
+    # Force reindex if requested
+    if force_reindex and hasattr(search, 'embedding_manager'):
+            for folder_path in search.folder_paths:
+                search.embedding_manager.index_folder(folder_path, force_reindex=True)
+
+    # Perform the search
+    results = search.run(query)
+    
+    if not results:
+        return {
+            "summary": f"No documents found in collection '{collection_name}' for query: '{query}'",
+            "documents": []
+        }
+    
+    # Get LLM to generate a summary of the results
+
+    docs_text = "\n\n".join([f"Document {i+1}: {doc.get('content', doc.get('snippet', ''))[:1000]}" 
+                            for i, doc in enumerate(results[:5])])  # Limit to first 5 docs and 1000 chars each
+    
+    summary_prompt = f"""Analyze these document excerpts related to the query: "{query}"
+    
+    {docs_text}
+    
+    Provide a concise summary of the key information found in these documents related to the query.
+    """
+    
+    summary_response = llm.invoke(summary_prompt)
+    if hasattr(summary_response, 'content'):
+        summary = remove_think_tags(summary_response.content)
+    else:
+        summary = str(summary_response)
+
+    # Create result dictionary
+    analysis_result = {
+        "summary": summary,
+        "documents": results,
+        "collection": collection_name,
+        "document_count": len(results)
+    }
+    
+    # Save to file if requested
+    if output_file:
+            with open(output_file, "w", encoding="utf-8") as f:
+                f.write(f"# Document Analysis: {query}\n\n")
+                f.write(f"## Summary\n\n{summary}\n\n")
+                f.write(f"## Documents Found: {len(results)}\n\n")
+                
+                for i, doc in enumerate(results):
+                    f.write(f"### Document {i+1}: {doc.get('title', 'Untitled')}\n\n")
+                    f.write(f"**Source:** {doc.get('link', 'Unknown')}\n\n")
+                    f.write(f"**Content:**\n\n{doc.get('content', doc.get('snippet', 'No content available'))[:1000]}...\n\n")
+                    f.write("---\n\n")
+                    
+            analysis_result["file_path"] = output_file
+            logger.info(f"Analysis saved to {output_file}")
+
+    return analysis_result
+
+def get_available_search_engines() -> Dict[str, str]:
+    """
+    Get a dictionary of available search engines.
+    
+    Returns:
+        Dictionary mapping engine names to descriptions
+    """
+
+    from ..web_search_engines.search_engine_factory import get_available_engines
+    engines = get_available_engines()
+    
+    # Add some descriptions for common engines
+    descriptions = {
+        "auto": "Automatic selection based on query type",
+        "wikipedia": "Wikipedia articles and general knowledge",
+        "arxiv": "Scientific papers and research",
+        "pubmed": "Medical and biomedical literature",
+        "semantic_scholar": "Academic papers across all fields",
+        "github": "Code repositories and technical documentation",
+        "local_all": "All local document collections"
+    }
+    
+    return {engine: descriptions.get(engine, "Search engine") for engine in engines}
+
+
+def get_available_collections() -> Dict[str, Dict[str, Any]]:
+    """
+    Get a dictionary of available local document collections.
+    
+    Returns:
+        Dictionary mapping collection names to their configuration
+    """
+
+
+    from ..config import LOCAL_COLLECTIONS_FILE
+    
+    if os.path.exists(LOCAL_COLLECTIONS_FILE):
+            collections = toml.load(LOCAL_COLLECTIONS_FILE)
+            return collections
+
+    return {}

local_deep_research/defaults/.env.template

@@ -0,0 +1,11 @@
+# API Keys
+# ANTHROPIC_API_KEY=your-api-key-here
+# OPENAI_API_KEY=your-openai-key-here
+# SERP_API_KEY=your-api-key-here
+# GUARDIAN_API_KEY=your-api-key-here
+# GOOGLE_PSE_API_KEY=your-google-api-key-here
+# GOOGLE_PSE_ENGINE_ID=your-programmable-search-engine-id-here
+
+# SearXNG Configuration, add at least SEARXNG_INSTANCE to .env file to use this search engine
+# SEARXNG_INSTANCE = "http://localhost:8080"
+# SEARXNG_DELAY = 2.0

{local_deep_research-0.1.22.dist-info → local_deep_research-0.1.24.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: local-deep-research
-Version: 0.1.22
+Version: 0.1.24
 Summary: AI-powered research assistant with deep, iterative analysis using LLMs and web searches
 Author-email: LearningCircuit <185559241+LearningCircuit@users.noreply.github.com>, HashedViking <6432677+HashedViking@users.noreply.github.com>
 License: MIT License
@@ -105,6 +105,28 @@ ldr # (OR python -m local_deep_research.main)
 
 Access the web interface at `http://127.0.0.1:5000` in your browser.
 
+## Docker Support
+
+### Build the image first if you haven't already
+```bash
+docker build -t local-deep-research .
+```
+
+### Quick Docker Run
+
+```bash
+# Run with default settings (connects to Ollama running on the host)
+docker run --network=host \
+  -e LDR_LLM__PROVIDER="ollama" \
+  -e LDR_LLM__MODEL="mistral" \
+  local-deep-research
+```
+
+For comprehensive Docker setup information, see:
+- [Docker Usage Guide](https://github.com/LearningCircuit/local-deep-research/blob/main/docs/docker-usage-readme.md)
+- [Docker Compose Guide](https://github.com/LearningCircuit/local-deep-research/blob/main/docs/docker-compose-guide.md)
+
+
 ## Features
 
 - 🔍 **Advanced Research Capabilities**
@@ -286,23 +308,27 @@ You can use local document search in several ways:
 3. **All collections**: Set `tool = "local_all"` to search across all collections
 4. **Query syntax**: Type `collection:project_docs your query` to target a specific collection
 
-## Docker Support
+## Programmatic Access
 
-Local Deep Research can run in Docker containers for easy deployment across environments.
+Local Deep Research now provides a simple API for programmatic access to its research capabilities:
 
-### Quick Docker Run
+```python
+from local_deep_research import quick_summary, generate_report
 
-```bash
-# Run with default settings (connects to Ollama running on the host)
-docker run --network=host \
-  -e LDR_LLM__PROVIDER="ollama" \
-  -e LDR_LLM__MODEL="mistral" \
-  local-deep-research
+# Generate a quick research summary
+results = quick_summary("advances in fusion energy")
+print(results["summary"])
+
+# Create a comprehensive structured report
+report = generate_report("impact of quantum computing on cryptography")
+print(report["content"])
+
+# Analyze documents in a local collection
+from local_deep_research import analyze_documents
+docs = analyze_documents("renewable energy", "research_papers")
 ```
 
-For comprehensive Docker setup information, see:
-- [Docker Usage Guide](https://github.com/LearningCircuit/local-deep-research/blob/main/docs/docker-usage-readme.md)
-- [Docker Compose Guide](https://github.com/LearningCircuit/local-deep-research/blob/main/docs/docker-compose-guide.md)
+These functions provide flexible options for customizing the search parameters, iterations, and output formats. For more examples, see the [programmatic access tutorial](https://github.com/LearningCircuit/local-deep-research/blob/programmatic-access/examples/programmatic_access.ipynb).
 
 ## Advanced Configuration
 

{local_deep_research-0.1.22.dist-info → local_deep_research-0.1.24.dist-info}/RECORD

@@ -1,9 +1,12 @@
-local_deep_research/__init__.py,sha256=pfHzjzYc6Szo8VCNLtFZRXyAlEz7CViY7r2fH9O7yms,584
+local_deep_research/__init__.py,sha256=Grde0sFEYyCXrPCfxd-9b9v1M6OurrzQbVYRmKQ9E7w,886
 local_deep_research/citation_handler.py,sha256=v_fwTy-2XvUuoH3OQRzmBrvaiN7mBk8jbNfySslmt5g,4357
 local_deep_research/config.py,sha256=3g8-QPMrxoIMjHvyjSJBFUELmAIyOQFHApUnd8p50a8,9881
 local_deep_research/main.py,sha256=uQXtGQ6LtZNd5Qw63D5ke4Q_LjYimouWVSUknVsk3JQ,3645
 local_deep_research/report_generator.py,sha256=EvaArnWirMgg42fMzmZeJczoEYujEbJ2ryHHYuuoXx8,8058
 local_deep_research/search_system.py,sha256=yY3BEzX68vdtUcYF9h6lC3yVao0YA_NSBj6W3-RwlKk,15459
+local_deep_research/api/__init__.py,sha256=H0WGFSohUR0T2QswtWngPZWoMYPs9VWQTQYaivAlrJU,440
+local_deep_research/api/research_functions.py,sha256=Z23wZYsB1x2ivdFYJ9uqIqCAwjR2RdOff7Bq30DxQYU,12099
+local_deep_research/defaults/.env.template,sha256=U4B_InwGZl4IVuAdbY_u0nKN_akHtebMBwUU_e_eljc,427
 local_deep_research/defaults/__init__.py,sha256=2Vvlkl-gmP_qPYWegE4JBgummypogl3VXrQ1XzptFDU,1381
 local_deep_research/defaults/llm_config.py,sha256=Ql0euemgLw_Uwg5g05sA1SkVzAYK7O_ZAnnBi3rsAi4,10095
 local_deep_research/defaults/local_collections.toml,sha256=zNa03PVnFrZ757JdZOuW6QDxkOc6ep5tG8baGBrMmXM,1778
@@ -50,9 +53,9 @@ local_deep_research/web_search_engines/engines/search_engine_semantic_scholar.py
 local_deep_research/web_search_engines/engines/search_engine_serpapi.py,sha256=XikEYnM-pAaR70VeAJ28lbqpRzCj4bCA9xY29taTV8g,9215
 local_deep_research/web_search_engines/engines/search_engine_wayback.py,sha256=astAvSLajDZ6rwgthJ3iBcHSWuDSYPO7uilIxaJhXmU,18132
 local_deep_research/web_search_engines/engines/search_engine_wikipedia.py,sha256=KSGJECbEcxZpVK-PhYsTCtzedSK0l1AjQmvGtx8KBks,9799
-local_deep_research-0.1.22.dist-info/licenses/LICENSE,sha256=Qg2CaTdu6SWnSqk1_JtgBPp_Da-LdqJDhT1Vt1MUc5s,1072
-local_deep_research-0.1.22.dist-info/METADATA,sha256=_kjb5M093i9x4yhJ1cQ198P1bnDJg-atHCc2otwcrc0,16181
-local_deep_research-0.1.22.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
-local_deep_research-0.1.22.dist-info/entry_points.txt,sha256=u-Y6Z3MWtR3dmsTDFYhXyfkPv7mALUA7YAnY4Fi1XDs,97
-local_deep_research-0.1.22.dist-info/top_level.txt,sha256=h6-uVE_wSuLOcoWwT9szhX23mBWufu77MqmM25UfbCY,20
-local_deep_research-0.1.22.dist-info/RECORD,,
+local_deep_research-0.1.24.dist-info/licenses/LICENSE,sha256=Qg2CaTdu6SWnSqk1_JtgBPp_Da-LdqJDhT1Vt1MUc5s,1072
+local_deep_research-0.1.24.dist-info/METADATA,sha256=mM-b8LezrBKyR-VjOYE0lMqoKzEwfvID2kMYgUJH9Z4,17096
+local_deep_research-0.1.24.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
+local_deep_research-0.1.24.dist-info/entry_points.txt,sha256=u-Y6Z3MWtR3dmsTDFYhXyfkPv7mALUA7YAnY4Fi1XDs,97
+local_deep_research-0.1.24.dist-info/top_level.txt,sha256=h6-uVE_wSuLOcoWwT9szhX23mBWufu77MqmM25UfbCY,20
+local_deep_research-0.1.24.dist-info/RECORD,,