docs/README_ETYMOLOGY_API.md

# Etymology App Integration Guide

## Overview
`etymology_api.py` provides a unified endpoint for generating historical illustrations from etymological data.

## Endpoints

### 1. Generate Illustration
**POST** `/api/v1/generate_illustration`

Generate a historical illustration for an etymological entry.

**Request Body:**
```json
{
  "word": "mercenaries",
  "etymology_context": "From Latin 'mercenarius' meaning hired soldier, derived from 'merces' (wages, pay)",
  "style": "historical_illustration"
}
```

**Response:**
```json
{
  "success": true,
  "image_url": "http://localhost:8000/archive_images/etym_mercenaries_a3f4.png",
  "image_base64": "iVBORw0KGgoAAAANSUhEUgAA...",
  "prompt_used": "Historical scene depicting Roman mercenaries...",
  "tags": ["person", "armor", "weapon", "etymology:mercenaries"],
  "source": "generated"
}
```

### 2. Search Archive
**GET** `/api/v1/search_archive?query=roman&limit=5`

Search the visual archive for relevant artifacts.

**Response:**
```json
{
  "results": [
    {
      "url": "http://localhost:8000/archive_images/met_12345.jpg",
      "tags": "roman,met_museum_open_access,armor",
      "prompt": "Roman legionary armor",
      "score": 0.23
    }
  ]
}
```

### 3. Health Check
**GET** `/health`

Verify API status and component health.

## Integration Example (JavaScript)

```javascript
async function generateEtymologyIllustration(word, etymologyText) {
  const response = await fetch('http://localhost:8000/api/v1/generate_illustration', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      word: word,
      etymology_context: etymologyText,
      style: 'historical_illustration'
    })
  });
  
  const data = await response.json();
  
  if (data.success) {
    // Option 1: Use URL
    const img = document.createElement('img');
    img.src = data.image_url;
    
    // Option 2: Use base64 for offline/embed
    img.src = `data:image/png;base64,${data.image_base64}`;
    
    return img;
  } else {
    console.error('Generation failed:', data.error);
    return null;
  }
}
```

## Deployment Notes

### Local Development
```bash
cd c:\Users\Administrador\cora
python etymology_api.py
```
API will be available at `http://localhost:8000`

### Production Considerations
1. **CORS**: Update `allow_origins` in `etymology_api.py` to your domain
2. **Rate Limiting**: Add rate limiting middleware for public deployments
3. **Authentication**: Add API key validation if needed
4. **Caching**: Consider caching generated images by etymology text hash

## Architecture

```
Etymology App (Frontend)
    ↓ HTTP POST /api/v1/generate_illustration
Etymology API (etymology_api.py)
    ↓
CoraCurator (prompt refinement)
    ↓
CoraEngine (image generation)
    ↓ (on 402 error)
CoraMemory (RAG fallback - serve museum artifacts)
    ↓
Response (image URL + base64 + metadata)
```