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](https://docs.conda.io/en/latest/) 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:**
```bash
conda create -n quran_llm python=3.10 -y
conda activate quran_llm
```

2. **Install Dependencies:**
```bash
pip install -r requirements.txt
```

3. **Environment Variables:**
Create a `.env` file in the project's root directory and add your OpenAI API key:
```env
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:
```bash
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):
```bash
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`.