Cora - Visual Curating System
AI-powered historical illustration generator for etymological applications
Cora transforms etymological entries into compelling historical illustrations using a hybrid approach of AI-generation with museum artifact fallback (RAG).
🎯 Overview
Cora is a complete visual generation pipeline designed to enhance etymology applications with historically-authentic illustrations. When modern AI generation fails (e.g., API payment limits), the system seamlessly falls back to serving curated museum artifacts from Smithsonian and Met Museum collections.
Key Features:
- 🎨 Visual Curator: LLM-powered prompt refinement for historical accuracy
- 🖼️ Dual-Source Generation: SDXL-Lightning primary + RAG fallback
- 🏛️ Museum Integration: Automated ingestion from Smithsonian & Met APIs
- 🔍 Hybrid Search: Semantic similarity + metadata filtering
- 🌐 Etymology API: Production-ready endpoint for integration
- 💾 Persistent Archive: ChromaDB-based vector store with CLIP embeddings
🏗️ Architecture
Etymology App (Frontend)
↓
Etymology API (Port 8000)
↓
┌─────────────────────────────────────────┐
│ CORA PIPELINE │
├─────────────────────────────────────────┤
│ 1. Curator (Prompt Refinement) │
│ ↓ │
│ 2. Engine (Image Generation) │
│ ├─ Primary: SDXL-Lightning (HF API) │
│ └─ Fallback: RAG (Museum Archives) │
│ ↓ │
│ 3. Vision (CLIP Embeddings) │
│ ↓ │
│ 4. Memory (ChromaDB Archival) │
└─────────────────────────────────────────┘
🚀 Quick Start
Prerequisites
- Python 3.8+
- Hugging Face API Token (for generation)
- Smithsonian API Key (for data ingestion)
Installation
# Clone/Navigate to project
cd c:\Users\Administrador\cora
# Install dependencies
pip install -r requirements.txt
# Configure environment
# Edit .env file with your API keys:
HF_API_TOKEN=your_huggingface_token
SI_API_KEY=your_smithsonian_key
Running the System
Option 1: Full Stack (UI + API)
# Terminal 1: Start API server
python api.py
# Terminal 2: Start Gradio UI
python ui.py
# Access UI at http://127.0.0.1:7861
Option 2: Etymology API Only
# Start etymology integration endpoint
python etymology_api.py
# Test the endpoint
python test_etymology_api.py
📦 Core Components
1. CoraCurator (cora_curator.py)
LLM-powered prompt refinement for visual accuracy.
from cora_curator import CoraCurator
curator = CoraCurator()
refined = curator.refine_prompt("mercenaries")
# → "Historical scene depicting Roman mercenaries in authentic armor..."
2. CoraEngine (cora_engine.py)
Image generation with automatic RAG fallback.
from cora_engine import CoraEngine
engine = CoraEngine()
image = engine.generate_from_text("Roman soldier")
# Returns PIL Image (generated or museum artifact)
3. CoraVision (cora_vision.py)
CLIP-based visual embeddings + YOLO object detection.
from cora_vision import CoraVision
vision = CoraVision()
embedding = vision.embed_image(pil_image) # 768-dim vector
tags = vision.detect_tags(pil_image) # ["person", "armor", "weapon"]
4. CoraMemory (cora_memory.py)
ChromaDB vector store with hybrid search.
from cora_memory import CoraMemory
memory = CoraMemory()
memory.save(path, embedding, prompt, tags)
results = memory.search_hybrid(vector, k=5, tag_filter=["roman"])
📚 Data Sources
Museum APIs
- Smithsonian Open Access:
loaders/smithsonian_loader.py - Met Museum Collection:
loaders/met_loader.py
Example Usage:
# Load Roman artifacts from Met Museum
python loaders/met_loader.py
# Load from Smithsonian
python loaders/smithsonian_loader.py
Indexed Artifacts: 16+ historical items (armor, sculptures, reliefs, engravings)
🔧 API Reference
See docs/README_ETYMOLOGY_API.md for complete API documentation.
Quick Example:
fetch('http://localhost:8000/api/v1/generate_illustration', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
word: "gladiator",
etymology_context: "From Latin 'gladius' (sword)",
style: "historical_illustration"
})
})
🧪 Testing
# Test generation parameters
python tests/test_gen_params.py
# Test etymology API integration
python tests/test_etymology_api.py
# Verify system components
python tests/verify_system.py
📁 Project Structure
cora/
├── api.py # Main API server (UI backend)
├── etymology_api.py # Etymology app integration endpoint
├── ui.py # Gradio interface
│
├── cora_curator.py # Prompt refinement (LLM)
├── cora_engine.py # Image generation + RAG
├── cora_vision.py # CLIP embeddings + YOLO
├── cora_memory.py # ChromaDB vector store
│
├── loaders/
│ ├── smithsonian_loader.py # Smithsonian API ingestion
│ └── met_loader.py # Met Museum API ingestion
│
├── scripts/
│ └── load_roman_artifacts.py # Example: batch artifact loading
│
├── tests/
│ ├── test_etymology_api.py
│ ├── test_gen_params.py
│ ├── verify_system.py
│ └── ... # Other test scripts
│
├── archive_images/ # Downloaded museum artifacts (gitignored)
├── archive_db/ # ChromaDB persistent storage (gitignored)
│
├── docs/
│ ├── README.md # Project overview (this file)
│ ├── ARCHITECTURE.md # System design details
│ ├── SETUP.md # Installation guide
│ └── README_ETYMOLOGY_API.md # API integration guide
│
├── requirements.txt
├── .env # API keys (gitignored)
└── .gitignore
🎨 Visual Style
Target Aesthetic: Historical Illustration / Strategy Game Art
Prompt Engineering: The system guides all prompts toward two narrative modes:
- Daily Life: Authentic period scenes (markets, workshops, households)
- Epic Dimension: Heroic/mythological moments (battles, ceremonies, divine encounters)
Technical Parameters (SDXL-Lightning):
guidance_scale = 0.0(no CFG)num_inference_steps = 4(ultra-fast)- Resolution: 1024x1024
🔍 Search & Retrieval
Hybrid Search Strategy:
- Semantic Search: CLIP embeddings for visual similarity
- Metadata Filtering: Cultural tags ("roman", "greek", "medieval")
- Auto-Detection: API extracts keywords from queries
Example:
# Query: "roman armor"
# → Auto-detects "roman" keyword
# → Filters results by tag:roman
# → Returns only Roman artifacts (not French baroque)
🛡️ Error Handling
Graceful Degradation:
- Primary generation (SDXL-Lightning) → 402 Payment Error
- RAG Fallback → Search archive for relevant artifact
- Serve museum image instead of failing
Zero Downtime: System never returns an error if archive is populated.
🚧 Known Issues
- API Crashes: Port 8000 conflicts occasionally require restart
- HF Rate Limits: Free tier subject to usage quotas
- Museum APIs: Smithsonian requires API key; Met is fully open
📝 License & Attribution
Museum Sources:
- Smithsonian Open Access (CC0)
- Met Museum Open Access (Public Domain)
AI Models:
- SDXL-Lightning (Stability AI)
- CLIP-ViT-L-14 (OpenAI)
- YOLOv8 (Ultralytics)
🤝 Contributing
This project is part of a larger etymology application. For integration questions, see docs/README_ETYMOLOGY_API.md.
Built with the philosophy of blending synthetic creation with authentic historical preservation.