docs/START.md

# 🚀 Quick Start Guide

## Unified Architecture API

The project now uses a **unified architecture** where every interface goes through the REST API.

```
┌─────────────────────────────────────────────┐
│                                             │
│  Gradio UI (app.py / app_ui.py)            │
│                                             │
└──────────────────┬──────────────────────────┘
                   │
                   │ HTTP/REST
                   │
┌──────────────────▼──────────────────────────┐
│                                             │
│  FastAPI Server (app_api.py)                │
│                                             │
├─────────────────────────────────────────────┤
│  Detection Service                          │
│  ├─ RF-DETR (detection)                     │
│  ├─ CLIP (classification)                   │
│  ├─ OCR (text extraction)                   │
│  └─ BLIP (visual description)               │
└─────────────────────────────────────────────┘
```

---

## 🎯 3 Ways to Launch

### Option 1: Automatic Launch (Recommended for tests)

**One command starts everything:**

```bash
python app.py
```

**What happens:**
1. ✅ Starts the API in the background (port 8000)
2. ✅ Waits until the API is ready
3. ✅ Launches the Gradio interface (port 7860)
4. ✅ Handles clean shutdown with Ctrl+C

**Access:**
- Gradio Interface: http://localhost:7860
- API Docs: http://localhost:8000/docs

---

### Option 2: Manual Launch (2 terminals)

**For more control and debugging:**

**Terminal 1 - API Server:**
```bash
python app_api.py
```

**Terminal 2 - Gradio UI:**
```bash
python app_ui.py
```

**Access:**
- Gradio Interface: http://localhost:7860
- API Docs: http://localhost:8000/docs

---

### Option 3: API Only

**To use only the API (integration, scripts, etc.):**

```bash
python app_api.py
```

**Test the API:**
```bash
# Health check
curl http://localhost:8000/health

# Detect elements
curl -X POST "http://localhost:8000/detect" \
  -F "image=@screenshot.png" \
  -F "confidence_threshold=0.35" \
  -F "enable_clip=true" \
  -F "enable_ocr=true"
```

**Interactive documentation:**
- OpenAPI Docs: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

---

## 🔧 Configuration

### Environment Variables

**API Server:**
```bash
export UVICORN_HOST="0.0.0.0"       # Default: 0.0.0.0
export UVICORN_PORT="8000"          # Default: 8000
```

**Gradio UI:**
```bash
export GRADIO_SERVER_NAME="0.0.0.0" # Default: 0.0.0.0
export GRADIO_SERVER_PORT="7860"    # Default: 7860
export CU1_API_URL="http://localhost:8000"  # API URL
```

**Example with custom ports:**
```bash
# API on port 9000, UI on port 9001
export UVICORN_PORT="9000"
export GRADIO_SERVER_PORT="9001"
export CU1_API_URL="http://localhost:9000"

python app.py
```

---

## 🧪 Quick Tests

### Test 1: Make sure the API works

```bash
# In one terminal
python app_api.py

# In another terminal
curl http://localhost:8000/health
```

**Expected result:**
```json
{
  "status": "healthy",
  "cuda_available": false,
  "device": "cpu"
}
```

---

### Test 2: Test detection via the interface

```bash
python app.py
```

1. Open http://localhost:7860
2. Upload an image
3. Click "🔍 Detect Elements"
4. Check the results

---

### Test 3: Test detection through the API

```bash
# Start the API
python app_api.py

# In another terminal, test with curl
curl -X POST "http://localhost:8000/detect" \
  -F "image=@votre_image.png" \
  -F "confidence_threshold=0.35" \
  -F "enable_ocr=true" \
  | jq .
```

---

## 🐛 Troubleshooting

### Issue: "Connection Error - Cannot connect to API"

**Solution:**
1. Make sure the API is running: `curl http://localhost:8000/health`
2. Check the ports: no conflict with other apps
3. Check the API logs for errors

### Issue: "Port already in use"

**Solution:**
```bash
# Find the process that uses the port
lsof -i :8000  # or :7860

# Kill the process
kill -9 <PID>

# Or use a different port
export UVICORN_PORT="9000"
export GRADIO_SERVER_PORT="9001"
```

### Issue: "Module not found"

**Solution:**
```bash
# Reinstall dependencies
pip install -r requirements.txt
```

### Issue: Models slow to load

**Reason:** The first startup downloads the models

**Solution:** Be patient, the models are cached after the first download
- RF-DETR model (~few MB)
- CLIP model (~600 MB)
- BLIP model (~1 GB)
- EasyOCR models (~100 MB)

---

## 📊 Monitoring

### API logs

The logs appear in the terminal where you launched `app_api.py`

### UI logs

The logs appear in the terminal where you launched `app.py` or `app_ui.py`

### Metrics

Visit http://localhost:8000/docs to view the API statistics

---

## ✅ Benefits of the Unified Architecture

1. **Single code path** → Easier to maintain
2. **Consistent behavior** → Same results everywhere
3. **Easy to test** → Only one API to test
4. **Scalable** → Can separate API and UI on different servers
5. **Simplified debugging** → Logs centralized in the API

---

## 🎯 For Developers

### Code Architecture

```
.
├── app.py              # ✨ Unified launcher (API + UI)
├── app_api.py          # FastAPI server
├── app_ui.py           # Gradio UI client (manual)
│
├── api/
│   └── endpoints.py    # FastAPI endpoints
│
├── detection/
│   ├── service.py           # Detection service
│   ├── service_factory.py   # Singleton pattern
│   ├── image_utils.py       # Image utilities
│   ├── ocr_handler.py       # OCR-only processing
│   └── response_builder.py  # Response formatting
│
└── ui/
    ├── detection_wrapper.py   # Detection wrappers
    ├── gradio_interface.py    # Gradio interface (API client)
    └── shared_interface.py    # Shared UI components
```

### Request Flow

```
1. User uploads image in Gradio
                ↓
2. `detect_with_api()` sends an HTTP POST to `/detect`
                ↓
3. API endpoint validates the request
                ↓
4. `DetectionService.analyze()` processes the image
                ↓
5. Response formatted with `response_builder`
                ↓
6. JSON returned to Gradio UI
                ↓
7. UI displays annotated image + results
```

---

## 📝 Notes

- **Thread Safety:** The service uses a singleton but passes parameters directly to `analyze()` to avoid race conditions
- **Performance:** The first call is slow (model loading), then fast
- **Memory:** Models use ~2-3 GB of RAM
- **GPU:** Automatic CUDA/MPS detection if available

---

## 🚀 Next Steps

1. **Test locally:** `python app.py`
2. **Explore the API:** http://localhost:8000/docs
3. **Customize:** Adjust parameters in the interface
4. **Deploy:** See `DEPLOYMENT.md` for production

Happy testing! 🎉