File size: 3,039 Bytes
38ab39c | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 | # 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)
```
|