local-deep-research 0.1.20__py3-none-any.whl → 0.1.21__py3-none-any.whl

local_deep_research/defaults/search_engines.toml

@@ -186,40 +186,40 @@ strengths = ["searches all local collections", "personal documents", "offline ac
 weaknesses = ["may return too many results", "requires indexing"]
 requires_llm = true
 
-[semantic_scholar]
-module_path = "local_deep_research.web_search_engines.engines.search_engine_semantic_scholar"
-class_name = "SemanticScholarSearchEngine"
-requires_api_key = false
-api_key_env = "S2_API_KEY"
-reliability = 0.87
-strengths = [
-    "comprehensive scientific literature", 
-    "extensive citation network", 
-    "AI-generated summaries (TLDRs)", 
-    "academic paper metadata", 
-    "cross-disciplinary coverage",
-    "200M+ papers across all fields",
-    "usable without API key"
-]
-weaknesses = [
-    "rate limited (1000 requests/day) without API key",
-    "limited to academic content"
-]
-supports_full_search = true
-requires_llm = false
+#[semantic_scholar]
+#module_path = "local_deep_research.web_search_engines.engines.search_engine_semantic_scholar"
+#class_name = "SemanticScholarSearchEngine"
+#requires_api_key = false
+#api_key_env = "S2_API_KEY"
+#reliability = 0.87
+#strengths = [
+#    "comprehensive scientific literature", 
+#    "extensive citation network", 
+#    "AI-generated summaries (TLDRs)", 
+#    "academic paper metadata", 
+#    "cross-disciplinary coverage",
+#    "200M+ papers across all fields",
+#    "usable without API key"
+#]
+#weaknesses = [
+#    "rate limited (1000 requests/day) without API key",
+#    "limited to academic content"
+#]
+#supports_full_search = true
+#requires_llm = false
 
-[semantic_scholar.default_params]
-max_results = 20
-get_abstracts = true
-get_tldr = true
-get_references = false
-get_citations = false
-get_embeddings = false
-citation_limit = 10
-reference_limit = 10
-optimize_queries = true
-max_retries = 5
-retry_backoff_factor = 1.0
+#[semantic_scholar.default_params]
+#max_results = 20
+#get_abstracts = true
+#get_tldr = true
+#get_references = false
+#get_citations = false
+#get_embeddings = false
+#citation_limit = 10
+#reference_limit = 10
+#optimize_queries = true
+#max_retries = 5
+#retry_backoff_factor = 1.0
 
 # Default search engine to use if none specified
 DEFAULT_SEARCH_ENGINE = "wikipedia"

{local_deep_research-0.1.20.dist-info → local_deep_research-0.1.21.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: local-deep-research
-Version: 0.1.20
+Version: 0.1.21
 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
@@ -106,6 +106,13 @@ ldr # (OR python -m local_deep_research.main)
 Access the web interface at `http://127.0.0.1:5000` in your browser.
 
 ## Features
+<div align="center">
+  <a href="https://www.youtube.com/watch?v=4tDqV__jzKY">
+    <img src="https://img.youtube.com/vi/4tDqV__jzKY/0.jpg" alt="Local Deep Research">
+    <br>
+    <span>▶️ Watch Video</span>
+  </a>
+</div>
 
 - 🔍 **Advanced Research Capabilities**
   - Automated deep research with intelligent follow-up questions
@@ -151,17 +158,17 @@ The package automatically creates and manages configuration files in your user d
 
 ### Default Configuration Files
 
-If you prefere environment variables please refere to this file: https://github.com/LearningCircuit/local-deep-research/blob/main/docs/env_configuration.md
-
 When you first run the tool, it creates these configuration files:
 
 | File | Purpose |
 |------|---------|
 | `settings.toml` | General settings for research, web interface, and search |
-| `llm_config.py` | Configure which LLM to use (local or cloud-based) |
+| `llm_config.py` | Advanced LLM configuration (rarely needs modification) |
 | `search_engines.toml` | Define and configure search engines |
 | `local_collections.toml` | Configure local document collections for RAG |
-| `.secrets.toml` | Store API keys for cloud services |
+| `.env` | Environment variables for configuration (recommended for API keys) |
+
+> **Note:** For comprehensive environment variable configuration, see our [Environment Variables Guide](https://github.com/LearningCircuit/local-deep-research/blob/main/docs/env_configuration.md).
 
 ## Setting Up AI Models
 
@@ -175,42 +182,34 @@ The system supports multiple LLM providers:
 
 ### Cloud Models
 
-Edit your `.secrets.toml` file to add API keys:
+Add API keys to your environment variables (recommended) by creating a `.env` file in your config directory:
 
-```toml
-ANTHROPIC_API_KEY = "your-api-key-here"      # For Claude models
-OPENAI_API_KEY = "your-openai-key-here"      # For GPT models
-OPENAI_ENDPOINT_API_KEY = "your-key-here"    # For OpenRouter or similar services
+```bash
+# Set API keys for cloud providers in .env
+ANTHROPIC_API_KEY=your-api-key-here      # For Claude models
+OPENAI_API_KEY=your-openai-key-here      # For GPT models
+OPENAI_ENDPOINT_API_KEY=your-key-here    # For OpenRouter or similar services
+
+# Set your preferred LLM provider and model (no need to edit llm_config.py)
+LDR_LLM__PROVIDER=ollama                 # Options: ollama, openai, anthropic, etc.
+LDR_LLM__MODEL=gemma3:12b                # Model name to use
 ```
 
-Then edit `llm_config.py` to change the default provider:
-
-```python
-# Set your preferred model provider here
-DEFAULT_PROVIDER = ModelProvider.OLLAMA  # Change to your preferred provider
-
-# Set your default model name here
-DEFAULT_MODEL = "mistral"  # Change to your preferred model
-```
+> **Important:** In most cases, you don't need to modify the `llm_config.py` file. Simply set the `LDR_LLM__PROVIDER` and `LDR_LLM__MODEL` environment variables to use your preferred model.
 
 ### Supported LLM Providers
 
 The system supports multiple LLM providers:
 
-| Provider | Type | Configuration | Notes |
-|----------|------|--------------|-------|
-| `OLLAMA` | Local | No API key needed | Default - install from ollama.ai |
-| `OPENAI` | Cloud | Requires `OPENAI_API_KEY` | GPT models (3.5, 4, 4o) |
-| `ANTHROPIC` | Cloud | Requires `ANTHROPIC_API_KEY` | Claude models (3 Opus, Sonnet, Haiku) |
-| `OPENAI_ENDPOINT` | Cloud | Requires `OPENAI_ENDPOINT_API_KEY` | For any OpenAI-compatible API |
-| `VLLM` | Local | No API key needed | For hosting models via vLLM |
-
-You can configure the OpenAI-compatible endpoint URL in `llm_config.py`:
-
-```python
-# For OpenRouter, Together.ai, Azure OpenAI, or any compatible endpoint
-OPENAI_ENDPOINT_URL = "https://openrouter.ai/api/v1"
-```
+| Provider | Type | API Key | Setup Details | Models |
+|----------|------|---------|---------------|--------|
+| `OLLAMA` | Local | No | Install from [ollama.ai](https://ollama.ai) | Mistral, Llama, Gemma, etc. |
+| `OPENAI` | Cloud | `OPENAI_API_KEY` | Set in environment | GPT-3.5, GPT-4, GPT-4o |
+| `ANTHROPIC` | Cloud | `ANTHROPIC_API_KEY` | Set in environment | Claude 3 Opus, Sonnet, Haiku |
+| `OPENAI_ENDPOINT` | Cloud | `OPENAI_ENDPOINT_API_KEY` | Set in environment | Any OpenAI-compatible model |
+| `VLLM` | Local | No | Requires GPU setup | Any supported by vLLM |
+| `LMSTUDIO` | Local | No | Use LM Studio server | Models from LM Studio |
+| `LLAMACPP` | Local | No | Configure model path | GGUF model formats |
 
 The `OPENAI_ENDPOINT` provider can access any service with an OpenAI-compatible API, including:
 - OpenRouter (access to hundreds of models)
@@ -219,26 +218,43 @@ The `OPENAI_ENDPOINT` provider can access any service with an OpenAI-compatible
 - Groq
 - Anyscale
 - Self-hosted LLM servers with OpenAI compatibility
-- Any other service that implements the OpenAI API specification
 
 ## Setting Up Search Engines
 
-The system includes multiple search engines. Some require API keys:
+Some search engines require API keys. Add them to your environment variables by creating a `.env` file in your config directory:
 
-Use .env in config folder if .secrets.toml doesnt work. 
+```bash
+# Search engine API keys (add to .env file)
+SERP_API_KEY=your-serpapi-key-here        # For Google results via SerpAPI
+GOOGLE_PSE_API_KEY=your-google-key-here   # For Google Programmable Search
+GOOGLE_PSE_ENGINE_ID=your-pse-id-here     # For Google Programmable Search
+BRAVE_API_KEY=your-brave-search-key-here  # For Brave Search
+GUARDIAN_API_KEY=your-guardian-key-here   # For The Guardian
+
+# Set your preferred search tool
+LDR_SEARCH__TOOL=auto                     # Default: intelligently selects best engine
+```
 
-You can also overwrite other settings via environment variables, e.g. to overwrite [web] port setting in settings.toml please use: **LDR_WEB__PORT=8080**
+> **Tip:** To override other settings via environment variables (e.g., to change the web port), use: **LDR_WEB__PORT=8080**
 
-```toml
-# Add to .secrets.toml
-SERP_API_KEY = "your-serpapi-key-here"        # For Google results via SerpAPI
-GOOGLE_PSE_API_KEY = "your-google-key-here"   # For Google Programmable Search
-GOOGLE_PSE_ENGINE_ID = "your-pse-id-here"     # For Google Programmable Search
-BRAVE_API_KEY = "your-brave-search-key-here"  # For Brave Search
-GUARDIAN_API_KEY = "your-guardian-key-here"   # For The Guardian
-```
+### Available Search Engines
+
+| Engine | Purpose | API Key Required? | Rate Limit |
+|--------|---------|-------------------|------------|
+| `auto` | Intelligently selects the best engine | No | Based on selected engine |
+| `wikipedia` | General knowledge and facts | No | No strict limit |
+| `arxiv` | Scientific papers and research | No | No strict limit |
+| `pubmed` | Medical and biomedical research | No | No strict limit |
+| `semantic_scholar` | Academic literature across all fields | No | 100/5min |
+| `github` | Code repositories and documentation | No | 60/hour (unauthenticated) |
+| `brave` | Web search (privacy-focused) | Yes | Based on plan |
+| `serpapi` | Google search results | Yes | Based on plan |
+| `google_pse` | Custom Google search | Yes | 100/day free tier |
+| `wayback` | Historical web content | No | No strict limit |
+| `searxng` | Local web search engine | No (requires local server) | No limit |
+| Any collection name | Search your local documents | No | No limit |
 
-No API key required for: Wikipedia, arXiv, PubMed, Semantic Scholar, and local collections.
+> **Note:** For detailed SearXNG setup, see our [SearXNG Setup Guide](https://github.com/LearningCircuit/local-deep-research/blob/main/docs/SearXNG-Setup.md).
 
 ## Local Document Search (RAG)
 
@@ -262,8 +278,6 @@ max_filtered_results = 5
 chunk_size = 1000
 chunk_overlap = 200
 cache_dir = "__CACHE_DIR__/local_search/project_docs"
-
-# More collections defined in the file...
 ```
 
 2. Create your document directories:
@@ -279,34 +293,29 @@ 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
 
-## Available Search Engines
+## Docker Support
 
-| Engine | Purpose | API Key Required? | Rate Limit |
-|--------|---------|-------------------|------------|
-| `auto` | Intelligently selects the best engine | No | Based on selected engine |
-| `wikipedia` | General knowledge and facts | No | No strict limit |
-| `arxiv` | Scientific papers and research | No | No strict limit |
-| `pubmed` | Medical and biomedical research | No | No strict limit |
-| `semantic_scholar` | Academic literature across all fields | No | 100/5min |
-| `github` | Code repositories and documentation | No | 60/hour (unauthenticated) |
-| `brave` | Web search (privacy-focused) | Yes | Based on plan |
-| `serpapi` | Google search results | Yes | Based on plan |
-| `google_pse` | Custom Google search | Yes | 100/day free tier |
-| `wayback` | Historical web content | No | No strict limit |
-| `searxng` | Local web search engine | No (requires local server) | No limit |
-| Any collection name | Search your local documents | No | No limit |
+Local Deep Research can run in Docker containers for easy deployment across environments.
 
-> **Support Free Knowledge:** If you frequently use the search engines in this tool, please consider making a donation to these organizations. They provide valuable services and rely on user support to maintain their operations:
-> - [Donate to Wikipedia](https://donate.wikimedia.org)
-> - [Support arXiv](https://arxiv.org/about/give)
-> - [Donate to DuckDuckGo](https://duckduckgo.com/donations)
-> - [Support PubMed/NCBI](https://www.nlm.nih.gov/pubs/donations/donations.html)
+### 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)
 
 ## Advanced Configuration
 
 ### Research Parameters
 
-Edit `settings.toml` to customize research parameters:
+Edit `settings.toml` to customize research parameters or use environment variables:
 
 ```toml
 [search]
@@ -324,8 +333,13 @@ max_results = 50
 
 # Results after relevance filtering
 max_filtered_results = 5
+```
 
-# More settings available...
+Using environment variables:
+```bash
+LDR_SEARCH__TOOL=auto
+LDR_SEARCH__ITERATIONS=3
+LDR_SEARCH__QUESTIONS_PER_ITERATION=2
 ```
 
 ## Web Interface
@@ -338,9 +352,6 @@ The web interface offers several features:
 - **PDF Export**: Download reports
 - **Research Management**: Terminate processes or delete records
 
-![Web Interface](./web1.png)
-![Web Interface](./web2.png)
-
 ## Command Line Interface
 
 The CLI version allows you to:
@@ -363,8 +374,6 @@ cd local-deep-research
 pip install -e .
 ```
 
-This creates an "editable" installation that uses your local code, so any changes you make are immediately available without reinstalling.
-
 You can run the application directly using Python module syntax:
 
 ```bash
@@ -375,12 +384,6 @@ python -m local_deep_research.web.app
 python -m local_deep_research.main
 ```
 
-This approach is useful for development and debugging, as it provides more detailed error messages and allows you to make code changes on the fly.
-
-## Example Research
-
-The repository includes complete research examples like our [fusion energy research analysis](https://github.com/LearningCircuit/local-deep-research/blob/main/examples/fusion-energy-research-developments.md) showcasing the system's capabilities.
-
 ## Community & Support
 
 Join our [Discord server](https://discord.gg/2E6gYU2Z) to exchange ideas, discuss usage patterns, and share research approaches.
@@ -393,24 +396,33 @@ This project is licensed under the MIT License.
 
 - Built with [Ollama](https://ollama.ai) for local AI processing
 - Search powered by multiple sources:
-  - [Wikipedia](https://www.wikipedia.org/) for factual knowledge (default search engine)
+  - [Wikipedia](https://www.wikipedia.org/) for factual knowledge
   - [arXiv](https://arxiv.org/) for scientific papers
   - [PubMed](https://pubmed.ncbi.nlm.nih.gov/) for biomedical literature
+  - [Semantic Scholar](https://www.semanticscholar.org/) for academic literature
   - [DuckDuckGo](https://duckduckgo.com) for web search
   - [The Guardian](https://www.theguardian.com/) for journalism
-  - [SerpAPI](https://serpapi.com) for Google search results (requires API key)
+  - [SerpAPI](https://serpapi.com) for Google search results
   - [SearXNG](https://searxng.org/) for local web-search engine
   - [Brave Search](https://search.brave.com/) for privacy-focused web search
-  - [Semantic Scholar](https://www.semanticscholar.org/) for academic literature
 - Built on [LangChain](https://github.com/hwchase17/langchain) framework
 - Uses [justext](https://github.com/miso-belica/justext), [Playwright](https://playwright.dev), [FAISS](https://github.com/facebookresearch/faiss), and more
 
+> **Support Free Knowledge:** If you frequently use the search engines in this tool, please consider making a donation to these organizations:
+> - [Donate to Wikipedia](https://donate.wikimedia.org)
+> - [Support arXiv](https://arxiv.org/about/give)
+> - [Donate to DuckDuckGo](https://duckduckgo.com/donations)
+> - [Support PubMed/NCBI](https://www.nlm.nih.gov/pubs/donations/donations.html)
+
 ## Contributing
 
 Contributions are welcome! Please feel free to submit a Pull Request.
 
 1. Fork the repository
 2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
-3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
-4. Push to the branch (`git push origin feature/AmazingFeature`)
-5. Open a Pull Request
+3. Make your changes
+4. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
+5. Push to the branch (`git push origin feature/AmazingFeature`)
+6. **Important:** Open a Pull Request against the `dev` branch, not the `main` branch
+
+We prefer all pull requests to be submitted against the `dev` branch for easier testing and integration before releasing to the main branch.

{local_deep_research-0.1.20.dist-info → local_deep_research-0.1.21.dist-info}/RECORD

@@ -8,7 +8,7 @@ local_deep_research/defaults/__init__.py,sha256=2Vvlkl-gmP_qPYWegE4JBgummypogl3V
 local_deep_research/defaults/llm_config.py,sha256=7wTIugVYD_ypG7Xwvu3DBt0yO8TWBf_drOIQOSOkdQQ,9628
 local_deep_research/defaults/local_collections.toml,sha256=zNa03PVnFrZ757JdZOuW6QDxkOc6ep5tG8baGBrMmXM,1778
 local_deep_research/defaults/main.toml,sha256=6Lzbc5sVLxMwu83bLBp_tpYOZgmtThCfPL1L42eTGro,1939
-local_deep_research/defaults/search_engines.toml,sha256=TYkOqVaZq9JPawz4fIPyGdkAtYa4t8F9H50VY-wv2ak,8101
+local_deep_research/defaults/search_engines.toml,sha256=g0-qrw10oMgW74z_lYpPDkGwMje25mvalfY1EJ0nL3g,8134
 local_deep_research/utilties/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 local_deep_research/utilties/enums.py,sha256=TVAZiu9szNbdacfb7whgaQJJlSk7oYByADaAierD4CE,229
 local_deep_research/utilties/llm_utils.py,sha256=IGv-_gJWqLTpO3_op1NHIwxKaFEzmXhhVYSLTTSMnIA,4522
@@ -50,9 +50,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.20.dist-info/licenses/LICENSE,sha256=Qg2CaTdu6SWnSqk1_JtgBPp_Da-LdqJDhT1Vt1MUc5s,1072
-local_deep_research-0.1.20.dist-info/METADATA,sha256=29URKDSkO8eCFRa5NkCoPIZ_lHYH5xOeK8ORQp5-v6k,15608
-local_deep_research-0.1.20.dist-info/WHEEL,sha256=DK49LOLCYiurdXXOXwGJm6U4DkHkg4lcxjhqwRa0CP4,91
-local_deep_research-0.1.20.dist-info/entry_points.txt,sha256=u-Y6Z3MWtR3dmsTDFYhXyfkPv7mALUA7YAnY4Fi1XDs,97
-local_deep_research-0.1.20.dist-info/top_level.txt,sha256=h6-uVE_wSuLOcoWwT9szhX23mBWufu77MqmM25UfbCY,20
-local_deep_research-0.1.20.dist-info/RECORD,,
+local_deep_research-0.1.21.dist-info/licenses/LICENSE,sha256=Qg2CaTdu6SWnSqk1_JtgBPp_Da-LdqJDhT1Vt1MUc5s,1072
+local_deep_research-0.1.21.dist-info/METADATA,sha256=wmEq00-MvscM4aUEqNZWCmNa4ytEAfiBvljEx3px5DQ,16405
+local_deep_research-0.1.21.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
+local_deep_research-0.1.21.dist-info/entry_points.txt,sha256=u-Y6Z3MWtR3dmsTDFYhXyfkPv7mALUA7YAnY4Fi1XDs,97
+local_deep_research-0.1.21.dist-info/top_level.txt,sha256=h6-uVE_wSuLOcoWwT9szhX23mBWufu77MqmM25UfbCY,20
+local_deep_research-0.1.21.dist-info/RECORD,,

{local_deep_research-0.1.20.dist-info → local_deep_research-0.1.21.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (78.0.2)
+Generator: setuptools (78.1.0)
 Root-Is-Purelib: true
 Tag: py3-none-any