Skip to content

~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.

15.2 KB
Raw Blame

Migration Guide: LDR v0.x to v1.0

Overview

Local Deep Research v1.0 introduces significant security and architectural improvements:

  • User Authentication: All access now requires authentication
  • Per-User Encrypted Databases: Each user has their own encrypted SQLCipher database
  • Settings Snapshots: Thread-safe settings management for concurrent operations
  • New API Structure: Reorganized endpoints under router prefixes

Breaking Changes

1. Authentication Required

v0.x: Open access, no authentication

# Direct API access
from local_deep_research.api import quick_summary
result = quick_summary("query")

v1.0: Authentication required

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

# Must authenticate first
with get_user_db_session(username="user", password="pass") as session:
    settings_manager = SettingsManager(session)
    settings_snapshot = settings_manager.get_all_settings()

    result = quick_summary(
        "query",
        settings_snapshot=settings_snapshot  # Required parameter
    )

2. HTTP API Changes

Endpoint Structure

  • v0.x: /api/v1/quick_summary
  • v1.0: /api/start_research

Authentication Flow

import requests

# v1.0 requires session-based authentication
session = requests.Session()

# 1. Login
session.post(
    "http://localhost:5000/auth/login",
    json={"username": "user", "password": "pass"}
)

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

# 3. Make API requests with CSRF token
response = session.post(
    "http://localhost:5000/api/start_research",
    json={"query": "test"},
    headers={"X-CSRF-Token": csrf}
)

3. Database Changes

v0.x

  • Single shared database: ldr.db
  • No encryption
  • Direct database access from any thread

v1.0

  • Per-user databases: encrypted_databases/{username}.db
  • SQLCipher encryption with user passwords
  • Thread-local session management
  • In-memory queue tracking (no more service_db)

4. Settings Management

v0.x

# Direct settings access
from local_deep_research.config import get_db_setting
value = get_db_setting("llm.provider")

v1.0

# Settings require context
from local_deep_research.settings import SettingsManager

# Within authenticated session
settings_manager = SettingsManager(session)
value = settings_manager.get_setting("llm.provider")

# Or use settings snapshot for thread safety
settings_snapshot = settings_manager.get_all_settings()

Migration Steps

1. Update Dependencies

pip install --upgrade local-deep-research

2. Create User Accounts

Users must create accounts through the web interface:

  1. Start the server: python -m local_deep_research.web.app
  2. Open http://localhost:5000
  3. Click "Register" and create an account
  4. Configure LLM providers and API keys in Settings

3. Update Programmatic Code

Before (v0.x):

from local_deep_research.api import (
    quick_summary,
    detailed_research,
    generate_report
)

# Direct usage
result = quick_summary("What is AI?")

After (v1.0):

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

def run_research(username, password, query):
    with get_user_db_session(username, password) as session:
        settings_manager = SettingsManager(session)
        settings_snapshot = settings_manager.get_all_settings()

        return quick_summary(
            query=query,
            settings_snapshot=settings_snapshot,
            # Other parameters remain the same
            iterations=2,
            questions_per_iteration=3
        )

4. Update HTTP API Calls

Create a wrapper for authenticated requests:

class LDRClient:
    def __init__(self, base_url="http://localhost:5000"):
        self.base_url = base_url
        self.session = requests.Session()
        self.csrf_token = None

    def login(self, username, password):
        response = self.session.post(
            f"{self.base_url}/auth/login",
            json={"username": username, "password": password}
        )
        if response.status_code == 200:
            self.csrf_token = self.session.get(
                f"{self.base_url}/auth/csrf-token"
            ).json()["csrf_token"]
        return response

    def start_research(self, query, **kwargs):
        return self.session.post(
            f"{self.base_url}/api/start_research",
            json={"query": query, **kwargs},
            headers={"X-CSRF-Token": self.csrf_token}
        )

# Usage
client = LDRClient()
client.login("user", "pass")
result = client.start_research("What is quantum computing?")

5. Update Configuration

API Keys

API keys are now stored encrypted in per-user databases. Users must:

  1. Login to the web interface
  2. Go to Settings
  3. Re-enter API keys for LLM providers

Custom LLMs

Custom LLM registrations now require settings context:

