~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
"""
HTTP Client for Local Deep Research API.
Simplifies authentication and API access by handling CSRF tokens automatically.
This client allows you to programmatically interact with the Local Deep Research (LDR)
application, enabling seamless integration with Python scripts and applications.
It handles all the complexity of authentication, session management, and request formatting.
Why CSRF with login?
--------------------
CSRF tokens prevent cross-site request forgery attacks. Even though you're logged in,
CSRF ensures requests come from YOUR code, not from malicious websites that might
try to use your browser's active session cookies to make unauthorized requests.
Features:
---------
- Automatic login and session management
- CSRF token handling
- Research query submission and result retrieval
- User settings management
- Research history access
Example usage:
-------------
from local_deep_research.api.client import LDRClient
# Simple usage
client = LDRClient()
client.login("username", "password")
result = client.quick_research("What is quantum computing?")
print(result["summary"])
# With context manager (auto-logout)
with LDRClient() as client:
client.login("username", "password")
result = client.quick_research("What is quantum computing?")
print(result["summary"])
# Get research history
with LDRClient() as client:
client.login("username", "password")
history = client.get_history()
for item in history:
print(f"Research: {item['query']}")
# One-liner for quick queries
from local_deep_research.api.client import quick_query
summary = quick_query("username", "password", "What is DNA?")
# Update user settings
with LDRClient() as client:
client.login("username", "password")
client.update_setting("llm.model", "gemma:7b")
settings = client.get_settings()
print(f"Current model: {settings['llm']['model']}")
"""
import time
from typing import Any
from ..constants import ResearchStatus
from loguru import logger
from local_deep_research.benchmarks.comparison.results import Benchmark_results
from local_deep_research.security import SafeSession
class LDRClient:
"""
HTTP client for LDR API access with automatic CSRF handling.
This client abstracts away the complexity of:
- Extracting CSRF tokens from HTML forms
- Managing session cookies
- Handling authentication flow
- Polling for research results
"""
def __init__(self, base_url: str = "http://localhost:5000"):
"""
Initialize the client.
Args:
base_url: URL of the LDR server (default: http://localhost:5000)
"""
self.base_url = base_url
# Use SafeSession with allow_localhost since client connects to local LDR server
self.session = SafeSession(allow_localhost=True)
self.csrf_token = None
self.logged_in = False
self.username = None
def login(self, username: str, password: str) -> bool:
"""
Login to LDR server. Handles all CSRF complexity internally.
This method:
1. Gets the login page to extract CSRF token from HTML form
2. Submits login with form data (not JSON)
3. Retrieves CSRF token for subsequent API calls
Args:
username: Your LDR username
password: Your LDR password
Returns:
True if login successful, False otherwise
"""
try:
# Step 1: Get login page to extract CSRF token
# We need to parse HTML because Flask-WTF embeds CSRF in forms
login_page = self.session.get(f"{self.base_url}/auth/login")
# Simple CSRF extraction without BeautifulSoup dependency
# Look for: <input type="hidden" name="csrf_token" value="..."/>
import re
csrf_match = re.search(
r'<input[^>]*name="csrf_token"[^>]*value="([^"]*)"',
login_page.text,
)
if not csrf_match:
logger.error("Could not find CSRF token in login page")
return False
login_csrf = csrf_match.group(1)
# Step 2: Login with form data (NOT JSON!)
# Flask-WTF expects form-encoded data for login
response = self.session.post(
f"{self.base_url}/auth/login",
data={
"username": username,
"password": password,
"csrf_token": login_csrf,
},
allow_redirects=True,
)
if response.status_code not in [200, 302]:
logger.error(
f"Login failed with status: {response.status_code}"
)
return False
# Step 3: Get CSRF token for API requests
# This uses our new endpoint that returns JSON
csrf_response = self.session.get(f"{self.base_url}/auth/csrf-token")
if csrf_response.status_code == 200:
self.csrf_token = csrf_response.json()["csrf_token"]
self.logged_in = True
self.username = username
logger.info(f"Successfully logged in as {username}")
return True
logger.warning("Logged in but could not get API CSRF token")
# Still logged in, just no CSRF for API calls
self.logged_in = True
self.username = username
return True
except Exception:
logger.exception("Login error")
return False
def _api_headers(self) -> dict[str, str]:
"""Get headers with CSRF token for API requests."""
if self.csrf_token:
return {"X-CSRF-Token": self.csrf_token}
return {}
def quick_research(
self,
query: str,
model: str | None = None,
search_engines: list[str] | None = None,
iterations: int = 2,
wait_for_result: bool = True,
timeout: int = 300,
) -> dict[str, Any]:
"""
Research a topic using LLMs and search engines.
This method runs a research process on your query using search engines
and large language models. It might take a few minutes to complete.
Args:
query: Your research question
model: LLM model to use (e.g., "gemma:7b", "llama2:7b")
search_engines: Search engines to use (default: ["searxng"])
iterations: How many research cycles to run (default: 2)
wait_for_result: If True, wait until done. If False, return immediately
timeout: Maximum seconds to wait (default: 300)
Returns:
If waiting for result: Dict with summary, sources, and findings
If not waiting: Dict with research_id to check status later
Raises:
RuntimeError: If not logged in or request fails
Example:
result = client.quick_research("Latest developments in fusion energy")
print(result["summary"])
"""
if not self.logged_in:
raise RuntimeError("Not logged in. Call login() first.")
# Default search engines
if search_engines is None:
search_engines = ["searxng"]
# Start research
response = self.session.post(
f"{self.base_url}/api/start_research",
json={
"query": query,
"model": model,
"search_engines": search_engines,
"iterations": iterations,
"questions_per_iteration": 3,
},
headers=self._api_headers(),
)
# Handle response
if response.status_code != 200:
# Try to extract error message
try:
error_data = response.json()
if isinstance(error_data, list) and len(error_data) > 0:
error_msg = error_data[0].get("message", "Unknown error")
else:
error_msg = str(error_data)
except (ValueError, KeyError, AttributeError):
error_msg = response.text[:200]
raise RuntimeError(f"Failed to start research: {error_msg}")
result = response.json()
research_id = result.get("research_id")
if not research_id:
raise RuntimeError("No research ID returned")
if not wait_for_result:
return {"research_id": research_id}
# Poll for results
return self.wait_for_research(research_id, timeout)
def wait_for_research(
self, research_id: str, timeout: int = 300
) -> dict[str, Any]:
"""
Wait for research to complete and get results.
Use this after starting research with quick_research(wait_for_result=False).
Checks status every 5 seconds until complete or timeout.
Args:
research_id: ID of the research to wait for
timeout: Maximum seconds to wait (default: 300)
Returns:
Dict with research results (summary, sources, findings)
Raises:
RuntimeError: If research fails or times out
Example:
# Start research without waiting
resp = client.quick_research("Climate change impacts", wait_for_result=False)
# Get results when ready
results = client.wait_for_research(resp["research_id"])
"""
start_time = time.time()
while time.time() - start_time < timeout:
status_response = self.session.get(
f"{self.base_url}/api/research/{research_id}/status"
)
if status_response.status_code == 200:
status = status_response.json()
if status.get("status") == ResearchStatus.COMPLETED:
# Get final results
results_response = self.session.get(
f"{self.base_url}/api/report/{research_id}"
)
if results_response.status_code == 200:
return results_response.json()
raise RuntimeError("Failed to get results")
if status.get("status") == ResearchStatus.FAILED:
error_msg = status.get("error", "Unknown error")
raise RuntimeError(f"Research failed: {error_msg}")
time.sleep(5)
raise RuntimeError(f"Research timed out after {timeout} seconds")
def get_settings(self) -> dict[str, Any]:
"""Get current user settings."""
if not self.logged_in:
raise RuntimeError("Not logged in. Call login() first.")
response = self.session.get(f"{self.base_url}/settings/api")
if response.status_code == 200:
return response.json()
raise RuntimeError(f"Failed to get settings: {response.status_code}")
def update_setting(self, key: str, value: Any) -> bool:
"""
Update a setting.
Args:
key: Setting key (e.g., "llm.model")
value: New value for the setting
Returns:
True if successful
"""
if not self.logged_in:
raise RuntimeError("Not logged in. Call login() first.")
response = self.session.put(
f"{self.base_url}/settings/api/{key}",
json={"value": value},
headers=self._api_headers(),
)
return response.status_code == 200
def get_history(self) -> list[dict[str, Any]]:
"""
Get your past research queries.
Returns a list of previous research sessions with their details.
Returns:
List of research items with query, timestamp, and status info
Raises:
RuntimeError: If not logged in
Example:
history = client.get_history()
for item in history[:5]:
print(f"{item['timestamp']}: {item['query']}")
"""
if not self.logged_in:
raise RuntimeError("Not logged in. Call login() first.")
response = self.session.get(f"{self.base_url}/history/api")
if response.status_code == 200:
data = response.json()
# Handle different response formats
if isinstance(data, dict):
return data.get("history", data.get("items", []))
if isinstance(data, list):
return data
return []
raise RuntimeError(f"Failed to get history: {response.status_code}")
def logout(self):
"""Logout and clear session."""
if self.logged_in:
self.session.post(
f"{self.base_url}/auth/logout", headers=self._api_headers()
)
self.session.close()
self.csrf_token = None
self.logged_in = False
self.username = None
def submit_benchmark(
self,
model,
hardware,
accuracy_focused,
accuracy_source,
avg_time_per_question,
context_window,
temperature,
ldr_version,
date_tested,
notes="",
):
"""
Submit your benchmark results to help the community.
Args:
model: Model name (e.g., "Llama-3.3-70B-Q4_K_M")
hardware: Hardware specs (e.g., "RTX 4090 24GB")
accuracy_focused: Accuracy percentage for focused strategy
accuracy_source: Accuracy percentage for source-based strategy
avg_time_per_question: Average time per question in seconds
context_window: Context window size used
temperature: Temperature setting used
ldr_version: Version of LDR used (e.g., "0.6.0")
date_tested: Date tested (YYYY-MM-DD format)
notes: Optional notes about the test
Returns:
True if submission was successful
Example:
client.submit_benchmark(
"Llama-3.3-70B-Q4_K_M", "RTX 4090 24GB",
87.0, 82.0, 45.2, 32000, 0.1, "0.6.0", "2024-01-15"
)
"""
benchmarks = Benchmark_results()
return benchmarks.add_result(
model,
hardware,
accuracy_focused,
accuracy_source,
avg_time_per_question,
context_window,
temperature,
ldr_version,
date_tested,
notes,
)
def get_benchmarks(self, best_only=False):
"""
Get community benchmark results.
Args:
best_only: If True, only return top performers
Returns:
List of benchmark results
Example:
all_results = client.get_benchmarks()
top_results = client.get_benchmarks(best_only=True)
"""
benchmarks = Benchmark_results()
if best_only:
return benchmarks.get_best()
return benchmarks.get_all()
def __enter__(self):
"""Support context manager for auto-cleanup."""
return self
def __exit__(self, exc_type, exc_val, exc_tb):
"""Auto logout when used as context manager."""
self.logout()
# Convenience functions for simple use cases
def quick_query(
username: str,
password: str,
query: str,
base_url: str = "http://localhost:5000",
) -> str:
"""
One-liner for quick research queries.
Example:
summary = quick_query("user", "pass", "What is DNA?")
print(summary)
Args:
username: LDR username
password: LDR password
query: Research question
base_url: Server URL
Returns:
Research summary as string
"""
with LDRClient(base_url) as client:
if not client.login(username, password):
raise RuntimeError("Login failed")
result = client.quick_research(query)
return result.get("summary", "No summary available")