local-deep-research/examples/api_usage/README.md

Local Deep Research API Examples

This directory contains examples for using LDR through different interfaces.

Important: Authentication Required (v2.0+)

Since LDR v2.0, all API access requires authentication due to per-user encrypted databases. You must:

1. Create a user account through the web interface
2. Authenticate before making API calls
3. Pass settings_snapshot for programmatic access

Directory Structure

• programmatic/ - Direct Python API usage (import from local_deep_research.api)

  • programmatic_access.ipynb - Jupyter notebook with comprehensive examples
  • retriever_usage_example.py - Using LangChain retrievers with LDR

• http/ - HTTP REST API usage (requires running server)

  • simple_working_example.py - ✅ BEST WORKING EXAMPLE - Clean, tested, and ready to use
  • simple_http_example.py - Quick start example (needs updating for auth)
  • http_api_examples.py - Comprehensive examples including batch processing

Quick Start

Programmatic API (Python Package)

from local_deep_research.api import quick_summary
from local_deep_research.settings import SettingsManager
from local_deep_research.database.session_context import get_user_db_session

# Authenticate and get settings
with get_user_db_session(username="your_username", password="your_password") as session:
    settings_manager = SettingsManager(session)
    settings_snapshot = settings_manager.get_all_settings()

    # Use the API
    result = quick_summary(
        "What is quantum computing?",
        settings_snapshot=settings_snapshot
    )
    print(result["summary"])

HTTP API (REST)

🎯 Quick Start - Works Completely Out of the Box!

Our tested working example requires zero manual setup:

# 1. Start the server
python -m local_deep_research.web.app

# 2. Run the working example (creates user automatically!)
python examples/api_usage/http/simple_working_example.py

# 3. Done! ✅ No other steps required

The example will:

• ✅ Create a unique test user automatically
• ✅ Test authentication with proper CSRF handling
• ✅ Execute a research query using the correct API endpoint
• ✅ Provide credentials for manual testing (if desired)
• ✅ Show results with direct links to view them

📋 Manual API Usage:

If you want to integrate the API into your own code:

import requests
from bs4 import BeautifulSoup

# Create session for cookie persistence
session = requests.Session()

# Login - get CSRF token first
login_page = session.get("http://localhost:5000/auth/login")
soup = BeautifulSoup(login_page.text, 'html.parser')
csrf_input = soup.find('input', {'name': 'csrf_token'})
login_csrf = csrf_input.get('value')

# Login with form data
session.post(
    "http://localhost:5000/auth/login",
    data={
        "username": "your_username",
        "password": "your_password",
        "csrf_token": login_csrf
    }
)

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

# Make API request
response = session.post(
    "http://localhost:5000/api/start_research",
    json={"query": "What is quantum computing?"},
    headers={"X-CSRF-Token": csrf_token, "Content-Type": "application/json"}
)
print(response.json())

⚠️ Important Notes:

• Use the correct endpoint: /api/start_research (not /research/api/start)
• Login with form data (not JSON)
• Handle CSRF tokens properly
• User must be created through web interface first

Which API Should I Use?

• Programmatic API: Use when integrating LDR into your Python application

  • ✅ Direct access, no HTTP overhead
  • ✅ Full access to all features and parameters
  • ✅ Can pass Python objects (like LangChain retrievers)
  • ❌ Requires LDR to be installed in your environment
  • ❌ Requires database session and settings snapshot

• HTTP API: Use when accessing LDR from other languages or remote systems

  • ✅ Language agnostic - works with any HTTP client
  • ✅ Can run LDR on a separate server
  • ✅ Easy to scale and deploy
  • ❌ Limited to JSON-serializable parameters
  • ❌ Requires running the web server
  • ❌ Requires authentication and CSRF tokens

API Changes in v2.0

Breaking Changes

1. Authentication Required: All endpoints now require login
2. Settings Snapshot: Programmatic API needs settings_snapshot parameter
3. New Endpoints: API routes moved (e.g., /api/v1/quick_summary → /api/start_research)
4. CSRF Protection: POST/PUT/DELETE requests need CSRF token

Migration Guide

Old (v1.x):

# Programmatic
from local_deep_research.api import quick_summary
result = quick_summary("query")

# HTTP
curl -X POST http://localhost:5000/api/v1/quick_summary \
  -d '{"query": "test"}'

New (v2.0+):

# Programmatic - with authentication and settings
with get_user_db_session(username, password) as session:
    settings_manager = SettingsManager(session)
    settings_snapshot = settings_manager.get_all_settings()
    result = quick_summary("query", settings_snapshot=settings_snapshot)

# HTTP - with authentication and CSRF
# See examples above

Running the Examples

Prerequisites

1. Install LDR: pip install local-deep-research
2. Create a user account:
   • Start server: python -m local_deep_research.web.app
   • Open http://localhost:5000 and register
3. Configure your LLM provider in settings

Programmatic Examples

# Update credentials in the example files first!
python examples/api_usage/programmatic/retriever_usage_example.py

# Or use the Jupyter notebook
jupyter notebook examples/api_usage/programmatic/programmatic_access.ipynb

HTTP Examples

# First, start the LDR server
python -m local_deep_research.web.app

# In another terminal, run the examples
# Note: These need to be updated for v2.0 authentication!
python examples/api_usage/http/simple_http_example.py
python examples/api_usage/http/http_api_examples.py

Need Help?

• See the API Quick Start Guide
• Check the FAQ
• Join our Discord for support