# v1.0 custom LLM with settings support
def create_custom_llm(model_name=None, temperature=None, settings_snapshot=None):
    # Access settings from snapshot if needed
    api_key = settings_snapshot.get("llm.custom.api_key", {}).get("value")
    return CustomLLM(api_key=api_key, model=model_name, temperature=temperature)

Common Issues and Solutions

Issue: "No settings context available in thread"

Solution: Pass settings_snapshot parameter to all API calls

Issue: "Encrypted database requires password"

Solution: Ensure you're using get_user_db_session() with credentials

Issue: CSRF token errors

Solution: Get fresh CSRF token before state-changing requests

Issue: Old endpoints return 404

Solution: Update to new endpoint structure (see mapping above)

Issue: Rate limiting not working

Solution: Rate limits are now per-user; ensure proper authentication

Backward Compatibility

For temporary backward compatibility, you can:

  1. Set environment variable: LDR_USE_SHARED_DB=1 (not recommended)
  2. Create a compatibility wrapper for your existing code
# compatibility.py
import os
os.environ["LDR_USE_SHARED_DB"] = "1"  # Use at your own risk

def quick_summary_compat(query, **kwargs):
    # Minimal compatibility wrapper
    # Note: This bypasses security features!
    from local_deep_research.api import quick_summary
    return quick_summary(query, settings_snapshot={}, **kwargs)

⚠️ Warning: Compatibility mode bypasses security features and is not recommended for production use.

Benefits of v1.0

  1. Security: Encrypted databases protect sensitive API keys and research data
  2. Multi-User: Multiple users can work simultaneously without conflicts
  3. Performance: Cached settings and thread-local sessions improve speed
  4. Reliability: Thread-safe operations prevent race conditions
  5. Privacy: User data is completely isolated

Upgrading to the FastAPI-based Release (Phase 1)

The server has migrated from Flask + Werkzeug to FastAPI + uvicorn. The sections below highlight the changes most likely to affect an interactive user. They are not the complete operator checklist, and several are permanent contract changes rather than one-time upgrade effects. Before upgrading, read the upgrade and rollback guide for the backup, verification and rollback procedure, and changelog.d/3299.breaking.md for the full list and client/API migration details.

You will need to log in again

