CVE-2025-57806

@@ -27,8 +27,10 @@ services:
       {%- if cookiecutter.enable_searxng %}
       - LDR_SEARCH_ENGINE_WEB_SEARXNG_DEFAULT_PARAMS_INSTANCE_URL=http://searxng:8080
       {% endif %}
+      # Data directory configuration
+      - LDR_DATA_DIR=/data
     volumes:
-      - ldr_data:/install/.venv/lib/python3.13/site-packages/data/
+      - ldr_data:/data
       - ./local_collections/personal_notes:/local_collections/personal_notes/
       - ./local_collections/project_docs:/local_collections/project_docs/
       - ./local_collections/research_papers:/local_collections/research_papers/
@@ -60,6 +62,8 @@ services:
       timeout: 5s
       start_period: 10m
       retries: 2
+    environment:
+      OLLAMA_KEEP_ALIVE: '30m'
     volumes:
       - ollama_data:/root/.ollama
       - ./scripts/:/scripts/

@@ -1,48 +1,80 @@
-name: 'local-ai'
-
 services:
+  local-deep-research:
+    image: localdeepresearch/local-deep-research
+
+    networks:
+      - ldr-network
+
+    ports:
+      - "5000:5000"
+    environment:
+      # Web Interface Settings
+      - LDR_WEB_PORT=5000
+      - LDR_WEB_HOST=0.0.0.0
+      - LDR_LLM_PROVIDER=ollama
+      - LDR_LLM_OLLAMA_URL=http://ollama:11434
+
+      - LDR_SEARCH_ENGINE_WEB_SEARXNG_DEFAULT_PARAMS_INSTANCE_URL=http://searxng:8080
+
+      # Data directory configuration
+      - LDR_DATA_DIR=/data
+    volumes:
+      - ldr_data:/data
+      - ./local_collections/personal_notes:/local_collections/personal_notes/
+      - ./local_collections/project_docs:/local_collections/project_docs/
+      - ./local_collections/research_papers:/local_collections/research_papers/
+    restart: unless-stopped
+    depends_on:
+      ollama:
+        condition: service_healthy
+
+      searxng:
+        condition: service_started
+
 
   ollama:
-    image: 'ollama/ollama:latest'
-    deploy:
+    image: ollama/ollama:latest
+    deploy: # Remove this section if you do not have an Nvidia GPU.
       resources:
         reservations:
           devices:
             - driver: nvidia
               count: 1
-              capabilities: [gpu]
+              capabilities: [ gpu ]
+
+    container_name: ollama_service
+    entrypoint: [ "/scripts/ollama_entrypoint.sh" ]
+    healthcheck:
+      test: [ "CMD", "ollama", "show", "gemma3:12b" ]
+      interval: 10s
+      timeout: 5s
+      start_period: 10m
+      retries: 2
     environment:
       OLLAMA_KEEP_ALIVE: '30m'
     volumes:
-      - type: 'volume'
-        source: 'ollama'
-        target: '/root/.ollama'
+      - ollama_data:/root/.ollama
+      - ./scripts/:/scripts/
+    networks:
+      - ldr-network
+
+
+    restart: unless-stopped
 
   searxng:
-    image: 'ghcr.io/searxng/searxng:latest'
+    image: searxng/searxng:latest
+    container_name: searxng
+    networks:
+      - ldr-network
 
-  deep-research:
-    image: 'localdeepresearch/local-deep-research:latest'
-    ports:
-      - target: '5000' # port bound by app inside container
-        published: '5000' # port bound on the docker host
-        protocol: 'tcp'
-    environment:
-      LDR_LLM_PROVIDER: 'ollama'
-      LDR_LLM_OLLAMA_URL: 'http://ollama:11434'
-      # change model depending on preference and available VRAM
-      LDR_LLM_MODEL: 'gemma3:12b'
-      LDR_SEARCH_ENGINE_WEB_SEARXNG_DEFAULT_PARAMS_INSTANCE_URL: 'http://searxng:8080'
     volumes:
-      - type: 'volume'
-        source: 'deep-research'
-        target: '/install/.venv/lib/python3.13/site-packages/data/'
-      - type: 'volume'
-        source: 'deep-research-outputs'
-        target: '/install/.venv/lib/python3.13/research_outputs'
+      - searxng_data:/etc/searxng
+    restart: unless-stopped
 
 
 volumes:
-  ollama:
-  deep-research:
-  deep-research-outputs:
+  ldr_data:
+  ollama_data:
+  searxng_data:
+networks:
+  ldr-network:

@@ -1,7 +1,13 @@
 ####
 # Used for building the LDR service dependencies.
 ####
-FROM python:3.13.2-slim AS builder
+FROM python:3.12.8-slim AS builder-base
+
+# Install system dependencies for SQLCipher
+RUN apt-get update && apt-get install -y \
+    libsqlcipher-dev \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
 
 # Install dependencies and tools
 RUN pip3 install --upgrade pip && pip install pdm playwright
@@ -15,14 +21,110 @@ COPY src/ src
 COPY LICENSE LICENSE
 COPY README.md README.md
 
+####
+# Builds the LDR service dependencies used in production.
+####
+FROM builder-base AS builder
+
 # Install the package using PDM
 RUN pdm install --check --prod --no-editable
 
 
+####
+# Container for running tests.
+####
+FROM builder-base AS ldr-test
+
+# Install runtime dependencies for SQLCipher, Node.js, and testing tools
+RUN apt-get update && apt-get install -y \
+    sqlcipher \
+    libsqlcipher0 \
+    curl \
+    xauth \
+    xvfb \
+    # Dependencies for Chromium
+    fonts-liberation \
+    libasound2 \
+    libatk-bridge2.0-0 \
+    libatk1.0-0 \
+    libatspi2.0-0 \
+    libcups2 \
+    libdbus-1-3 \
+    libdrm2 \
+    libgbm1 \
+    libgtk-3-0 \
+    libnspr4 \
+    libnss3 \
+    libxcomposite1 \
+    libxdamage1 \
+    libxfixes3 \
+    libxkbcommon0 \
+    libxrandr2 \
+    xdg-utils \
+    && curl -fsSL https://deb.nodesource.com/setup_lts.x | bash - \
+    && apt-get install -y nodejs \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set up Puppeteer environment
+ENV PUPPETEER_CACHE_DIR=/app/puppeteer-cache
+ENV DOCKER_ENV=true
+# Don't skip Chrome download - let Puppeteer download its own Chrome as fallback
+# ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
+
+# Create puppeteer cache directory with proper permissions
+RUN mkdir -p /app/puppeteer-cache && chmod -R 777 /app/puppeteer-cache
+
+# Install Playwright with Chromium first (before npm packages)
+RUN playwright install --with-deps chromium || echo "Playwright install failed, will use Puppeteer's Chrome"
+
+# Copy test package files
+COPY tests/api_tests_with_login/package.json /install/tests/api_tests_with_login/
+COPY tests/ui_tests/package.json /install/tests/ui_tests/
+
+# Install npm packages - Skip Puppeteer Chrome download since we have Playwright's Chrome
+WORKDIR /install/tests/api_tests_with_login
+ENV PUPPETEER_SKIP_DOWNLOAD=true
+ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
+RUN npm install
+WORKDIR /install/tests/ui_tests
+RUN npm install
+
+# Set CHROME_BIN to help Puppeteer find Chrome from Playwright
+# Try to find and set Chrome binary path from Playwright's installation
+RUN CHROME_PATH=$(find /root/.cache/ms-playwright -name chrome -type f 2>/dev/null | head -1) && \
+    if [ -n "$CHROME_PATH" ]; then \
+        echo "export CHROME_BIN=$CHROME_PATH" >> /etc/profile.d/chrome.sh; \
+        echo "export PUPPETEER_EXECUTABLE_PATH=$CHROME_PATH" >> /etc/profile.d/chrome.sh; \
+    fi || true
+
+# Set environment variables for Puppeteer to use Playwright's Chrome
+ENV PUPPETEER_SKIP_DOWNLOAD=true
+ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
+ENV PUPPETEER_EXECUTABLE_PATH=/root/.cache/ms-playwright/chromium-1181/chrome-linux/chrome
+
+# Copy test files to /app where they will be run from
+RUN mkdir -p /app && cp -r /install/tests /app/
+
+# Ensure Chrome binaries have correct permissions
+RUN chmod -R 755 /app/puppeteer-cache
+
+WORKDIR /install
+
+# Install the package using PDM
+RUN pdm install --check --no-editable
+# Configure path to default to the venv python.
+ENV PATH="/install/.venv/bin:$PATH"
+
 ####
 # Runs the LDR service.
 ###
-FROM python:3.13.2-slim AS ldr
+FROM python:3.12.8-slim AS ldr
+
+# Install runtime dependencies for SQLCipher
+RUN apt-get update && apt-get install -y \
+    sqlcipher \
+    libsqlcipher0 \
+    && rm -rf /var/lib/apt/lists/*
 
 # retrieve packages from build stage
 COPY --from=builder /install/.venv/ /install/.venv

@@ -1,53 +1,200 @@
 # API Quick Start
 
-## Starting the API Server
+## Overview
 
-```bash
-cd .
-python -m src.local_deep_research.web.app
-```
+Local Deep Research provides both HTTP REST API and programmatic Python API access. Since version 2.0, authentication is required for all API endpoints, and the system uses per-user encrypted databases.
 
-The API will be available at `http://localhost:5000/api/v1/`
+## Authentication
 
-## Basic Usage Examples
+### Web UI Authentication
 
-### 1. Check API Status
-```bash
-curl http://localhost:5000/api/v1/health
-```
+The API requires authentication through the web interface first:
+
+1. Start the server:
+   ```bash
+   python -m local_deep_research.web.app
+   ```
+
+2. Open http://localhost:5000 in your browser
+3. Register a new account or login
+4. Your session cookie will be used for API authentication
+
+### HTTP API Authentication
+
+For HTTP API requests, you need to:
+
+1. First authenticate through the login endpoint
+2. Include the session cookie in subsequent requests
+3. Include CSRF token for state-changing operations
+
+Example authentication flow:
+
+```python
+import requests
+
+# Create a session to persist cookies
+session = requests.Session()
 
-### 2. Get a Quick Summary
-```bash
-curl -X POST http://localhost:5000/api/v1/quick_summary \
-  -H "Content-Type: application/json" \
-  -d '{"query": "What is Python programming?"}'
+# 1. Login
+login_response = session.post(
+    "http://localhost:5000/auth/login",
+    json={"username": "your_username", "password": "your_password"}
+)
+
+if login_response.status_code == 200:
+    print("Login successful")
+    # Session cookie is automatically stored
+else:
+    print(f"Login failed: {login_response.text}")
+
+# 2. Get CSRF token for API requests
+csrf_response = session.get("http://localhost:5000/auth/csrf-token")
+csrf_token = csrf_response.json()["csrf_token"]
+
+# 3. Make API requests with authentication
+headers = {"X-CSRF-Token": csrf_token}
+api_response = session.post(
+    "http://localhost:5000/research/api/start",
+    json={
+        "query": "What is quantum computing?",
+        "model": "gpt-3.5-turbo",
+        "search_engines": ["searxng"],
+    },
+    headers=headers
+)
 ```
 
-### 3. Generate a Report (Long-running)
-```bash
-curl -X POST http://localhost:5000/api/v1/generate_report \
-  -H "Content-Type: application/json" \
-  -d '{"query": "Machine learning basics"}'
+## Programmatic API Access
+
+The programmatic API now requires a settings snapshot for proper context:
+
+```python
+from local_deep_research.api import quick_summary
+from local_deep_research.settings import CachedSettingsManager
+from local_deep_research.database.session_context import get_user_db_session
+
+# Get user session and settings
+with get_user_db_session(username="your_username", password="your_password") as session:
+    settings_manager = CachedSettingsManager(session, "your_username")
+    settings_snapshot = settings_manager.get_all_settings()
+
+    # Use the API with settings snapshot
+    result = quick_summary(
+        query="What is machine learning?",
+        settings_snapshot=settings_snapshot,
+        iterations=2,
+        questions_per_iteration=3
+    )
+
+    print(result["summary"])
 ```
 
-### 4. Python Example
+## API Endpoints
+
+### Research Endpoints
+
+All research endpoints are under `/research/api/`:
+
+- `POST /research/api/start` - Start new research
+- `GET /research/api/research/{id}/status` - Check research status
+- `GET /research/api/research/{id}/result` - Get research results
+- `POST /research/api/research/{id}/terminate` - Stop running research
+
+### Settings Endpoints
+
+Settings endpoints are under `/settings/api/`:
+
+- `GET /settings/api` - Get all settings
+- `GET /settings/api/{key}` - Get specific setting
+- `PUT /settings/api/{key}` - Update setting
+- `GET /settings/api/available-models` - Get available LLM providers
+- `GET /settings/api/available-search-engines` - Get search engines
+
+### History Endpoints
+
+- `GET /history/api` - Get research history
+- `GET /history/api/{id}` - Get specific research details
+
+## Important Changes from v1.x
+
+1. **Authentication Required**: All API endpoints now require authentication
+2. **Settings Snapshot**: Programmatic API calls need settings_snapshot parameter
+3. **Per-User Databases**: Each user has their own encrypted database
+4. **CSRF Protection**: State-changing requests require CSRF token
+5. **New Endpoint Structure**: APIs moved under blueprint prefixes (e.g., `/research/api/`)
+
+## Example: Complete Research Flow
+
 ```python
 import requests
+import time
 
-# Get a quick summary
-response = requests.post(
-    "http://localhost:5000/api/v1/quick_summary",
-    json={"query": "What is AI?"}
+# Setup session and login
+session = requests.Session()
+session.post(
+    "http://localhost:5000/auth/login",
+    json={"username": "user", "password": "pass"}
 )
 
-print(response.json()["summary"])
+# Get CSRF token
+csrf = session.get("http://localhost:5000/auth/csrf-token").json()["csrf_token"]
+headers = {"X-CSRF-Token": csrf}
+
+# Start research
+research = session.post(
+    "http://localhost:5000/research/api/start",
+    json={
+        "query": "Latest advances in quantum computing",
+        "model": "gpt-3.5-turbo",
+        "search_engines": ["arxiv", "wikipedia"],
+        "iterations": 3
+    },
+    headers=headers
+).json()
+
+research_id = research["research_id"]
+
+# Poll for results
+while True:
+    status = session.get(
+        f"http://localhost:5000/research/api/research/{research_id}/status"
+    ).json()
+
+    if status["status"] in ["completed", "failed"]:
+        break
+
+    print(f"Progress: {status.get('progress', 'unknown')}")
+    time.sleep(5)
+
+# Get final results
+results = session.get(
+    f"http://localhost:5000/research/api/research/{research_id}/result"
+).json()
+
+print(f"Summary: {results['summary']}")
+print(f"Sources: {len(results['sources'])}")
 ```
 
-## Key Points
+## Rate Limiting
+
+The API includes adaptive rate limiting:
+- Default: 60 requests per minute per user
+- Automatic retry with exponential backoff
+- Rate limits are per-user, not per-IP
+
+## Error Handling
+
+Common error responses:
+- `401`: Not authenticated - login required
+- `403`: CSRF token missing or invalid
+- `404`: Resource not found
+- `429`: Rate limit exceeded
+- `500`: Server error
+
+Always check response status and handle errors appropriately.
 
-- **Quick Summary**: Fast responses using LLM (seconds)
-- **Generate Report**: Comprehensive research (hours)
-- **Rate Limit**: 60 requests/minute
-- **Timeout**: API requests may timeout on long operations
+## Next Steps
 
-For full documentation, see [api-usage.md](api-usage.md)
+- See [examples/api_usage](../examples/api_usage/) for complete examples
+- Check [docs/CUSTOM_LLM_INTEGRATION.md](CUSTOM_LLM_INTEGRATION.md) for custom LLM setup
+- Read [docs/LANGCHAIN_RETRIEVER_INTEGRATION.md](LANGCHAIN_RETRIEVER_INTEGRATION.md) for custom retrievers

@@ -0,0 +1,178 @@
+# Data Migration Guide
+
+> **⚠️ Important Note for v1.0**: The upcoming v1.0 release does not support automatic database migration from previous versions. This guide is provided for reference, but users upgrading to v1.0 will need to start with a fresh database. We recommend exporting any important data (API keys, research results) before upgrading.
+
+## Overview
+
+Local Deep Research has updated its data storage locations to improve security and follow platform best practices. Previously, data files were stored alongside the application source code. Now, they are stored in user-specific directories that vary by operating system.
+
+This guide will help you migrate your existing data to the new locations. We recommend creating a backup of your data before proceeding.
+
+## New Storage Locations
+
+The application now stores data in platform-specific user directories:
+
+- **Windows**: `C:\Users\<YourUsername>\AppData\Local\local-deep-research`
+- **macOS**: `~/Library/Application Support/local-deep-research`
+- **Linux**: `~/.local/share/local-deep-research`
+
+## What Needs to be Migrated
+
+The following data will be migrated automatically when possible:
+
+1. **Database files** (*.db) - Contains your API keys, research history, and settings
+2. **Research outputs** - Your generated research reports and findings
+3. **Cache files** - Cached pricing information and search results
+4. **Log files** - Application logs
+5. **Benchmark results** - Performance benchmark data
+6. **Optimization results** - LLM optimization data
+
+## Migration Options
+
+> **Note**: These migration options are not available in v1.0. Please see the warning at the top of this document.
+
+### Option 1: Automatic Migration (Recommended for User Installs)
+
+If you installed Local Deep Research with `pip install --user`, the automatic migration should work:
+
+```bash
+# Simply run the application
+python -m local-deep_research.web.app
+```
+
+The application will automatically detect and migrate your data on startup.
+
+### Option 2: Run Application with Administrator Privileges
+
+If you installed with `sudo pip install` or have permission issues, run the application once with administrator privileges:
+
+```bash
+# Run the application with sudo to allow migration
+sudo python -m local_deep_research.web.app
+```
+
+This will:
+- Grant the necessary permissions for the automatic migration
+- Move all data files to the new user-specific directories
+- Complete the migration process
+- After this, you can run normally without sudo
+
+### Option 3: Manual Migration
+
+If you prefer to migrate manually or the automatic options don't work:
+
+#### Step 1: Find Your Current Data Location
+
+```bash
+# Find where the application is installed
+python -c "import local_deep_research; import os; print(os.path.dirname(local_deep_research.__file__))"
+```
+
+#### Step 2: Identify Files to Migrate
+
+Look for these files/directories in the installation directory:
+- `data/ldr.db` (and any other .db files)
+- `research_outputs/` directory
+- `data/cache/` directory
+- `data/logs/` directory
+- `data/benchmark_results/` directory
+- `data/optimization_results/` directory
+
+#### Step 3: Create New Directories
+
+```bash
+# Linux/macOS
+mkdir -p ~/.local/share/local-deep-research
+
+# Windows (PowerShell)
+New-Item -ItemType Directory -Force -Path "$env:LOCALAPPDATA\local-deep-research"
+```
+
+#### Step 4: Move Your Data
+
+**Important**: Back up your data before moving!
+
+```bash
+# Example for Linux/macOS (adjust paths as needed)
+# Move databases
+sudo mv /usr/local/lib/python*/site-packages/local_deep_research/data/*.db ~/.local/share/local-deep-research/
+
+# Move research outputs
+sudo mv /usr/local/lib/python*/site-packages/local_deep_research/research_outputs ~/.local/share/local-deep-research/
+
+# Move other data directories
+sudo mv /usr/local/lib/python*/site-packages/local_deep_research/data/cache ~/.local/share/local-deep-research/
+sudo mv /usr/local/lib/python*/site-packages/local_deep_research/data/logs ~/.local/share/local-deep-research/
+```
+
+### Option 4: Start Fresh
+
+If you don't need your existing data, you can simply:
+
+1. Delete the old data files (requires administrator privileges for system installs)
+2. Start using the application - it will create new files in the correct locations
+
+## Troubleshooting
+
+### Permission Denied Errors
+
+If you see "permission denied" errors:
+
+1. You likely have a system-wide installation (installed with `sudo pip install`)
+2. Use Option 2 (Migration Helper) or Option 3 (Manual Migration) above
+3. Administrator/sudo privileges will be required to move files from system directories
+
+### Files Not Found
+
+If the migration can't find your files:
+
+1. Check if you have multiple Python installations
+2. Verify where the application is installed (Step 1 in Manual Migration)
+3. Look for data files in your current working directory
+
+### Migration Partially Completed
+
+If some files were migrated but others weren't:
+
+1. Check the application logs for specific errors
+2. Manually move any remaining files following Option 3
+3. Ensure you have write permissions to the new directories
+
+## Verifying Migration Success
+
+After migration, verify everything worked:
+
+```bash
+# Check if files exist in new location (Linux/macOS)
+ls -la ~/.local/share/local-deep-research/
+
+# Check if files exist in new location (Windows PowerShell)
+Get-ChildItem "$env:LOCALAPPDATA\local-deep-research"
+```
+
+You should see:
+- `ldr.db` (and possibly other .db files)
+- `research_outputs/` directory with your reports
+- `cache/` directory
+- `logs/` directory
+
+## Security Benefits
+
+This migration provides several security improvements:
+
+1. **User Isolation**: Data is now stored in user-specific directories
+2. **Proper Permissions**: User directories have appropriate access controls
+3. **Package Updates**: Updates won't affect your data
+4. **No System-Wide Access**: Your API keys and research data are private to your user account
+
+## Getting Help
+
+If you encounter issues:
+
+1. Check the application logs in the new logs directory
+2. Report issues at: https://github.com/LearningCircuit/local-deep-research/issues
+3. Include your operating system and installation method (pip, pip --user, etc.)
+
+## Reverting Migration (Not Recommended)
+
+If you absolutely need to revert to the old behavior, you can set environment variables to override the new paths. However, this is not recommended for security reasons and may not be supported in future versions.

@@ -125,3 +125,21 @@ set LDR_ANTHROPIC_API_KEY=your-key-here
 export LDR_SEARCH__TOOL=wikipedia  # Linux/Mac
 set LDR_SEARCH__TOOL=wikipedia     # Windows
 ```
+
+### Data Directory Location
+
+By default, Local Deep Research stores all data (database, research outputs, cache, logs) in platform-specific user directories. You can override this location using the `LDR_DATA_DIR` environment variable:
+
+```bash
+# Linux/Mac
+export LDR_DATA_DIR=/path/to/your/data/directory
+
+# Windows
+set LDR_DATA_DIR=C:\path\to\your\data\directory
+```
+
+All application data will be organized under this directory:
+- `$LDR_DATA_DIR/ldr.db` - Application database
+- `$LDR_DATA_DIR/research_outputs/` - Research reports
+- `$LDR_DATA_DIR/cache/` - Cached data
+- `$LDR_DATA_DIR/logs/` - Application logs

