chore: import upstream snapshot with attribution

examples/api_usage/README.md

@@ -0,0 +1,199 @@
+# 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