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

# Local Deep Research API Examples

This directory contains examples for using LDR through different interfaces.

## Important: Authentication Required (v2.0+)

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

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

## Directory Structure

- **`programmatic/`** - Direct Python API usage (import from `local_deep_research.api`)
  - `programmatic_access.ipynb` - Jupyter notebook with comprehensive examples
  - `retriever_usage_example.py` - Using LangChain retrievers with LDR

- **`http/`** - HTTP REST API usage (requires running server)
  - `simple_working_example.py` - ✅ **BEST WORKING EXAMPLE** - Clean, tested, and ready to use
  - `simple_http_example.py` - Quick start example (needs updating for auth)
  - `http_api_examples.py` - Comprehensive examples including batch processing

## Quick Start

### Programmatic API (Python Package)

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

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

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

### HTTP API (REST)

**🎯 Quick Start - Works Completely Out of the Box!**

Our tested working example requires zero manual setup:

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

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

# 3. Done! ✅ No other steps required
```

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

**📋 Manual API Usage:**

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

```python
import requests
from bs4 import BeautifulSoup

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

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

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

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

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

**⚠️ Important Notes:**
- Use the correct endpoint: `/api/start_research` (not `/research/api/start`)
- Login with form data (not JSON)
- Handle CSRF tokens properly
- User must be created through web interface first

## Which API Should I Use?

- **Programmatic API**: Use when integrating LDR into your Python application
  - ✅ Direct access, no HTTP overhead
  - ✅ Full access to all features and parameters
  - ✅ Can pass Python objects (like LangChain retrievers)
  - ❌ Requires LDR to be installed in your environment
  - ❌ Requires database session and settings snapshot

- **HTTP API**: Use when accessing LDR from other languages or remote systems
  - ✅ Language agnostic - works with any HTTP client
  - ✅ Can run LDR on a separate server
  - ✅ Easy to scale and deploy
  - ❌ Limited to JSON-serializable parameters
  - ❌ Requires running the web server
  - ❌ Requires authentication and CSRF tokens

## API Changes in v2.0

### Breaking Changes

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

### Migration Guide

#### Old (v1.x):
```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 = SettingsManager(session)
    settings_snapshot = settings_manager.get_all_settings()
    result = quick_summary("query", settings_snapshot=settings_snapshot)

# HTTP - with authentication and CSRF
# See examples above
```

## Running the Examples

### Prerequisites

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

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

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

### HTTP Examples
```bash
# First, start the LDR server
python -m local_deep_research.web.app

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

## Need Help?

- See the [API Quick Start Guide](../../docs/api-quickstart.md)
- Check the [FAQ](../../docs/faq.md)
- Join our [Discord](https://discord.gg/ttcqQeFcJ3) for support