@@ -0,0 +1,261 @@
+# 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 blueprint prefixes
+
+## Breaking Changes
+
+### 1. Authentication Required
+
+**v0.x**: Open access, no authentication
+```python
+# Direct API access
+from local_deep_research.api import quick_summary
+result = quick_summary("query")
+```
+
+**v1.0**: Authentication required
+```python
+from local_deep_research.api import quick_summary
+from local_deep_research.settings import CachedSettingsManager
+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 = CachedSettingsManager(session, "user")
+    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**: `/research/api/start`
+
+#### Authentication Flow
+```python
+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/research/api/start",
+    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
+```python
+# Direct settings access
+from local_deep_research.config import get_db_setting
+value = get_db_setting("llm.provider")
+```
+
+#### v1.0
+```python
+# Settings require context
+from local_deep_research.settings import CachedSettingsManager
+
+# Within authenticated session
+settings_manager = CachedSettingsManager(session, username)
+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
+
+```bash
+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):
+```python
+from local_deep_research.api import (
+    quick_summary,
+    detailed_research,
+    generate_report
+)
+
+# Direct usage
+result = quick_summary("What is AI?")
+```
+
+#### After (v1.0):
+```python
+from local_deep_research.api import quick_summary
+from local_deep_research.settings import CachedSettingsManager
+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 = CachedSettingsManager(session, username)
+        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:
+
+```python
+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}/research/api/start",
+            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:
+
+```python
+# 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
+
+```python
+# 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
+
+## Getting Help
+
+- Check the [API Quick Start Guide](api-quickstart.md)
+- See [examples/api_usage](../examples/api_usage/) for updated examples
+- Join our [Discord](https://discord.gg/ttcqQeFcJ3) for migration support
+- Report issues on [GitHub](https://github.com/LearningCircuit/local-deep-research/issues)

@@ -0,0 +1,221 @@
+# News API Exception Handling
+
+## Overview
+
+The news API module now uses a structured exception handling approach instead of returning error dictionaries. This provides better error handling, cleaner code, and consistent API responses.
+
+## Exception Hierarchy
+
+All news API exceptions inherit from `NewsAPIException`, which provides:
+- Human-readable error messages
+- HTTP status codes
+- Machine-readable error codes
+- Optional additional details
+
+```python
+from local_deep_research.news.exceptions import NewsAPIException
+
+class NewsAPIException(Exception):
+    def __init__(self, message: str, status_code: int = 500,
+                 error_code: Optional[str] = None,
+                 details: Optional[Dict[str, Any]] = None)
+```
+
+## Available Exceptions
+
+### InvalidLimitException
+- **Status Code**: 400
+- **Error Code**: `INVALID_LIMIT`
+- **Usage**: When an invalid limit parameter is provided
+- **Example**:
+```python
+if limit < 1:
+    raise InvalidLimitException(limit)
+```
+
+### SubscriptionNotFoundException
+- **Status Code**: 404
+- **Error Code**: `SUBSCRIPTION_NOT_FOUND`
+- **Usage**: When a requested subscription doesn't exist
+- **Example**:
+```python
+if not subscription:
+    raise SubscriptionNotFoundException(subscription_id)
+```
+
+### SubscriptionCreationException
+- **Status Code**: 500
+- **Error Code**: `SUBSCRIPTION_CREATE_FAILED`
+- **Usage**: When subscription creation fails
+- **Example**:
+```python
+except Exception as e:
+    raise SubscriptionCreationException(str(e), {"query": query})
+```
+
+### SubscriptionUpdateException
+- **Status Code**: 500
+- **Error Code**: `SUBSCRIPTION_UPDATE_FAILED`
+- **Usage**: When subscription update fails
+
+### SubscriptionDeletionException
+- **Status Code**: 500
+- **Error Code**: `SUBSCRIPTION_DELETE_FAILED`
+- **Usage**: When subscription deletion fails
+
+### DatabaseAccessException
+- **Status Code**: 500
+- **Error Code**: `DATABASE_ERROR`
+- **Usage**: When database operations fail
+- **Example**:
+```python
+except Exception as e:
+    raise DatabaseAccessException("operation_name", str(e))
+```
+
+### NewsFeedGenerationException
+- **Status Code**: 500
+- **Error Code**: `FEED_GENERATION_FAILED`
+- **Usage**: When news feed generation fails
+
+### ResearchProcessingException
+- **Status Code**: 500
+- **Error Code**: `RESEARCH_PROCESSING_FAILED`
+- **Usage**: When processing research items fails
+
+### NotImplementedException
+- **Status Code**: 501
+- **Error Code**: `NOT_IMPLEMENTED`
+- **Usage**: For features not yet implemented
+- **Example**:
+```python
+raise NotImplementedException("feature_name")
+```
+
+### InvalidParameterException
+- **Status Code**: 400
+- **Error Code**: `INVALID_PARAMETER`
+- **Usage**: When invalid parameters are provided
+
+### SchedulerNotificationException
+- **Status Code**: 500
+- **Error Code**: `SCHEDULER_NOTIFICATION_FAILED`
+- **Usage**: When scheduler notification fails (non-critical)
+
+## Flask Integration
+
+### Error Handlers
+
+The Flask application automatically handles `NewsAPIException` and its subclasses:
+
+```python
+@app.errorhandler(NewsAPIException)
+def handle_news_api_exception(error):
+    return jsonify(error.to_dict()), error.status_code
+```
+
+### Response Format
+
+All exceptions are converted to consistent JSON responses:
+
+```json
+{
+    "error": "Human-readable error message",
+    "error_code": "MACHINE_READABLE_CODE",
+    "status_code": 400,
+    "details": {
+        "additional": "context",
+        "if": "available"
+    }
+}
+```
+
+## Migration Guide
+
+### Before (Error Dictionaries)
+
+```python
+def get_news_feed(limit):
+    if limit < 1:
+        return {
+            "error": "Limit must be at least 1",
+            "news_items": []
+        }
+
+    try:
+        # ... code ...
+    except Exception as e:
+        logger.exception("Error getting news feed")
+        return {"error": str(e), "news_items": []}
+```
+
+### After (Exceptions)
+
+```python
+def get_news_feed(limit):
+    if limit < 1:
+        raise InvalidLimitException(limit)
+
+    try:
+        # ... code ...
+    except NewsAPIException:
+        raise  # Re-raise our custom exceptions
+    except Exception as e:
+        logger.exception("Error getting news feed")
+        raise NewsFeedGenerationException(str(e))
+```
+
+## Benefits
+
+1. **Cleaner Code**: Functions focus on their primary logic without error response formatting
+2. **Consistent Error Handling**: All errors follow the same format
+3. **Better Testing**: Easier to test exception cases with pytest.raises
+4. **Type Safety**: IDEs can better understand return types
+5. **Centralized Logging**: Error logging can be handled in one place
+6. **HTTP Status Codes**: Proper HTTP status codes are automatically set
+
+## Testing
+
+Test exception handling using pytest:
+
+```python
+import pytest
+from local_deep_research.news.exceptions import InvalidLimitException
+
+def test_invalid_limit():
+    with pytest.raises(InvalidLimitException) as exc_info:
+        news_api.get_news_feed(limit=-1)
+
+    assert exc_info.value.status_code == 400
+    assert exc_info.value.details["provided_limit"] == -1
+```
+
+## Best Practices
+
+1. **Always catch and re-raise NewsAPIException subclasses**:
+```python
+except NewsAPIException:
+    raise  # Let Flask handle it
+except Exception as e:
+    # Convert to appropriate NewsAPIException
+    raise DatabaseAccessException("operation", str(e))
+```
+
+2. **Include relevant details**:
+```python
+raise SubscriptionCreationException(
+    "Database constraint violated",
+    details={"query": query, "type": subscription_type}
+)
+```
+
+3. **Use appropriate exception types**: Choose the most specific exception that matches the error condition
+
+4. **Log before raising**: For unexpected errors, log the full exception before converting to NewsAPIException
+
+## Future Improvements
+
+- Add retry logic for transient errors
+- Implement exception metrics/monitoring
+- Add internationalization support for error messages
+- Create exception middleware for advanced error handling

@@ -0,0 +1,132 @@
+# SQLCipher Installation Guide
+
+Local Deep Research uses SQLCipher to provide encrypted databases for each user. This ensures that all user data, including API keys and research results, are encrypted at rest.
+
+## Installation by Platform
+
+### Ubuntu/Debian Linux
+
+SQLCipher can be easily installed from the package manager:
+
+```bash
+sudo apt update
+sudo apt install sqlcipher libsqlcipher-dev
+```
+
+After installation, you can install the Python binding:
+```bash
+pdm add pysqlcipher3
+# or
+pip install pysqlcipher3
+```
+
+### macOS
+
+Install using Homebrew:
+
+```bash
+brew install sqlcipher
+```
+
+You may need to set environment variables for the Python binding:
+```bash
+export LDFLAGS="-L$(brew --prefix sqlcipher)/lib"
+export CPPFLAGS="-I$(brew --prefix sqlcipher)/include"
+pdm add pysqlcipher3
+```
+
+### Windows
+
+Windows installation is more complex and requires building from source:
+
+1. Install Visual Studio 2015 or later (Community Edition works)
+2. Install the "Desktop Development with C++" workload
+3. Download SQLCipher source from https://github.com/sqlcipher/sqlcipher
+4. Build using Visual Studio Native Tools Command Prompt
+
+For easier installation on Windows, consider using WSL2 with Ubuntu.
+
+## Alternative: Using Docker
+
+If you have difficulty installing SQLCipher, you can run Local Deep Research in a Docker container where SQLCipher is pre-installed:
+
+```dockerfile
+FROM python:3.11-slim
+
+# Install SQLCipher
+RUN apt-get update && apt-get install -y \
+    sqlcipher \
+    libsqlcipher-dev \
+    gcc \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Local Deep Research
+RUN pip install local-deep-research pysqlcipher3
+
+CMD ["ldr", "serve"]
+```
+
+## Verifying Installation
+
+You can verify SQLCipher is installed correctly:
+
+```bash
+# Check command line tool
+sqlcipher --version
+
+# Test Python binding
+python -c "import pysqlcipher3; print('SQLCipher is installed!')"
+```
+
+## Fallback Mode
+
+If SQLCipher is not available, Local Deep Research will fall back to using regular SQLite databases. However, this means your data will not be encrypted at rest. A warning will be displayed when running without encryption.
+
+## Security Notes
+
+- Each user's database is encrypted with their password
+- There is no password recovery mechanism - if a user forgets their password, their data cannot be recovered
+- The encryption uses SQLCipher's default settings with AES-256
+- API keys and sensitive data are only stored in the encrypted user databases
+
+## Troubleshooting
+
+### Linux: "Package not found"
+
+If your distribution doesn't have SQLCipher in its repositories, you may need to build from source or use a third-party repository.
+
+### macOS: "Library not loaded"
+
+Make sure you've set the LDFLAGS and CPPFLAGS environment variables as shown above.
+
+### Windows: Build errors
+
+Ensure you're using the Visual Studio Native Tools Command Prompt and have all required dependencies installed.
+
+### Python: "No module named pysqlcipher3"
+
+Try using the alternative package:
+```bash
+pip install sqlcipher3
+```
+
+## For Developers
+
+To add SQLCipher to an automated installation script:
+
+```bash
+#!/bin/bash
+# For Ubuntu/Debian
+if command -v apt-get &> /dev/null; then
+    sudo apt-get update
+    sudo apt-get install -y sqlcipher libsqlcipher-dev
+fi
+
+# For macOS with Homebrew
+if command -v brew &> /dev/null; then
+    brew install sqlcipher
+fi
+
+# Install Python package
+pip install pysqlcipher3 || pip install sqlcipher3
+```

@@ -0,0 +1,249 @@
+# Troubleshooting OpenAI API Key Configuration
+
+This guide helps troubleshoot common issues with OpenAI API key configuration in Local Deep Research v1.0+.
+
+## Quick Test
+
+Run the end-to-end test to verify your configuration:
+
+```bash
+# Using command line arguments
+python tests/test_openai_api_key_e2e.py \
+  --username YOUR_USERNAME \
+  --password YOUR_PASSWORD \
+  --api-key YOUR_OPENAI_API_KEY
+
+# Using environment variables
+export LDR_USERNAME=your_username
+export LDR_PASSWORD=your_password
+export OPENAI_API_KEY=sk-your-api-key
+python tests/test_openai_api_key_e2e.py
+```
+
+## Common Issues and Solutions
+
+### 1. "No API key found"
+
+**Symptoms:**
+- Error message about missing API key
+- Research fails to start
+
+**Solutions:**
+
+1. **Via Web Interface:**
+   - Login to LDR web interface
+   - Go to Settings
+   - Select "OpenAI" as LLM Provider
+   - Enter your API key in the "OpenAI API Key" field
+   - Click Save
+
+2. **Via Environment Variable:**
+   ```bash
+   export OPENAI_API_KEY=sk-your-api-key
+   python -m local_deep_research.web.app
+   ```
+
+3. **Programmatically:**
+   ```python
+   from local_deep_research.settings import CachedSettingsManager
+   from local_deep_research.database.session_context import get_user_db_session
+
+   with get_user_db_session(username="user", password="pass") as session:
+       settings_manager = CachedSettingsManager(session, "user")
+       settings_manager.set_setting("llm.provider", "openai")
+       settings_manager.set_setting("llm.openai.api_key", "sk-your-api-key")
+   ```
+
+### 2. "Invalid API key"
+
+**Symptoms:**
+- 401 Unauthorized errors
+- "Incorrect API key provided" messages
+
+**Solutions:**
+
+1. **Verify API Key Format:**
+   - OpenAI keys start with `sk-`
+   - Should be around 51 characters long
+   - No extra spaces or quotes
+
+2. **Check API Key Validity:**
+   ```bash
+   # Test directly with curl
+   curl https://api.openai.com/v1/models \
+     -H "Authorization: Bearer YOUR_API_KEY"
+   ```
+
+3. **Regenerate API Key:**
+   - Go to https://platform.openai.com/api-keys
+   - Create a new API key
+   - Update in LDR settings
+
+### 3. "Rate limit exceeded"
+
+**Symptoms:**
+- 429 errors
+- "You exceeded your current quota" messages
+
+**Solutions:**
+
+1. **Check OpenAI Usage:**
+   - Visit https://platform.openai.com/usage
+   - Verify you have available credits
+
+2. **Add Payment Method:**
+   - OpenAI requires payment info for API access
+   - Add at https://platform.openai.com/account/billing
+
+3. **Use Different Model:**
+   ```python
+   settings_manager.set_setting("llm.model", "gpt-3.5-turbo")  # Cheaper
+   # Instead of gpt-4 which is more expensive
+   ```
+
+### 4. "Settings not persisting"
+
+**Symptoms:**
+- API key needs to be re-entered after restart
+- Settings revert to defaults
+
+**Solutions:**
+
+1. **Ensure Proper Shutdown:**
+   - Use Ctrl+C to stop server (not kill -9)
+   - Wait for "Server stopped" message
+
+2. **Check Database Permissions:**
+   ```bash
+   ls -la encrypted_databases/
+   # Should show your user database with write permissions
+   ```
+
+3. **Verify Settings Save:**
+   ```python
+   # After setting, verify it was saved
+   saved_key = settings_manager.get_setting("llm.openai.api_key")
+   print(f"Saved key: {'*' * 20 if saved_key else 'Not saved'}")
+   ```
+
+### 5. "API key not being used"
+
+**Symptoms:**
+- Settings show OpenAI configured but different LLM is used
+- API key is saved but not applied
+
+**Solutions:**
+
+1. **Check Provider Setting:**
+   ```python
+   provider = settings_manager.get_setting("llm.provider")
+   print(f"Current provider: {provider}")  # Should be "openai"
+   ```
+
+2. **Verify Settings Snapshot:**
+   ```python
+   settings_snapshot = settings_manager.get_all_settings()
+   print("Provider:", settings_snapshot.get("llm.provider", {}).get("value"))
+   print("API Key:", "Set" if settings_snapshot.get("llm.openai.api_key", {}).get("value") else "Not set")
+   ```
+
+3. **Force Provider Selection:**
+   ```python
+   # In research call
+   result = quick_summary(
+       query="Test",
+       settings_snapshot=settings_snapshot,
+       provider="openai",  # Force OpenAI
+       model_name="gpt-3.5-turbo"
+   )
+   ```
+
+## Testing Your Configuration
+
+### 1. Simple API Test
+
+```python
+from local_deep_research.config.llm_config import get_llm
+from local_deep_research.settings import CachedSettingsManager
+from local_deep_research.database.session_context import get_user_db_session
+
+with get_user_db_session(username="user", password="pass") as session:
+    settings_manager = CachedSettingsManager(session, "user")
+    settings_snapshot = settings_manager.get_all_settings()
+
+    # Test LLM initialization
+    try:
+        llm = get_llm(settings_snapshot=settings_snapshot)
+        print("✓ LLM initialized successfully")
+
+        # Test response
+        from langchain.schema import HumanMessage
+        response = llm.invoke([HumanMessage(content="Say hello")])
+        print(f"✓ Response: {response.content}")
+    except Exception as e:
+        print(f"✗ Error: {e}")
+```
+
+### 2. Full Research Test
+
+```python
+from local_deep_research.api.research_functions import quick_summary
+
+result = quick_summary(
+    query="What is OpenAI?",
+    settings_snapshot=settings_snapshot,
+    iterations=1,
+    questions_per_iteration=1
+)
+
+print(f"Research ID: {result['research_id']}")
+print(f"Summary: {result['summary'][:200]}...")
+```
+
+## Advanced Configuration
+
+### Using Azure OpenAI
+
+```python
+settings_manager.set_setting("llm.provider", "openai")
+settings_manager.set_setting("llm.openai.api_key", "your-azure-key")
+settings_manager.set_setting("llm.openai.api_base", "https://your-resource.openai.azure.com/")
+settings_manager.set_setting("llm.model", "your-deployment-name")
+```
+
+### Using OpenAI-Compatible Endpoints
+
+```python
+settings_manager.set_setting("llm.provider", "openai")
+settings_manager.set_setting("llm.openai.api_key", "your-api-key")
+settings_manager.set_setting("llm.openai.api_base", "https://your-endpoint.com/v1")
+```
+
+### Organization ID
+
+```python
+settings_manager.set_setting("llm.openai.organization", "org-your-org-id")
+```
+
+## Getting Help
+
+1. **Run Diagnostic Test:**
+   ```bash
+   python tests/test_openai_api_key_e2e.py --verbose
+   ```
+
+2. **Check Logs:**
+   ```bash
+   # Look for OpenAI-related errors
+   grep -i "openai\|api.*key" logs/ldr.log
+   ```
+
+3. **Community Support:**
+   - GitHub Issues: https://github.com/LearningCircuit/local-deep-research/issues
+   - Discord: https://discord.gg/ttcqQeFcJ3
+
+4. **API Key Best Practices:**
+   - Never commit API keys to version control
+   - Use environment variables for production
+   - Rotate keys regularly
+   - Set usage limits in OpenAI dashboard

@@ -1,325 +1,397 @@
 #!/usr/bin/env python3
 """
-HTTP API Examples for Local Deep Research
+HTTP API Examples for Local Deep Research v1.0+
 
-This script demonstrates how to use the LDR HTTP API endpoints.
-Make sure the LDR server is running before running these examples:
-    python -m src.local_deep_research.web.app
+This script demonstrates comprehensive usage of the LDR HTTP API with authentication.
+Includes examples for research, settings management, and batch operations.
+
+Requirements:
+- LDR v1.0+ (with authentication features)
+- User account created through web interface
+- LDR server running: python -m local_deep_research.web.app
 """
 
-import requests
-import json
 import time
-from typing import Dict, Any
+from typing import Any, Dict, List
+import requests
 
-# Base URL for the API
-BASE_URL = "http://localhost:5000/api/v1"
+# Configuration
+BASE_URL = "http://localhost:5000"
+USERNAME = "your_username"  # Change this!
+PASSWORD = "your_password"  # Change this!
 
 
-def check_health() -> None:
-    """Check if the API server is running."""
-    try:
-        response = requests.get(f"{BASE_URL}/health")
-        print(f"Health check: {response.json()}")
-    except requests.exceptions.ConnectionError:
-        print("Error: Cannot connect to API server. Make sure it's running:")
-        print("  python -m src.local_deep_research.web.app")
-        exit(1)
-
-
-def quick_summary_example() -> Dict[str, Any]:
-    """Example: Generate a quick summary of a topic."""
-    print("\n=== Quick Summary Example ===")
-
-    payload = {
-        "query": "What are the latest advances in quantum computing?",
-        "search_tool": "wikipedia",  # Optional: specify search engine
-        "iterations": 1,  # Optional: number of research iterations
-        "questions_per_iteration": 2,  # Optional: questions per iteration
-    }
-
-    response = requests.post(
-        f"{BASE_URL}/quick_summary",
-        json=payload,
-        headers={"Content-Type": "application/json"},
-    )
+class LDRClient:
+    """Client for interacting with LDR API v1.0+ with authentication"""
 
-    if response.status_code == 200:
-        result = response.json()
-        print(f"Summary: {result['summary'][:500]}...")
-        print(f"Number of findings: {len(result.get('findings', []))}")
-        print(f"Research iterations: {result.get('iterations', 0)}")
-        return result
-    else:
-        print(f"Error: {response.status_code} - {response.text}")
-        return {}
-
-
-def detailed_research_example() -> Dict[str, Any]:
-    """Example: Perform detailed research on a topic."""
-    print("\n=== Detailed Research Example ===")
-
-    payload = {
-        "query": "Impact of AI on software development",
-        "search_tool": "auto",  # Auto-select best search engine
-        "iterations": 2,
-        "questions_per_iteration": 3,
-        "search_strategy": "source_based",  # Optional: specify strategy
-    }
-
-    response = requests.post(
-        f"{BASE_URL}/detailed_research",
-        json=payload,
-        headers={"Content-Type": "application/json"},
-    )
+    def __init__(self, base_url: str = BASE_URL):
+        self.base_url = base_url
+        self.session = requests.Session()
+        self.csrf_token = None
+        self.username = None
 
-    if response.status_code == 200:
-        result = response.json()
-        print(f"Query: {result['query']}")
-        print(f"Research ID: {result['research_id']}")
-        print(f"Summary length: {len(result['summary'])} characters")
-        print(f"Sources found: {len(result.get('sources', []))}")
-
-        # Print metadata
-        if "metadata" in result:
-            print("\nMetadata:")
-            for key, value in result["metadata"].items():
-                print(f"  {key}: {value}")
-
-        return result
-    else:
-        print(f"Error: {response.status_code} - {response.text}")
-        return {}
-
-
-def generate_report_example() -> Dict[str, Any]:
-    """Example: Generate a comprehensive research report."""
-    print("\n=== Generate Report Example ===")
-    print("Note: This can take several minutes to complete...")
-
-    payload = {
-        "query": "Future of renewable energy",
-        "searches_per_section": 2,
-        "iterations": 1,
-        "provider": "openai_endpoint",  # Optional: LLM provider
-        "model_name": "llama-3.3-70b-instruct",  # Optional: model
-        "temperature": 0.7,  # Optional: generation temperature
-    }
-
-    # Start the report generation
-    response = requests.post(
-        f"{BASE_URL}/generate_report",
-        json=payload,
-        headers={"Content-Type": "application/json"},
-        timeout=300,  # 5 minute timeout
-    )
+    def login(self, username: str, password: str) -> bool:
+        """Authenticate with the LDR server."""
+        response = self.session.post(
+            f"{self.base_url}/auth/login",
+            json={"username": username, "password": password},
+        )
 
-    if response.status_code == 200:
-        result = response.json()
-
-        # Save the report to a file
-        if "content" in result:
-            with open("generated_report.md", "w", encoding="utf-8") as f:
-                f.write(result["content"])
-            print("Report saved to: generated_report.md")
-
-            # Show report preview
-            print("\nReport preview (first 500 chars):")
-            print(result["content"][:500] + "...")
-
-            # Show metadata
-            if "metadata" in result:
-                print("\nReport metadata:")
-                for key, value in result["metadata"].items():
-                    print(f"  {key}: {value}")
-
-        return result
-    else:
-        print(f"Error: {response.status_code} - {response.text}")
-        return {}
-
-
-def search_with_retriever_example() -> Dict[str, Any]:
-    """Example: Using custom retrievers via HTTP API."""
-    print("\n=== Search with Custom Retriever Example ===")
-    print("Note: This example shows the API structure but won't work")
-    print("without a real retriever implementation on the server side.")
-
-    # This demonstrates the API structure, but actual retrievers
-    # need to be registered on the server side
-    payload = {
-        "query": "company policies on remote work",
-        "search_tool": "company_docs",  # Use a named retriever
-        "iterations": 1,
-    }
-
-    response = requests.post(
-        f"{BASE_URL}/quick_summary",
-        json=payload,
-        headers={"Content-Type": "application/json"},
-    )
+        if response.status_code == 200:
+            self.username = username
+            # Get CSRF token
+            csrf_response = self.session.get(f"{self.base_url}/auth/csrf-token")
+            self.csrf_token = csrf_response.json()["csrf_token"]
+            return True
+        return False
+
+    def logout(self) -> None:
+        """Logout from the server."""
+        if self.csrf_token:
+            self.session.post(
+                f"{self.base_url}/auth/logout",
+                headers={"X-CSRF-Token": self.csrf_token},
+            )
 
-    if response.status_code == 200:
-        result = response.json()
-        print("Found information from custom retriever")
-        return result
-    else:
-        print(
-            f"Expected error (retriever not registered): {response.status_code}"
-        )
-        return {}
+    def _get_headers(self) -> Dict[str, str]:
+        """Get headers with CSRF token."""
+        return {"X-CSRF-Token": self.csrf_token} if self.csrf_token else {}
 
+    def check_health(self) -> Dict[str, Any]:
+        """Check API health status."""
+        response = self.session.get(f"{self.base_url}/auth/check")
+        return response.json()
 
-def get_available_search_engines() -> Dict[str, Any]:
-    """Example: Get list of available search engines."""
-    print("\n=== Available Search Engines ===")
+    def start_research(self, query: str, **kwargs) -> Dict[str, Any]:
+        """Start a new research task."""
+        payload = {
+            "query": query,
+            "model": kwargs.get("model"),
+            "search_engines": kwargs.get("search_engines", ["wikipedia"]),
+            "iterations": kwargs.get("iterations", 2),
+            "questions_per_iteration": kwargs.get("questions_per_iteration", 3),
+            "temperature": kwargs.get("temperature", 0.7),
+            "local_context": kwargs.get("local_context", 2000),
+            "web_context": kwargs.get("web_context", 2000),
+        }
 
-    response = requests.get(f"{BASE_URL}/search_engines")
+        response = self.session.post(
+            f"{self.base_url}/research/api/start",
+            json=payload,
+            headers=self._get_headers(),
+        )
+
+        if response.status_code == 200:
+            return response.json()
+        else:
+            raise Exception(f"Failed to start research: {response.text}")
 
-    if response.status_code == 200:
-        engines = response.json()
-        print("Available search engines:")
-        for name, info in engines.items():
-            if isinstance(info, dict):
-                print(
-                    f"  - {name}: {info.get('description', 'No description')}"
+    def get_research_status(self, research_id: str) -> Dict[str, Any]:
+        """Get the status of a research task."""
+        response = self.session.get(
+            f"{self.base_url}/research/api/research/{research_id}/status"
+        )
+        return response.json()
+
+    def get_research_result(self, research_id: str) -> Dict[str, Any]:
+        """Get the results of a completed research task."""
+        response = self.session.get(
+            f"{self.base_url}/research/api/research/{research_id}/result"
+        )
+        return response.json()
+
+    def wait_for_research(
+        self, research_id: str, timeout: int = 300
+    ) -> Dict[str, Any]:
+        """Wait for research to complete and return results."""
+        start_time = time.time()
+
+        while time.time() - start_time < timeout:
+            status = self.get_research_status(research_id)
+
+            if status.get("status") == "completed":
+                return self.get_research_result(research_id)
+            elif status.get("status") == "failed":
+                raise Exception(
+                    f"Research failed: {status.get('error', 'Unknown error')}"
                 )
-            else:
-                print(f"  - {name}")
-        return engines
-    else:
-        print(f"Error: {response.status_code} - {response.text}")
-        return {}
 
+            print(
+                f"  Status: {status.get('status', 'unknown')} - {status.get('progress', 'N/A')}"
+            )
+            time.sleep(3)
 
-def batch_research_example() -> None:
-    """Example: Perform multiple research queries in batch."""
-    print("\n=== Batch Research Example ===")
+        raise TimeoutError(
+            f"Research {research_id} timed out after {timeout} seconds"
+        )
 
-    queries = [
-        "Impact of 5G on IoT",
-        "Blockchain in supply chain",
-        "Edge computing trends",
-    ]
+    def get_settings(self) -> Dict[str, Any]:
+        """Get all user settings."""
+        response = self.session.get(f"{self.base_url}/settings/api")
+        return response.json()
 
-    results = []
+    def get_setting(self, key: str) -> Any:
+        """Get a specific setting value."""
+        response = self.session.get(f"{self.base_url}/settings/api/{key}")
+        if response.status_code == 200:
+            return response.json()
+        return None
+
+    def update_setting(self, key: str, value: Any) -> bool:
+        """Update a setting value."""
+        response = self.session.put(
+            f"{self.base_url}/settings/api/{key}",
+            json={"value": value},
+            headers=self._get_headers(),
+        )
+        return response.status_code in [200, 201]
 
-    for query in queries:
-        print(f"\nResearching: {query}")
+    def get_history(self, limit: int = 10) -> List[Dict[str, Any]]:
+        """Get research history."""
+        response = self.session.get(
+            f"{self.base_url}/history/api", params={"limit": limit}
+        )
+        data = response.json()
+        return data.get("items", data.get("history", []))
 
-        payload = {
-            "query": query,
-            "search_tool": "wikipedia",
-            "iterations": 1,
-            "questions_per_iteration": 1,
-        }
+    def get_available_models(self) -> Dict[str, str]:
+        """Get available LLM providers and models."""
+        response = self.session.get(
+            f"{self.base_url}/settings/api/available-models"
+        )
+        data = response.json()
+        return data.get("providers", data.get("models", {}))
 
-        response = requests.post(
-            f"{BASE_URL}/quick_summary",
-            json=payload,
-            headers={"Content-Type": "application/json"},
+    def get_available_search_engines(self) -> List[str]:
+        """Get available search engines."""
+        response = self.session.get(
+            f"{self.base_url}/settings/api/available-search-engines"
         )
+        data = response.json()
+        return data.get("engines", data.get("engine_options", []))
 
-        if response.status_code == 200:
-            result = response.json()
-            results.append(
-                {
-                    "query": query,
-                    "summary": result["summary"][:200] + "...",
-                    "findings_count": len(result.get("findings", [])),
-                }
-            )
-            print(f"  ✓ Completed - {len(result['summary'])} chars")
-        else:
-            print(f"  ✗ Failed - {response.status_code}")
 
-        # Be nice to the API - add a small delay between requests
-        time.sleep(1)
+def example_quick_research(client: LDRClient) -> None:
+    """Example: Quick research with minimal parameters."""
+    print("\n=== Example 1: Quick Research ===")
 
-    # Display batch results
-    print("\n=== Batch Results Summary ===")
-    for r in results:
-        print(f"\nQuery: {r['query']}")
-        print(f"Findings: {r['findings_count']}")
-        print(f"Summary: {r['summary']}")
+    research = client.start_research(
+        query="What are the key principles of machine learning?",
+        iterations=1,
+        questions_per_iteration=2,
+    )
 
+    print(f"Started research ID: {research['research_id']}")
 
-def stream_research_example() -> None:
-    """Example: Stream research progress (if supported by server)."""
-    print("\n=== Streaming Research Example ===")
-    print("Note: This shows how streaming would work if implemented")
+    # Wait for completion
+    result = client.wait_for_research(research["research_id"])
 
-    # This is a conceptual example - actual streaming depends on server implementation
-    payload = {
-        "query": "Latest developments in AI ethics",
-        "stream": True,  # Request streaming responses
-    }
+    print(f"\nSummary: {result['summary'][:500]}...")
+    print(f"Sources: {len(result.get('sources', []))}")
+    print(f"Findings: {len(result.get('findings', []))}")
 
-    try:
-        response = requests.post(
-            f"{BASE_URL}/quick_summary",
-            json=payload,
-            headers={"Content-Type": "application/json"},
-            stream=True,
-        )
 
-        if response.status_code == 200:
-            for line in response.iter_lines():
-                if line:
-                    # Parse streaming JSON responses
-                    data = json.loads(line.decode("utf-8"))
-                    if "progress" in data:
-                        print(f"Progress: {data['progress']}")
-                    elif "result" in data:
-                        print("Final result received")
-        else:
-            print(f"Streaming not supported or error: {response.status_code}")
+def example_detailed_research(client: LDRClient) -> None:
+    """Example: Detailed research with multiple search engines."""
+    print("\n=== Example 2: Detailed Research ===")
 
-    except Exception as e:
-        print(f"Streaming example failed: {e}")
-        print("This is expected if the server doesn't support streaming")
+    # Check available search engines
+    engines = client.get_available_search_engines()
+    print(f"Available search engines: {engines}")
 
+    # Use multiple engines
+    selected_engines = (
+        ["wikipedia", "arxiv"] if "arxiv" in engines else ["wikipedia"]
+    )
 
-def main():
-    """Run all examples."""
-    print("=== Local Deep Research HTTP API Examples ===")
-    print(f"Using API at: {BASE_URL}")
+    research = client.start_research(
+        query="Impact of climate change on global food security",
+        search_engines=selected_engines,
+        iterations=3,
+        questions_per_iteration=4,
+        temperature=0.7,
+    )
 
-    # Check if server is running
-    check_health()
+    print(f"Started detailed research ID: {research['research_id']}")
 
-    # Run examples
-    try:
-        # Basic examples
-        quick_summary_example()
-        time.sleep(2)  # Rate limiting
+    # Monitor progress
+    result = client.wait_for_research(research["research_id"], timeout=600)
 
-        detailed_research_example()
-        time.sleep(2)
+    print(f"\nTitle: {result.get('query', 'N/A')}")
+    print(f"Summary length: {len(result['summary'])} characters")
+    print(f"Sources: {len(result.get('sources', []))}")
 
-        # Get available engines
-        get_available_search_engines()
-        time.sleep(2)
+    # Show some findings
+    findings = result.get("findings", [])
+    if findings:
+        print("\nTop findings:")
+        for i, finding in enumerate(findings[:3], 1):
+            print(f"{i}. {finding.get('text', 'N/A')[:100]}...")
 
-        # Advanced examples
-        search_with_retriever_example()
-        time.sleep(2)
 
-        batch_research_example()
-        time.sleep(2)
+def example_settings_management(client: LDRClient) -> None:
+    """Example: Managing user settings."""
+    print("\n=== Example 3: Settings Management ===")
 
-        stream_research_example()
-        time.sleep(2)
+    # Get current settings
+    settings = client.get_settings()
+    settings_data = settings.get("settings", {})
 
-        # Long-running example (optional - uncomment to run)
-        # generate_report_example()
+    # Display current LLM configuration
+    llm_provider = settings_data.get("llm.provider", {}).get("value", "Not set")
+    llm_model = settings_data.get("llm.model", {}).get("value", "Not set")
 
-    except KeyboardInterrupt:
-        print("\nExamples interrupted by user")
-    except Exception as e:
-        print(f"\nError running examples: {e}")
+    print(f"Current LLM Provider: {llm_provider}")
+    print(f"Current LLM Model: {llm_model}")
+
+    # Get available models
+    models = client.get_available_models()
+    print(f"\nAvailable providers: {list(models.keys())}")
+
+    # Example: Update temperature setting
+    current_temp = settings_data.get("llm.temperature", {}).get("value", 0.7)
+    print(f"\nCurrent temperature: {current_temp}")
+
+    # Update temperature (example - uncomment to actually update)
+    # success = client.update_setting("llm.temperature", 0.5)
+    # print(f"Temperature update: {'Success' if success else 'Failed'}")
+
+
+def example_batch_research(client: LDRClient) -> None:
+    """Example: Running multiple research tasks in batch."""
+    print("\n=== Example 4: Batch Research ===")
+
+    queries = [
+        "What is quantum entanglement?",
+        "How does CRISPR gene editing work?",
+        "What are the applications of blockchain technology?",
+    ]
+
+    research_ids = []
 
-    print("\n=== Examples completed ===")
+    # Start all research tasks
+    for query in queries:
+        try:
+            research = client.start_research(
+                query=query, iterations=1, questions_per_iteration=2
+            )
+            research_ids.append(
+                {
+                    "id": research["research_id"],
+                    "query": query,
+                    "status": "started",
+                }
+            )
+            print(f"Started: {query} (ID: {research['research_id']})")
+        except Exception as e:
+            print(f"Failed to start '{query}': {e}")
+
+    # Wait for all to complete
+    print("\nWaiting for batch completion...")
+    completed = 0
+
+    while completed < len(research_ids):
+        for research in research_ids:
+            if research["status"] != "completed":
+                try:
+                    status = client.get_research_status(research["id"])
+                    if status.get("status") == "completed":
+                        research["status"] = "completed"
+                        completed += 1
+                        print(f"✓ Completed: {research['query']}")
+                except Exception:
+                    pass
+
+        if completed < len(research_ids):
+            time.sleep(3)
+
+    # Get all results
+    print("\nBatch Results Summary:")
+    for research in research_ids:
+        try:
+            result = client.get_research_result(research["id"])
+            print(f"\n{research['query']}:")
+            print(f"  - Summary: {result['summary'][:150]}...")
+            print(f"  - Sources: {len(result.get('sources', []))}")
+        except Exception as e:
+            print(f"  - Error getting results: {e}")
+
+
+def example_research_history(client: LDRClient) -> None:
+    """Example: Viewing research history."""
+    print("\n=== Example 5: Research History ===")
+
+    history = client.get_history(limit=5)
+
+    if not history:
+        print("No research history found.")
+        return
+
+    print(f"Found {len(history)} recent research items:\n")
+
+    for item in history:
+        created = item.get("created_at", "Unknown date")
+        query = item.get("query", "Unknown query")
+        status = item.get("status", "Unknown")
+        research_id = item.get("id", item.get("research_id", "N/A"))
+
+        print(f"ID: {research_id}")
+        print(f"Query: {query}")
+        print(f"Date: {created}")
+        print(f"Status: {status}")
+        print("-" * 40)
+
+
+def main():
+    """Run all examples."""
+    print("=== LDR HTTP API v1.0 Examples ===")
+
+    # Create client
+    client = LDRClient(BASE_URL)
+
+    # Check if we need to update credentials
+    if USERNAME == "your_username":
+        print(
+            "\n⚠️  WARNING: Please update USERNAME and PASSWORD in this script!"
+        )
+        print("Steps:")
+        print("1. Start server: python -m local_deep_research.web.app")
+        print("2. Open: http://localhost:5000")
+        print("3. Register an account")
+        print("4. Update USERNAME and PASSWORD in this script")
+        return
+
+    try:
+        # Login
+        print(f"\nLogging in as: {USERNAME}")
+        if not client.login(USERNAME, PASSWORD):
+            print("❌ Login failed! Please check your credentials.")
+            return
+
+        print("✅ Login successful")
+
+        # Check health
+        health = client.check_health()
+        print(f"Authenticated: {health.get('authenticated', False)}")
+        print(f"Username: {health.get('username', 'N/A')}")
+
+        # Run examples
+        example_quick_research(client)
+        example_detailed_research(client)
+        example_settings_management(client)
+        example_batch_research(client)
+        example_research_history(client)
+
+    except requests.exceptions.ConnectionError:
+        print("\n❌ Cannot connect to LDR server!")
+        print("Make sure the server is running:")
+        print("  python -m local_deep_research.web.app")
+    except Exception as e:
+        print(f"\n❌ Error: {e}")
+    finally:
+        # Always logout
+        client.logout()
+        print("\n✅ Logged out")
 
 
 if __name__ == "__main__":

@@ -1,43 +1,147 @@
 #!/usr/bin/env python3
 """
-Simple HTTP API Example for Local Deep Research
+Simple HTTP API Example for Local Deep Research v1.0+
 
-Quick example showing how to use the LDR API with Python requests library.
+This example shows how to use the LDR API with authentication.
+Requires LDR v1.0+ with authentication features.
 """
 
 import requests
+import time
+import sys
 
-# Make sure LDR server is running: python -m src.local_deep_research.web.app
-API_URL = "http://localhost:5000/api/v1"
-
-# Example 1: Quick Summary
-print("=== Quick Summary ===")
-response = requests.post(
-    f"{API_URL}/quick_summary", json={"query": "What is machine learning?"}
-)
-
-if response.status_code == 200:
-    result = response.json()
-    print(f"Summary: {result['summary'][:300]}...")
-    print(f"Found {len(result.get('findings', []))} findings")
-else:
-    print(f"Error: {response.status_code}")
-
-# Example 2: Detailed Research
-print("\n=== Detailed Research ===")
-response = requests.post(
-    f"{API_URL}/detailed_research",
-    json={
-        "query": "Impact of climate change on agriculture",
-        "iterations": 2,
-        "search_tool": "wikipedia",
-    },
-)
-
-if response.status_code == 200:
-    result = response.json()
-    print(f"Research ID: {result['research_id']}")
-    print(f"Summary length: {len(result['summary'])} characters")
-    print(f"Sources: {len(result.get('sources', []))}")
-else:
-    print(f"Error: {response.status_code}")
+# Configuration
+API_URL = "http://localhost:5000"
+USERNAME = "your_username"  # Change this!
+PASSWORD = "your_password"  # Change this!
+
+
+def main():
+    # Create a session to persist cookies
+    session = requests.Session()
+
+    print("=== LDR HTTP API Example ===")
+    print(f"Connecting to: {API_URL}")
+
+    # Step 1: Login
+    print("\n1. Authenticating...")
+    login_response = session.post(
+        f"{API_URL}/auth/login",
+        json={"username": USERNAME, "password": PASSWORD},
+    )
+
+    if login_response.status_code != 200:
+        print(f"❌ Login failed: {login_response.text}")
+        print("\nPlease ensure:")
+        print("- The server is running: python -m local_deep_research.web.app")
+        print("- You have created an account through the web interface")
+        print("- You have updated USERNAME and PASSWORD in this script")
+        sys.exit(1)
+
+    print("✅ Login successful")
+
+    # Step 2: Get CSRF token
+    print("\n2. Getting CSRF token...")
+    csrf_response = session.get(f"{API_URL}/auth/csrf-token")
+    csrf_token = csrf_response.json()["csrf_token"]
+    headers = {"X-CSRF-Token": csrf_token}
+    print("✅ CSRF token obtained")
+
+    # Example 1: Quick Summary (using the start endpoint)
+    print("\n=== Example 1: Quick Summary ===")
+    research_request = {
+        "query": "What is machine learning?",
+        "model": None,  # Will use default from settings
+        "search_engines": ["wikipedia"],  # Fast for demo
+        "iterations": 1,
+        "questions_per_iteration": 2,
+    }
+
+    # Start research
+    start_response = session.post(
+        f"{API_URL}/research/api/start", json=research_request, headers=headers
+    )
+
+    if start_response.status_code != 200:
+        print(f"❌ Failed to start research: {start_response.text}")
+        sys.exit(1)
+
+    research_data = start_response.json()
+    research_id = research_data["research_id"]
+    print(f"✅ Research started with ID: {research_id}")
+
+    # Poll for results
+    print("\nWaiting for results...")
+    while True:
+        status_response = session.get(
+            f"{API_URL}/research/api/research/{research_id}/status"
+        )
+
+        if status_response.status_code == 200:
+            status = status_response.json()
+            print(f"  Status: {status.get('status', 'unknown')}")
+
+            if status.get("status") == "completed":
+                break
+            elif status.get("status") == "failed":
+                print(
+                    f"❌ Research failed: {status.get('error', 'Unknown error')}"
+                )
+                sys.exit(1)
+
+        time.sleep(2)
+
+    # Get results
+    results_response = session.get(
+        f"{API_URL}/research/api/research/{research_id}/result"
+    )
+
+    if results_response.status_code == 200:
+        results = results_response.json()
+        print(f"\n📝 Summary: {results['summary'][:300]}...")
+        print(f"📚 Sources: {len(results.get('sources', []))} found")
+        print(f"🔍 Findings: {len(results.get('findings', []))} findings")
+
+    # Example 2: Check Settings
+    print("\n=== Example 2: Current Settings ===")
+    settings_response = session.get(f"{API_URL}/settings/api")
+
+    if settings_response.status_code == 200:
+        settings = settings_response.json()["settings"]
+
+        # Show some key settings
+        llm_provider = settings.get("llm.provider", {}).get("value", "Not set")
+        llm_model = settings.get("llm.model", {}).get("value", "Not set")
+
+        print(f"LLM Provider: {llm_provider}")
+        print(f"LLM Model: {llm_model}")
+
+    # Example 3: Get Research History
+    print("\n=== Example 3: Research History ===")
+    history_response = session.get(f"{API_URL}/history/api")
+
+    if history_response.status_code == 200:
+        history = history_response.json()
+        items = history.get("items", history.get("history", []))
+
+        print(f"Found {len(items)} research items")
+        for item in items[:3]:  # Show first 3
+            print(
+                f"- {item.get('query', 'Unknown query')} ({item.get('created_at', 'Unknown date')})"
+            )
+
+    # Logout
+    print("\n4. Logging out...")
+    session.post(f"{API_URL}/auth/logout", headers=headers)
+    print("✅ Logged out successfully")
+
+
+if __name__ == "__main__":
+    print("Make sure the LDR server is running:")
+    print("  python -m local_deep_research.web.app\n")
+
+    if USERNAME == "your_username":
+        print("⚠️  WARNING: Please update USERNAME and PASSWORD in this script!")
+        print("    Create an account through the web interface first.\n")
+
+    main()

@@ -0,0 +1,611 @@
+#!/usr/bin/env python3
+"""
+Advanced Features Example for Local Deep Research
+
+This example demonstrates advanced programmatic features including:
+1. generate_report() - Create comprehensive markdown reports
+2. Export formats - Save reports in different formats
+3. Result analysis - Extract and analyze research findings
+4. Keyword extraction - Identify key topics and concepts
+"""
+
+import json
+from typing import Dict, List, Any
+
+from local_deep_research.api import (
+    generate_report,
+    detailed_research,
+    quick_summary,
+)
+from local_deep_research.api.settings_utils import create_settings_snapshot
+
+
+def demonstrate_report_generation():
+    """
+    Generate a comprehensive research report using generate_report().
+
+    This function creates a structured markdown report with:
+    - Executive summary
+    - Detailed findings organized by sections
+    - Source citations
+    - Conclusions and recommendations
+    """
+    print("=" * 70)
+    print("GENERATE COMPREHENSIVE REPORT")
+    print("=" * 70)
+    print("""
+This demonstrates the generate_report() function which:
+- Creates a structured markdown report
+- Performs multiple searches per section
+- Organizes findings into coherent sections
+- Includes citations and references
+    """)
+
+    # Configure settings for programmatic mode
+    settings = create_settings_snapshot(
+        overrides={
+            "programmatic_mode": True,
+            "search.tool": "wikipedia",
+            "llm.temperature": 0.5,  # Lower for more focused output
+        }
+    )
+
+    # Generate a comprehensive report
+    print(
+        "Generating report on 'Applications of Machine Learning in Healthcare'..."
+    )
+    report = generate_report(
+        query="Applications of Machine Learning in Healthcare",
+        output_file="ml_healthcare_report.md",
+        searches_per_section=2,  # Multiple searches per section for depth
+        settings_snapshot=settings,
+        iterations=2,
+        questions_per_iteration=3,
+    )
+
+    print("\n✓ Report generated successfully!")
+    print(f"  - Report length: {len(report['content'])} characters")
+    print(
+        f"  - File saved to: {report.get('file_path', 'ml_healthcare_report.md')}"
+    )
+
+    # Show first part of report
+    print("\nReport preview (first 500 chars):")
+    print("-" * 40)
+    print(report["content"][:500] + "...")
+
+    return report
+
+
+def demonstrate_export_formats():
+    """
+    Show how to export research results in different formats.
+
+    Demonstrates:
+    - Markdown export (default)
+    - JSON export for programmatic processing
+    - Custom formatting with templates
+    """
+    print("\n" + "=" * 70)
+    print("EXPORT FORMATS")
+    print("=" * 70)
+    print("""
+Exporting research in different formats:
+- Markdown: Human-readable reports
+- JSON: Structured data for processing
+- Custom: Template-based formatting
+    """)
+
+    settings = create_settings_snapshot(
+        overrides={
+            "programmatic_mode": True,
+            "search.tool": "wikipedia",
+        }
+    )
+
+    # Get research results
+    result = detailed_research(
+        query="Renewable energy technologies",
+        settings_snapshot=settings,
+        iterations=1,
+        questions_per_iteration=2,
+    )
+
+    # Export as JSON
+    json_file = "research_results.json"
+    with open(json_file, "w", encoding="utf-8") as f:
+        json.dump(result, f, indent=2, default=str)
+    print(f"\n✓ JSON export saved to: {json_file}")
+    print(f"  - Contains: {len(result.get('findings', []))} findings")
+    print(f"  - Sources: {len(result.get('sources', []))} sources")
+
+    # Export as Markdown
+    md_content = format_as_markdown(result)
+    md_file = "research_results.md"
+    with open(md_file, "w", encoding="utf-8") as f:
+        f.write(md_content)
+    print(f"\n✓ Markdown export saved to: {md_file}")
+    print(f"  - Length: {len(md_content)} characters")
+
+    # Export as custom format (e.g., BibTeX-like citations)
+    citations = extract_citations(result)
+    cite_file = "research_citations.txt"
+    with open(cite_file, "w", encoding="utf-8") as f:
+        for i, citation in enumerate(citations, 1):
+            f.write(f"[{i}] {citation}\n")
+    print(f"\n✓ Citations export saved to: {cite_file}")
+    print(f"  - Total citations: {len(citations)}")
+
+    return result
+
+
+def demonstrate_result_analysis():
+    """
+    Analyze research results to extract insights and patterns.
+
+    Shows how to:
+    - Extract key findings
+    - Identify recurring themes
+    - Analyze source reliability
+    - Generate statistics
+    """
+    print("\n" + "=" * 70)
+    print("RESULT ANALYSIS")
+    print("=" * 70)
+    print("""
+Analyzing research results to extract:
+- Key findings and insights
+- Common themes and patterns
+- Source statistics
+- Quality metrics
+    """)
+
+    settings = create_settings_snapshot(
+        overrides={
+            "programmatic_mode": True,
+            "search.tool": "wikipedia",
+        }
+    )
+
+    # Perform research
+    result = detailed_research(
+        query="Impact of artificial intelligence on employment",
+        settings_snapshot=settings,
+        search_strategy="source-based",
+        iterations=2,
+        questions_per_iteration=3,
+    )
+
+    # Analyze findings
+    analysis = analyze_findings(result)
+
+    print("\n📊 Research Analysis:")
+    print(f"  - Total findings: {analysis['total_findings']}")
+    print(f"  - Unique sources: {analysis['unique_sources']}")
+    print(f"  - Questions explored: {analysis['total_questions']}")
+    print(f"  - Iterations completed: {analysis['iterations']}")
+
+    print("\n🔍 Finding Categories:")
+    for category, count in analysis["categories"].items():
+        print(f"  - {category}: {count} findings")
+
+    print("\n📈 Source Distribution:")
+    for source_type, count in analysis["source_types"].items():
+        print(f"  - {source_type}: {count} sources")
+
+    # Extract themes
+    themes = extract_themes(result)
+    print("\n🎯 Key Themes Identified:")
+    for i, theme in enumerate(themes[:5], 1):
+        print(f"  {i}. {theme}")
+
+    return analysis
+
+
+def demonstrate_keyword_extraction():
+    """
+    Extract keywords and key concepts from research results.
+
+    Demonstrates:
+    - Keyword extraction from findings
+    - Concept identification
+    - Topic clustering
+    - Trend analysis
+    """
+    print("\n" + "=" * 70)
+    print("KEYWORD & CONCEPT EXTRACTION")
+    print("=" * 70)
+    print("""
+Extracting keywords and concepts:
+- Important terms and phrases
+- Technical concepts
+- Named entities
+- Trend indicators
+    """)
+
+    settings = create_settings_snapshot(
+        overrides={
+            "programmatic_mode": True,
+            "search.tool": "wikipedia",
+        }
+    )
+
+    # Quick research for keyword extraction
+    result = quick_summary(
+        query="Quantum computing breakthroughs 2024",
+        settings_snapshot=settings,
+        iterations=1,
+        questions_per_iteration=3,
+    )
+
+    # Extract keywords
+    keywords = extract_keywords(result)
+
+    print("\n🔑 Top Keywords:")
+    for keyword, frequency in keywords[:10]:
+        print(f"  - {keyword}: {frequency} occurrences")
+
+    # Extract concepts
+    concepts = extract_concepts(result)
+
+    print("\n💡 Key Concepts:")
+    for i, concept in enumerate(concepts[:5], 1):
+        print(f"  {i}. {concept}")
+
+    # Identify technical terms
+    technical_terms = extract_technical_terms(result)
+
+    print("\n🔬 Technical Terms:")
+    for term in technical_terms[:8]:
+        print(f"  - {term}")
+
+    return keywords, concepts
+
+
+def format_as_markdown(result: Dict[str, Any]) -> str:
+    """Convert research results to markdown format."""
+    md = f"# Research Report: {result['query']}\n\n"
+    md += f"**Research ID:** {result.get('research_id', 'N/A')}\n\n"
+
+    # Summary
+    md += "## Summary\n\n"
+    md += result.get("summary", "No summary available") + "\n\n"
+
+    # Findings
+    md += "## Key Findings\n\n"
+    findings = result.get("findings", [])
+    for i, finding in enumerate(findings, 1):
+        finding_text = finding if isinstance(finding, str) else str(finding)
+        md += f"{i}. {finding_text}\n\n"
+
+    # Sources
+    md += "## Sources\n\n"
+    sources = result.get("sources", [])
+    for i, source in enumerate(sources, 1):
+        source_text = source if isinstance(source, str) else str(source)
+        md += f"- [{i}] {source_text}\n"
+
+    # Metadata
+    md += "\n## Metadata\n\n"
+    metadata = result.get("metadata", {})
+    for key, value in metadata.items():
+        md += f"- **{key}:** {value}\n"
+
+    return md
+
+
+def extract_citations(result: Dict[str, Any]) -> List[str]:
+    """Extract citations from research results."""
+    citations = []
+    sources = result.get("sources", [])
+
+    for source in sources:
+        if isinstance(source, dict):
+            # Extract URL or title
+            citation = source.get("url", source.get("title", str(source)))
+        else:
+            citation = str(source)
+        citations.append(citation)
+
+    return citations
+
+
+def analyze_findings(result: Dict[str, Any]) -> Dict[str, Any]:
+    """Analyze research findings for patterns and statistics."""
+    findings = result.get("findings", [])
+    sources = result.get("sources", [])
+    questions = result.get("questions", {})
+
+    # Categorize findings (simplified)
+    categories = {
+        "positive": 0,
+        "negative": 0,
+        "neutral": 0,
+        "technical": 0,
+    }
+
+    for finding in findings:
+        finding_text = str(finding).lower()
+        if any(
+            word in finding_text
+            for word in ["benefit", "improve", "enhance", "positive"]
+        ):
+            categories["positive"] += 1
+        elif any(
+            word in finding_text
+            for word in ["risk", "challenge", "negative", "concern"]
+        ):
+            categories["negative"] += 1
+        elif any(
+            word in finding_text
+            for word in ["algorithm", "system", "technology", "method"]
+        ):
+            categories["technical"] += 1
+        else:
+            categories["neutral"] += 1
+
+    # Analyze sources
+    source_types = {}
+    for source in sources:
+        source_text = str(source).lower()
+        if "wikipedia" in source_text:
+            source_type = "Wikipedia"
+        elif "arxiv" in source_text:
+            source_type = "ArXiv"
+        elif "github" in source_text:
+            source_type = "GitHub"
+        else:
+            source_type = "Other"
+        source_types[source_type] = source_types.get(source_type, 0) + 1
+
+    return {
+        "total_findings": len(findings),
+        "unique_sources": len(sources),
+        "total_questions": sum(len(qs) for qs in questions.values()),
+        "iterations": result.get("iterations", 0),
+        "categories": categories,
+        "source_types": source_types,
+    }
+
+
+def extract_themes(result: Dict[str, Any]) -> List[str]:
+    """Extract main themes from research results."""
+    # Simplified theme extraction based on common patterns
+    themes = []
+    summary = result.get("summary", "")
+    findings = result.get("findings", [])
+
+    # Combine text for analysis
+    full_text = summary + " ".join(str(f) for f in findings)
+
+    # Simple theme patterns (in production, use NLP libraries)
+    theme_patterns = {
+        "automation": ["automation", "automated", "automatic"],
+        "job displacement": ["job loss", "unemployment", "displacement"],
+        "skill requirements": ["skills", "training", "education"],
+        "economic impact": ["economy", "economic", "gdp", "growth"],
+        "innovation": ["innovation", "innovative", "breakthrough"],
+    }
+
+    for theme, keywords in theme_patterns.items():
+        if any(keyword in full_text.lower() for keyword in keywords):
+            themes.append(theme.title())
+
+    return themes
+
+
+def extract_keywords(result: Dict[str, Any]) -> List[tuple]:
+    """Extract keywords with frequency from research results."""
+    from collections import Counter
+    import re
+
+    # Combine all text
+    summary = result.get("summary", "")
+    findings = " ".join(str(f) for f in result.get("findings", []))
+    full_text = f"{summary} {findings}".lower()
+
+    # Simple word extraction (in production, use NLP libraries)
+    words = re.findall(r"\b[a-z]{4,}\b", full_text)
+
+    # Filter common words
+    stopwords = {
+        "that",
+        "this",
+        "with",
+        "from",
+        "have",
+        "been",
+        "were",
+        "which",
+        "their",
+        "about",
+    }
+    words = [w for w in words if w not in stopwords]
+
+    # Count frequencies
+    word_freq = Counter(words)
+
+    return word_freq.most_common(20)
+
+
+def extract_concepts(result: Dict[str, Any]) -> List[str]:
+    """Extract key concepts from research results."""
+    concepts = []
+    summary = result.get("summary", "")
+
+    # Simple concept patterns (in production, use NLP for entity extraction)
+    concept_patterns = [
+        r"quantum \w+",
+        r"\w+ computing",
+        r"\w+ algorithm",
+        r"machine learning",
+        r"artificial intelligence",
+        r"\w+ technology",
+    ]
+
+    import re
+
+    for pattern in concept_patterns:
+        matches = re.findall(pattern, summary.lower())
+        concepts.extend(matches)
+
+    # Deduplicate and clean
+    concepts = list(set(concepts))
+
+    return concepts[:10]
+
+
+def extract_technical_terms(result: Dict[str, Any]) -> List[str]:
+    """Extract technical terms from research results."""
+    technical_terms = []
+
+    # Common technical term patterns
+    tech_indicators = [
+        "algorithm",
+        "system",
+        "protocol",
+        "framework",
+        "architecture",
+        "quantum",
+        "neural",
+        "network",
+        "model",
+        "optimization",
+    ]
+
+    summary = result.get("summary", "").lower()
+    import re
+
+    for indicator in tech_indicators:
+        # Find words containing or adjacent to technical indicators
+        pattern = rf"\b\w*{indicator}\w*\b"
+        matches = re.findall(pattern, summary)
+        technical_terms.extend(matches)
+
+    # Deduplicate
+    technical_terms = list(set(technical_terms))
+
+    return technical_terms
+
+
+def demonstrate_batch_research():
+    """
+    Show how to perform batch research on multiple topics.
+
+    Useful for:
+    - Comparative analysis
+    - Trend monitoring
+    - Systematic reviews
+    """
+    print("\n" + "=" * 70)
+    print("BATCH RESEARCH PROCESSING")
+    print("=" * 70)
+    print("""
+Processing multiple research queries:
+- Efficient batch processing
+- Comparative analysis
+- Result aggregation
+    """)
+
+    settings = create_settings_snapshot(
+        overrides={
+            "programmatic_mode": True,
+            "search.tool": "wikipedia",
+        }
+    )
+
+    # Topics for batch research
+    topics = [
+        "Solar energy innovations",
+        "Wind power technology",
+        "Hydrogen fuel cells",
+    ]
+
+    batch_results = {}
+
+    print("\n📚 Batch Research:")
+    for topic in topics:
+        print(f"\n  Researching: {topic}")
+        result = quick_summary(
+            query=topic,
+            settings_snapshot=settings,
+            iterations=1,
+            questions_per_iteration=2,
+        )
+        batch_results[topic] = result
+        print(f"    ✓ Found {len(result.get('findings', []))} findings")
+
+    # Aggregate results
+    print("\n📊 Aggregate Analysis:")
+    total_findings = sum(
+        len(r.get("findings", [])) for r in batch_results.values()
+    )
+    total_sources = sum(
+        len(r.get("sources", [])) for r in batch_results.values()
+    )
+
+    print(f"  - Total topics researched: {len(topics)}")
+    print(f"  - Total findings: {total_findings}")
+    print(f"  - Total sources: {total_sources}")
+    print(f"  - Average findings per topic: {total_findings / len(topics):.1f}")
+
+    # Save batch results
+    batch_file = "batch_research_results.json"
+    with open(batch_file, "w", encoding="utf-8") as f:
+        json.dump(batch_results, f, indent=2, default=str)
+    print(f"\n✓ Batch results saved to: {batch_file}")
+
+    return batch_results
+
+
+def main():
+    """Run all advanced feature demonstrations."""
+    print("=" * 70)
+    print("LOCAL DEEP RESEARCH - ADVANCED FEATURES DEMONSTRATION")
+    print("=" * 70)
+    print("""
+This example demonstrates advanced programmatic features:
+1. Report generation with generate_report()
+2. Multiple export formats
+3. Result analysis and insights
+4. Keyword and concept extraction
+5. Batch research processing
+    """)
+
+    # Run demonstrations
+    demonstrate_report_generation()
+    demonstrate_export_formats()
+    demonstrate_result_analysis()
+    demonstrate_keyword_extraction()
+    demonstrate_batch_research()
+
+    print("\n" + "=" * 70)
+    print("DEMONSTRATION COMPLETE")
+    print("=" * 70)
+    print("""
+✓ All advanced features demonstrated successfully!
+
+Key Takeaways:
+1. generate_report() creates comprehensive markdown reports
+2. Results can be exported in multiple formats (JSON, MD, custom)
+3. Analysis tools extract insights, themes, and patterns
+4. Keyword extraction identifies important terms and concepts
+5. Batch processing enables systematic research
+
+Files created:
+- ml_healthcare_report.md - Full research report
+- research_results.json - Structured research data
+- research_results.md - Markdown formatted results
+- research_citations.txt - Extracted citations
+- batch_research_results.json - Batch research results
+
+Next Steps:
+- Customize report templates for your domain
+- Integrate with data visualization tools
+- Build automated research pipelines
+- Create domain-specific analysis functions
+    """)
+
+
+if __name__ == "__main__":
+    main()

@@ -0,0 +1,207 @@
+#!/usr/bin/env python3
+"""
+Example of using a custom LLM with a custom retriever in Local Deep Research.
+
+This demonstrates how to integrate your own LLM implementation and custom
+retrieval system for programmatic access.
+"""
+
+from typing import List, Dict
+from langchain_ollama import ChatOllama
+from langchain.schema import Document
+from langchain_community.vectorstores import FAISS
+from langchain_community.embeddings import OllamaEmbeddings
+
+# Import the search system
+from local_deep_research.search_system import AdvancedSearchSystem
+
+# Re-enable logging after import
+from loguru import logger
+import sys
+
+logger.remove()
+logger.add(sys.stderr, level="INFO", format="{time} {level} {message}")
+logger.enable("local_deep_research")
+
+
+class CustomRetriever:
+    """Custom retriever that can fetch from multiple sources."""
+
+    def __init__(self):
+        # Initialize with sample documents for demonstration
+        self.documents = [
+            {
+                "content": "Quantum computing uses quantum bits (qubits) that can exist in superposition, "
+                "allowing parallel computation of multiple states simultaneously.",
+                "title": "Quantum Computing Fundamentals",
+                "source": "quantum_basics.pdf",
+                "metadata": {"topic": "quantum", "year": 2024},
+            },
+            {
+                "content": "Machine learning algorithms can be categorized into supervised, unsupervised, "
+                "and reinforcement learning approaches, each suited for different tasks.",
+                "title": "ML Algorithm Categories",
+                "source": "ml_overview.pdf",
+                "metadata": {"topic": "ml", "year": 2024},
+            },
+            {
+                "content": "Neural networks are inspired by biological neurons and consist of interconnected "
+                "nodes that process information through weighted connections.",
+                "title": "Neural Network Architecture",
+                "source": "nn_architecture.pdf",
+                "metadata": {"topic": "neural_networks", "year": 2023},
+            },
+            {
+                "content": "Natural language processing enables computers to understand, interpret, and "
+                "generate human language, powering applications like chatbots and translation.",
+                "title": "NLP Applications",
+                "source": "nlp_apps.pdf",
+                "metadata": {"topic": "nlp", "year": 2024},
+            },
+        ]
+
+        # Create embeddings for similarity search
+        logger.info("Initializing custom retriever with embeddings...")
+        self.embeddings = OllamaEmbeddings(model="nomic-embed-text")
+
+        # Create vector store from documents
+        docs = [
+            Document(
+                page_content=doc["content"],
+                metadata={
+                    "title": doc["title"],
+                    "source": doc["source"],
+                    **doc["metadata"],
+                },
+            )
+            for doc in self.documents
+        ]
+        self.vectorstore = FAISS.from_documents(docs, self.embeddings)
+
+    def retrieve(self, query: str, k: int = 3) -> List[Dict]:
+        """Custom retrieval logic."""
+        logger.info(f"Custom Retriever: Searching for '{query}'")
+
+        # Use vector similarity search
+        similar_docs = self.vectorstore.similarity_search(query, k=k)
+
+        # Convert to expected format
+        results = []
+        for i, doc in enumerate(similar_docs):
+            results.append(
+                {
+                    "title": doc.metadata.get("title", f"Document {i + 1}"),
+                    "link": doc.metadata.get("source", "custom_source"),
+                    "snippet": doc.page_content[:150] + "...",
+                    "full_content": doc.page_content,
+                    "rank": i + 1,
+                    "metadata": doc.metadata,
+                }
+            )
+
+        logger.info(
+            f"Custom Retriever: Found {len(results)} relevant documents"
+        )
+        return results
+
+
+class CustomSearchEngine:
+    """Adapter to integrate custom retriever with the search system."""
+
+    def __init__(self, retriever: CustomRetriever, settings_snapshot=None):
+        self.retriever = retriever
+        self.settings_snapshot = settings_snapshot or {}
+
+    def run(self, query: str, research_context=None) -> List[Dict]:
+        """Execute search using custom retriever."""
+        return self.retriever.retrieve(query, k=5)
+
+
+def main():
+    """Demonstrate custom LLM and retriever integration."""
+    print("=== Custom LLM and Retriever Example ===\n")
+
+    # 1. Create custom LLM (just using regular Ollama for simplicity)
+    print("1. Initializing LLM...")
+    llm = ChatOllama(model="gemma3:12b", temperature=0.7)
+
+    # 2. Create custom retriever
+    print("2. Setting up custom retriever...")
+    custom_retriever = CustomRetriever()
+
+    # 3. Create settings
+    settings = {
+        "search.iterations": 2,
+        "search.questions_per_iteration": 3,
+        "search.strategy": "source-based",
+        "rate_limiting.enabled": False,  # Disable rate limiting for custom setup
+    }
+
+    # 4. Create search engine adapter
+    print("3. Creating search engine adapter...")
+    search_engine = CustomSearchEngine(custom_retriever, settings)
+
+    # 5. Initialize the search system
+    print("4. Initializing AdvancedSearchSystem with custom components...")
+    # Pass programmatic_mode=True to avoid database dependencies
+    search_system = AdvancedSearchSystem(
+        llm=llm,
+        search=search_engine,
+        settings_snapshot=settings,
+        programmatic_mode=True,
+    )
+
+    # 6. Run research queries
+    queries = [
+        "How do quantum computers differ from classical computers?",
+        "What are the main types of machine learning algorithms?",
+    ]
+
+    for query in queries:
+        print(f"\n{'=' * 60}")
+        print(f"Research Query: {query}")
+        print("=" * 60)
+
+        result = search_system.analyze_topic(query)
+
+        # Display results
+        print("\n=== FINDINGS ===")
+        print(result["formatted_findings"])
+
+        # Show metadata
+        print("\n=== SEARCH METADATA ===")
+        print(f"• Total findings: {len(result['findings'])}")
+        print(f"• Iterations: {result['iterations']}")
+
+        # Get actual sources from all_links_of_system or search_results
+        all_links = result.get("all_links_of_system", [])
+        for finding in result.get("findings", []):
+            if "search_results" in finding and finding["search_results"]:
+                all_links = finding["search_results"]
+                break
+
+        print(f"• Sources found: {len(all_links)}")
+        if all_links and len(all_links) > 0:
+            print("\n=== SOURCES ===")
+            for i, link in enumerate(all_links[:5], 1):  # Show first 5
+                if isinstance(link, dict):
+                    title = link.get("title", "No title")
+                    url = link.get("link", link.get("source", "Unknown"))
+                    print(f"  [{i}] {title}")
+                    print(f"      URL: {url}")
+
+        # Show generated questions
+        if result.get("questions_by_iteration"):
+            print("\n=== RESEARCH QUESTIONS GENERATED ===")
+            for iteration, questions in result[
+                "questions_by_iteration"
+            ].items():
+                print(f"\nIteration {iteration}:")
+                for q in questions[:3]:  # Show first 3 questions
+                    print(f"  • {q}")
+
+    print("\n✓ Custom LLM and Retriever integration successful!")
+
+
+if __name__ == "__main__":
+    main()

@@ -0,0 +1,403 @@
+#!/usr/bin/env python3
+"""
+Hybrid Search Example for Local Deep Research
+
+This example demonstrates how to combine multiple search sources:
+1. Multiple named retrievers for different document types
+2. Combining custom retrievers with web search
+3. Analyzing and comparing sources from different origins
+"""
+
+from typing import List
+from langchain.schema import Document, BaseRetriever
+from langchain_community.vectorstores import FAISS
+from langchain_community.embeddings import OllamaEmbeddings
+
+from local_deep_research.api import quick_summary, detailed_research
+from local_deep_research.api.settings_utils import create_settings_snapshot
+
+
+class TechnicalDocsRetriever(BaseRetriever):
+    """Mock retriever for technical documentation."""
+
+    def get_relevant_documents(self, query: str) -> List[Document]:
+        """Return mock technical documents."""
+        # In a real scenario, this would search actual technical docs
+        return [
+            Document(
+                page_content=f"Technical specification for {query}: Implementation requires careful consideration of system architecture, performance metrics, and scalability factors.",
+                metadata={
+                    "source": "tech_docs",
+                    "type": "specification",
+                    "title": f"Technical Spec: {query}",
+                },
+            ),
+            Document(
+                page_content=f"Best practices for {query}: Follow industry standards, implement proper error handling, and ensure comprehensive testing coverage.",
+                metadata={
+                    "source": "tech_docs",
+                    "type": "best_practices",
+                    "title": f"Best Practices: {query}",
+                },
+            ),
+        ]
+
+    async def aget_relevant_documents(self, query: str) -> List[Document]:
+        """Async version."""
+        return self.get_relevant_documents(query)
+
+
+class BusinessDocsRetriever(BaseRetriever):
+    """Mock retriever for business/strategy documents."""
+
+    def get_relevant_documents(self, query: str) -> List[Document]:
+        """Return mock business documents."""
+        return [
+            Document(
+                page_content=f"Business implications of {query}: Consider market impact, ROI analysis, and strategic alignment with organizational goals.",
+                metadata={
+                    "source": "business_docs",
+                    "type": "strategy",
+                    "title": f"Business Strategy: {query}",
+                },
+            ),
+            Document(
+                page_content=f"Cost-benefit analysis for {query}: Initial investment requirements, expected returns, and risk assessment factors.",
+                metadata={
+                    "source": "business_docs",
+                    "type": "analysis",
+                    "title": f"Cost Analysis: {query}",
+                },
+            ),
+        ]
+
+    async def aget_relevant_documents(self, query: str) -> List[Document]:
+        """Async version."""
+        return self.get_relevant_documents(query)
+
+
+def create_knowledge_base_retriever() -> BaseRetriever:
+    """Create a FAISS-based retriever with sample knowledge base documents."""
+    documents = [
+        Document(
+            page_content="Machine learning models require training data, validation strategies, and performance metrics for evaluation.",
+            metadata={"source": "ml_knowledge_base", "topic": "ml_basics"},
+        ),
+        Document(
+            page_content="Cloud computing provides scalable infrastructure, reducing capital expenditure and enabling flexible resource allocation.",
+            metadata={
+                "source": "cloud_knowledge_base",
+                "topic": "cloud_benefits",
+            },
+        ),
+        Document(
+            page_content="Agile methodology emphasizes iterative development, customer collaboration, and responding to change.",
+            metadata={"source": "project_knowledge_base", "topic": "agile"},
+        ),
+        Document(
+            page_content="Data privacy regulations like GDPR require explicit consent, data minimization, and user rights management.",
+            metadata={
+                "source": "compliance_knowledge_base",
+                "topic": "privacy",
+            },
+        ),
+    ]
+
+    # Create embeddings and vector store
+    embeddings = OllamaEmbeddings(model="nomic-embed-text")
+    vectorstore = FAISS.from_documents(documents, embeddings)
+    return vectorstore.as_retriever(search_kwargs={"k": 2})
+
+
+def demonstrate_multiple_retrievers():
+    """Show how to use multiple named retrievers for different document types."""
+    print("=" * 70)
+    print("MULTIPLE NAMED RETRIEVERS")
+    print("=" * 70)
+    print("""
+Using multiple specialized retrievers:
+- Technical documentation retriever
+- Business documentation retriever
+- Knowledge base retriever
+Each provides different perspectives on the same topic.
+    """)
+
+    # Create different retrievers
+    tech_retriever = TechnicalDocsRetriever()
+    business_retriever = BusinessDocsRetriever()
+    kb_retriever = create_knowledge_base_retriever()
+
+    # Configure settings
+    settings = create_settings_snapshot(
+        {
+            "search.tool": "auto",  # Will use all provided retrievers
+        }
+    )
+
+    # Use multiple retrievers in research
+    result = quick_summary(
+        query="Implementing machine learning in production",
+        settings_snapshot=settings,
+        retrievers={
+            "technical": tech_retriever,
+            "business": business_retriever,
+            "knowledge_base": kb_retriever,
+        },
+        search_tool="auto",  # Use all retrievers
+        iterations=2,
+        questions_per_iteration=2,
+        programmatic_mode=True,
+    )
+
+    print("\nResearch Summary (first 400 chars):")
+    print(result["summary"][:400] + "...")
+
+    # Analyze sources by type
+    sources = result.get("sources", [])
+    print(f"\nTotal sources found: {len(sources)}")
+
+    # Group sources by retriever
+    source_types = {}
+    for source in sources:
+        if isinstance(source, dict):
+            source_type = source.get("metadata", {}).get("source", "unknown")
+        else:
+            source_type = "other"
+        source_types[source_type] = source_types.get(source_type, 0) + 1
+
+    print("\nSources by retriever:")
+    for stype, count in source_types.items():
+        print(f"  - {stype}: {count} sources")
+
+    return result
+
+
+def demonstrate_retriever_plus_web():
+    """Show how to combine custom retrievers with web search."""
+    print("\n" + "=" * 70)
+    print("RETRIEVER + WEB SEARCH COMBINATION")
+    print("=" * 70)
+    print("""
+Combining internal knowledge with web search:
+- Internal: Custom retriever with proprietary knowledge
+- External: Wikipedia for general context
+This provides both specific and general information.
+    """)
+
+    # Create internal knowledge retriever
+    internal_retriever = create_knowledge_base_retriever()
+
+    # Configure settings to use both retriever and web
+    settings = create_settings_snapshot(
+        {
+            "search.tool": "wikipedia",  # Also use Wikipedia
+        }
+    )
+
+    # Research combining internal and external sources
+    result = detailed_research(
+        query="Best practices for cloud migration",
+        settings_snapshot=settings,
+        retrievers={
+            "internal_kb": internal_retriever,
+        },
+        search_tool="wikipedia",  # Also search Wikipedia
+        search_strategy="source-based",
+        iterations=2,
+        questions_per_iteration=3,
+        programmatic_mode=True,
+    )
+
+    print(f"\nResearch ID: {result['research_id']}")
+    print(f"Summary length: {len(result['summary'])} characters")
+
+    # Analyze source distribution
+    sources = result.get("sources", [])
+    internal_sources = 0
+    external_sources = 0
+
+    for source in sources:
+        if isinstance(source, dict) and "knowledge_base" in str(source):
+            internal_sources += 1
+        else:
+            external_sources += 1
+
+    print("\nSource distribution:")
+    print(f"  - Internal knowledge base: {internal_sources} sources")
+    print(f"  - External (Wikipedia): {external_sources} sources")
+
+    # Show how different sources complement each other
+    print("\nComplementary insights from hybrid search:")
+    print(
+        "  - Internal sources provide: Specific procedures, proprietary knowledge"
+    )
+    print(
+        "  - External sources provide: Industry context, general best practices"
+    )
+
+    return result
+
+
+def demonstrate_source_analysis():
+    """Show how to analyze and compare sources from different origins."""
+    print("\n" + "=" * 70)
+    print("SOURCE ANALYSIS AND COMPARISON")
+    print("=" * 70)
+    print("""
+Analyzing source quality and relevance:
+- Track source origins
+- Compare information consistency
+- Identify unique insights from each source type
+    """)
+
+    # Create multiple retrievers
+    tech_retriever = TechnicalDocsRetriever()
+    business_retriever = BusinessDocsRetriever()
+
+    settings = create_settings_snapshot(
+        {
+            "search.tool": "wikipedia",
+        }
+    )
+
+    # Run research with detailed source tracking
+    result = quick_summary(
+        query="Artificial intelligence implementation strategies",
+        settings_snapshot=settings,
+        retrievers={
+            "technical": tech_retriever,
+            "business": business_retriever,
+        },
+        search_tool="wikipedia",  # Also use web search
+        iterations=2,
+        questions_per_iteration=2,
+        programmatic_mode=True,
+    )
+
+    # Detailed source analysis
+    print("\nSource Analysis:")
+    sources = result.get("sources", [])
+
+    # Categorize sources
+    source_categories = {"technical": [], "business": [], "web": []}
+
+    for source in sources:
+        if isinstance(source, dict):
+            source_type = source.get("metadata", {}).get("source", "")
+            if "tech" in source_type:
+                source_categories["technical"].append(source)
+            elif "business" in source_type:
+                source_categories["business"].append(source)
+            else:
+                source_categories["web"].append(source)
+        else:
+            source_categories["web"].append(source)
+
+    # Report on each category
+    for category, category_sources in source_categories.items():
+        print(f"\n{category.upper()} Sources ({len(category_sources)}):")
+        if category_sources:
+            for i, source in enumerate(category_sources[:2], 1):  # Show first 2
+                if isinstance(source, dict):
+                    title = source.get("metadata", {}).get("title", "Untitled")
+                    print(f"  {i}. {title}")
+                else:
+                    print(f"  {i}. {str(source)[:60]}...")
+
+    # Show findings breakdown
+    findings = result.get("findings", [])
+    print(f"\nTotal findings: {len(findings)}")
+    print("Findings provide integrated insights from all source types")
+
+    return result
+
+
+def demonstrate_meta_search_config():
+    """Show how to use meta search configuration for complex setups."""
+    print("\n" + "=" * 70)
+    print("META SEARCH CONFIGURATION")
+    print("=" * 70)
+    print("""
+Using meta search for sophisticated search strategies:
+- Combine multiple search engines
+- Configure aggregation and deduplication
+- Control search priority and weighting
+    """)
+
+    # Create retrievers
+    tech_retriever = TechnicalDocsRetriever()
+
+    settings = create_settings_snapshot({})
+
+    # Advanced meta search configuration
+    result = quick_summary(
+        query="Quantum computing applications",
+        settings_snapshot=settings,
+        retrievers={
+            "tech_docs": tech_retriever,
+        },
+        search_tool="meta",  # Use meta search
+        meta_search_config={
+            "retrievers": ["tech_docs"],  # Include custom retriever
+            "engines": ["wikipedia", "arxiv"],  # Also search these
+            "aggregate": True,  # Combine results
+            "deduplicate": True,  # Remove duplicate content
+            "max_results_per_engine": 5,  # Limit per source
+        },
+        iterations=2,
+        questions_per_iteration=3,
+        programmatic_mode=True,
+    )
+
+    print("\nMeta search results:")
+    print(f"  - Total sources: {len(result.get('sources', []))}")
+    print(f"  - Summary length: {len(result.get('summary', ''))} chars")
+    print(f"  - Findings: {len(result.get('findings', []))}")
+
+    print("\nMeta search advantages:")
+    print("  - Comprehensive coverage from multiple sources")
+    print("  - Automatic deduplication of similar content")
+    print("  - Balanced perspective from different source types")
+
+    return result
+
+
+def main():
+    """Run all hybrid search demonstrations."""
+    print("=" * 70)
+    print("LOCAL DEEP RESEARCH - HYBRID SEARCH DEMONSTRATION")
+    print("=" * 70)
+    print("""
+This example shows how to combine multiple search sources:
+- Custom retrievers for proprietary knowledge
+- Web search engines for public information
+- Meta search for sophisticated strategies
+    """)
+
+    # Run demonstrations
+    demonstrate_multiple_retrievers()
+    demonstrate_retriever_plus_web()
+    demonstrate_source_analysis()
+    demonstrate_meta_search_config()
+
+    print("\n" + "=" * 70)
+    print("KEY TAKEAWAYS")
+    print("=" * 70)
+    print("""
+1. Multiple Retrievers: Use specialized retrievers for different document types
+2. Hybrid Search: Combine internal knowledge with web search for comprehensive results
+3. Source Analysis: Track and analyze sources to understand information origin
+4. Meta Search: Configure complex search strategies with aggregation and deduplication
+
+Best Practices:
+- Name your retrievers descriptively for easy tracking
+- Balance internal and external sources based on your needs
+- Use source analysis to verify information consistency
+- Configure meta search for optimal result aggregation
+    """)
+
+    print("\n✓ Hybrid search demonstration complete!")
+
+
+if __name__ == "__main__":
+    main()

@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+"""
+Minimal working example for programmatic access to Local Deep Research.
+
+This shows how to use the core functionality without database dependencies.
+"""
+
+from langchain_ollama import ChatOllama
+from local_deep_research.search_system import AdvancedSearchSystem
+
+# Re-enable logging after import (it gets disabled in __init__.py)
+from loguru import logger
+import sys
+
+logger.remove()
+logger.add(sys.stderr, level="WARNING", format="{time} {level} {message}")
+logger.enable("local_deep_research")
+
+
+class MinimalSearchEngine:
+    """Minimal search engine that returns hardcoded results."""
+
+    def __init__(self, settings_snapshot=None):
+        self.settings_snapshot = settings_snapshot or {}
+
+    def run(self, query, research_context=None):
+        """Return some fake search results."""
+        return [
+            {
+                "title": "Introduction to AI",
+                "link": "https://example.com/ai-intro",
+                "snippet": "Artificial Intelligence (AI) is the simulation of human intelligence...",
+                "full_content": "Full article about AI basics...",
+                "rank": 1,
+            },
+            {
+                "title": "Machine Learning Explained",
+                "link": "https://example.com/ml-explained",
+                "snippet": "Machine learning is a subset of AI that enables systems to learn...",
+                "full_content": "Detailed explanation of machine learning...",
+                "rank": 2,
+            },
+        ]
+
+
+def main():
+    """Minimal example of programmatic access."""
+    print("=== Minimal Local Deep Research Example ===\n")
+
+    # 1. Create LLM
+    print("1. Creating Ollama LLM...")
+    llm = ChatOllama(model="gemma3:12b")
+
+    # 2. Create minimal search engine
+    print("2. Creating minimal search engine...")
+
+    # Settings for search system (without programmatic_mode)
+    settings = {
+        "search.iterations": 1,
+        "search.strategy": "direct",
+    }
+
+    search = MinimalSearchEngine(settings)
+
+    # 3. Create search system
+    print("3. Creating AdvancedSearchSystem...")
+    # IMPORTANT: Pass programmatic_mode=True to avoid database dependencies
+    system = AdvancedSearchSystem(
+        llm=llm,
+        search=search,
+        settings_snapshot=settings,
+        programmatic_mode=True,
+    )
+
+    # 4. Run a search
+    print("\n4. Running search...")
+    result = system.analyze_topic("What is artificial intelligence?")
+
+    # 5. Show results
+    print("\n=== RESULTS ===")
+    print(f"Found {len(result['findings'])} findings")
+    print(f"\nSummary:\n{result['current_knowledge']}")
+
+    print("\n✓ Success! Programmatic access works without database.")
+
+
+if __name__ == "__main__":
+    main()

@@ -0,0 +1,238 @@
+# Local Deep Research - Programmatic API Examples
+
+This directory contains examples demonstrating how to use Local Deep Research programmatically without requiring authentication or database access.
+
+## Quick Start
+
+All examples use the programmatic API that bypasses authentication:
+
+```python
+from local_deep_research.api import quick_summary, detailed_research
+from local_deep_research.api.settings_utils import create_settings_snapshot
+
+# Create settings for programmatic mode
+settings = create_settings_snapshot({
+    "search.tool": "wikipedia"
+})
+
+# Run research
+result = quick_summary(
+    "your topic",
+    settings_snapshot=settings,
+    programmatic_mode=True
+)
+```
+
+## Examples Overview
+
+| Example | Purpose | Key Features | Difficulty |
+|---------|---------|--------------|------------|
+| **minimal_working_example.py** | Simplest possible example | Basic setup, minimal code | Beginner |
+| **simple_programmatic_example.py** | Common use cases with the new API | quick_summary, detailed_research, generate_report, custom parameters | Beginner |
+| **search_strategies_example.py** | Demonstrates search strategies | source-based vs focused-iteration strategies | Intermediate |
+| **hybrid_search_example.py** | Combine multiple search sources | Multiple retrievers, web + retriever combo | Intermediate |
+| **advanced_features_example.py** | Advanced programmatic features | generate_report, export formats, result analysis, keyword extraction | Advanced |
+| **custom_llm_retriever_example.py** | Custom LLM and retriever integration | Ollama, custom retrievers, FAISS | Advanced |
+| **searxng_example.py** | Web search with SearXNG | SearXNG integration, error handling | Advanced |
+
+## Example Details
+
+### minimal_working_example.py
+**Purpose:** Show the absolute minimum code needed to use LDR programmatically.
+- Creates a simple LLM and search engine
+- Runs a basic search
+- No external dependencies beyond Ollama
+
+### simple_programmatic_example.py
+**Purpose:** Demonstrate the main API functions with practical examples.
+- `quick_summary()` - Fast research with summary
+- `detailed_research()` - Comprehensive research with findings
+- `generate_report()` - Create full markdown reports
+- Custom search parameters
+- Different search tools (Wikipedia, auto, etc.)
+
+### search_strategies_example.py
+**Purpose:** Explain and demonstrate the two main search strategies.
+- **source-based**: Comprehensive research with detailed citations
+- **focused-iteration**: Iterative refinement of research questions
+- Side-by-side comparison of strategies
+- When to use each strategy
+
+### hybrid_search_example.py
+**Purpose:** Show how to combine multiple search sources for comprehensive research.
+- Multiple named retrievers for different document types
+- Combining custom retrievers with web search
+- Source analysis and tracking
+- Meta search configuration
+
+### advanced_features_example.py
+**Purpose:** Demonstrate advanced programmatic features and analysis capabilities.
+- `generate_report()` - Create comprehensive markdown reports
+- Export formats - JSON, Markdown, custom formats
+- Result analysis - Extract insights and patterns
+- Keyword extraction - Identify key terms and concepts
+- Batch research - Process multiple queries efficiently
+
+### custom_llm_retriever_example.py
+**Purpose:** Advanced integration with custom components.
+- Custom LLM implementation (using Ollama)
+- Custom retriever with embeddings
+- Vector store integration (FAISS)
+- Direct use of AdvancedSearchSystem
+
+### searxng_example.py
+**Purpose:** Web search integration using SearXNG.
+- SearXNG configuration
+- Error handling and fallbacks
+- Real-time web search
+- Direct use of search engines
+
+## Key Concepts
+
+### Programmatic Mode
+All examples use `programmatic_mode=True` as an explicit parameter to bypass authentication:
+```python
+result = quick_summary(
+    query="your topic",
+    settings_snapshot=settings,
+    programmatic_mode=True
+)
+```
+
+### Search Strategies
+- **source-based**: Best for academic research, fact-checking
+- **focused-iteration**: Best for exploratory research, complex topics
+
+### Search Tools
+Available search tools include:
+- `wikipedia` - Wikipedia search
+- `arxiv` - Academic papers
+- `searxng` - Web search via SearXNG
+- `auto` - Automatically select best tool
+- `meta` - Combine multiple tools
+
+### Custom Retrievers
+You can provide your own retrievers:
+```python
+result = quick_summary(
+    query="topic",
+    retrievers={"my_docs": custom_retriever},
+    search_tool="my_docs",
+    settings_snapshot=settings,
+    programmatic_mode=True
+)
+```
+
+## API Functions
+
+### `quick_summary()`
+Generate a quick research summary:
+```python
+from local_deep_research.api import quick_summary
+from local_deep_research.api.settings_utils import create_settings_snapshot
+
+settings = create_settings_snapshot({})
+result = quick_summary(
+    query="Your research question",
+    settings_snapshot=settings,
+    search_tool="wikipedia",
+    iterations=2,
+    programmatic_mode=True
+)
+```
+
+### `detailed_research()`
+Perform in-depth research with multiple iterations:
+```python
+from local_deep_research.api import detailed_research
+
+result = detailed_research(
+    query="Your research question",
+    settings_snapshot=settings,
+    search_strategy="source-based",
+    iterations=3,
+    questions_per_iteration=5,
+    programmatic_mode=True
+)
+```
+
+### `generate_report()`
+Generate comprehensive markdown reports with structured sections:
+```python
+from local_deep_research.api import generate_report
+from local_deep_research.api.settings_utils import create_settings_snapshot
+
+settings = create_settings_snapshot(overrides={"programmatic_mode": True})
+result = generate_report(
+    query="Your research question",
+    settings_snapshot=settings,
+    output_file="report.md",
+    searches_per_section=3
+)
+```
+
+## Requirements
+
+- Python 3.8+
+- Local Deep Research installed
+- Ollama (for most examples)
+- SearXNG instance (for searxng_example.py)
+
+## Running the Examples
+
+1. Install Local Deep Research:
+   ```bash
+   pip install -e .
+   ```
+
+2. Start Ollama (if using Ollama examples):
+   ```bash
+   ollama serve
+   ollama pull gemma3:12b
+   ollama pull nomic-embed-text  # For embeddings
+   ```
+
+3. Run any example:
+   ```bash
+   python minimal_working_example.py
+   python simple_programmatic_example.py
+   python search_strategies_example.py
+   ```
+
+## Troubleshooting
+
+### "No settings context available" Error
+Make sure to pass `settings_snapshot` and `programmatic_mode` to all API functions:
+```python
+settings = create_settings_snapshot({})
+result = quick_summary(
+    "topic",
+    settings_snapshot=settings,
+    programmatic_mode=True
+)
+```
+
+### Ollama Connection Error
+Ensure Ollama is running:
+```bash
+ollama serve
+```
+
+### SearXNG Connection Error
+Start a SearXNG instance or use the fallback in the example:
+```bash
+docker run -p 8080:8080 searxng/searxng
+```
+
+
+## Contributing
+
+When adding new examples:
+1. Focus on demonstrating specific features
+2. Include clear comments explaining the code
+3. Handle errors gracefully
+4. Update this README with the new example
+
+## License
+
+See the main project LICENSE file.

@@ -1,199 +0,0 @@
-"""
-Example of using LangChain retrievers with LDR.
-
-This example shows how to use any LangChain retriever as a search engine in LDR.
-"""
-
-from typing import List
-from langchain.schema import Document, BaseRetriever
-from langchain.vectorstores import FAISS
-from langchain.embeddings import OpenAIEmbeddings
-
-# Import LDR functions
-from local_deep_research.api.research_functions import (
-    quick_summary,
-    detailed_research,
-)
-
-
-# Example 1: Simple mock retriever for testing
-class MockRetriever(BaseRetriever):
-    """Mock retriever for demonstration."""
-
-    def get_relevant_documents(self, query: str) -> List[Document]:
-        """Return mock documents."""
-        return [
-            Document(
-                page_content=f"This is a mock document about {query}. It contains relevant information.",
-                metadata={
-                    "title": f"Document about {query}",
-                    "source": "mock_db",
-                },
-            ),
-            Document(
-                page_content=f"Another document discussing {query} in detail.",
-                metadata={
-                    "title": f"Detailed analysis of {query}",
-                    "source": "mock_db",
-                },
-            ),
-        ]
-
-    async def aget_relevant_documents(self, query: str) -> List[Document]:
-        """Async version."""
-        return self.get_relevant_documents(query)
-
-
-def example_single_retriever():
-    """Example using a single retriever."""
-    print("=== Example 1: Single Retriever ===")
-
-    # Create a mock retriever
-    retriever = MockRetriever()
-
-    # Use it with LDR
-    result = quick_summary(
-        query="What are the best practices for ML deployment?",
-        retrievers={"mock_kb": retriever},
-        search_tool="mock_kb",  # Use only this retriever
-        iterations=2,
-        questions_per_iteration=3,
-    )
-
-    print(f"Summary: {result['summary'][:200]}...")
-    print(f"Sources: {len(result.get('sources', []))} sources found")
-
-
-def example_multiple_retrievers():
-    """Example using multiple retrievers."""
-    print("\n=== Example 2: Multiple Retrievers ===")
-
-    # Create multiple mock retrievers
-    tech_retriever = MockRetriever()
-    business_retriever = MockRetriever()
-
-    # Use them with LDR
-    result = detailed_research(
-        query="What are the business and technical implications of ML deployment?",
-        retrievers={
-            "tech_docs": tech_retriever,
-            "business_docs": business_retriever,
-        },
-        search_tool="auto",  # Use all retrievers
-        iterations=3,
-    )
-
-    print(f"Research ID: {result['research_id']}")
-    print(f"Summary: {result['summary'][:200]}...")
-    print(f"Findings: {len(result['findings'])} findings")
-
-
-def example_hybrid_search():
-    """Example mixing retrievers with web search."""
-    print("\n=== Example 3: Hybrid Search (Retriever + Web) ===")
-
-    # Create retriever
-    retriever = MockRetriever()
-
-    # Use retriever + web search
-    result = quick_summary(
-        query="Compare our internal ML practices with industry standards",
-        retrievers={"internal_kb": retriever},
-        search_tool="auto",  # Will use both retriever and web search
-        search_engines=[
-            "internal_kb",
-            "wikipedia",
-            "searxng",
-        ],  # Specify which to use
-        iterations=3,
-    )
-
-    print(f"Summary: {result['summary'][:200]}...")
-
-
-def example_real_vector_store():
-    """Example with a real vector store (requires OpenAI API key)."""
-    print("\n=== Example 4: Real Vector Store ===")
-    print("This example requires OpenAI API key to be set")
-
-    try:
-        # Create embeddings and vector store
-        embeddings = OpenAIEmbeddings()
-
-        # Create some sample documents
-        texts = [
-            "Machine learning deployment requires careful consideration of infrastructure.",
-            "Model versioning is crucial for production ML systems.",
-            "Monitoring and alerting are essential for ML in production.",
-            "A/B testing helps validate model improvements.",
-            "Feature stores centralize feature computation and storage.",
-        ]
-
-        # Create vector store
-        vectorstore = FAISS.from_texts(texts, embeddings)
-        retriever = vectorstore.as_retriever(search_kwargs={"k": 3})
-
-        # Use with LDR
-        result = quick_summary(
-            query="What are the key considerations for ML deployment?",
-            retrievers={"ml_knowledge": retriever},
-            search_tool="ml_knowledge",
-            iterations=2,
-        )
-
-        print(f"Summary: {result['summary'][:200]}...")
-
-    except Exception as e:
-        print(f"Skipping real vector store example: {e}")
-
-
-def example_selective_retriever_usage():
-    """Example showing how to selectively use different retrievers."""
-    print("\n=== Example 5: Selective Retriever Usage ===")
-
-    # Create specialized retrievers
-    retrievers = {
-        "technical": MockRetriever(),
-        "business": MockRetriever(),
-        "legal": MockRetriever(),
-    }
-
-    # Query 1: Technical only
-    result1 = quick_summary(
-        query="How to implement distributed training?",
-        retrievers=retrievers,
-        search_tool="technical",  # Use only technical retriever
-    )
-    print(f"Technical query result: {result1['summary'][:100]}...")
-
-    # Query 2: Business only
-    result2 = quick_summary(
-        query="What is the ROI of ML investments?",
-        retrievers=retrievers,
-        search_tool="business",  # Use only business retriever
-    )
-    print(f"Business query result: {result2['summary'][:100]}...")
-
-    # Query 3: All retrievers
-    result3 = quick_summary(
-        query="What are the implications of ML adoption?",
-        retrievers=retrievers,
-        search_tool="auto",  # Use all retrievers
-    )
-    print(f"Comprehensive query result: {result3['summary'][:100]}...")
-
-
-if __name__ == "__main__":
-    print("LangChain Retriever Integration Examples")
-    print("=" * 50)
-
-    # Run examples
-    example_single_retriever()
-    example_multiple_retrievers()
-    example_hybrid_search()
-    example_selective_retriever_usage()
-
-    # Uncomment to run vector store example (requires OpenAI API key)
-    # example_real_vector_store()
-
-    print("\n✅ Examples completed!")

@@ -0,0 +1,225 @@
+#!/usr/bin/env python3
+"""
+Search Strategies Example for Local Deep Research
+
+This example demonstrates the two main search strategies:
+1. source-based: Comprehensive research with source citation
+2. focused-iteration: Iterative refinement of research questions
+
+Each strategy has different strengths and use cases.
+"""
+
+from local_deep_research.api import quick_summary, detailed_research
+from local_deep_research.api.settings_utils import create_settings_snapshot
+
+
+def demonstrate_source_based_strategy():
+    """
+    Source-based strategy:
+    - Focuses on gathering and synthesizing information from multiple sources
+    - Provides detailed citations and source tracking
+    - Best for: Academic research, fact-checking, comprehensive reports
+    """
+    print("=" * 70)
+    print("SOURCE-BASED STRATEGY")
+    print("=" * 70)
+    print("""
+This strategy:
+- Systematically searches for sources related to your topic
+- Synthesizes information across multiple sources
+- Provides detailed citations for all claims
+- Ideal for research requiring source verification
+    """)
+
+    # Configure settings for programmatic mode
+    settings = create_settings_snapshot(
+        {
+            "search.tool": "wikipedia",  # Using Wikipedia for demonstration
+        }
+    )
+
+    # Run research with source-based strategy
+    result = detailed_research(
+        query="What are the main causes of climate change?",
+        settings_snapshot=settings,
+        search_strategy="source-based",  # Explicitly set strategy
+        iterations=2,  # Number of research iterations
+        questions_per_iteration=3,  # Questions to explore per iteration
+        programmatic_mode=True,
+    )
+
+    print(f"Research ID: {result['research_id']}")
+    print("\nSummary (first 500 chars):")
+    print(result["summary"][:500] + "...")
+
+    # Show sources found
+    sources = result.get("sources", [])
+    print(f"\nSources found: {len(sources)}")
+    if sources:
+        print("\nFirst 3 sources:")
+        for i, source in enumerate(sources[:3], 1):
+            print(f"  {i}. {source}")
+
+    # Show the questions that were researched
+    questions = result.get("questions", {})
+    print(f"\nQuestions researched across {len(questions)} iterations:")
+    for iteration, qs in questions.items():
+        print(f"\n  Iteration {iteration}:")
+        for q in qs[:2]:  # Show first 2 questions per iteration
+            print(f"    - {q}")
+
+    return result
+
+
+def demonstrate_focused_iteration_strategy():
+    """
+    Focused-iteration strategy:
+    - Iteratively refines the research based on previous findings
+    - Adapts questions based on what's been learned
+    - Best for: Deep dives, evolving research questions, exploratory research
+    """
+    print("\n" + "=" * 70)
+    print("FOCUSED-ITERATION STRATEGY")
+    print("=" * 70)
+    print("""
+This strategy:
+- Starts with initial research on the topic
+- Analyzes findings to generate more targeted questions
+- Iteratively refines understanding through multiple rounds
+- Ideal for complex topics requiring deep exploration
+    """)
+
+    # Configure settings
+    settings = create_settings_snapshot(
+        {
+            "search.tool": "wikipedia",
+        }
+    )
+
+    # Run research with focused-iteration strategy
+    result = quick_summary(
+        query="How do neural networks learn?",
+        settings_snapshot=settings,
+        search_strategy="focused-iteration",  # Use focused iteration
+        iterations=3,  # More iterations for deeper exploration
+        questions_per_iteration=2,  # Fewer but more focused questions
+        temperature=0.7,  # Slightly higher for creative question generation
+        programmatic_mode=True,
+    )
+
+    print("\nSummary (first 500 chars):")
+    print(result["summary"][:500] + "...")
+
+    # Show how questions evolved
+    questions = result.get("questions", {})
+    if questions:
+        print("\nQuestion evolution across iterations:")
+        for iteration, qs in questions.items():
+            print(f"\n  Iteration {iteration}:")
+            for q in qs:
+                print(f"    - {q}")
+
+    # Show findings
+    findings = result.get("findings", [])
+    print(f"\nKey findings: {len(findings)}")
+    if findings:
+        print("\nFirst 2 findings:")
+        for i, finding in enumerate(findings[:2], 1):
+            text = (
+                finding.get("text", "N/A")
+                if isinstance(finding, dict)
+                else str(finding)
+            )
+            print(f"  {i}. {text[:150]}...")
+
+    return result
+
+
+def compare_strategies():
+    """
+    Direct comparison of both strategies on the same topic.
+    """
+    print("\n" + "=" * 70)
+    print("STRATEGY COMPARISON")
+    print("=" * 70)
+    print(
+        "\nComparing both strategies on the same topic: 'Quantum Computing Applications'\n"
+    )
+
+    settings = create_settings_snapshot(
+        {
+            "search.tool": "wikipedia",
+        }
+    )
+
+    # Same topic, different strategies
+    topic = "Quantum computing applications in cryptography"
+
+    print("1. Source-based approach:")
+    source_result = quick_summary(
+        query=topic,
+        settings_snapshot=settings,
+        search_strategy="source-based",
+        iterations=2,
+        questions_per_iteration=3,
+        programmatic_mode=True,
+    )
+    print(f"   - Sources found: {len(source_result.get('sources', []))}")
+    print(f"   - Summary length: {len(source_result.get('summary', ''))} chars")
+    print(f"   - Findings: {len(source_result.get('findings', []))}")
+
+    print("\n2. Focused-iteration approach:")
+    focused_result = quick_summary(
+        query=topic,
+        settings_snapshot=settings,
+        search_strategy="focused-iteration",
+        iterations=2,
+        questions_per_iteration=3,
+        programmatic_mode=True,
+    )
+    print(f"   - Sources found: {len(focused_result.get('sources', []))}")
+    print(
+        f"   - Summary length: {len(focused_result.get('summary', ''))} chars"
+    )
+    print(f"   - Findings: {len(focused_result.get('findings', []))}")
+
+    print("\n" + "=" * 70)
+    print("WHEN TO USE EACH STRATEGY")
+    print("=" * 70)
+    print("""
+Use SOURCE-BASED when you need:
+- Comprehensive coverage with citations
+- Academic or professional research
+- Fact-checking and verification
+- Documentation with source tracking
+
+Use FOCUSED-ITERATION when you need:
+- Deep exploration of complex topics
+- Adaptive research that evolves
+- Discovery of unexpected connections
+- Exploratory or investigative research
+    """)
+
+
+def main():
+    """Run all demonstrations."""
+    print("=" * 70)
+    print("LOCAL DEEP RESEARCH - SEARCH STRATEGIES DEMONSTRATION")
+    print("=" * 70)
+
+    # Demonstrate each strategy
+    demonstrate_source_based_strategy()
+    demonstrate_focused_iteration_strategy()
+
+    # Compare strategies
+    compare_strategies()
+
+    print("\n✓ Search strategies demonstration complete!")
+    print("\nNote: Both strategies can be combined with different search tools")
+    print(
+        "(wikipedia, arxiv, searxng, etc.) and custom parameters for optimal results."
+    )
+
+
+if __name__ == "__main__":
+    main()

@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+"""
+Example of using SearXNG search engine with Local Deep Research.
+
+This demonstrates how to use SearXNG for web search in programmatic mode.
+Note: Requires a running SearXNG instance.
+"""
+
+import os
+from langchain_ollama import ChatOllama
+from local_deep_research.search_system import AdvancedSearchSystem
+from local_deep_research.web_search_engines.engines.search_engine_searxng import (
+    SearXNGSearchEngine,
+)
+
+# Re-enable logging
+from loguru import logger
+import sys
+
+logger.remove()
+logger.add(sys.stderr, level="INFO", format="{time} {level} {message}")
+logger.enable("local_deep_research")
+
+
+def main():
+    """Demonstrate using SearXNG with Local Deep Research."""
+    print("=== SearXNG Search Engine Example ===\n")
+
+    # Check if SearXNG URL is configured
+    searxng_url = os.getenv("SEARXNG_URL", "http://localhost:8080")
+    print(f"Using SearXNG instance at: {searxng_url}")
+    print(
+        "(Set SEARXNG_URL environment variable to use a different instance)\n"
+    )
+
+    # 1. Create LLM
+    print("1. Setting up Ollama LLM...")
+    llm = ChatOllama(model="gemma3:12b", temperature=0.3)
+
+    # 2. Configure settings
+    settings = {
+        "search.iterations": 2,
+        "search.questions_per_iteration": 3,
+        "search.strategy": "source-based",
+        "rate_limiting.enabled": False,  # Disable rate limiting for demo
+        # SearXNG specific settings
+        "search_engines.searxng.base_url": searxng_url,
+        "search_engines.searxng.timeout": 30,
+        "search_engines.searxng.categories": ["general", "science"],
+        "search_engines.searxng.engines": ["google", "duckduckgo", "bing"],
+        "search_engines.searxng.language": "en",
+        "search_engines.searxng.time_range": "",  # all time
+        "search_engines.searxng.safesearch": 0,  # 0=off, 1=moderate, 2=strict
+    }
+
+    # 3. Create SearXNG search engine
+    print("2. Initializing SearXNG search engine...")
+    try:
+        search_engine = SearXNGSearchEngine(settings_snapshot=settings)
+
+        # Test the connection
+        print("   Testing SearXNG connection...")
+        test_results = search_engine.run("test query", research_context={})
+        if test_results:
+            print(
+                f"   ✓ SearXNG is working! Got {len(test_results)} test results."
+            )
+        else:
+            print("   ⚠ SearXNG returned no results for test query.")
+    except Exception as e:
+        print(f"\n⚠ Error connecting to SearXNG: {e}")
+        print("\nPlease ensure SearXNG is running. You can start it with:")
+        print("  docker run -p 8888:8080 searxng/searxng")
+        print("\nFalling back to mock search engine for demonstration...")
+
+        # Fallback to mock search engine
+        class MockSearchEngine:
+            def __init__(self, settings_snapshot=None):
+                self.settings_snapshot = settings_snapshot or {}
+
+            def run(self, query, research_context=None):
+                return [
+                    {
+                        "title": f"Result for: {query}",
+                        "link": "https://example.com/result",
+                        "snippet": f"This is a mock result for the query: {query}. "
+                        "In a real scenario, SearXNG would provide actual web search results.",
+                        "full_content": "Full content would be fetched here...",
+                        "rank": 1,
+                    }
+                ]
+
+        search_engine = MockSearchEngine(settings)
+
+    # 4. Create the search system
+    print("3. Creating AdvancedSearchSystem...")
+    # Pass programmatic_mode=True to disable database dependencies
+    search_system = AdvancedSearchSystem(
+        llm=llm,
+        search=search_engine,
+        settings_snapshot=settings,
+        programmatic_mode=True,
+    )
+
+    # 5. Run research queries
+    queries = [
+        "What are the latest developments in quantum computing in 2024?",
+        "How does CRISPR gene editing technology work?",
+    ]
+
+    for query in queries:
+        print(f"\n{'=' * 60}")
+        print(f"Research Query: {query}")
+        print("=" * 60)
+
+        try:
+            result = search_system.analyze_topic(query)
+
+            # Display results
+            print("\n=== RESEARCH FINDINGS ===")
+            if result.get("formatted_findings"):
+                print(result["formatted_findings"])
+            else:
+                print(
+                    "Summary:", result.get("current_knowledge", "No findings")
+                )
+
+            # Show metadata
+            print("\n=== METADATA ===")
+            print(f"• Iterations completed: {result.get('iterations', 0)}")
+            print(f"• Total findings: {len(result.get('findings', []))}")
+
+            # Show search sources from all_links_of_system or search_results in findings
+            all_links = result.get("all_links_of_system", [])
+
+            # Also check findings for search_results
+            for finding in result.get("findings", []):
+                if "search_results" in finding and finding["search_results"]:
+                    all_links = finding["search_results"]
+                    break
+
+            if all_links:
+                print(f"• Sources found: {len(all_links)}")
+                for i, link in enumerate(
+                    all_links[:5], 1
+                ):  # Show first 5 sources
+                    if isinstance(link, dict):
+                        title = link.get("title", "No title")
+                        url = link.get("link", "Unknown")
+                        print(f"  [{i}] {title}")
+                        print(f"      {url}")
+
+            # Show generated questions
+            if result.get("questions_by_iteration"):
+                print("\n=== RESEARCH QUESTIONS ===")
+                for iteration, questions in result[
+                    "questions_by_iteration"
+                ].items():
+                    print(f"Iteration {iteration}:")
+                    for q in questions[
+                        :2
+                    ]:  # Show first 2 questions per iteration
+                        print(f"  • {q}")
+
+        except Exception as e:
+            logger.exception("Error during research")
+            print(f"\n⚠ Error: {e}")
+
+    print("\n✓ SearXNG integration example completed!")
+    print(
+        "\nNote: For best results, ensure SearXNG is properly configured with multiple search engines."
+    )
+
+
+if __name__ == "__main__":
+    main()

@@ -5,11 +5,33 @@
 Quick example showing how to use the LDR Python API directly.
 """
 
-from local_deep_research.api import quick_summary, detailed_research
+from local_deep_research.api import (
+    detailed_research,
+    quick_summary,
+    generate_report,
+)
+from local_deep_research.api.settings_utils import (
+    create_settings_snapshot,
+)
+
+# Use default settings with minimal overrides
+# This provides all necessary settings with sensible defaults
+settings_snapshot = create_settings_snapshot(
+    overrides={
+        "search.tool": "wikipedia",  # Use Wikipedia for this example
+    }
+)
+
+# Alternative: Use completely default settings
+# settings_snapshot = get_default_settings_snapshot()
 
 # Example 1: Quick Summary
 print("=== Quick Summary ===")
-result = quick_summary("What is machine learning?")
+result = quick_summary(
+    "What is machine learning?",
+    settings_snapshot=settings_snapshot,
+    programmatic_mode=True,
+)
 print(f"Summary: {result['summary'][:300]}...")
 print(f"Found {len(result.get('findings', []))} findings")
 
@@ -20,6 +42,8 @@
     iterations=2,
     search_tool="wikipedia",
     search_strategy="source_based",
+    settings_snapshot=settings_snapshot,
+    programmatic_mode=True,
 )
 print(f"Research ID: {result['research_id']}")
 print(f"Summary length: {len(result['summary'])} characters")
@@ -35,23 +59,27 @@
     temperature=0.5,  # Lower temperature for focused results
     provider="openai_endpoint",  # Specify LLM provider
     model_name="llama-3.3-70b-instruct",  # Specify model
+    settings_snapshot=settings_snapshot,
+    programmatic_mode=True,
 )
 print(f"Completed {result['iterations']} iterations")
 print(
     f"Generated {sum(len(qs) for qs in result.get('questions', {}).values())} questions"
 )
 
 # Example 4: Generate and Save a Report
-print("\n=== Generate Report (Optional - Uncomment to run) ===")
+print("\n=== Generate Report ===")
 print("Note: Report generation can take several minutes")
-# Uncomment the following to generate a full report:
-"""
+
+# Generate a comprehensive report
 report = generate_report(
     query="Future of artificial intelligence",
     output_file="ai_future_report.md",  # Save directly to file
     searches_per_section=2,
-    iterations=1
+    iterations=1,
+    settings_snapshot=settings_snapshot,  # Now works with programmatic mode!
 )
 print(f"Report saved to: {report.get('file_path', 'ai_future_report.md')}")
 print(f"Report length: {len(report['content'])} characters")
-"""
+print("Report preview (first 300 chars):")
+print(report["content"][:300] + "...")

@@ -0,0 +1,30 @@
+#!/usr/bin/env python3
+"""Test importing search_system directly without going through __init__.py"""
+
+import sys
+
+# Try importing the search_system module directly
+try:
+    print("Attempting to import search_system module directly...")
+    from local_deep_research import search_system
+
+    print("✓ search_system module imported!")
+
+    # Now try to access AdvancedSearchSystem
+    print("\nTrying to access AdvancedSearchSystem class...")
+    AdvancedSearchSystem = search_system.AdvancedSearchSystem
+    print("✓ Got AdvancedSearchSystem class!")
+
+except Exception as e:
+    print(f"✗ Failed: {e}")
+    import traceback
+
+    traceback.print_exc()
+
+# Also try a more direct import
+try:
+    print("\nAttempting direct file import...")
+    sys.path.insert(0, "src")
+    print("✓ Direct import worked!")
+except Exception as e:
+    print(f"✗ Direct import failed: {e}")

@@ -2,14 +2,22 @@
 
 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_http_example.py` - Quick start example
+  - `simple_http_example.py` - Quick start example (needs updating for auth)
   - `http_api_examples.py` - Comprehensive examples including batch processing
 
 ## Quick Start
@@ -18,27 +26,52 @@ This directory contains examples for using LDR through different interfaces.
 
 ```python
 from local_deep_research.api import quick_summary
-
-result = quick_summary("What is quantum computing?")
-print(result["summary"])
+from local_deep_research.settings import CachedSettingsManager
+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 = CachedSettingsManager(session, "your_username")
+    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)
 
 First, start the server:
 ```bash
-python -m src.local_deep_research.web.app
+python -m local_deep_research.web.app
 ```
 
-Then use the API:
+Then authenticate and use the API:
 ```python
 import requests
 
-response = requests.post(
-    "http://localhost:5000/api/v1/quick_summary",
-    json={"query": "What is quantum computing?"}
+# Create session for cookie persistence
+session = requests.Session()
+
+# Login
+session.post(
+    "http://localhost:5000/auth/login",
+    json={"username": "your_username", "password": "your_password"}
+)
+
+# 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/research/api/start",
+    json={"query": "What is quantum computing?"},
+    headers={"X-CSRF-Token": csrf_token}
 )
-print(response.json()["summary"])
+print(response.json())
 ```
 
 ## Which API Should I Use?
@@ -48,19 +81,63 @@ print(response.json()["summary"])
   - ✅ 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` → `/research/api/start`)
+4. **CSRF Protection**: POST/PUT/DELETE requests need CSRF token
+
+### Migration Guide
+
+#### Old (v1.x):
+```python
+# 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+):
+```python
+# Programmatic - with authentication and settings
+with get_user_db_session(username, password) as session:
+    settings_manager = CachedSettingsManager(session, username)
+    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
 ```bash
-# Run the retriever example
+# Update credentials in the example files first!
 python examples/api_usage/programmatic/retriever_usage_example.py
 
 # Or use the Jupyter notebook
@@ -70,9 +147,16 @@ jupyter notebook examples/api_usage/programmatic/programmatic_access.ipynb
 ### HTTP Examples
 ```bash
 # First, start the LDR server
-python -m src.local_deep_research.web.app
+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](../../docs/api-quickstart.md)
+- Check the [FAQ](../../docs/faq.md)
+- Join our [Discord](https://discord.gg/ttcqQeFcJ3) for support

@@ -0,0 +1,65 @@
+# Important: Examples Updated for LDR v1.0
+
+## Authentication Required
+
+Starting with LDR v1.0, all API access requires authentication due to the new per-user encrypted database architecture.
+
+## Updated Examples
+
+The following examples have been updated for v1.0:
+
+### ✅ Updated Examples:
+- `http/simple_http_example.py` - Basic HTTP API usage with authentication
+- `http/http_api_examples.py` - Comprehensive HTTP API examples with LDRClient class
+- `programmatic/retriever_usage_example.py` - LangChain retriever integration with auth
+- `programmatic/programmatic_access_v1.py` - NEW: Complete programmatic API examples
+
+### ⚠️ Needs Manual Update:
+- `programmatic/programmatic_access.ipynb` - Jupyter notebook (see programmatic_access_v1.py for reference)
+
+## Quick Migration Guide
+
+### Old Code (pre-v1.0):
+```python
+from local_deep_research.api import quick_summary
+result = quick_summary("query")
+```
+
+### New Code (v1.0+):
+```python
+from local_deep_research.api import quick_summary
+from local_deep_research.settings import CachedSettingsManager
+from local_deep_research.database.session_context import get_user_db_session
+
+with get_user_db_session(username="user", password="pass") as session:
+    settings_manager = CachedSettingsManager(session, "user")
+    settings_snapshot = settings_manager.get_all_settings()
+    result = quick_summary("query", settings_snapshot=settings_snapshot)
+```
+
+## Before Running Examples
+
+1. **Create an account**:
+   ```bash
+   python -m local_deep_research.web.app
+   # Open http://localhost:5000 and register
+   ```
+
+2. **Configure LLM provider** in Settings (e.g., OpenAI, Anthropic, Ollama)
+
+3. **Update credentials** in the example files:
+   - Change `USERNAME = "your_username"` to your actual username
+   - Change `PASSWORD = "your_password"` to your actual password
+
+## Common Issues
+
+- **"No settings context available"**: Pass `settings_snapshot` to API functions
+- **"Encrypted database requires password"**: Use `get_user_db_session()` with credentials
+- **"CSRF token missing"**: Get CSRF token before POST/PUT/DELETE requests
+- **404 errors**: Check new endpoint paths (e.g., `/research/api/start`)
+
+## Need Help?
+
+- See [Migration Guide](../../docs/MIGRATION_GUIDE_v1.md) for detailed changes
+- Check [API Quick Start](../../docs/api-quickstart.md) for authentication details
+- Join our [Discord](https://discord.gg/ttcqQeFcJ3) for support

@@ -11,12 +11,13 @@
 import random
 import re
 import sys
+from pathlib import Path
 from typing import Optional
 
 import pandas as pd
 
 # Set up Python path
-current_dir = os.path.dirname(os.path.abspath(__file__))
+current_dir = str(Path(__file__).parent.resolve())
 sys.path.insert(0, current_dir)
 
 try:
@@ -70,10 +71,10 @@ def decrypt(ciphertext_b64: str, password: str) -> str:
     try:
         encrypted = base64.b64decode(ciphertext_b64)
         key = derive_key(password, len(encrypted))
-        decrypted = bytes(a ^ b for a, b in zip(encrypted, key))
+        decrypted = bytes(a ^ b for a, b in zip(encrypted, key, strict=False))
         return decrypted.decode()
     except Exception as e:
-        print(f"Error decrypting data: {str(e)}")
+        print(f"Error decrypting data: {e!s}")
         return f"Error: Could not decrypt data: {str(e)[:100]}"
 
 
@@ -91,8 +92,8 @@ def run_browsecomp_evaluation(
     Run the BrowseComp evaluation using Local Deep Research.
     """
     # Ensure output directory exists
-    os.makedirs(output_dir, exist_ok=True)
-    output_path = os.path.join(output_dir, output_file)
+    Path(output_dir).mkdir(parents=True, exist_ok=True)
+    output_path = str(Path(output_dir) / output_file)
 
     # Load BrowseComp dataset
     print(f"Loading dataset from {dataset_path}")
@@ -113,7 +114,7 @@ def run_browsecomp_evaluation(
         print(f"Sampled {num_examples} examples from {len(df)} total examples")
 
     # Remove output file if it exists to avoid appending
-    if os.path.exists(output_path):
+    if Path(output_path).exists():
         os.remove(output_path)
 
     results = []
@@ -216,7 +217,7 @@ def run_browsecomp_evaluation(
             )
 
         except Exception as e:
-            print(f"Error processing question {i + 1}: {str(e)}")
+            print(f"Error processing question {i + 1}: {e!s}")
             # In case of error, write a placeholder result
             result = {
                 "id": example.get("id", f"q{i}"),
@@ -245,7 +246,7 @@ def run_browsecomp_evaluation(
         "search_tool": search_tool,
     }
 
-    report_path = os.path.join(output_dir, "browsecomp_summary.json")
+    report_path = str(Path(output_dir) / "browsecomp_summary.json")
     with open(report_path, "w") as f:
         json.dump(report, f, indent=2)
 

@@ -12,84 +12,70 @@
 - Provides detailed metrics and accuracy reports
 """
 
-import logging
 import os
 import sys
 import time
-from datetime import datetime
+from datetime import datetime, UTC
+from pathlib import Path
+
 
 # Set up Python path
-src_dir = os.path.abspath(os.path.join(os.path.dirname(__file__), "src"))
+src_dir = str((Path(__file__).parent / "src").resolve())
 if src_dir not in sys.path:
     sys.path.insert(0, src_dir)
 
-# Set the data directory with the database
-data_dir = os.path.join(src_dir, "data")
-if os.path.exists(os.path.join(data_dir, "ldr.db")):
-    print(f"Found database at {os.path.join(data_dir, 'ldr.db')}")
-    # Set environment variable to use this database
-    os.environ["LDR_DATA_DIR"] = data_dir
-else:
-    print(f"Warning: Database not found at {os.path.join(data_dir, 'ldr.db')}")
+# Note: Database configuration is now per-user
+# For benchmarks, API keys should be provided via environment variables
+# or configuration files rather than relying on a shared database
 
-# Configure logging
-logging.basicConfig(
-    level=logging.INFO,
-    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
-)
-logger = logging.getLogger(__name__)
+# Logger is already imported from loguru
 
 
 def setup_grading_config():
     """
-    Create a custom evaluation configuration that uses the local database
+    Create a custom evaluation configuration that uses environment variables
     for API keys and specifically uses Claude 3 Sonnet for grading.
 
     Returns:
         Dict containing the evaluation configuration
     """
-    # Import necessary function to get database settings
-    try:
-        from local_deep_research.utilities.db_utils import get_db_setting
-    except ImportError as e:
-        print(f"Error importing database utilities: {e}")
-        print("Current sys.path:", sys.path)
-        return None
 
     # Create config that uses Claude 3 Sonnet via Anthropic directly
-    # This will use the API key from the database
     # Only use parameters that get_llm() accepts
     evaluation_config = {
         "model_name": "claude-3-sonnet-20240229",  # Correct Anthropic model name
         "provider": "anthropic",  # Use Anthropic directly
         "temperature": 0,  # Zero temp for consistent evaluation
     }
 
-    # Check if anthropic API key is available in the database
-    try:
-        anthropic_key = get_db_setting("llm.anthropic.api_key")
-        if anthropic_key:
+    # Check if anthropic API key is available in environment
+    anthropic_key = os.environ.get("ANTHROPIC_API_KEY")
+    if anthropic_key:
+        print(
+            "Found Anthropic API key in environment, will use Claude 3 Sonnet for grading"
+        )
+    else:
+        print(
+            "Warning: No Anthropic API key found in ANTHROPIC_API_KEY environment variable"
+        )
+        print("Checking for alternative providers...")
+
+        # Try OpenRouter as a fallback
+        openrouter_key = os.environ.get("OPENROUTER_API_KEY")
+        if openrouter_key:
             print(
-                "Found Anthropic API key in database, will use Claude 3 Sonnet for grading"
+                "Found OpenRouter API key, will use OpenRouter with Claude 3 Sonnet"
             )
+            evaluation_config = {
+                "model_name": "anthropic/claude-3-sonnet-20240229",  # OpenRouter format
+                "provider": "openai_endpoint",
+                "openai_endpoint_url": "https://openrouter.ai/api/v1",
+                "temperature": 0,
+            }
         else:
-            print("Warning: No Anthropic API key found in database")
-            print("Checking for alternative providers...")
-
-            # Try OpenRouter as a fallback
-            openrouter_key = get_db_setting("llm.openai_endpoint.api_key")
-            if openrouter_key:
-                print(
-                    "Found OpenRouter API key, will use OpenRouter with Claude 3 Sonnet"
-                )
-                evaluation_config = {
-                    "model_name": "anthropic/claude-3-sonnet-20240229",  # OpenRouter format
-                    "provider": "openai_endpoint",
-                    "openai_endpoint_url": "https://openrouter.ai/api/v1",
-                    "temperature": 0,
-                }
-    except Exception as e:
-        print(f"Error checking for API keys: {e}")
+            print("ERROR: No API keys found in environment variables")
+            print("Please set either ANTHROPIC_API_KEY or OPENROUTER_API_KEY")
+            return None
 
     return evaluation_config
 
@@ -159,11 +145,9 @@ def custom_get_evaluation_llm(custom_config=None):
         traceback.print_exc()
 
     # Create timestamp for output
-    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
-    output_dir = os.path.join(
-        "benchmark_results", f"claude_grading_{timestamp}"
-    )
-    os.makedirs(output_dir, exist_ok=True)
+    timestamp = datetime.now(UTC).strftime("%Y%m%d_%H%M%S")
+    output_dir = str(Path("benchmark_results") / f"claude_grading_{timestamp}")
+    Path(output_dir).mkdir(parents=True, exist_ok=True)
 
     config = {
         "search_strategy": strategy,
@@ -190,7 +174,7 @@ def custom_get_evaluation_llm(custom_config=None):
         simpleqa_results = simpleqa.evaluate(
             config,
             num_examples=examples,
-            output_dir=os.path.join(output_dir, "simpleqa"),
+            output_dir=str(Path(output_dir) / "simpleqa"),
         )
 
         simpleqa_duration = time.time() - simpleqa_start
@@ -203,7 +187,7 @@ def custom_get_evaluation_llm(custom_config=None):
         # Save results
         import json
 
-        with open(os.path.join(output_dir, "simpleqa_results.json"), "w") as f:
+        with open(Path(output_dir) / "simpleqa_results.json", "w") as f:
             json.dump(simpleqa_results, f, indent=2)
     except Exception as e:
         print(f"Error during SimpleQA evaluation: {e}")
@@ -226,7 +210,7 @@ def custom_get_evaluation_llm(custom_config=None):
         browsecomp_results = browsecomp.evaluate(
             config,
             num_examples=examples,
-            output_dir=os.path.join(output_dir, "browsecomp"),
+            output_dir=str(Path(output_dir) / "browsecomp"),
         )
 
         browsecomp_duration = time.time() - browsecomp_start
@@ -237,9 +221,7 @@ def custom_get_evaluation_llm(custom_config=None):
         print(f"BrowseComp metrics: {browsecomp_results.get('metrics', {})}")
 
         # Save results
-        with open(
-            os.path.join(output_dir, "browsecomp_results.json"), "w"
-        ) as f:
+        with open(Path(output_dir) / "browsecomp_results.json", "w") as f:
             json.dump(browsecomp_results, f, indent=2)
     except Exception as e:
         print(f"Error during BrowseComp evaluation: {e}")
@@ -262,7 +244,7 @@ def custom_get_evaluation_llm(custom_config=None):
         composite_results = composite.evaluate(
             config,
             num_examples=examples,
-            output_dir=os.path.join(output_dir, "composite"),
+            output_dir=str(Path(output_dir) / "composite"),
         )
 
         composite_duration = time.time() - composite_start
@@ -272,7 +254,7 @@ def custom_get_evaluation_llm(custom_config=None):
         print(f"Composite score: {composite_results.get('score', 0):.4f}")
 
         # Save results
-        with open(os.path.join(output_dir, "composite_results.json"), "w") as f:
+        with open(Path(output_dir) / "composite_results.json", "w") as f:
             json.dump(composite_results, f, indent=2)
     except Exception as e:
         print(f"Error during composite evaluation: {e}")

@@ -3,10 +3,10 @@
 Fixed benchmark with Gemini 2.0 Flash via OpenRouter
 """
 
-import os
 import sys
 import time
-from datetime import datetime
+from datetime import datetime, UTC
+from pathlib import Path
 
 # Import the benchmark functions
 from local_deep_research.benchmarks.benchmark_functions import (
@@ -62,11 +62,13 @@ def run_benchmark(examples=1):
     """Run benchmarks with Gemini 2.0 Flash"""
     try:
         # Create timestamp for output
-        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
-        output_dir = os.path.join(
-            "../../benchmark_results", f"gemini_eval_{timestamp}"
+        timestamp = datetime.now(UTC).strftime("%Y%m%d_%H%M%S")
+        output_dir = str(
+            Path(__file__).parent.parent.parent
+            / "benchmark_results"
+            / f"gemini_eval_{timestamp}"
         )
-        os.makedirs(output_dir, exist_ok=True)
+        Path(output_dir).mkdir(parents=True, exist_ok=True)
 
         # Setup the Gemini configuration
         gemini_config = setup_gemini_config()
@@ -82,7 +84,7 @@ def run_benchmark(examples=1):
             search_tool="searxng",
             evaluation_model=gemini_config["model_name"],
             evaluation_provider=gemini_config["provider"],
-            output_dir=os.path.join(output_dir, "simpleqa"),
+            output_dir=str(Path(output_dir) / "simpleqa"),
         )
 
         simpleqa_duration = time.time() - simpleqa_start
@@ -110,7 +112,7 @@ def run_benchmark(examples=1):
             search_tool="searxng",
             evaluation_model=gemini_config["model_name"],
             evaluation_provider=gemini_config["provider"],
-            output_dir=os.path.join(output_dir, "browsecomp"),
+            output_dir=str(Path(output_dir) / "browsecomp"),
         )
 
         browsecomp_duration = time.time() - browsecomp_start

@@ -21,6 +21,7 @@
 import re
 import sys
 import time
+from pathlib import Path
 from typing import Any, Dict
 
 from loguru import logger
@@ -44,11 +45,11 @@ def decrypt(ciphertext_b64: str, password: str) -> str:
     try:
         encrypted = base64.b64decode(ciphertext_b64)
         key = derive_key(password, len(encrypted))
-        decrypted = bytes(a ^ b for a, b in zip(encrypted, key))
+        decrypted = bytes(a ^ b for a, b in zip(encrypted, key, strict=False))
         return decrypted.decode()
     except Exception as e:
-        logger.error(f"Error decrypting data: {str(e)}")
-        return f"Error: Could not decrypt data - {str(e)}"
+        logger.exception(f"Error decrypting data: {e!s}")
+        return f"Error: Could not decrypt data - {e!s}"
 
 
 def run_browsecomp_with_canary(
@@ -83,16 +84,16 @@ def run_browsecomp_with_canary(
 
     # Set up output files
     timestamp = time.strftime("%Y%m%d_%H%M%S")
-    results_file = os.path.join(
-        output_dir, f"browsecomp_{timestamp}_results.jsonl"
+    results_file = str(
+        Path(output_dir) / f"browsecomp_{timestamp}_results.jsonl"
     )
-    evaluation_file = os.path.join(
-        output_dir, f"browsecomp_{timestamp}_evaluation.jsonl"
+    evaluation_file = str(
+        Path(output_dir) / f"browsecomp_{timestamp}_evaluation.jsonl"
     )
 
     # Make sure output files don't exist
     for file in [results_file, evaluation_file]:
-        if os.path.exists(file):
+        if Path(file).exists():
             os.remove(file)
 
     # Process each example
@@ -173,7 +174,7 @@ def run_browsecomp_with_canary(
                 f.write(json.dumps(result) + "\n")
 
         except Exception as e:
-            logger.error(f"Error processing example {i + 1}: {str(e)}")
+            logger.exception(f"Error processing example {i + 1}: {e!s}")
 
             # Create error result
             error_result = {
@@ -212,7 +213,7 @@ def run_browsecomp_with_canary(
             dataset_type="browsecomp",
         )
     except Exception as e:
-        logger.error(f"Evaluation failed: {str(e)}")
+        logger.exception(f"Evaluation failed: {e!s}")
         evaluation_results = []
 
     # Calculate basic metrics
@@ -266,7 +267,7 @@ def main():
     parser.add_argument(
         "--output-dir",
         type=str,
-        default=os.path.join("examples", "benchmarks", "results", "browsecomp"),
+        default=str(Path("examples") / "benchmarks" / "results" / "browsecomp"),
         help="Output directory",
     )
 

@@ -17,6 +17,7 @@
 import os
 import time
 from datetime import datetime
+from pathlib import Path
 
 # Import the benchmark functionality
 from local_deep_research.benchmarks.benchmark_functions import (
@@ -61,11 +62,13 @@ def run_benchmark(args):
     os.environ["LDR_LLM__OPENAI_ENDPOINT_URL"] = config["openai_endpoint_url"]
 
     # Create timestamp for output directory
-    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
-    base_output_dir = os.path.join(
-        "examples", "benchmarks", "results", f"gemini_{timestamp}"
+    from datetime import timezone
+
+    timestamp = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
+    base_output_dir = str(
+        Path("examples") / "benchmarks" / "results" / f"gemini_{timestamp}"
     )
-    os.makedirs(base_output_dir, exist_ok=True)
+    Path(base_output_dir).mkdir(parents=True, exist_ok=True)
 
     # Configure benchmark settings
     results = {}
@@ -76,7 +79,7 @@ def run_benchmark(args):
             {
                 "name": "SimpleQA",
                 "function": evaluate_simpleqa,
-                "output_dir": os.path.join(base_output_dir, "simpleqa"),
+                "output_dir": str(Path(base_output_dir) / "simpleqa"),
             }
         )
 
@@ -85,7 +88,7 @@ def run_benchmark(args):
             {
                 "name": "BrowseComp",
                 "function": evaluate_browsecomp,
-                "output_dir": os.path.join(base_output_dir, "browsecomp"),
+                "output_dir": str(Path(base_output_dir) / "browsecomp"),
             }
         )
 

@@ -20,7 +20,7 @@
 import os
 import sys
 import time
-from datetime import datetime
+from datetime import datetime, UTC
 from pathlib import Path
 from typing import Any, Dict, Optional, Tuple
 
@@ -38,19 +38,16 @@
 )
 from local_deep_research.benchmarks.runners import format_query
 
-
 # Add the src directory to the Python path
-project_root = os.path.abspath(
-    os.path.dirname(os.path.dirname(os.path.dirname(__file__)))
-)
+project_root = str(Path(__file__).parent.parent.parent.resolve())
 
 logger.enable("local_deep_research")
 
 
 def load_existing_results(results_file: str) -> Dict[str, Dict]:
     """Load existing results from JSONL file."""
     results = {}
-    if os.path.exists(results_file):
+    if Path(results_file).exists():
         logger.info(f"Loading existing results from: {results_file}")
         with open(results_file, "r") as f:
             for line in f:
@@ -74,8 +71,8 @@ def find_latest_results_file(
 ) -> Optional[str]:
     """Find the most recent results file for a dataset."""
     # First try dataset subdirectory
-    dataset_dir = os.path.join(output_dir, dataset_type)
-    if os.path.exists(dataset_dir):
+    dataset_dir = str(Path(output_dir) / dataset_type)
+    if Path(dataset_dir).exists():
         pattern = f"{dataset_type}_*_results.jsonl"
         files = list(Path(dataset_dir).glob(pattern))
         if files:
@@ -112,15 +109,15 @@ def run_resumable_benchmark(
     )
 
     # Determine output files
-    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
-    results_file = os.path.join(
-        output_dir, f"{dataset_type}_{timestamp}_results.jsonl"
+    timestamp = datetime.now(UTC).strftime("%Y%m%d_%H%M%S")
+    results_file = str(
+        Path(output_dir) / f"{dataset_type}_{timestamp}_results.jsonl"
     )
-    evaluation_file = os.path.join(
-        output_dir, f"{dataset_type}_{timestamp}_evaluation.jsonl"
+    evaluation_file = str(
+        Path(output_dir) / f"{dataset_type}_{timestamp}_evaluation.jsonl"
     )
-    report_file = os.path.join(
-        output_dir, f"{dataset_type}_{timestamp}_report.md"
+    report_file = str(
+        Path(output_dir) / f"{dataset_type}_{timestamp}_report.md"
     )
 
     # Load existing results if resuming
@@ -222,7 +219,7 @@ def run_resumable_benchmark(
                     f.write(json.dumps(result) + "\n")
 
             except Exception as e:
-                logger.error(f"Error processing example {i + 1}: {str(e)}")
+                logger.exception("Error processing example")
                 error_count += 1
 
                 # Create error result
@@ -274,7 +271,7 @@ def run_resumable_benchmark(
             "errors": error_count,
         }
     except Exception as e:
-        logger.error(f"Error during evaluation: {str(e)}")
+        logger.exception("Error during evaluation")
         return {
             "accuracy": 0,
             "metrics": {},
@@ -298,7 +295,7 @@ def run_simpleqa_benchmark_wrapper(args: Tuple) -> Dict[str, Any]:
     results = run_resumable_benchmark(
         dataset_type="simpleqa",
         num_examples=num_examples,
-        output_dir=os.path.join(output_dir, "simpleqa"),
+        output_dir=str(Path(output_dir) / "simpleqa"),
         search_config=search_config,
         evaluation_config=evaluation_config,
         resume_from=resume_from,
@@ -325,7 +322,7 @@ def run_browsecomp_benchmark_wrapper(args: Tuple) -> Dict[str, Any]:
     results = run_resumable_benchmark(
         dataset_type="browsecomp",
         num_examples=num_examples,
-        output_dir=os.path.join(output_dir, "browsecomp"),
+        output_dir=str(Path(output_dir) / "browsecomp"),
         search_config=browsecomp_config,
         evaluation_config=evaluation_config,
         resume_from=resume_from,
@@ -411,19 +408,23 @@ def main():
     # Determine output directory
     if args.resume_from:
         # Create new directory but link to old results
-        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
-        output_dir = os.path.join(
-            project_root, "benchmark_results", f"resumed_benchmark_{timestamp}"
+        timestamp = datetime.now(UTC).strftime("%Y%m%d_%H%M%S")
+        output_dir = str(
+            Path(project_root)
+            / "benchmark_results"
+            / f"resumed_benchmark_{timestamp}"
         )
-        os.makedirs(output_dir, exist_ok=True)
+        Path(output_dir).mkdir(parents=True, exist_ok=True)
         logger.info(
             f"Resuming from {args.resume_from}, new results in {output_dir}"
         )
     else:
         # Create new timestamp directory
-        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
-        output_dir = os.path.join(
-            project_root, "benchmark_results", f"parallel_benchmark_{timestamp}"
+        timestamp = datetime.now(UTC).strftime("%Y%m%d_%H%M%S")
+        output_dir = str(
+            Path(project_root)
+            / "benchmark_results"
+            / f"parallel_benchmark_{timestamp}"
         )
         os.makedirs(output_dir, exist_ok=True)
         logger.info(f"Starting new benchmark in: {output_dir}")
@@ -516,8 +517,8 @@ def main():
                 print(
                     f"BrowseComp benchmark completed: {result['new_results']} new, {result['reused_results']} reused"
                 )
-        except Exception as e:
-            logger.error(f"Error in {dataset_name} benchmark: {e}")
+        except Exception:
+            logger.exception("Error in benchmark")
 
     # Calculate total time
     total_duration = time.time() - total_start_time
@@ -566,12 +567,12 @@ def main():
         }
 
         with open(
-            os.path.join(output_dir, "parallel_benchmark_summary.json"), "w"
+            Path(output_dir) / "parallel_benchmark_summary.json", "w"
         ) as f:
             json.dump(summary, f, indent=2)
 
-    except Exception as e:
-        logger.error(f"Error saving summary: {e}")
+    except Exception:
+        logger.exception("Error saving summary")
 
     return 0
 

@@ -14,8 +14,8 @@
 """
 
 import argparse
-import os
 import sys
+from pathlib import Path
 
 # Import the benchmark functionality
 from local_deep_research.benchmarks.benchmark_functions import evaluate_simpleqa
@@ -39,7 +39,7 @@ def main():
     parser.add_argument(
         "--output-dir",
         type=str,
-        default=os.path.join("examples", "benchmarks", "results", "simpleqa"),
+        default=str(Path("examples") / "benchmarks" / "results" / "simpleqa"),
         help="Output directory",
     )
     parser.add_argument(

@@ -12,84 +12,69 @@
 - Provides detailed metrics and accuracy reports
 """
 
-import logging
 import os
 import sys
 import time
-from datetime import datetime
+from datetime import datetime, UTC
+from pathlib import Path
+
 
 # Set up Python path
-src_dir = os.path.abspath(os.path.join(os.path.dirname(__file__), "src"))
+src_dir = str((Path(__file__).parent / "src").resolve())
 if src_dir not in sys.path:
     sys.path.insert(0, src_dir)
 
-# Set the data directory with the database
-data_dir = os.path.join(src_dir, "data")
-if os.path.exists(os.path.join(data_dir, "ldr.db")):
-    print(f"Found database at {os.path.join(data_dir, 'ldr.db')}")
-    # Set environment variable to use this database
-    os.environ["LDR_DATA_DIR"] = data_dir
-else:
-    print(f"Warning: Database not found at {os.path.join(data_dir, 'ldr.db')}")
+# Note: Database configuration is now per-user
+# For benchmarks, API keys should be provided via environment variables
+# or configuration files rather than relying on a shared database
 
-# Configure logging
-logging.basicConfig(
-    level=logging.INFO,
-    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
-)
-logger = logging.getLogger(__name__)
+# Logger is already imported from loguru
 
 
 def setup_grading_config():
     """
-    Create a custom evaluation configuration that uses the local database
+    Create a custom evaluation configuration that uses environment variables
     for API keys and specifically uses Claude 3 Sonnet for grading.
 
     Returns:
         Dict containing the evaluation configuration
     """
-    # Import necessary function to get database settings
-    try:
-        from local_deep_research.utilities.db_utils import get_db_setting
-    except ImportError as e:
-        print(f"Error importing database utilities: {e}")
-        print("Current sys.path:", sys.path)
-        return None
-
     # Create config that uses Claude 3 Sonnet via Anthropic directly
-    # This will use the API key from the database
     # Only use parameters that get_llm() accepts
     evaluation_config = {
         "model_name": "claude-3-sonnet-20240229",  # Correct Anthropic model name
         "provider": "anthropic",  # Use Anthropic directly
         "temperature": 0,  # Zero temp for consistent evaluation
     }
 
-    # Check if anthropic API key is available in the database
-    try:
-        anthropic_key = get_db_setting("llm.anthropic.api_key")
-        if anthropic_key:
+    # Check if anthropic API key is available in environment
+    anthropic_key = os.environ.get("ANTHROPIC_API_KEY")
+    if anthropic_key:
+        print(
+            "Found Anthropic API key in environment, will use Claude 3 Sonnet for grading"
+        )
+    else:
+        print(
+            "Warning: No Anthropic API key found in ANTHROPIC_API_KEY environment variable"
+        )
+        print("Checking for alternative providers...")
+
+        # Try OpenRouter as a fallback
+        openrouter_key = os.environ.get("OPENROUTER_API_KEY")
+        if openrouter_key:
             print(
-                "Found Anthropic API key in database, will use Claude 3 Sonnet for grading"
+                "Found OpenRouter API key, will use OpenRouter with Claude 3 Sonnet"
             )
+            evaluation_config = {
+                "model_name": "anthropic/claude-3-sonnet-20240229",  # OpenRouter format
+                "provider": "openai_endpoint",
+                "openai_endpoint_url": "https://openrouter.ai/api/v1",
+                "temperature": 0,
+            }
         else:
-            print("Warning: No Anthropic API key found in database")
-            print("Checking for alternative providers...")
-
-            # Try OpenRouter as a fallback
-            openrouter_key = get_db_setting("llm.openai_endpoint.api_key")
-            if openrouter_key:
-                print(
-                    "Found OpenRouter API key, will use OpenRouter with Claude 3 Sonnet"
-                )
-                evaluation_config = {
-                    "model_name": "anthropic/claude-3-sonnet-20240229",  # OpenRouter format
-                    "provider": "openai_endpoint",
-                    "openai_endpoint_url": "https://openrouter.ai/api/v1",
-                    "temperature": 0,
-                }
-    except Exception as e:
-        print(f"Error checking for API keys: {e}")
+            print("ERROR: No API keys found in environment variables")
+            print("Please set either ANTHROPIC_API_KEY or OPENROUTER_API_KEY")
+            return None
 
     return evaluation_config
 
@@ -159,11 +144,9 @@ def custom_get_evaluation_llm(custom_config=None):
         traceback.print_exc()
 
     # Create timestamp for output
-    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
-    output_dir = os.path.join(
-        "benchmark_results", f"claude_grading_{timestamp}"
-    )
-    os.makedirs(output_dir, exist_ok=True)
+    timestamp = datetime.now(UTC).strftime("%Y%m%d_%H%M%S")
+    output_dir = str(Path("benchmark_results") / f"claude_grading_{timestamp}")
+    Path(output_dir).mkdir(parents=True, exist_ok=True)
 
     config = {
         "search_strategy": strategy,
@@ -190,7 +173,7 @@ def custom_get_evaluation_llm(custom_config=None):
         simpleqa_results = simpleqa.evaluate(
             config,
             num_examples=examples,
-            output_dir=os.path.join(output_dir, "simpleqa"),
+            output_dir=str(Path(output_dir) / "simpleqa"),
         )
 
         simpleqa_duration = time.time() - simpleqa_start
@@ -203,7 +186,7 @@ def custom_get_evaluation_llm(custom_config=None):
         # Save results
         import json
 
-        with open(os.path.join(output_dir, "simpleqa_results.json"), "w") as f:
+        with open(Path(output_dir) / "simpleqa_results.json", "w") as f:
             json.dump(simpleqa_results, f, indent=2)
     except Exception as e:
         print(f"Error during SimpleQA evaluation: {e}")
@@ -226,7 +209,7 @@ def custom_get_evaluation_llm(custom_config=None):
         browsecomp_results = browsecomp.evaluate(
             config,
             num_examples=examples,
-            output_dir=os.path.join(output_dir, "browsecomp"),
+            output_dir=str(Path(output_dir) / "browsecomp"),
         )
 
         browsecomp_duration = time.time() - browsecomp_start
@@ -237,9 +220,7 @@ def custom_get_evaluation_llm(custom_config=None):
         print(f"BrowseComp metrics: {browsecomp_results.get('metrics', {})}")
 
         # Save results
-        with open(
-            os.path.join(output_dir, "browsecomp_results.json"), "w"
-        ) as f:
+        with open(Path(output_dir) / "browsecomp_results.json", "w") as f:
             json.dump(browsecomp_results, f, indent=2)
     except Exception as e:
         print(f"Error during BrowseComp evaluation: {e}")
@@ -262,7 +243,7 @@ def custom_get_evaluation_llm(custom_config=None):
         composite_results = composite.evaluate(
             config,
             num_examples=examples,
-            output_dir=os.path.join(output_dir, "composite"),
+            output_dir=str(Path(output_dir) / "composite"),
         )
 
         composite_duration = time.time() - composite_start
@@ -272,7 +253,7 @@ def custom_get_evaluation_llm(custom_config=None):
         print(f"Composite score: {composite_results.get('score', 0):.4f}")
 
         # Save results
-        with open(os.path.join(output_dir, "composite_results.json"), "w") as f:
+        with open(Path(output_dir) / "composite_results.json", "w") as f:
             json.dump(composite_results, f, indent=2)
     except Exception as e:
         print(f"Error during composite evaluation: {e}")

@@ -9,84 +9,67 @@
 accesses the database for API keys, and uses Claude Anthropic 3.7 for grading.
 """
 
-import logging
 import os
 import sys
 import time
-from datetime import datetime
+from datetime import datetime, UTC
+from pathlib import Path
+
 
 # Set up Python path
-src_dir = os.path.abspath(os.path.join(os.path.dirname(__file__), "src"))
+src_dir = str((Path(__file__).parent / "src").resolve())
 if src_dir not in sys.path:
     sys.path.insert(0, src_dir)
 
-# Set the data directory with the database
-data_dir = os.path.join(src_dir, "data")
-if os.path.exists(os.path.join(data_dir, "ldr.db")):
-    print(f"Found database at {os.path.join(data_dir, 'ldr.db')}")
-    # Set environment variable to use this database
-    os.environ["LDR_DATA_DIR"] = data_dir
-else:
-    print(f"Warning: Database not found at {os.path.join(data_dir, 'ldr.db')}")
-
-# Configure logging
-logging.basicConfig(
-    level=logging.INFO,
-    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
-)
-logger = logging.getLogger(__name__)
+# Use environment variables for configuration
+# The system should be configured with proper environment variables:
+# - ANTHROPIC_API_KEY for Anthropic API access
+# - OPENROUTER_API_KEY for OpenRouter API access (if used)
+# - LDR_DATA_DIR for data directory location (if needed)
+data_dir = os.environ.get("LDR_DATA_DIR", str(Path(src_dir) / "data"))
 
 
 def setup_grading_config():
     """
-    Create a custom evaluation configuration that uses the local database
+    Create a custom evaluation configuration that uses environment variables
     for API keys and specifically uses Claude Anthropic 3.7 Sonnet for grading.
 
     Returns:
         Dict containing the evaluation configuration
     """
-    # Import necessary function to get database settings
-    try:
-        from local_deep_research.utilities.db_utils import get_db_setting
-    except ImportError as e:
-        print(f"Error importing database utilities: {e}")
-        print("Current sys.path:", sys.path)
-        return None
+    # No need to import database utilities anymore
 
     # Create config that uses Claude 3 Sonnet via Anthropic directly
-    # This will use the API key from the database
+    # This will use the API key from environment variables
     # Only use parameters that get_llm() accepts
     evaluation_config = {
         "model_name": "claude-3-sonnet-20240229",  # Correct Anthropic model name
         "provider": "anthropic",  # Use Anthropic directly
         "temperature": 0,  # Zero temp for consistent evaluation
     }
 
-    # Check if anthropic API key is available in the database
-    try:
-        anthropic_key = get_db_setting("llm.anthropic.api_key")
-        if anthropic_key:
+    # Check if anthropic API key is available in environment
+    anthropic_key = os.environ.get("ANTHROPIC_API_KEY")
+    if anthropic_key:
+        print(
+            "Found Anthropic API key in environment, will use Claude 3.7 Sonnet for grading"
+        )
+    else:
+        print("Warning: No Anthropic API key found in environment")
+        print("Checking for alternative providers...")
+
+        # Try OpenRouter as a fallback
+        openrouter_key = os.environ.get("OPENROUTER_API_KEY")
+        if openrouter_key:
             print(
-                "Found Anthropic API key in database, will use Claude 3.7 Sonnet for grading"
+                "Found OpenRouter API key, will use OpenRouter with Claude 3.7 Sonnet"
             )
-        else:
-            print("Warning: No Anthropic API key found in database")
-            print("Checking for alternative providers...")
-
-            # Try OpenRouter as a fallback
-            openrouter_key = get_db_setting("llm.openai_endpoint.api_key")
-            if openrouter_key:
-                print(
-                    "Found OpenRouter API key, will use OpenRouter with Claude 3.7 Sonnet"
-                )
-                evaluation_config = {
-                    "model_name": "anthropic/claude-3-7-sonnet",  # OpenRouter format
-                    "provider": "openai_endpoint",
-                    "openai_endpoint_url": "https://openrouter.ai/api/v1",
-                    "temperature": 0,
-                }
-    except Exception as e:
-        print(f"Error checking for API keys: {e}")
+            evaluation_config = {
+                "model_name": "anthropic/claude-3-7-sonnet",  # OpenRouter format
+                "provider": "openai_endpoint",
+                "openai_endpoint_url": "https://openrouter.ai/api/v1",
+                "temperature": 0,
+            }
 
     return evaluation_config
 
@@ -156,9 +139,9 @@ def custom_get_evaluation_llm(custom_config=None):
         traceback.print_exc()
 
     # Create timestamp for output
-    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
-    output_dir = os.path.join("benchmark_results", f"direct_eval_{timestamp}")
-    os.makedirs(output_dir, exist_ok=True)
+    timestamp = datetime.now(UTC).strftime("%Y%m%d_%H%M%S")
+    output_dir = str(Path("benchmark_results") / f"direct_eval_{timestamp}")
+    Path(output_dir).mkdir(parents=True, exist_ok=True)
 
     config = {
         "search_strategy": strategy,
@@ -185,7 +168,7 @@ def custom_get_evaluation_llm(custom_config=None):
         simpleqa_results = simpleqa.evaluate(
             config,
             num_examples=examples,
-            output_dir=os.path.join(output_dir, "simpleqa"),
+            output_dir=str(Path(output_dir) / "simpleqa"),
         )
 
         simpleqa_duration = time.time() - simpleqa_start
@@ -198,7 +181,7 @@ def custom_get_evaluation_llm(custom_config=None):
         # Save results
         import json
 
-        with open(os.path.join(output_dir, "simpleqa_results.json"), "w") as f:
+        with open(Path(output_dir) / "simpleqa_results.json", "w") as f:
             json.dump(simpleqa_results, f, indent=2)
     except Exception as e:
         print(f"Error during SimpleQA evaluation: {e}")
@@ -221,7 +204,7 @@ def custom_get_evaluation_llm(custom_config=None):
         browsecomp_results = browsecomp.evaluate(
             config,
             num_examples=examples,
-            output_dir=os.path.join(output_dir, "browsecomp"),
+            output_dir=str(Path(output_dir) / "browsecomp"),
         )
 
         browsecomp_duration = time.time() - browsecomp_start
@@ -232,9 +215,7 @@ def custom_get_evaluation_llm(custom_config=None):
         print(f"BrowseComp metrics: {browsecomp_results.get('metrics', {})}")
 
         # Save results
-        with open(
-            os.path.join(output_dir, "browsecomp_results.json"), "w"
-        ) as f:
+        with open(Path(output_dir) / "browsecomp_results.json", "w") as f:
             json.dump(browsecomp_results, f, indent=2)
     except Exception as e:
         print(f"Error during BrowseComp evaluation: {e}")
@@ -257,7 +238,7 @@ def custom_get_evaluation_llm(custom_config=None):
         composite_results = composite.evaluate(
             config,
             num_examples=examples,
-            output_dir=os.path.join(output_dir, "composite"),
+            output_dir=str(Path(output_dir) / "composite"),
         )
 
         composite_duration = time.time() - composite_start
@@ -267,7 +248,7 @@ def custom_get_evaluation_llm(custom_config=None):
         print(f"Composite score: {composite_results.get('score', 0):.4f}")
 
         # Save results
-        with open(os.path.join(output_dir, "composite_results.json"), "w") as f:
+        with open(Path(output_dir) / "composite_results.json", "w") as f:
             json.dump(composite_results, f, indent=2)
     except Exception as e:
         print(f"Error during composite evaluation: {e}")

@@ -7,82 +7,66 @@
 """
 
 import argparse
-import logging
 import os
 import sys
 import time
+from pathlib import Path
+
 
 # Set up Python path
-src_dir = os.path.abspath(os.path.join(os.path.dirname(__file__), "src"))
+src_dir = str((Path(__file__).parent / "src").resolve())
 if src_dir not in sys.path:
     sys.path.insert(0, src_dir)
 
-# Set the data directory with the database
-data_dir = os.path.join(src_dir, "data")
-if os.path.exists(os.path.join(data_dir, "ldr.db")):
-    print(f"Found database at {os.path.join(data_dir, 'ldr.db')}")
-    # Set environment variable to use this database
-    os.environ["LDR_DATA_DIR"] = data_dir
-else:
-    print(f"Warning: Database not found at {os.path.join(data_dir, 'ldr.db')}")
-
-# Configure logging
-logging.basicConfig(
-    level=logging.INFO,
-    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
-)
-logger = logging.getLogger(__name__)
+# Use environment variables for configuration
+# The system should be configured with proper environment variables:
+# - ANTHROPIC_API_KEY for Anthropic API access
+# - OPENROUTER_API_KEY for OpenRouter API access (if used)
+# - LDR_DATA_DIR for data directory location (if needed)
+data_dir = os.environ.get("LDR_DATA_DIR", str(Path(src_dir) / "data"))
 
 
 def setup_grading_config():
     """
-    Create a custom evaluation configuration that uses the local database
+    Create a custom evaluation configuration that uses environment variables
     for API keys and specifically uses Claude 3 Sonnet for grading.
 
     Returns:
         Dict containing the evaluation configuration
     """
-    # Import necessary function to get database settings
-    try:
-        from local_deep_research.utilities.db_utils import get_db_setting
-    except ImportError as e:
-        print(f"Error importing database utilities: {e}")
-        print("Current sys.path:", sys.path)
-        return None
+    # No need to import database utilities anymore
 
     # Create config that uses Claude 3 Sonnet via Anthropic directly
+    # This will use the API key from environment variables
     # Only use parameters that get_llm() accepts
     evaluation_config = {
         "model_name": "claude-3-sonnet-20240229",  # Correct Anthropic model name
         "provider": "anthropic",  # Use Anthropic directly
         "temperature": 0,  # Zero temp for consistent evaluation
     }
 
-    # Check if anthropic API key is available in the database
-    try:
-        anthropic_key = get_db_setting("llm.anthropic.api_key")
-        if anthropic_key:
+    # Check if anthropic API key is available in environment
+    anthropic_key = os.environ.get("ANTHROPIC_API_KEY")
+    if anthropic_key:
+        print(
+            "Found Anthropic API key in environment, will use Claude 3 Sonnet for grading"
+        )
+    else:
+        print("Warning: No Anthropic API key found in environment")
+        print("Checking for alternative providers...")
+
+        # Try OpenRouter as a fallback
+        openrouter_key = os.environ.get("OPENROUTER_API_KEY")
+        if openrouter_key:
             print(
-                "Found Anthropic API key in database, will use Claude 3 Sonnet for grading"
+                "Found OpenRouter API key, will use OpenRouter with Claude 3 Sonnet"
             )
-        else:
-            print("Warning: No Anthropic API key found in database")
-            print("Checking for alternative providers...")
-
-            # Try OpenRouter as a fallback
-            openrouter_key = get_db_setting("llm.openai_endpoint.api_key")
-            if openrouter_key:
-                print(
-                    "Found OpenRouter API key, will use OpenRouter with Claude 3 Sonnet"
-                )
-                evaluation_config = {
-                    "model_name": "anthropic/claude-3-sonnet-20240229",  # OpenRouter format
-                    "provider": "openai_endpoint",
-                    "openai_endpoint_url": "https://openrouter.ai/api/v1",
-                    "temperature": 0,
-                }
-    except Exception as e:
-        print(f"Error checking for API keys: {e}")
+            evaluation_config = {
+                "model_name": "anthropic/claude-3-sonnet-20240229",  # OpenRouter format
+                "provider": "openai_endpoint",
+                "openai_endpoint_url": "https://openrouter.ai/api/v1",
+                "temperature": 0,
+            }
 
     return evaluation_config
 
@@ -142,12 +126,12 @@ def custom_get_evaluation_llm(custom_config=None):
             traceback.print_exc()
 
         # Create the evaluation output path
-        results_dir = os.path.dirname(results_path)
-        results_filename = os.path.basename(results_path)
+        results_dir = str(Path(results_path).parent)
+        results_filename = Path(results_path).name
         evaluation_filename = results_filename.replace(
             "_results.jsonl", "_evaluation.jsonl"
         )
-        evaluation_path = os.path.join(results_dir, evaluation_filename)
+        evaluation_path = str(Path(results_dir) / evaluation_filename)
 
         # Run the grading
         print("Starting grading of benchmark results...")
@@ -227,10 +211,10 @@ def generate_summary(evaluation_path, output_dir=None):
 
         # Determine output directory
         if output_dir is None:
-            output_dir = os.path.dirname(evaluation_path)
+            output_dir = str(Path(evaluation_path).parent)
 
         # Generate report
-        report_path = os.path.join(output_dir, "evaluation_report.md")
+        report_path = str(Path(output_dir) / "evaluation_report.md")
         generate_report(
             metrics=metrics,
             output_file=report_path,
@@ -286,7 +270,7 @@ def main():
     args = parser.parse_args()
 
     # Check if the results file exists
-    if not os.path.exists(args.results):
+    if not Path(args.results).exists():
         print(f"Error: Results file not found: {args.results}")
         return 1
 

@@ -3,27 +3,24 @@
 展示如何索引文档和搜索数据。(Demonstrates how to index documents and search data.)
 """
 
-import logging
 import sys
 from pathlib import Path
 
+from loguru import logger
+
 # 添加项目根目录到 Python 路径 (Add project root directory to Python path)
 sys.path.append(str(Path(__file__).parent.parent))
 
 # Import after adding project root to path
-from src.local_deep_research.utilities.es_utils import (  # noqa: E402
+from src.local_deep_research.utilities.es_utils import (
     ElasticsearchManager,
 )
-from src.local_deep_research.web_search_engines.engines.search_engine_elasticsearch import (  # noqa: E402
+from src.local_deep_research.web_search_engines.engines.search_engine_elasticsearch import (
     ElasticsearchSearchEngine,
 )
 
 # 配置日志 (Configure logging)
-logging.basicConfig(
-    level=logging.INFO,
-    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
-)
-logger = logging.getLogger(__name__)
+# Loguru automatically handles logging configuration
 
 
 def index_sample_documents():
@@ -169,10 +166,10 @@ def main():
         advanced_search_examples(index_name)
 
     except Exception as e:
-        logger.error(
-            f"运行示例时出错: {str(e)}"
+        logger.exception(
+            f"运行示例时出错: {e!s}"
         )  # Error running example: {str(e)}
-        logger.error(
+        logger.info(
             "请确保 Elasticsearch 正在运行，默认地址为 http://localhost:9200"
         )  # Make sure Elasticsearch is running, default address is http://localhost:9200
 

@@ -4,15 +4,14 @@
 This helps debug issues with the BrowseComp dataset.
 """
 
-import logging
 import sys
 
-# Configure logging
-logging.basicConfig(
-    level=logging.DEBUG,
-    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
-)
-logger = logging.getLogger()
+from loguru import logger
+
+# Logger is already imported from loguru
+# Set debug level for this script
+logger.remove()
+logger.add(sys.stderr, level="DEBUG")
 
 # Add path to import local_deep_research
 sys.path.append(".")

@@ -9,14 +9,15 @@
 """
 
 import time
-from typing import List, Optional, Any, Dict
-from langchain_core.language_models import BaseChatModel
-from langchain_core.messages import BaseMessage, AIMessage
-from langchain_core.outputs import ChatResult, ChatGeneration
+from typing import Any, Dict, List, Optional
+
 from langchain_core.callbacks import CallbackManagerForLLMRun
+from langchain_core.language_models import BaseChatModel
+from langchain_core.messages import AIMessage, BaseMessage
+from langchain_core.outputs import ChatGeneration, ChatResult
 from loguru import logger
 
-from local_deep_research.api import quick_summary, detailed_research
+from local_deep_research.api import detailed_research, quick_summary
 
 
 class RetryLLM(BaseChatModel):

@@ -5,11 +5,13 @@
 with LDR's research functions.
 """
 
+from typing import Any, List, Optional
+
 from langchain_core.language_models import BaseChatModel
-from langchain_core.messages import BaseMessage, AIMessage
-from langchain_core.outputs import ChatResult, ChatGeneration
-from typing import List, Optional, Any
-from local_deep_research.api import quick_summary, detailed_research
+from langchain_core.messages import AIMessage, BaseMessage
+from langchain_core.outputs import ChatGeneration, ChatResult
+
+from local_deep_research.api import detailed_research, quick_summary
 
 
 class CustomLLM(BaseChatModel):

@@ -9,13 +9,14 @@
 - CI/CD pipelines
 """
 
-from typing import List, Optional, Any, Dict
-from langchain_core.language_models import BaseChatModel
-from langchain_core.messages import BaseMessage, AIMessage
-from langchain_core.outputs import ChatResult, ChatGeneration
 import json
+from typing import Any, Dict, List, Optional
+
+from langchain_core.language_models import BaseChatModel
+from langchain_core.messages import AIMessage, BaseMessage
+from langchain_core.outputs import ChatGeneration, ChatResult
 
-from local_deep_research.api import quick_summary, generate_report
+from local_deep_research.api import generate_report, quick_summary
 
 
 class MockLLM(BaseChatModel):

@@ -15,34 +15,30 @@
 """
 
 import json
-import logging
-import os
 import sys
 from datetime import datetime
+from pathlib import Path
+
 
 from local_deep_research.benchmarks.optimization import optimize_parameters
 
 # Add the src directory to the Python path
-project_root = os.path.abspath(
-    os.path.dirname(os.path.dirname(os.path.dirname(__file__)))
-)
-sys.path.insert(0, os.path.join(project_root, "src"))
-
-# Configure logging to see progress
-logging.basicConfig(
-    level=logging.INFO,
-    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
-)
-logger = logging.getLogger(__name__)
+project_root = str(Path(__file__).parent.parent.parent.resolve())
+sys.path.insert(0, str(Path(project_root) / "src"))
 
 
 def main():
     # Create timestamp for unique output directory
-    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
-    output_dir = os.path.join(
-        "examples", "optimization", "results", f"browsecomp_opt_{timestamp}"
+    from datetime import timezone
+
+    timestamp = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
+    output_dir = str(
+        Path("examples")
+        / "optimization"
+        / "results"
+        / f"browsecomp_opt_{timestamp}"
     )
-    os.makedirs(output_dir, exist_ok=True)
+    Path(output_dir).mkdir(parents=True, exist_ok=True)
 
     print(
         f"Starting BrowseComp optimization - results will be saved to {output_dir}"
@@ -96,7 +92,7 @@ def main():
     }
 
     with open(
-        os.path.join(output_dir, "browsecomp_optimization_summary.json"), "w"
+        Path(output_dir) / "browsecomp_optimization_summary.json", "w"
     ) as f:
         json.dump(summary, f, indent=2)
 

@@ -5,20 +5,19 @@
 SimpleQA and BrowseComp benchmarks with custom weights.
 """
 
-import logging
 import os
 import sys
 from datetime import datetime
+from pathlib import Path
 from typing import Any, Dict
 
+
 # Print current directory and python path for debugging
 print(f"Current directory: {os.getcwd()}")
 print(f"Python path: {sys.path}")
 
 # Add appropriate paths
-sys.path.insert(
-    0, os.path.abspath(os.path.join(os.path.dirname(__file__), "../.."))
-)
+sys.path.insert(0, str(Path(__file__).parent.parent.resolve()))
 
 try:
     # Try to import from the local module structure
@@ -109,9 +108,7 @@ def optimize_for_speed(*args, **kwargs):
             }, 0.67
 
 
-# Set up logging
-logging.basicConfig(level=logging.INFO)
-logger = logging.getLogger(__name__)
+# Loguru automatically handles logging configuration
 
 
 def print_optimization_results(params: Dict[str, Any], score: float):
@@ -129,7 +126,9 @@ def print_optimization_results(params: Dict[str, Any], score: float):
 def main():
     """Run the multi-benchmark optimization examples."""
     # Create a timestamp-based directory for results
-    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    from datetime import timezone
+
+    timestamp = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
     output_dir = f"optimization_demo_{timestamp}"
     os.makedirs(output_dir, exist_ok=True)
 
@@ -141,7 +140,7 @@ def main():
     params1, score1 = optimize_parameters(
         query=query,
         n_trials=3,  # Using a small number for quick demonstration
-        output_dir=os.path.join(output_dir, "simpleqa_only"),
+        output_dir=str(Path(output_dir) / "simpleqa_only"),
     )
     print_optimization_results(params1, score1)
 
@@ -150,7 +149,7 @@ def main():
     params2, score2 = optimize_parameters(
         query=query,
         n_trials=3,  # Using a small number for quick demonstration
-        output_dir=os.path.join(output_dir, "browsecomp_only"),
+        output_dir=str(Path(output_dir) / "browsecomp_only"),
         benchmark_weights={"browsecomp": 1.0},
     )
     print_optimization_results(params2, score2)
@@ -160,7 +159,7 @@ def main():
     params3, score3 = optimize_parameters(
         query=query,
         n_trials=5,  # Using a small number for quick demonstration
-        output_dir=os.path.join(output_dir, "weighted_combination"),
+        output_dir=str(Path(output_dir) / "weighted_combination"),
         benchmark_weights={
             "simpleqa": 0.6,  # 60% weight for SimpleQA
             "browsecomp": 0.4,  # 40% weight for BrowseComp
@@ -173,7 +172,7 @@ def main():
     params4, score4 = optimize_for_quality(
         query=query,
         n_trials=3,
-        output_dir=os.path.join(output_dir, "quality_focused"),
+        output_dir=str(Path(output_dir) / "quality_focused"),
         benchmark_weights={"simpleqa": 0.6, "browsecomp": 0.4},
     )
     print_optimization_results(params4, score4)
@@ -183,7 +182,7 @@ def main():
     params5, score5 = optimize_for_speed(
         query=query,
         n_trials=3,
-        output_dir=os.path.join(output_dir, "speed_focused"),
+        output_dir=str(Path(output_dir) / "speed_focused"),
         benchmark_weights={"simpleqa": 0.5, "browsecomp": 0.5},
     )
     print_optimization_results(params5, score5)

@@ -14,32 +14,28 @@
 """
 
 import json
-import logging
-import os
-from datetime import datetime
+from datetime import datetime, UTC
+from pathlib import Path
+
 
 # Import the optimization functionality
 from local_deep_research.benchmarks.optimization import (
     optimize_parameters,
 )
 
-# Configure logging to see progress
-logging.basicConfig(
-    level=logging.INFO,
-    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
-)
+# Loguru automatically handles logging configuration
 
 
 def main():
     # Create timestamp for unique output directory
-    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
-    output_dir = os.path.join(
-        "examples",
-        "optimization",
-        "results",
-        f"optimization_results_{timestamp}",
+    timestamp = datetime.now(UTC).strftime("%Y%m%d_%H%M%S")
+    output_dir = str(
+        Path("examples")
+        / "optimization"
+        / "results"
+        / f"optimization_results_{timestamp}"
     )
-    os.makedirs(output_dir, exist_ok=True)
+    Path(output_dir).mkdir(parents=True, exist_ok=True)
 
     print(
         f"Starting quick optimization demo - results will be saved to {output_dir}"
@@ -72,7 +68,7 @@ def main():
         query="SimpleQA quick demo",  # Task descriptor
         search_tool="searxng",  # Using SearXNG
         n_trials=2,  # Just 2 trials for quick demo
-        output_dir=os.path.join(output_dir, "demo"),
+        output_dir=str(Path(output_dir) / "demo"),
         param_space=param_space,  # Limited parameter space
         metric_weights={"quality": 0.5, "speed": 0.5},
     )
@@ -86,7 +82,7 @@ def main():
         "demo": {"parameters": balanced_params, "score": balanced_score},
     }
 
-    with open(os.path.join(output_dir, "optimization_summary.json"), "w") as f:
+    with open(Path(output_dir) / "optimization_summary.json", "w") as f:
         json.dump(summary, f, indent=2)
 
     print(f"\nDemo complete! Results saved to {output_dir}")

@@ -14,20 +14,15 @@
 """
 
 import json
-import logging
-import os
 import random
 import time
-from datetime import datetime
+from datetime import datetime, UTC
+from pathlib import Path
 from typing import Any, Dict, Tuple
 
-# Configure logging
-logging.basicConfig(
-    level=logging.INFO,
-    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
-)
+from loguru import logger
 
-logger = logging.getLogger(__name__)
+# Loguru automatically handles logging configuration
 
 
 def simulate_optimization(
@@ -192,11 +187,14 @@ def optimize_for_quality(
 
 def main():
     # Create timestamp for unique output directory
-    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
-    output_dir = os.path.join(
-        "examples", "optimization", "results", f"optimization_demo_{timestamp}"
+    timestamp = datetime.now(UTC).strftime("%Y%m%d_%H%M%S")
+    output_dir = str(
+        Path("examples")
+        / "optimization"
+        / "results"
+        / f"optimization_demo_{timestamp}"
     )
-    os.makedirs(output_dir, exist_ok=True)
+    Path(output_dir).mkdir(parents=True, exist_ok=True)
 
     print(
         f"Starting quick optimization demo - results will be saved to {output_dir}"
@@ -259,7 +257,7 @@ def main():
         },
     }
 
-    with open(os.path.join(output_dir, "optimization_summary.json"), "w") as f:
+    with open(Path(output_dir) / "optimization_summary.json", "w") as f:
         json.dump(summary, f, indent=2)
 
     print(

@@ -19,10 +19,12 @@
 
 import argparse
 import json
-import logging
 import os
 import sys
-from datetime import datetime
+from datetime import datetime, timezone
+from pathlib import Path
+
+from loguru import logger
 
 # Import the optimization functionality
 from local_deep_research.benchmarks.optimization import (
@@ -31,13 +33,6 @@
     optimize_parameters,
 )
 
-# Configure logging to see progress
-logging.basicConfig(
-    level=logging.INFO,
-    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
-)
-logger = logging.getLogger(__name__)
-
 
 def setup_gemini_config(api_key=None):
     """
@@ -101,14 +96,17 @@ def main():
         return 1
 
     # Create timestamp for unique output directory
-    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    timestamp = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
     if args.output_dir:
         output_dir = args.output_dir
     else:
-        output_dir = os.path.join(
-            "examples", "optimization", "results", f"gemini_opt_{timestamp}"
+        output_dir = str(
+            Path("examples")
+            / "optimization"
+            / "results"
+            / f"gemini_opt_{timestamp}"
         )
-    os.makedirs(output_dir, exist_ok=True)
+    Path(output_dir).mkdir(parents=True, exist_ok=True)
 
     print(
         f"Starting optimization with Gemini 2.0 Flash - results will be saved to {output_dir}"
@@ -197,15 +195,15 @@ def main():
         }
 
         with open(
-            os.path.join(output_dir, "gemini_optimization_summary.json"), "w"
+            Path(output_dir) / "gemini_optimization_summary.json", "w"
         ) as f:
             json.dump(summary, f, indent=2)
 
         print(f"\nOptimization complete! Results saved to {output_dir}")
         print(f"Recommended parameters for {args.mode} mode: {best_params}")
 
-    except Exception as e:
-        logger.exception(f"Error during optimization: {e}")
+    except Exception:
+        logger.exception("Error during optimization")
         return 1
 
     return 0

@@ -13,7 +13,8 @@
 import argparse
 import os
 import sys
-from datetime import datetime
+from datetime import datetime, UTC
+from pathlib import Path
 from typing import Any, Dict, Optional
 
 from loguru import logger
@@ -112,15 +113,15 @@ def main():
     args = parser.parse_args()
 
     # Create timestamp-based directory for results
-    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    timestamp = datetime.now(UTC).strftime("%Y%m%d_%H%M%S")
     if args.output_dir:
         output_dir = args.output_dir
     else:
-        output_dir = os.path.join(
-            "examples",
-            "optimization",
-            "results",
-            f"llm_multi_benchmark_{timestamp}",
+        output_dir = str(
+            Path("examples")
+            / "optimization"
+            / "results"
+            / f"llm_multi_benchmark_{timestamp}"
         )
 
     os.makedirs(output_dir, exist_ok=True)
@@ -215,9 +216,7 @@ def main():
         # Save results to file
         import json
 
-        with open(
-            os.path.join(output_dir, "multi_benchmark_results.json"), "w"
-        ) as f:
+        with open(Path(output_dir) / "multi_benchmark_results.json", "w") as f:
             json.dump(
                 {
                     "timestamp": timestamp,
@@ -235,11 +234,11 @@ def main():
             )
 
         print(
-            f"Results saved to {os.path.join(output_dir, 'multi_benchmark_results.json')}"
+            f"Results saved to {Path(output_dir) / 'multi_benchmark_results.json'}"
         )
 
-    except Exception as e:
-        logger.error(f"Error running optimization: {e}")
+    except Exception:
+        logger.exception("Error running optimization")
         import traceback
 
         traceback.print_exc()

@@ -6,19 +6,13 @@
 """
 
 import json
-import logging
-import os
 import random
 import time
-from datetime import datetime
+from datetime import datetime, UTC
+from pathlib import Path
 from typing import Any, Dict, Optional, Tuple
 
-# Configure logging
-logging.basicConfig(
-    level=logging.INFO,
-    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
-)
-logger = logging.getLogger(__name__)
+from loguru import logger
 
 
 class BenchmarkSimulator:
@@ -340,9 +334,9 @@ def print_optimization_results(params: Dict[str, Any], score: float):
 def main():
     """Run the multi-benchmark optimization simulation."""
     # Create a timestamp-based directory for results
-    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    timestamp = datetime.now(UTC).strftime("%Y%m%d_%H%M%S")
     output_dir = "optimization_sim_" + timestamp
-    os.makedirs(output_dir, exist_ok=True)
+    Path(output_dir).mkdir(parents=True, exist_ok=True)
 
     print("\n🔬 Multi-Benchmark Optimization Simulation 🔬")
     print(f"Results will be saved to: {output_dir}")
@@ -393,7 +387,7 @@ def main():
         },
     }
 
-    results_file = os.path.join(output_dir, "multi_benchmark_results.json")
+    results_file = str(Path(output_dir) / "multi_benchmark_results.json")
     with open(results_file, "w") as f:
         # Convert all values to serializable types
         json.dump(

@@ -13,12 +13,12 @@
     python ../examples/optimization/multi_benchmark_speed_demo.py
 """
 
-import os
 import sys
+from pathlib import Path
 from typing import Any, Dict
 
 # Add src directory to Python path
-src_dir = os.path.abspath(os.path.join(os.path.dirname(__file__), "../../src"))
+src_dir = str((Path(__file__).parent.parent / "src").resolve())
 if src_dir not in sys.path:
     sys.path.insert(0, src_dir)
 

@@ -15,25 +15,19 @@
 """
 
 import argparse
-import logging
-import os
 import sys
 import time
-from datetime import datetime
+from datetime import datetime, UTC
+from pathlib import Path
 from typing import Any, Dict, List, Optional
 
+from loguru import logger
+
 # Add the src directory to the Python path
-project_root = os.path.abspath(
-    os.path.dirname(os.path.dirname(os.path.dirname(__file__)))
-)
-sys.path.insert(0, os.path.join(project_root, "src"))
+project_root = str(Path(__file__).parent.parent.parent.resolve())
+sys.path.insert(0, str(Path(project_root) / "src"))
 
-# Configure logging
-logging.basicConfig(
-    level=logging.INFO,
-    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
-)
-logger = logging.getLogger(__name__)
+# Loguru automatically handles logging configuration
 
 
 def setup_gemini_config(api_key: Optional[str] = None) -> Dict[str, Any]:
@@ -117,13 +111,15 @@ def run_benchmarks(
         return {"error": "Failed to set up Gemini configuration"}
 
     # Create timestamp for output
-    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    timestamp = datetime.now(UTC).strftime("%Y%m%d_%H%M%S")
     if not output_dir:
-        output_dir = os.path.join(
-            project_root, "benchmark_results", f"gemini_eval_{timestamp}"
+        output_dir = str(
+            Path(project_root)
+            / "benchmark_results"
+            / f"gemini_eval_{timestamp}"
         )
 
-    os.makedirs(output_dir, exist_ok=True)
+    Path(output_dir).mkdir(parents=True, exist_ok=True)
 
     # Set benchmark list
     if not benchmarks:
@@ -148,7 +144,7 @@ def run_benchmarks(
                     search_model=gemini_config["model_name"],
                     search_provider=gemini_config["provider"],
                     endpoint_url=gemini_config["endpoint_url"],
-                    output_dir=os.path.join(output_dir, "simpleqa"),
+                    output_dir=str(Path(output_dir) / "simpleqa"),
                 )
             elif benchmark.lower() == "browsecomp":
                 logger.info(
@@ -162,7 +158,7 @@ def run_benchmarks(
                     search_model=gemini_config["model_name"],
                     search_provider=gemini_config["provider"],
                     endpoint_url=gemini_config["endpoint_url"],
-                    output_dir=os.path.join(output_dir, "browsecomp"),
+                    output_dir=str(Path(output_dir) / "browsecomp"),
                 )
             else:
                 logger.warning(f"Unknown benchmark: {benchmark}")
@@ -185,7 +181,7 @@ def run_benchmarks(
             }
 
         except Exception as e:
-            logger.error(f"Error running {benchmark} benchmark: {e}")
+            logger.exception(f"Error running {benchmark} benchmark")
             import traceback
 
             traceback.print_exc()
@@ -217,7 +213,7 @@ def run_benchmarks(
     logger.info("=" * 50)
 
     # Save summary to a file
-    summary_file = os.path.join(output_dir, "benchmark_summary.json")
+    summary_file = str(Path(output_dir) / "benchmark_summary.json")
     try:
         import json
 
@@ -250,8 +246,8 @@ def run_benchmarks(
                 indent=2,
             )
         logger.info(f"Summary saved to {summary_file}")
-    except Exception as e:
-        logger.error(f"Error saving summary: {e}")
+    except Exception:
+        logger.exception("Error saving summary")
 
     return {
         "status": "complete",

@@ -13,25 +13,25 @@
     python ../examples/optimization/run_multi_benchmark.py
 """
 
-import logging
 import os
 import sys
-from datetime import datetime
+from datetime import datetime, UTC
+from pathlib import Path
 from typing import Any, Dict
 
+from loguru import logger
+
 # Add src directory to Python path
-src_dir = os.path.abspath(os.path.join(os.path.dirname(__file__), "../../src"))
+src_dir = str((Path(__file__).parent.parent / "src").resolve())
 if src_dir not in sys.path:
     sys.path.insert(0, src_dir)
 
-# Set the data directory with the database
-data_dir = os.path.join(src_dir, "data")
-if os.path.exists(os.path.join(data_dir, "ldr.db")):
-    print(f"Found database at {os.path.join(data_dir, 'ldr.db')}")
-    # Set environment variable to use this database
-    os.environ["LDR_DATA_DIR"] = data_dir
-else:
-    print(f"Warning: Database not found at {os.path.join(data_dir, 'ldr.db')}")
+# Use environment variables for configuration
+# The system should be configured with proper environment variables:
+# - ANTHROPIC_API_KEY for Anthropic API access
+# - OPENROUTER_API_KEY for OpenRouter API access (if used)
+# - LDR_DATA_DIR for data directory location (if needed)
+data_dir = os.environ.get("LDR_DATA_DIR", str(Path(src_dir) / "data"))
 
 # Import benchmark optimization functions
 try:
@@ -45,13 +45,6 @@
     print("Current sys.path:", sys.path)
     sys.exit(1)
 
-# Configure logging
-logging.basicConfig(
-    level=logging.INFO,
-    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
-)
-logger = logging.getLogger(__name__)
-
 
 def print_optimization_results(params: Dict[str, Any], score: float):
     """Print optimization results in a nicely formatted way."""
@@ -68,16 +61,18 @@ def print_optimization_results(params: Dict[str, Any], score: float):
 def main():
     """Run multi-benchmark optimization examples."""
     # Create a timestamp-based directory for results
-    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    timestamp = datetime.now(UTC).strftime("%Y%m%d_%H%M%S")
 
     # Put results in the data directory for easier access
-    if os.path.isdir(data_dir):
-        output_dir = os.path.join(
-            data_dir, "optimization_results", "multi_benchmark_" + timestamp
+    if Path(data_dir).is_dir():
+        output_dir = str(
+            Path(data_dir)
+            / "optimization_results"
+            / f"multi_benchmark_{timestamp}"
         )
     else:
-        output_dir = os.path.join(
-            "optimization_results", "multi_benchmark_" + timestamp
+        output_dir = str(
+            Path("optimization_results") / f"multi_benchmark_{timestamp}"
         )
 
     os.makedirs(output_dir, exist_ok=True)
@@ -154,7 +149,7 @@ def main():
         quality_results = evaluator.evaluate(
             system_config=mini_system_config,
             num_examples=1,  # Use just 1 example for speed
-            output_dir=os.path.join(output_dir, "simpleqa_test"),
+            output_dir=str(Path(output_dir) / "simpleqa_test"),
         )
 
         print("Benchmark evaluation complete!")
@@ -173,14 +168,14 @@ def main():
         params1, score1 = optimize_parameters(
             query=query,
             param_space=tiny_param_space,  # Use tiny param space
-            output_dir=os.path.join(output_dir, "simpleqa_only"),
+            output_dir=str(Path(output_dir) / "simpleqa_only"),
             n_trials=1,  # Just one trial for testing
             benchmark_weights={"simpleqa": 1.0},  # SimpleQA only
             timeout=5,  # Limit to 5 seconds
         )
         print_optimization_results(params1, score1)
     except Exception as e:
-        logger.error(f"Error running SimpleQA optimization: {e}")
+        logger.exception("Error running SimpleQA optimization")
         print(f"Error: {e}")
 
     # Run 2: BrowseComp benchmark only (minimal test)
@@ -193,7 +188,7 @@ def main():
         bc_results = browsecomp_evaluator.evaluate(
             system_config=mini_system_config,
             num_examples=1,  # Just 1 example for speed
-            output_dir=os.path.join(output_dir, "browsecomp_test"),
+            output_dir=str(Path(output_dir) / "browsecomp_test"),
         )
 
         print("BrowseComp evaluation complete!")
@@ -207,7 +202,7 @@ def main():
         )
 
     except Exception as e:
-        logger.error(f"Error running BrowseComp evaluation: {e}")
+        logger.exception("Error running BrowseComp evaluation")
         print(f"Error: {e}")
 
     # Run 3: Combined benchmark with weights (minimal test)
@@ -224,7 +219,7 @@ def main():
         combo_results = composite_evaluator.evaluate(
             system_config=mini_system_config,
             num_examples=1,  # Just 1 example for speed
-            output_dir=os.path.join(output_dir, "combined_test"),
+            output_dir=str(Path(output_dir) / "combined_test"),
         )
 
         print("Combined benchmark evaluation complete!")
@@ -239,7 +234,7 @@ def main():
         )
 
     except Exception as e:
-        logger.error(f"Error running combined benchmark evaluation: {e}")
+        logger.exception("Error running combined benchmark evaluation")
         print(f"Error: {e}")
 
     # Run 4: Combined benchmark with speed optimization
@@ -254,7 +249,7 @@ def main():
         # Very minimal run with just 1 trial for demonstration
         params_speed, score_speed = optimize_for_speed(
             query=query,
-            output_dir=os.path.join(output_dir, "speed_optimization"),
+            output_dir=str(Path(output_dir) / "speed_optimization"),
             n_trials=1,  # Just one trial for testing
             benchmark_weights={"simpleqa": 0.6, "browsecomp": 0.4},
             timeout=5,  # Limit to 5 seconds
@@ -265,8 +260,8 @@ def main():
         print("Speed metrics weighting: Quality (20%), Speed (80%)")
 
     except Exception as e:
-        logger.error(
-            f"Error running speed optimization with multi-benchmark: {e}"
+        logger.exception(
+            "Error running speed optimization with multi-benchmark"
         )
         print(f"Error: {e}")
 
@@ -282,7 +277,7 @@ def main():
         # Very minimal run with just 1 trial for demonstration
         params_efficiency, score_efficiency = optimize_for_efficiency(
             query=query,
-            output_dir=os.path.join(output_dir, "efficiency_optimization"),
+            output_dir=str(Path(output_dir) / "efficiency_optimization"),
             n_trials=1,  # Just one trial for testing
             benchmark_weights={"simpleqa": 0.6, "browsecomp": 0.4},
             timeout=5,  # Limit to 5 seconds
@@ -295,8 +290,8 @@ def main():
         )
 
     except Exception as e:
-        logger.error(
-            f"Error running efficiency optimization with multi-benchmark: {e}"
+        logger.exception(
+            "Error running efficiency optimization with multi-benchmark"
         )
         print(f"Error: {e}")
 

@@ -17,7 +17,8 @@
 import json
 import os
 import sys
-from datetime import datetime
+from datetime import datetime, UTC
+from pathlib import Path
 
 # Import the optimization functionality
 from local_deep_research.benchmarks.optimization import (
@@ -36,7 +37,7 @@ def main():
     parser.add_argument("query", help="Research query to optimize for")
     parser.add_argument(
         "--output-dir",
-        default=os.path.join("examples", "optimization", "results"),
+        default=str(Path("examples") / "optimization" / "results"),
         help="Directory to save results",
     )
     parser.add_argument(
@@ -84,8 +85,8 @@ def main():
     args = parser.parse_args()
 
     # Create timestamp for unique output directory
-    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
-    output_dir = os.path.join(args.output_dir, f"opt_{timestamp}")
+    timestamp = datetime.now(UTC).strftime("%Y%m%d_%H%M%S")
+    output_dir = str(Path(args.output_dir) / f"opt_{timestamp}")
     os.makedirs(output_dir, exist_ok=True)
 
     print(
@@ -185,7 +186,7 @@ def main():
         "custom_weights": custom_weights,
     }
 
-    with open(os.path.join(output_dir, "optimization_summary.json"), "w") as f:
+    with open(Path(output_dir) / "optimization_summary.json", "w") as f:
         json.dump(summary, f, indent=2)
 
     return 0

@@ -15,24 +15,17 @@
 
 import argparse
 import concurrent.futures
-import logging
 import os
 import sys
 import time
-from datetime import datetime
+from datetime import datetime, UTC
+from pathlib import Path
 
-# Add the src directory to the Python path
-project_root = os.path.abspath(
-    os.path.dirname(os.path.dirname(os.path.dirname(__file__)))
-)
-sys.path.insert(0, os.path.join(project_root, "src"))
+from loguru import logger
 
-# Configure logging
-logging.basicConfig(
-    level=logging.INFO,
-    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
-)
-logger = logging.getLogger(__name__)
+# Add the src directory to the Python path
+project_root = str(Path(__file__).parent.parent.parent.resolve())
+sys.path.insert(0, str(Path(project_root) / "src"))
 
 
 def run_simpleqa_benchmark(
@@ -61,7 +54,7 @@ def run_simpleqa_benchmark(
         search_model=model,
         search_provider=provider,
         endpoint_url=endpoint_url,
-        output_dir=os.path.join(output_dir, "simpleqa"),
+        output_dir=str(Path(output_dir) / "simpleqa"),
         evaluation_provider="ANTHROPIC",
         evaluation_model="claude-3-7-sonnet-20250219",
     )
@@ -101,7 +94,7 @@ def run_browsecomp_benchmark(
         search_model=model,
         search_provider=provider,
         endpoint_url=endpoint_url,
-        output_dir=os.path.join(output_dir, "browsecomp"),
+        output_dir=str(Path(output_dir) / "browsecomp"),
         evaluation_provider="ANTHROPIC",
         evaluation_model="claude-3-7-sonnet-20250219",
     )
@@ -176,11 +169,13 @@ def main():
     args = parser.parse_args()
 
     # Create timestamp for unique output directory
-    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
-    output_dir = os.path.join(
-        project_root, "benchmark_results", f"parallel_benchmark_{timestamp}"
+    timestamp = datetime.now(UTC).strftime("%Y%m%d_%H%M%S")
+    output_dir = str(
+        Path(project_root)
+        / "benchmark_results"
+        / f"parallel_benchmark_{timestamp}"
     )
-    os.makedirs(output_dir, exist_ok=True)
+    Path(output_dir).mkdir(parents=True, exist_ok=True)
 
     # Display start information
     print(f"Starting parallel benchmarks with {args.examples} examples each")
@@ -224,15 +219,15 @@ def main():
         try:
             simpleqa_results = simpleqa_future.result()
             print("SimpleQA benchmark completed successfully")
-        except Exception as e:
-            logger.error(f"Error in SimpleQA benchmark: {e}")
+        except Exception:
+            logger.exception("Error in SimpleQA benchmark")
             simpleqa_results = None
 
         try:
             browsecomp_results = browsecomp_future.result()
             print("BrowseComp benchmark completed successfully")
-        except Exception as e:
-            logger.error(f"Error in BrowseComp benchmark: {e}")
+        except Exception:
+            logger.exception("Error in BrowseComp benchmark")
             browsecomp_results = None
 
     # Calculate total time
@@ -289,12 +284,12 @@ def main():
         }
 
         with open(
-            os.path.join(output_dir, "parallel_benchmark_summary.json"), "w"
+            Path(output_dir) / "parallel_benchmark_summary.json", "w"
         ) as f:
             json.dump(summary, f, indent=2)
 
-    except Exception as e:
-        logger.error(f"Error saving summary: {e}")
+    except Exception:
+        logger.exception("Error saving summary")
 
     return 0
 

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 # This script should be run from the project root directory using:
-# cd /home/martin/code/LDR/local-deep-research
+# cd /path/to/local-deep-research
 # python -m examples.optimization.strategy_benchmark_plan
 """
 Strategy Benchmark Plan - Comprehensive Optuna-based optimization for search strategies
@@ -10,34 +10,29 @@
 """
 
 import json
-import logging
 import os
 import random
 import sys
 import time
-from datetime import datetime
+from datetime import datetime, UTC
+from pathlib import Path
 from typing import Any, Dict, Tuple
 
+from loguru import logger
+
 # Skip flake8 import order checks for this file due to sys.path manipulation
 # flake8: noqa: E402
 
 # Add the src directory to the Python path before local imports
-project_root = os.path.abspath(
-    os.path.dirname(os.path.dirname(os.path.dirname(__file__)))
-)
-sys.path.insert(0, os.path.join(project_root, "src"))
+project_root = str(Path(__file__).parent.parent.parent.resolve())
+sys.path.insert(0, str(Path(project_root) / "src"))
 
 # Now we can import from the local project
 from local_deep_research.benchmarks.optimization.optuna_optimizer import (
     OptunaOptimizer,
 )
 
-# Configure logging
-logging.basicConfig(
-    level=logging.INFO,
-    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
-)
-logger = logging.getLogger(__name__)
+# Logger is already imported from loguru at the top
 
 # Number of examples to use in each benchmark experiment
 NUM_EXAMPLES = 500
@@ -82,10 +77,10 @@ def run_strategy_comparison():
             f"Default questions per iteration from DB: {questions_per_iteration}"
         )
     except Exception as e:
-        logger.error(f"Error initializing LLM or search settings: {str(e)}")
-        logger.error("Please check your database configuration")
+        logger.exception(f"Error initializing LLM or search settings: {e!s}")
+        logger.info("Please check your database configuration")
         return {"error": str(e)}
-    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    timestamp = datetime.now(UTC).strftime("%Y%m%d_%H%M%S")
     base_output_dir = f"strategy_benchmark_results_{timestamp}"
     os.makedirs(base_output_dir, exist_ok=True)
 
@@ -132,8 +127,8 @@ def run_strategy_comparison():
 
     # ====== EXPERIMENT 1: Quality-focused optimization ======
     logger.info("Starting quality-focused benchmark with 500 examples")
-    quality_output_dir = os.path.join(base_output_dir, "quality_focused")
-    os.makedirs(quality_output_dir, exist_ok=True)
+    quality_output_dir = str(Path(base_output_dir) / "quality_focused")
+    Path(quality_output_dir).mkdir(parents=True, exist_ok=True)
 
     # Create optimizer for quality
     quality_optimizer = OptunaOptimizer(
@@ -169,13 +164,13 @@ def run_strategy_comparison():
     logger.info(f"Best quality score: {best_quality_score}")
     logger.info(f"Duration: {quality_end - quality_start} seconds")
 
-    with open(os.path.join(quality_output_dir, "results.json"), "w") as f:
+    with open(Path(quality_output_dir) / "results.json", "w") as f:
         json.dump(quality_result, f, indent=2)
 
     # ====== EXPERIMENT 2: Speed-focused optimization ======
     logger.info("Starting speed-focused benchmark with 500 examples")
-    speed_output_dir = os.path.join(base_output_dir, "speed_focused")
-    os.makedirs(speed_output_dir, exist_ok=True)
+    speed_output_dir = str(Path(base_output_dir) / "speed_focused")
+    Path(speed_output_dir).mkdir(parents=True, exist_ok=True)
 
     # Create optimizer for speed
     speed_optimizer = OptunaOptimizer(
@@ -211,13 +206,13 @@ def run_strategy_comparison():
     logger.info(f"Best speed score: {best_speed_score}")
     logger.info(f"Duration: {speed_end - speed_start} seconds")
 
-    with open(os.path.join(speed_output_dir, "results.json"), "w") as f:
+    with open(Path(speed_output_dir) / "results.json", "w") as f:
         json.dump(speed_result, f, indent=2)
 
     # ====== EXPERIMENT 3: Balanced optimization ======
     logger.info("Starting balanced benchmark with 500 examples")
-    balanced_output_dir = os.path.join(base_output_dir, "balanced")
-    os.makedirs(balanced_output_dir, exist_ok=True)
+    balanced_output_dir = str(Path(base_output_dir) / "balanced")
+    Path(balanced_output_dir).mkdir(parents=True, exist_ok=True)
 
     # Create optimizer for balanced approach
     balanced_optimizer = OptunaOptimizer(
@@ -253,13 +248,13 @@ def run_strategy_comparison():
     logger.info(f"Best balanced score: {best_balanced_score}")
     logger.info(f"Duration: {balanced_end - balanced_start} seconds")
 
-    with open(os.path.join(balanced_output_dir, "results.json"), "w") as f:
+    with open(Path(balanced_output_dir) / "results.json", "w") as f:
         json.dump(balanced_result, f, indent=2)
 
     # ====== EXPERIMENT 4: Multi-Benchmark (SimpleQA + BrowseComp) ======
     logger.info("Starting multi-benchmark optimization with 500 examples")
-    multi_output_dir = os.path.join(base_output_dir, "multi_benchmark")
-    os.makedirs(multi_output_dir, exist_ok=True)
+    multi_output_dir = str(Path(base_output_dir) / "multi_benchmark")
+    Path(multi_output_dir).mkdir(parents=True, exist_ok=True)
 
     # Create optimizer with multi-benchmark weights
     multi_optimizer = OptunaOptimizer(
@@ -296,7 +291,7 @@ def run_strategy_comparison():
     logger.info(f"Best multi-benchmark score: {best_multi_score}")
     logger.info(f"Duration: {multi_end - multi_start} seconds")
 
-    with open(os.path.join(multi_output_dir, "results.json"), "w") as f:
+    with open(Path(multi_output_dir) / "results.json", "w") as f:
         json.dump(multi_result, f, indent=2)
 
     # ====== Save summary of all executions ======
@@ -305,7 +300,7 @@ def run_strategy_comparison():
     )
     execution_stats["timestamp"] = timestamp
 
-    with open(os.path.join(base_output_dir, "summary.json"), "w") as f:
+    with open(Path(base_output_dir) / "summary.json", "w") as f:
         json.dump(execution_stats, f, indent=2)
 
     # Generate summary report
@@ -366,7 +361,7 @@ def generate_summary_report(base_dir, stats):
 """
 
     # Write summary to file
-    with open(os.path.join(base_dir, "summary_report.md"), "w") as f:
+    with open(Path(base_dir) / "summary_report.md", "w") as f:
         f.write(summary_text)
 
 
@@ -378,7 +373,7 @@ def run_strategy_simulation(num_examples=10):
     This fallback simulation mode doesn't require actual database or LLM access,
     making it useful for testing the script structure.
     """
-    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    timestamp = datetime.now(UTC).strftime("%Y%m%d_%H%M%S")
     sim_output_dir = f"strategy_sim_results_{timestamp}"
     os.makedirs(sim_output_dir, exist_ok=True)
 
@@ -432,7 +427,7 @@ def run_strategy_simulation(num_examples=10):
         best_params, best_score = sim_optimizer.optimize(strategy_param_space)
 
     except Exception as e:
-        logger.warning(f"Could not initialize real optimizer: {str(e)}")
+        logger.warning(f"Could not initialize real optimizer: {e!s}")
         logger.warning(
             "Falling back to pure simulation mode (no real benchmarks)"
         )
@@ -456,9 +451,7 @@ def run_strategy_simulation(num_examples=10):
         "best_score": best_score,
     }
 
-    with open(
-        os.path.join(sim_output_dir, "simulation_results.json"), "w"
-    ) as f:
+    with open(Path(sim_output_dir) / "simulation_results.json", "w") as f:
         json.dump(sim_result, f, indent=2)
 
     return sim_result

@@ -18,23 +18,15 @@
 """
 
 import argparse
-import logging
-import os
 import sys
+from pathlib import Path
 from typing import Optional
 
-# Add the src directory to the Python path
-project_root = os.path.abspath(
-    os.path.dirname(os.path.dirname(os.path.dirname(__file__)))
-)
-sys.path.insert(0, os.path.join(project_root, "src"))
+from loguru import logger
 
-# Configure logging
-logging.basicConfig(
-    level=logging.INFO,
-    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
-)
-logger = logging.getLogger(__name__)
+# Add the src directory to the Python path
+project_root = str(Path(__file__).parent.parent.parent.resolve())
+sys.path.insert(0, str(Path(project_root) / "src"))
 
 
 def update_llm_configuration(
@@ -66,7 +58,7 @@ def update_llm_configuration(
             update_db_setting,
         )
     except ImportError:
-        logger.error(
+        logger.exception(
             "Could not import database utilities. Make sure you're in the correct directory."
         )
         return False
@@ -149,7 +141,7 @@ def update_llm_configuration(
         return True
 
     except Exception as e:
-        logger.error(f"Error updating LLM configuration: {str(e)}")
+        logger.exception(f"Error updating LLM configuration: {e!s}")
         return False
 
 

@@ -6,22 +6,15 @@
 """
 
 import argparse
-import logging
 import os
 
+
 from local_deep_research.api.benchmark_functions import (
     compare_configurations,
     evaluate_browsecomp,
     evaluate_simpleqa,
 )
 
-# Configure logging
-logging.basicConfig(
-    level=logging.INFO,
-    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
-)
-logger = logging.getLogger(__name__)
-
 
 def main():
     """Run benchmark examples."""

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+"""
+Example script showing all available environment variables for LDR configuration.
+This demonstrates the centralized environment variable management in SettingsManager.
+"""
+
+import sys
+import os
+from pathlib import Path
+
+# Add parent directory to path
+sys.path.insert(0, str(Path(__file__).parent.parent / "src"))
+
+from local_deep_research.settings.manager import SettingsManager
+
+
+def main():
+    print("=== Local Deep Research Environment Variables ===\n")
+
+    all_env_vars = SettingsManager.get_all_env_vars()
+
+    for category, vars_dict in all_env_vars.items():
+        print(f"\n{category.upper()} VARIABLES:")
+        print("-" * 50)
+
+        for var_name, description in sorted(vars_dict.items()):
+            # Check if currently set
+            current_value = os.environ.get(var_name)
+            if current_value:
+                # Mask sensitive values
+                if any(
+                    sensitive in var_name
+                    for sensitive in ["KEY", "PASSWORD", "SECRET"]
+                ):
+                    display_value = "***SET***"
+                else:
+                    display_value = current_value
+                status = f" [Current: {display_value}]"
+            else:
+                status = ""
+
+            print(f"  {var_name}")
+            print(f"    {description}{status}")
+
+    print("\n\n=== Environment Variable Formats ===")
+    print("-" * 50)
+    print(
+        "Settings can be overridden via environment variables using this format:"
+    )
+    print("  Setting key: app.host")
+    print("  Environment variable: LDR_APP__HOST")
+    print(
+        "\nNote: Use double underscores (__) to separate setting path components."
+    )
+
+    print("\n\n=== Bootstrap Variables ===")
+    print("-" * 50)
+    print("The following variables must be set before database access:")
+    bootstrap_vars = SettingsManager.get_bootstrap_env_vars()
+    for var in sorted(bootstrap_vars.keys()):
+        print(f"  - {var}")
+
+
+if __name__ == "__main__":
+    main()

@@ -0,0 +1,74 @@
+name: Accessibility Tests
+
+on:
+  push:
+    branches: [ main, dev, develop ]
+  pull_request:
+    branches: [ main, dev, develop ]
+  workflow_dispatch:
+
+jobs:
+  accessibility-tests:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Set up PDM
+      uses: pdm-project/setup-pdm@v4
+      with:
+        python-version: '3.11'
+
+    - name: Cache pip packages
+      uses: actions/cache@v3
+      with:
+        path: ~/.cache/pip
+        key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
+        restore-keys: |
+          ${{ runner.os }}-pip-
+
+    - name: Install system dependencies for SQLCipher
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y libsqlcipher-dev
+
+    - name: Install Python dependencies
+      run: |
+        pdm sync -d
+
+    - name: Run accessibility compliance tests
+      run: |
+        # Run all accessibility tests
+        pdm run pytest tests/accessibility/ -v --tb=short || true
+
+        # Run specific accessibility test files that exist
+        pdm run pytest tests/ui_tests/test_accessibility_compliance.py -v --tb=short || true
+        pdm run pytest tests/ui_tests/test_wcag_compliance.py -v --tb=short || true
+        pdm run pytest tests/ui_tests/test_keyboard_navigation.py -v --tb=short || true
+        pdm run pytest tests/ui_tests/test_screen_reader.py -v --tb=short || true
+
+        # Run HTML structure tests that may contain accessibility checks
+        pdm run pytest tests/test_html_structure.py -v --tb=short || true
+
+    - name: Generate accessibility report
+      if: always()
+      run: |
+        echo "Accessibility Tests Report"
+        echo "=========================="
+        echo "Tests check for:"
+        echo "- WCAG 2.1 Level AA compliance"
+        echo "- Keyboard navigation support"
+        echo "- Screen reader compatibility"
+        echo "- Color contrast ratios"
+        echo "- ARIA labels and roles"
+        echo "- Focus management"
+
+    - name: Upload accessibility test results
+      if: failure()
+      uses: actions/upload-artifact@v4
+      with:
+        name: accessibility-test-results
+        path: |
+          tests/accessibility/
+          .pytest_cache/

@@ -35,21 +35,32 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.11'
+          python-version: '3.12'
 
       - name: Set up PDM
         uses: pdm-project/setup-pdm@v4
+        with:
+          python-version: '3.12'
+
+      - name: Install system dependencies for SQLCipher
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libsqlcipher-dev
 
       - name: Install dependencies
         run: |
-          pdm install
-          pdm install -d
+          # Install in development mode to ensure all modules are available
+          pdm sync -d
+          # Verify the package is installed correctly
+          pdm run python -c "import local_deep_research; print('Package imported:', local_deep_research.__file__)"
+          pdm run python -c "import local_deep_research.memory_cache; print('Memory cache module imported successfully')"
 
       - name: Start server for API unit tests
         run: |
           export LDR_USE_FALLBACK_LLM=true
+          export PYTHONPATH=$PWD/src:$PYTHONPATH
           echo "Starting server for API unit tests..."
-          pdm run ldr-web 2>&1 | tee server.log &
+          pdm run python -m local_deep_research.web.app 2>&1 | tee server.log &
           SERVER_PID=$!
 
           # Wait for server to start
@@ -134,8 +145,9 @@ jobs:
           fi
 
           # Now try with pdm run ldr-web
-          echo "Starting server with pdm run ldr-web..."
-          pdm run ldr-web 2>&1 | tee server.log &
+          echo "Starting server with pdm run python..."
+          export PYTHONPATH=$PWD/src:$PYTHONPATH
+          pdm run python -m local_deep_research.web.app 2>&1 | tee server.log &
           SERVER_PID=$!
 
           # Give server a moment to start logging