~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
#!/usr/bin/env python3
"""
LDR Research Script
Reads a research query from stdin and uses Local Deep Research to find
relevant documentation, sources, and context. Returns JSON with the
research output.
Usage:
# Pipe a query from stdin
echo "What is RAG?" | python scripts/ldr-research.py
# Or pass a file
python scripts/ldr-research.py < query.txt
# With CLI arguments (easier local testing)
python scripts/ldr-research.py --provider openrouter --model gpt-4o < query.txt
Output: JSON with research results, sources, and findings.
Environment variables (can be overridden by CLI args):
OPENROUTER_API_KEY - API key for OpenRouter
SERPER_API_KEY - API key for Serper.dev search
LDR_PROVIDER - LLM provider (default: openrouter)
LDR_SEARCH_TOOL - Search tool (default: serper)
LDR_RESEARCH_MODEL - Model name (default: google/gemini-2.0-flash-001 for openrouter)
LDR_STRATEGY - Search strategy (default: langgraph-agent)
Note: This uses the programmatic API and does NOT require a running LDR server.
"""
import argparse
import faulthandler
import json
import os
import sys
# Dump a Python traceback to stderr on SIGABRT/SIGSEGV/SIGFPE/SIGBUS/SIGILL.
faulthandler.enable()
def make_serializable(obj):
"""Convert objects to JSON-serializable format."""
if obj is None:
return None
if isinstance(obj, (str, int, float, bool)):
return obj
if isinstance(obj, dict):
return {k: make_serializable(v) for k, v in obj.items()}
if isinstance(obj, (list, tuple)):
return [make_serializable(item) for item in obj]
# Handle LangChain Document objects
if hasattr(obj, "page_content") and hasattr(obj, "metadata"):
return {
"content": obj.page_content,
"metadata": make_serializable(obj.metadata),
}
# Handle other objects with __dict__
if hasattr(obj, "__dict__"):
return make_serializable(obj.__dict__)
# Fallback to string representation
return str(obj)
def parse_args():
parser = argparse.ArgumentParser(
description="Run LDR research on a query read from stdin"
)
parser.add_argument(
"--provider",
default=os.environ.get("LDR_PROVIDER", "openrouter"),
help="LLM provider (default: openrouter)",
)
parser.add_argument(
"--search-tool",
default=os.environ.get("LDR_SEARCH_TOOL", "serper"),
help="Search tool (default: serper)",
)
parser.add_argument(
"--model",
default=os.environ.get("LDR_RESEARCH_MODEL"),
help="Model name (default: provider's default)",
)
parser.add_argument(
"--iterations",
type=int,
default=None,
help=(
"Number of research iterations. If unset, the strategy uses "
"its own default (e.g. langgraph-agent reads "
"langgraph_agent.max_iterations from settings)."
),
)
parser.add_argument(
"--strategy",
default=os.environ.get("LDR_STRATEGY", "langgraph-agent"),
help="Search strategy name (default: langgraph-agent)",
)
return parser.parse_args()
def main():
# Flush in finally: SIGABRT during interpreter shutdown won't drain the stdout buffer.
try:
args = parse_args()
# Read query from stdin
query = sys.stdin.read().strip()
if not query:
print(json.dumps({"error": "No query provided on stdin"}))
sys.exit(1)
# Default model for OpenRouter if not specified
model_name = args.model
if not model_name and args.provider == "openrouter":
model_name = "google/gemini-2.0-flash-001"
# Check required API keys
if args.provider == "openrouter" and not os.environ.get(
"OPENROUTER_API_KEY"
):
print(json.dumps({"error": "OPENROUTER_API_KEY not set"}))
sys.exit(1)
if args.search_tool == "serper" and not os.environ.get(
"SERPER_API_KEY"
):
print(json.dumps({"error": "SERPER_API_KEY not set"}))
sys.exit(1)
try:
from local_deep_research.api import quick_summary
from local_deep_research.api.settings_utils import (
create_settings_snapshot,
)
# Build settings overrides
overrides = {
"search.tool": args.search_tool,
"llm.provider": args.provider,
}
if model_name:
overrides["llm.model"] = model_name
# Add API keys from environment
if os.environ.get("OPENROUTER_API_KEY"):
overrides["llm.openrouter.api_key"] = os.environ[
"OPENROUTER_API_KEY"
]
if os.environ.get("SERPER_API_KEY"):
overrides["search.engine.web.serper.api_key"] = os.environ[
"SERPER_API_KEY"
]
settings = create_settings_snapshot(overrides=overrides)
# Build kwargs
kwargs = {
"query": query,
"provider": args.provider,
"search_tool": args.search_tool,
"settings_snapshot": settings,
"programmatic_mode": True,
"search_strategy": args.strategy,
}
if model_name:
kwargs["model_name"] = model_name
if args.iterations is not None:
kwargs["iterations"] = args.iterations
result = quick_summary(**kwargs)
# Use formatted_findings if available (already properly formatted with sources)
# Fall back to summary if not
research_output = result.get("formatted_findings") or result.get(
"summary", str(result)
)
# Build output - make sure everything is JSON serializable
output = {
"research": research_output,
"sources": make_serializable(result.get("sources", [])),
"findings": make_serializable(result.get("findings", [])),
"iterations": result.get("iterations"),
}
print(json.dumps(output))
except Exception as e:
message = type(e).__name__
try:
from local_deep_research.security.log_sanitizer import (
sanitize_error_for_client,
scrub_error,
)
secrets = [
os.environ[name]
for name in ("OPENROUTER_API_KEY", "SERPER_API_KEY")
if os.environ.get(name)
]
message = sanitize_error_for_client(scrub_error(e, *secrets))
except Exception: # noqa: silent-exception
pass
print(json.dumps({"error": message}))
sys.exit(1)
finally:
try:
sys.stdout.flush()
except Exception: # noqa: silent-exception
pass
if __name__ == "__main__":
main()