chore: import upstream snapshot with attribution

examples/api_usage/http/README.md

@@ -0,0 +1,202 @@
+# HTTP API Examples
+
+This directory contains working examples for using the LDR HTTP API with authentication.
+
+## 🚀 Quick Start
+
+### 1. Start the LDR Server
+
+```bash
+# Option 1: Direct startup
+python -m local_deep_research.web.app
+
+# Option 2: Use the restart script (recommended)
+bash scripts/dev/restart_server.sh
+
+# Option 3: Docker compose
+docker-compose up -d
+```
+
+### 2. Run the Simple Working Example
+
+```bash
+# This example works completely out of the box!
+python simple_working_example.py
+```
+
+## 📁 Available Examples
+
+### 🎯 `simple_working_example.py` - **RECOMMENDED START**
+- ✅ **Works completely out of the box**
+- ✅ **Automatic user creation** (no manual setup needed)
+- ✅ **Correct API endpoints** and authentication
+- ✅ **Tested and verified** to work
+- ⏱️ **Runtime:** 2-10 minutes (research processing time)
+
+**Perfect for:** First-time users, testing if API works, quick demos
+
+## 📚 Advanced Examples (`advanced/` folder)
+
+More comprehensive examples for learning and advanced use cases:
+
+### 📚 `advanced/simple_http_example.py` - **COMPREHENSIVE GUIDE**
+- ✅ **Automatic user creation**
+- 📊 **Multiple API examples** (research, settings, history)
+- 🔍 **Progress monitoring** with status updates
+- ⏱️ **Runtime:** 3-15 minutes (more comprehensive testing)
+
+**Perfect for:** Learning different API endpoints, understanding the full API surface
+
+### 🚀 `advanced/http_api_examples.py` - **ADVANCED CLIENT**
+- 🔧 **Reusable client class** for integration
+- 📈 **Advanced features** (batch processing, polling)
+- 🎛️ **Comprehensive patterns** for production use
+- ⏱️ **Runtime:** 5-30 minutes (extensive testing)
+
+**Perfect for:** Building applications, production integration, advanced use cases
+
+
+## ⚙️ Configuration
+
+### Environment Variables
+
+You can configure the LDR service endpoints using environment variables:
+
+```bash
+# For local Ollama (default)
+export LDR_LLM_OLLAMA_URL=http://localhost:11434
+
+# For remote Ollama server
+export LDR_LLM_OLLAMA_URL=http://192.168.178.66:11434
+
+# For Docker compose service names
+export LDR_LLM_OLLAMA_URL=http://ollama:11434
+
+# For Docker with host networking
+export LDR_LLM_OLLAMA_URL=http://host.docker.internal:11434
+```
+
+### Docker Compose
+
+In your `docker-compose.yml`, you can set the Ollama URL:
+
+```yaml
+services:
+  ldr:
+    environment:
+      # For service name (recommended for docker-compose)
+      - LDR_LLM_OLLAMA_URL=http://ollama:11434
+
+      # For remote Ollama instance
+      # - LDR_LLM_OLLAMA_URL=http://192.168.178.66:11434
+
+      # For host machine Ollama
+      # - LDR_LLM_OLLAMA_URL=http://host.docker.internal:11434
+```
+
+### Common Network Scenarios
+
+| Scenario | Environment Variable | When to Use |
+|----------|---------------------|-------------|
+| **Local Ollama** | `http://localhost:11434` | Running Ollama on same machine |
+| **Remote Ollama** | `http://IP:11434` | Ollama on different server |
+| **Docker Compose** | `http://ollama:11434` | Using docker-compose service names |
+| **Docker Host** | `http://host.docker.internal:11434` | Docker container accessing host Ollama |
+
+## 🔍 Monitoring Progress
+
+### Server Logs
+```bash
+# Monitor real-time progress
+tail -f /tmp/ldr_server_5000.log
+
+# Check recent logs
+tail -20 /tmp/ldr_server_5000.log
+```
+
+### Web Interface
+- **Research Results:** http://localhost:5000/results/{research_id}
+- **Settings:** http://localhost:5000/settings
+- **History:** http://localhost:5000/history
+
+## 🚨 Troubleshooting
+
+### Common Issues
+
+**❌ "Cannot connect to server"**
+```bash
+# Start the server first
+python -m local_deep_research.web.app
+# or
+bash scripts/dev/restart_server.sh
+```
+
+**❌ "Authentication failed"**
+- The examples create users automatically, so this shouldn't happen
+- If it does, check that the server is running correctly
+
+**❌ "Research failed"**
+```bash
+# Check server logs for details
+tail -f /tmp/ldr_server_5000.log
+
+# Common issues:
+# - Ollama not running or wrong URL
+# - Model not available in Ollama
+# - Network connectivity issues
+```
+
+**❌ "No output from script"**
+- Scripts may take 2-10 minutes to complete research
+- Monitor progress in server logs
+- Check if research started successfully
+
+### Model Configuration
+
+Make sure your Ollama has the required models:
+
+```bash
+# List available models
+ollama list
+
+# Pull a model if needed
+ollama pull gemma3:12b
+ollama pull llama3
+ollama pull mistral
+```
+
+## 📚 What Each Example Demonstrates
+
+### simple_working_example.py
+- ✅ User creation and authentication
+- ✅ Basic research request
+- ✅ Proper CSRF token handling
+- ✅ Result URL generation
+
+### advanced/simple_http_example.py
+- ✅ All of the above PLUS:
+- ✅ Settings management
+- ✅ Research history
+- ✅ Progress polling
+- ✅ Multiple research examples
+
+### advanced/http_api_examples.py
+- ✅ All of the above PLUS:
+- ✅ Batch processing
+- ✅ Advanced polling strategies
+- ✅ Error handling patterns
+- ✅ Production-ready client class
+
+
+## 🎯 Recommended Usage Path
+
+1. **Start with `simple_working_example.py`** - Verify everything works
+2. **Try `advanced/simple_http_example.py`** - Learn the API surface
+3. **Use `advanced/http_api_examples.py`** - Build your application
+
+## 🔗 Related Documentation
+
+- [Main API Documentation](../README.md)
+- [API Quick Start](../../../docs/api-quickstart.md)
+- [Docker Configuration](../../../docker-compose.yml)
+- [Troubleshooting Guide](../../../docs/troubleshooting.md)