README.md

Quran RAG Agent System

A comprehensive AI-powered system designed to provide deep, scholarly Tafsir (interpretations) of the Quran. Built using LangChain, OpenAI, and ChromaDB, the system employs a robust Dual-Agent Architecture to accurately extract Quranic references and contextualize interpretations from a diverse pool of authenticated scholarly works.

Features

• Dual-Agent Workflow:
  • Contextualizing Agent (Quran Expert): Precision-parses user queries to identify and extract exact Ayah (verse) references.
  • RAG Agent (Tafsir Specialist): Analyzes the localized embeddings and generates high-level scholarly responses grounded explicitly in the retrieved Tafsir chunks.
• Robust Fallback Logic: Identifies potential model token-limit exceptions when evaluating multiple scattered verses, safely downgrading to single-verse analysis and alerting the user.
• Interactive UI: A full Gradio-based web interface (quran_rag_agent.py).
• RESTful API: A FastAPI backend (quran_api.py) for integration into external apps.

Prerequisites

To run this project, make sure you have Conda installed on your primary system.

Installation & Setup

All execution and dependency management must happen inside the quran_llm Conda environment.

1. Create and activate the Conda Environment:

conda create -n quran_llm python=3.10 -y
conda activate quran_llm

2. Install Dependencies:

pip install -r requirements.txt

3. Environment Variables: Create a .env file in the project's root directory and add your OpenAI API key:

OPENAI_API_KEY=your_openai_api_key_here

Running the Project

Option 1: Gradio Web Interface

To interact directly with the Quran Expert assistant through a user-friendly Chat UI:

conda activate quran_llm
python quran_rag_agent.py

The web app will generally launch on http://127.0.0.1:7860.

Option 2: FastAPI Server

To launch the RESTful backend endpoints (great for frontend/mobile app integrations):

conda activate quran_llm
uvicorn quran_api:app --reload --host 0.0.0.0 --port 8000

Explore the interactive API documentation at http://127.0.0.1:8000/docs.

Initial Run & Vector Store Ingestion

The first time you run the application, it will dynamically authenticate with HuggingFace, download the MohamedRashad/Quran-Tafseer dataset, convert all verses and interpretations using OpenAI's text-embedding-3-small model, and build the persistent ChromaDB index locally. This will take time. Once complete, the vector index will be saved to ./chromadb_quran_tafsir for instant startup on future executions.

Architecture Guidelines

To modify the core Tafsir generation prompts, update the System Prompts contained within:

• agent1_system_prompt (Ayah parsing logic)
• agent2_system_prompt (Generation, restriction, hallucination-guarding logic) Within both quran_rag_agent.py and quran_api.py.