myltiplex1/ChoralMind

A bilingual (English & Yoruba) hymn search bot using embeddings, FAISS, Telegram and gradio for quick lyric-based lookup. # 🎶 ChoralMind – Hymn Search Bot ChoralMind is a Telegram bot that helps you search and retrieve **English** and **Yoruba** hymns using semantic search with FAISS embeddings. Try here: ChoralMind or here: ChoralMind ## 📌 Features - Search hymns in **English** and **Yoruba** by typing any line from the hymn. - Retrieves relevant hymns using **Google Generative AI embeddings** (`models/text-embedding-004`). - Supports multilingual hymn databases with separate FAISS indexes. - Interactive **language selection** via Telegram inline buttons. - Logs all bot activity for debugging and analytics. - Maintains `hymn_id` mapping so results link back to the full hymn text. ## 🛠 Tech Stack - **Python 3.12** - python-telegram-bot - LangChain for text chunking and FAISS vector storage - Google Generative AI API for embeddings - FAISS for similarity search - pdfplumber for PDF hymn extraction - Gradio for interactive web interface ## 📂 Project Structure ``` ├── docs/ # hymns PDF source ├── data/ # Extracted hymns in JSON ├── embeddings/ # embedding scripts and FAISS Index ├── retriever/ │ └── retriever.py # HymnRetriever class ├── llm/ │ └── generate_response.py # Formats retrieved results into Telegram reply ├── telegran_bot # Telegram bot entrypoint │ └── bot.py ├── main.py # main program ├── requirements.txt # Python dependencies |── gradio_app.py # interactive web interface ``` ## ⚙️ Installation **Clone the repository** ```bash git clone github.com cd ChoralMind ``` ## 📦 Create and Activate a Virtual Environment ```bash python -m venv venv source venv/bin/activate # Linux/Mac venv\Scripts\activate # Windows ``` ## 📥 Install Dependencies ```bash pip install -r requirements.txt ``` ## ⚙️ Set Up Environment Variables Create a `.env` file: ```ini TELEGRAM_BOT_TOKEN=your_telegram_bot_token GEMINI_API_KEY=your_google_generative_ai_key ``` --- ## 📜 …