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:

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

Response:

{
  "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:

{
  "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)

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

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)