Flask and Starlette (FastAPI's session middleware) sign session cookies using different itsdangerous schemes, so the session cookie your browser holds from the Flask version is not readable by the new server. You will be redirected to the login page on first visit and must re-enter your password. Your data is not affected — only the browser session.

Default bind address is now 127.0.0.1

Prior Flask-era releases bound to 0.0.0.0 (all interfaces) by default, which silently exposed the server to the LAN or public internet. The new default is 127.0.0.1 (localhost only). To expose the server to other machines — for example a home server — set the environment variable LDR_WEB_HOST=0.0.0.0 explicitly. Docker users are unaffected: the Dockerfile sets this env var automatically so container port mapping still works.

Reverse proxies must opt in to forwarded request metadata

Set TRUST_PROXY_HEADERS=true when TLS terminates at a trusted reverse proxy. Without it, uvicorn keeps the request scheme as HTTP, so secure-cookie, HSTS, and WebSocket same-origin behaviour will be wrong. Client-IP extraction for rate limiting follows a separate rule, so a single proxy must overwrite forwarded client-IP headers even when this variable is unset. Behind a chain of proxies (CDN → nginx) the default settings key every client on the outer proxy's address, so all clients share one rate-limit bucket: either have the inner proxy resolve the real client itself (nginx realip) and overwrite with that address, or make every inner proxy append and set a multi-hop setting — see Proxy chains. Use the hardened examples in Reverse proxy configuration.

With TRUST_PROXY_HEADERS=true, also set LDR_SERVER_FORWARDED_ALLOW_IPS to your reverse proxy's IP address(es) as LDR sees them — every hop, for a chain whose inner proxies append. For LDR in Docker behind a proxy on the host, that is the Docker network's gateway, not 127.0.0.1 (see Reverse proxy configuration). It defaults to * (every peer, the value LDR used before), which keeps booting but logs a warning, because a client that reaches LDR directly can then forge X-Forwarded-For. Two cases need action:

  • Your proxy connects from a public or carrier-grade-NAT address and sends X-Real-IP without X-Forwarded-For (a cloud load balancer, a Tailscale 100.64.x.x peer, a public nginx host). Without a restricted LDR_SERVER_FORWARDED_ALLOW_IPS, X-Real-IP is honoured only from a private, loopback or link-local peer; once a restricted list is set, ONLY listed peers are trusted, so list the proxy that connects to LDR even if its address is private (and, for a chain, see Proxy chains). Without that, every client shares one rate-limit bucket and the login and registration lockouts apply to everyone at once. Set LDR_SERVER_FORWARDED_ALLOW_IPS to that proxy's IP address as LDR sees it, or have a single proxy overwrite X-Forwarded-For with the address it observed ($remote_addr), never pass a client-sent one through. Without TRUST_PROXY_HEADERS, only LDR_SERVER_FORWARDED_ALLOW_IPS helps: a public-address proxy's X-Forwarded-For is ignored too.
  • You set LDR_SERVER_TRUSTED_PROXY_COUNT or an explicit LDR_SERVER_FORWARDED_ALLOW_IPS while the allow-list still trusts every peer (*, 0.0.0.0/0, ...). LDR refuses to start, because that combination is always exploitable. List your proxy's real IP(s) instead.

The previous behaviour (trusting X-Real-IP from any peer) cannot be turned back on: it let any client choose its own rate-limit bucket.

The Socket.IO endpoint moved to /ws/socket.io

The Socket.IO server is now an ASGI sub-app mounted at /ws (app.mount("/ws", socket_app) in web/fastapi_app.py), and it is served under the path /ws/socket.io (socketio_path="/ws/socket.io" in web/services/socketio_asgi.py). The bundled UI already connects with path: '/ws/socket.io'. If you wrote your own Socket.IO client, or if your reverse proxy has an explicit location block for the old default /socket.io path, update it — see Reverse proxy configuration.

WebSocket cross-origin default is unchanged

LDR_SECURITY_WEBSOCKET_ALLOWED_ORIGINS behaves exactly as before: unset means same-origin only. Set it explicitly if you need cross-origin WS access (rare).

An earlier version of this section said the default was "tightened" from "*" to same-origin. That was wrong — the previous release's web/services/socket_service.py already fell through to a same-origin allowlist when the variable was unset. Nothing about origin policy changed in this migration; only the transport moved.

Session cookies explicitly use SameSite=Lax

Following a top-level link from another site preserves the authenticated session. Cross-site unsafe requests do not carry the cookie, and unsafe methods also require the session CSRF token. That token does not help when a page's own script makes the request, and a link from another site can open any page signed in. So GET routes must not change state, and page-load scripts must not turn URL parameters into state-changing requests.

  • Model discovery and refresh require POST; ordinary model-list GET requests only read cached models, including when the cache is empty or expired.
  • A /chat/?q=<text> link no longer sends anything by itself. Earlier versions could send the query and start a research run as soon as the page loaded. Now q only pre-fills the chat box of a new chat, or of a chat with no messages yet, without focusing it, and nothing is sent until the user presses Send; an auto-repeated Enter from a key that was already held down does not send. In addition, when the browser's Sec-Fetch-Site header says the link came from another origin (cross-site or same-site; browsers send the header to HTTPS and localhost origins), the server redirects to the same page without q. The login page drops q from a chat page in its next parameter, whatever the header says, both in the form it renders and in the redirect after signing in. A typed or bookmarked URL, or a link opened from another app such as a mail or chat client, arrives with Sec-Fetch-Site: none and keeps q, as does any link to a plain-HTTP address other than localhost, where browsers send no Sec-Fetch-Site; for a signed-in user such a link pre-fills the chat box. Chat mode on the main page submits its message through the protected API before opening its clean chat URL, so one submit still starts the chat. Queries are not staged in browser storage.

The cookie policy is explicitly set to same_site="lax" where SessionMiddleware is installed (web/fastapi_app.py); it is not a setting or environment variable.

Graceful shutdown timeout is bounded (10 s)

uvicorn.run(timeout_graceful_shutdown=10) — in-flight SSE streams are closed after 10 seconds when the server receives SIGTERM/SIGINT, rather than blocking indefinitely. This is currently hardcoded — there is no setting or environment variable to lengthen the drain window. If you run very long single-request operations and need one, please open an issue.

Getting Help