curl -O https://raw.githubusercontent.com/LearningCircuit/local-deep-research/main/docker-compose.yml
docker compose up -d

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor \
  -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt-get update && sudo apt-get install nvidia-container-toolkit -y
sudo systemctl restart docker
nvidia-smi  # verify it worked

curl -O https://raw.githubusercontent.com/LearningCircuit/local-deep-research/main/docker-compose.yml
curl -O https://raw.githubusercontent.com/LearningCircuit/local-deep-research/mai

n/docker-compose.gpu.override.yml docker compose -f docker-compose.yml -f docker-compose.gpu.override.yml up -d

**Option 2: pip (For developers / Python integration)**

Install the package

pip install local-deep-research

Run SearXNG in Docker for search

docker run -d -p 8080:8080 --name searxng searxng/searxng

Install Ollama from https://ollama.ai, then pull a model

ollama pull gemma3:12b

Start the web UI

python -m local_deep_research.web.app

**Important note on encryption:** The pip install does not automatically set up SQLCipher (the AES-256 encrypted database LDR uses for storing your data and API keys). If you hit errors during setup, bypass it for now with:

export LDR_ALLOW_UNENCRYPTED=true

This stores data in plain SQLite. Fine for local dev, not recommended for production or shared setups. Docker handles encryption out of the box.

### Programmatic Integration
**Python API:**

from local_deep_research.api import LDRClient, quick_query

One-liner research

summary = quick_query("username", "password", "What is the current state of Rust async runtimes?") print(summary)

Client for more control

client = LDRClient() client.login("username", "password") result = client.quick_research("Compare FAISS vs Hnswlib for vector search at scale") print(result["summary"])

**HTTP API:**
LDR exposes a REST API with session-based authentication and CSRF protection. The auth flow is a bit verbose but works reliably:

import requests from bs4 import BeautifulSoup

session = requests.Session()

Get CSRF token from login page

login_page = session.get("http://localhost:5000/auth/login") soup = BeautifulSoup(login_page.text, "html.parser") csrf = soup.find("input", {"name": "csrf_token"}).get("value")

Authenticate

session.post("http://localhost:5000/auth/login", data={ "username": "user", "password": "pass", "csrf_token": csrf })

Get API CSRF token

api_csrf = session.get("http://localhost:5000/auth/csrf-token").json()["csrf_token"]

Submit a research query

response = session.post( "http://localhost:5000/api/start_research", json={"query": "What are the tradeoffs between gRPC and REST for internal microservices?"}, headers={"X-CSRF-Token": api_csrf} ) print(response.json())

The repository includes ready-to-run HTTP examples under `examples/api_usage/http/` that handle authentication, retry logic, and progress polling.

### Enterprise / RAG Integration
LDR integrates with existing vector stores via LangChain retrievers, enabling hybrid search across live web results and internal knowledge bases:

from local_deep_research.api import quick_summary

result = quick_summary( query="What are our current deployment procedures for the payments service?", retrievers={"internal_kb": your_langchain_retriever}, search_tool="internal_kb" )

Supported backends include FAISS, Chroma, Pinecone, Weaviate, Elasticsearch, and any LangChain-compatible retriever.

### Search Sources & LLM Configuration
**Free (no API key needed):** arXiv, PubMed, Semantic Scholar, Wikipedia, SearXNG, GitHub, The Guardian, Wikinews, Wayback Machine.
**Premium (API key required):** Tavily, Google (SerpAPI/Programmable Search), Brave Search.
**Local LLMs:** Llama 3, Mistral, Gemma, DeepSeek, and any Ollama-supported model.
**Cloud LLMs:** OpenAI (GPT-4, GPT-4.1-mini), Anthropic (Claude 3), Google (Gemini), 100+ models via OpenRouter.

## Pitfall Guide
1. **SQLCipher Encryption Bypass in pip Install**: The `pip install` path does not auto-configure SQLCipher. Setting `LDR_ALLOW_UNENCRYPTED=true` drops data into plain SQLite, which is acceptable for local development but violates security compliance in production or multi-user environments. Always validate encryption status before deploying to shared infrastructure.
2. **Hardware Constraints for Local LLM Execution**: Running Ollama + SearXNG + LDR concurrently demands significant RAM and VRAM. CPU-only setups will experience severe latency during synthesis loops. A dedicated GPU (8GB+ VRAM recommended) is required for acceptable throughput, and NVIDIA Container Toolkit misconfiguration is a common deployment blocker.
3. **CSRF Token Handling in HTTP API**: The REST API enforces strict CSRF protection. Failing to extract the token from the login page HTML and attach it to subsequent requests will result in `403 Forbidden` errors. Always parse the `<input name="csrf_token">` value and include it in both authentication and research submission headers.
4. **Over-Provisioning for Simple Q&A Workloads**: LDR is engineered for multi-step research synthesis, not conversational Q&A. Routing simple factual queries through the iterative search loop introduces unnecessary latency and resource consumption. Reserve LDR for literature reviews, competitive analysis, and complex technical investigations.
5. **GPU Passthrough & NVIDIA Container Toolkit Configuration**: Docker GPU acceleration requires explicit `--gpus all` flags and proper NVIDIA driver/container toolkit alignment. Mismatched driver versions or missing `nvidia-container-toolkit` packages will cause silent fallback to CPU execution, degrading performance by 10-50x. Verify with `nvidia-smi` inside the container.
6. **Ignoring Zero-Knowledge Password Recovery Limits**: LDR's zero-knowledge architecture means there is no password recovery mechanism. If you lose credentials, the SQLCipher database becomes permanently inaccessible. Implement secure credential management (e.g., HashiCorp Vault, Bitwarden) and maintain encrypted backups of the database volume.

## Deliverables
**📘 Deployment & Architecture Blueprint**
A structured reference covering the LDR service topology (Ollama → SearXNG → LDR Core → SQLCipher), network port mapping, GPU passthrough requirements, and hybrid RAG integration patterns. Includes environment variable matrices for cloud vs. local LLM routing.

**✅ Pre-Flight & Integration Checklist**
- [ ] Verify NVIDIA driver & container toolkit compatibility (Linux/GPU path)
- [ ] Validate SQLCipher encryption initialization or explicitly acknowledge unencrypted fallback
- [ ] Configure SearXNG instance and confirm meta-search endpoint responsiveness
- [ ] Pull target Ollama model and verify VRAM allocation via `ollama ps`
- [ ] Test CSRF token extraction flow before automating HTTP API calls
- [ ] Map LangChain retrievers to internal vector stores (FAISS/Chroma/Pinecone)
- [ ] Establish credential backup strategy aligned with zero-knowledge constraints
- [ ] Run SimpleQA benchmark query to validate synthesis loop & citation accuracy