docs/README.md

# 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

```bash
# 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)**
```bash
# 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**
```bash
# 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.

```python
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.

```python
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.

```python
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.

```python
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:**
```bash
# 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](docs/README_ETYMOLOGY_API.md) for complete API documentation.

**Quick Example:**
```javascript
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

```bash
# 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:**
1. **Semantic Search**: CLIP embeddings for visual similarity
2. **Metadata Filtering**: Cultural tags ("roman", "greek", "medieval")
3. **Auto-Detection**: API extracts keywords from queries

**Example:**
```python
# Query: "roman armor"
# → Auto-detects "roman" keyword
# → Filters results by tag:roman
# → Returns only Roman artifacts (not French baroque)
```

---

## 🛡️ Error Handling

**Graceful Degradation:**
1. Primary generation (SDXL-Lightning) → 402 Payment Error
2. RAG Fallback → Search archive for relevant artifact
3. 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.**