README.md

metadata

title: Sacred Texts RAG
emoji: 🕊️
colorFrom: yellow
colorTo: gray
sdk: docker
app_port: 7860
pinned: false

🕊️ Sacred Texts RAG — Multi-Religion Knowledge Base

A Retrieval-Augmented Generation (RAG) application that answers spiritual queries using the Bhagavad Gita, Quran, Bible, and Guru Granth Sahib as the sole knowledge sources. Now with multi-turn conversation memory — ask follow-up questions naturally, just like a real dialogue.

---

📁 Project Structure

sacred-texts-rag/
├── README.md
├── requirements.txt
├── .env.example
├── ingest.py               # Step 1: Load PDFs → chunk → embed → store
├── rag_chain.py            # Core RAG chain logic (with session memory)
├── app.py                  # FastAPI backend server
└── frontend/
    └── index.html          # Chat UI (served by FastAPI)

---

⚙️ Setup Instructions

1. Install Dependencies

pip install -r requirements.txt

2. Configure Environment

cp .env.example .env
# Edit .env and add your NVIDIA_API_KEY

3. Add Your PDF Books

Place your PDF files in a books/ folder:

books/
├── bhagavad_gita.pdf
├── quran.pdf
├── bible.pdf
└── guru_granth_sahib.pdf

4. Ingest the Books (Run Once)

python ingest.py

This will:

• Load and parse all PDFs
• Split into semantic chunks
• Create embeddings using NVIDIA's llama-nemotron-embed-vl-1b-v2 model
• Store in a local ChromaDB vector store (./chroma_db/)

5. Start the Backend

python app.py

Server runs at: http://localhost:7860

6. Open the Frontend

Navigate to http://localhost:7860 in your browser — the FastAPI server serves the UI directly.

---

🔑 Environment Variables

Variable	Description	Default
NVIDIA_API_KEY	Your NVIDIA API key	—
CHROMA_DB_PATH	Path to ChromaDB storage	./chroma_db
COLLECTION_NAME	ChromaDB collection name	sacred_texts
CHUNKS_PER_BOOK	Chunks retrieved per book per query	3
MAX_HISTORY_TURNS	Max conversation turns kept in memory per session	6
HOST	Server bind host	0.0.0.0
PORT	Server port	7860

---

🧠 How It Works

User Query
    │
    ▼
[Session Memory]  ←── Injects prior conversation turns into LLM context
    │
    ▼
[Query Augmentation]  ←── Short follow-ups are enriched with previous question
    │
    ▼
[Hybrid Retrieval: BM25 + Vector Search]  ←── Per-book guaranteed slots
    │
    ▼
[NVIDIA Reranker]  ←── llama-3.2-nv-rerankqa-1b-v2 re-scores pooled candidates
    │
    ▼
[Semantic Cache Check]  ←── Skip LLM if a similar question was answered before
    │
    ▼
[Prompt with Context + History]
    │
    ▼
[Llama-3.3-70b-instruct]  ←── Answer grounded ONLY in retrieved texts
    │
    ▼
Streamed response with source citations (book + chapter/verse)

---

💬 Multi-Turn Conversation

The app maintains per-session conversation history so you can ask natural follow-up questions:

You:  "What do the scriptures say about forgiveness?"
AI:   [Answer citing Gita, Quran, Bible, Guru Granth Sahib]

You:  "Elaborate on the second point"       ← follow-up, no context needed
AI:   [Continues from previous answer]

You:  "What does the Bible say specifically?"  ← drill-down
AI:   [Focuses on Bible passages from the thread]

How sessions work:

• A session ID is created automatically on your first question and persisted in the browser's localStorage
• The server keeps the last MAX_HISTORY_TURNS (default: 6) human+AI pairs in memory
• Click ↺ New Conversation in the header to clear history and start fresh
• Sessions are scoped to the server process — they reset on server restart

---

🌐 API Endpoints

Method	Endpoint	Description
POST	/ask	Ask a question; streams NDJSON response
POST	/clear	Clear conversation history for a session
GET	/history	Inspect conversation history for a session
GET	/books	List all books indexed in the knowledge base
GET	/health	Health check
GET	/	Serves the frontend UI
GET	/docs	Swagger UI

/ask Request Body

{
  "question": "What do the scriptures say about compassion?",
  "session_id": "optional-uuid-string"
}

/ask Response (streamed NDJSON)

{"type": "token",   "data": "The Bhagavad Gita teaches..."}
{"type": "token",   "data": " compassion as..."}
{"type": "sources", "data": [{"book": "Bhagavad Gita 2:47", "page": "2:47", "snippet": "..."}]}

Cache hits return a single {"type": "cache", "data": {"answer": "...", "sources": [...]}} line.

---

📝 Notes

• The LLM is instructed never to answer from outside the provided texts
• Each response includes source citations (book + chapter/verse where available)
• Responses synthesize wisdom across all books when relevant
• The semantic cache skips the LLM for repeated or near-identical questions (cosine distance < 0.35)
• Follow-up retrieval automatically augments vague short queries with the previous question for better semantic matching

---

🗺️ Planned Features

• Contextual chunk expansion (fetch ±1 surrounding chunks)
• HyDE — Hypothetical Document Embedding for abstract queries
• Answer faithfulness scoring (LLM-as-judge)
• Query rewriting for vague inputs
• Snippet preview on source hover
• Query suggestions after each answer
• Compare mode — side-by-side view across books
• Hallucination guardrail
• Out-of-scope detection
• Rate limiting & API key hardening

---

🎬 Demo

App Link: https://shouvik99-lifeguide.hf.space/