learningcircuit--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

```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)