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

HTTP API Examples

This directory contains working examples for using the LDR HTTP API with authentication.

🚀 Quick Start

1. Start the LDR Server

# 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

# 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:

# 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:

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

# Monitor real-time progress
tail -f /tmp/ldr_server.log

# Check recent logs
tail -20 /tmp/ldr_server.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"

# 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"

# Check server logs for details
tail -f /tmp/ldr_server.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:

# 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
• API Quick Start
• Docker Configuration
• Troubleshooting Guide