docs/memory/DECISIONS.md

Decisions: Cora

1. Unified Entry Point (FastAPI + Gradio)

• Problem: Running a separate API and UI process in Hugging Face Spaces is complex.
• Solution: Use gr.mount_gradio_app to serve the Gradio UI from a FastAPI instance in app.py.
• Why: Allows both programmatic API access and a user-friendly interface in a single Docker container.

2. Model Fallback Chain

• Problem: Free tier Hugging Face Inference API can be flaky or return invalid data stream errors under load.
• Solution: Implemented a "Ghost" logic chain: SDXL-Lightning -> Stable Diffusion 2.1 -> RAG Fallback (Archive Search).
• Why: Maximizes uptime and ensures the user always gets a relevant image, even if generation fails.

3. ChromaDB for Semantic Search

• Decision: Use ChromaDB as the vector store.
• Why: Lightweight, persistent, and easy to integrate with CLIP embeddings for semantic retrieval.

4. Environment Variable Fallback

• Decision: Support both HF_API_TOKEN (legacy/local) and HF_TOKEN (standard Hugging Face secret).
• Why: To ensure seamless deployment on Hugging Face Spaces where HF_TOKEN is the default secret name provided to the environment.