🏹 Cupid's Archive

When love leaves you speechless, let the greatest poets in history speak for your heart.

An AI-powered love letter generator that uses Retrieval-Augmented Generation (RAG) to channel the voices of legendary poets like Shakespeare, Pablo Neruda, Elizabeth Barrett Browning, and Rumi to craft personalized, heartfelt love letters.

---

✨ Features

• 🎭 4 Legendary Poets - Choose from Shakespeare, Neruda, Browning, or Rumi
• 🧠 RAG-Powered - Uses semantic search to find relevant poetic snippets
• 🆓 Free Local Embeddings - No API quota limits (HuggingFace + FAISS)
• 💌 Personalized Letters - Weaves your details into authentic poetic style
• 📜 Letter Archive - Save and revisit your love letters
• ✨ Poet Match Quiz - Discover which poet matches your love language
• 🎨 Beautiful UI - Romantic parchment-style design with glassmorphism

---

🚀 Quick Start

1. Clone the repository

git clone https://github.com/yourusername/cupids-archive.git
cd cupids-archive

2. Install dependencies

pip install -r requirements.txt

3. Set your Google API Key

# Windows PowerShell
$env:GOOGLE_API_KEY="your-api-key-here"

# Linux/Mac
export GOOGLE_API_KEY="your-api-key-here"

Get your free API key from Google AI Studio

4. Run the app

streamlit run app.py

5. Open in browser

Navigate to http://localhost:8501 🎉

---

🛠️ Tech Stack

Core Framework

Technology	Version	Purpose
Python	3.8+	Core programming language
Streamlit	1.28+	Modern web UI framework for data apps

LangChain Ecosystem

Package	Purpose
langchain-core	Core abstractions for LLM chains, prompts, and output parsers
langchain-google-genai	Integration with Google's Gemini models
langchain-huggingface	Integration with HuggingFace embedding models
langchain-community	Community integrations including FAISS vector store

RAG Components

Component	Technology	Description
Embeddings	HuggingFace all-MiniLM-L6-v2	Free, local sentence embeddings (384 dimensions)
Vector Store	FAISS (Facebook AI Similarity Search)	Efficient similarity search and clustering
LLM	Google Gemini Flash Lite	Fast, capable language model for generation

Key Libraries

Library	Purpose
sentence-transformers	State-of-the-art sentence embeddings
faiss-cpu	Vector similarity search
langchain	LLM application framework

---

🏗️ Architecture

RAG Pipeline Flow

┌─────────────────────────────────────────────────────────────┐
│                    USER INPUT                                │
│         "She has beautiful eyes and loves poetry"            │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│              EMBEDDING LAYER (Local - FREE!)                 │
│  ┌─────────────────────────────────────────────────────┐    │
│  │  HuggingFaceEmbeddings                               │    │
│  │  Model: all-MiniLM-L6-v2                            │    │
│  │  Output: 384-dimensional vector                      │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│              VECTOR STORE (FAISS)                            │
│  ┌─────────────────────────────────────────────────────┐    │
│  │  24 poet snippets indexed                            │    │
│  │  Similarity search: cosine distance                  │    │
│  │  Returns: Top 3 most relevant snippets               │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│              LANGCHAIN PIPELINE                              │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐   │
│  │PromptTemplate│ -> │  Gemini LLM  │ -> │StrOutputParser│  │
│  │              │    │  Flash Lite  │    │              │   │
│  └──────────────┘    └──────────────┘    └──────────────┘   │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                    OUTPUT                                    │
│            💌 Personalized Love Letter                       │
│         Written in the style of chosen poet                  │
└─────────────────────────────────────────────────────────────┘

Component Breakdown

# 1. Embeddings (Free, Local)
embeddings = HuggingFaceEmbeddings(
    model_name="all-MiniLM-L6-v2"
)

# 2. Vector Store
vector_db = FAISS.from_documents(documents, embeddings)

# 3. Retrieval
relevant_docs = vector_db.similarity_search(query, k=3)

# 4. LangChain Chain
chain = PromptTemplate | ChatGoogleGenerativeAI | StrOutputParser

---

📁 Project Structure

cupids-archive/
├── app.py              # Main Streamlit application
│   ├── Page Config     # Streamlit page setup
│   ├── CSS Styling     # Romantic UI theme
│   ├── Poet Data       # 4 poets with 6 snippets each
│   ├── RAG Engine      # FAISS + HuggingFace embeddings
│   ├── UI Components   # Landing, Quiz, Form, Display, Archive
│   └── Main Logic      # View routing and state management
├── requirements.txt    # Python dependencies
├── README.md          # This documentation
└── .gitignore         # Git ignore rules

---

🎭 The Poets

Poet	Era	Style	Signature
👑 William Shakespeare	16th-17th Century	Timeless romance, eloquent verse	Sonnets, metaphors, "thee/thou"
🌹 Pablo Neruda	20th Century	Passionate, sensual, earthly love	Nature imagery, raw emotion
💐 Elizabeth Barrett Browning	19th Century	Pure devotion, spiritual depth	"How do I love thee"
🌙 Rumi	13th Century	Transcendent, soul-deep, divine love	Mystical, philosophical

---

🔧 How RAG Works in This App

What is RAG?

Retrieval-Augmented Generation (RAG) combines:

1. Retrieval: Finding relevant information from a knowledge base
2. Generation: Using an LLM to generate responses based on retrieved context

Our Implementation:

1. Indexing (on startup):

   • All 24 poet snippets are embedded using HuggingFace
   • Vectors stored in FAISS for fast similarity search

2. Retrieval (when user submits):

   • User's description is embedded
   • FAISS finds the 3 most similar poet snippets
   • Only snippets from the selected poet are used

3. Generation:

   • LangChain creates a prompt with retrieved snippets
   • Gemini generates a letter in the poet's authentic voice
   • Output is parsed and displayed

---

💡 Why These Technologies?

Choice	Reason
Local Embeddings	No API limits, privacy, works offline
FAISS	Industry standard, fast, memory efficient
LangChain	Clean abstractions, easy to extend
Gemini Flash Lite	Fast, cost-effective, good quality
Streamlit	Rapid prototyping, beautiful UI components

---

🤝 Contributing

Contributions are welcome! Ideas:

• Add more poets (Emily Dickinson, Lord Byron, etc.)
• Implement letter sharing/export features
• Add more quiz questions
• Improve the UI/UX
• Add multi-language support

---

📄 License

MIT License - feel free to use this for your own projects!

---

💝 Made with Love

Built with ❤️ using:

• 🦜 LangChain for LLM orchestration
• 🤗 HuggingFace for free embeddings
• ⚡ FAISS for vector search
• ✨ Gemini for generation
• 🎈 Streamlit for the UI

---

"Love looks not with the eyes, but with the mind, and therefore is winged Cupid painted blind." - Shakespeare