🌙 Islamic Knowledge Chatbot

An AI-powered chatbot that answers questions about Islam, Quran, and Hadith using RAG (Retrieval-Augmented Generation) and a Multi-Agent System with persistent conversation memory.

✨ Features

🤖 Multi-Agent System - 3 specialized agents for classification, generation, and validation
📚 RAG Implementation - Retrieves relevant information from Islamic texts (PDFs & CSVs)
💾 Persistent Conversation Memory - Maintains context across conversations with session support
🔄 Iterative Refinement - Up to 3 iterations to improve response quality
🌐 REST API with Sessions - FastAPI-based API with multi-session support
📖 Multi-lingual Support - Handles Arabic, Urdu, and English content
🎯 Smart Classification - Filters non-Islamic queries
🔐 Session Management - Independent conversation history per user session

🏗️ Architecture

User Query → Agent 1 (Classifier) → Agent 2 (Generator) → Agent 3 (Validator) → User
                                           ↑                        ↓
                                           └──── Feedback Loop ─────┘
                                              (max 3 iterations)
                                              
Session Memory: Stores conversation history per session

Agent Roles

Agent	Role	Description
Agent 1	Classifier	Determines if the question is related to Islamic topics
Agent 2	Generator	Retrieves relevant context and generates responses using RAG with memory context
Agent 3	Validator	Validates response quality and provides feedback for improvement

Memory System

ConversationManager - Maintains conversation history with HumanMessage and AIMessage objects
Session-Based Storage - Each API session gets its own independent memory
Iteration Tracking - Records all refinement iterations per question
History Retrieval - Access full or recent conversation history

📋 Prerequisites

Before you begin, ensure you have the following:

Python 3.8 or higher
Ollama installed and running
At least 4GB RAM available
2-3GB disk space for models

🚀 Installation

Step 1: Clone or Download the Project

cd islamic_rag_chatbot

Step 2: Create Virtual Environment

Windows:

python -m venv .venv
.venv\Scripts\activate

Mac/Linux:

python3 -m venv .venv
source .venv/bin/activate

Step 3: Install Dependencies

pip install -r requirements.txt

Step 4: Install Ollama Models

# Install Ollama from https://ollama.ai

# Pull required models
ollama pull gemma3:1b          # Chat model
ollama pull nomic-embed-text   # Embedding model

Step 5: Start Ollama Service

Keep this running in a separate terminal:

ollama serve

Step 6: Prepare Your Data

# Create data directories
mkdir -p data/pdfs data/csvs

# Add your Islamic content:
# - PDF files (Hadith, Islamic books) → data/pdfs/
# - CSV files (Quran translations) → data/csvs/

📁 Project Structure

islamic_rag_chatbot/
├── agents/
│   ├── __init__.py
│   ├── classifier_agent.py      # Agent 1: Question classification
│   ├── generator_agent.py       # Agent 2: Response generation with memory
│   └── validator_agent.py       # Agent 3: Response validation
│
├── utils/
│   ├── __init__.py
│   ├── document_loader.py       # PDF & CSV loading
│   ├── vector_store.py          # ChromaDB vector store
│   └── memory.py                # Conversation memory manager
│
├── data/
│   ├── pdfs/                    # Islamic PDF documents
│   └── csvs/                    # Quran CSV data
│
├── vectorstore/                 # Auto-generated embeddings
│
├── main.py                      # Command-line interface with memory
├── api.py                       # FastAPI REST API with session management
├── requirements.txt
├── .gitignore
└── README.md

🎯 Usage

Command-Line Interface

Start the chatbot in interactive mode with persistent memory:

python main.py

Available Commands

Command	Description
Type your question	Ask anything about Islam - memory is maintained
`history`	View full conversation history
`quit` or `exit`	Exit the chatbot

Example Session

You: What are the 5 pillars of Islam?
🤖 Assistant: The five pillars of Islam are...

You: Tell me more about Salah
🤖 Assistant: Salah (prayer) is one of the five pillars you asked about. It is...

You: history
📜 History:
You: What are the 5 pillars of Islam?
Assistant: The five pillars of Islam are...

You: Tell me more about Salah
Assistant: Salah (prayer) is one of the five pillars you asked about...

REST API with Session Memory

Start the API server:

uvicorn api:app --host 0.0.0.0 --port 8000 --reload

Or simply:

python api.py

Interactive API Documentation:
Open http://localhost:8000/docs in your browser

📡 API Endpoints

Health Check

Check if the API is running:

GET /health

Response:
{
  "status": "healthy",
  "message": "Islamic Knowledge Chatbot is running",
  "models": {
    "chat_model": "gemma3:1b",
    "embedding_model": "nomic-embed-text"
  }
}

Create Session

Create a new chat session with independent memory:

POST /session/new

Response:
{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2024-01-15T10:30:00"
}

Chat with Memory

Send a message and get a response (memory is automatically maintained):

POST /chat

Body:
{
  "message": "What is Ramadan?",
  "session_id": "550e8400-e29b-41d4-a716-446655440000"  (optional, generates new if not provided)
}

Response:
{
  "response": "Ramadan is the ninth month of the Islamic calendar...",
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "is_relevant": true,
  "timestamp": "2024-01-15T10:35:00"
}

Multi-turn Example:

# First message
POST /chat
{
  "message": "What is Salah?",
  "session_id": "550e8400-e29b-41d4-a716-446655440000"
}

# Second message (chatbot remembers the first question)
POST /chat
{
  "message": "How many times should I perform it daily?",
  "session_id": "550e8400-e29b-41d4-a716-446655440000"
}

# Response will reference the previous Salah discussion

Get Conversation History

Retrieve full conversation history for a session:

GET /history/{session_id}

Response:
{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "history": "You: What is Ramadan?\n\nAssistant: Ramadan is...\n\nYou: Why is fasting important?\n\nAssistant: Fasting in Ramadan is important because...",
  "message_count": 4
}

List All Sessions

Get all active sessions with their message counts:

GET /sessions

Response:
{
  "total_sessions": 3,
  "sessions": [
    {
      "session_id": "550e8400-e29b-41d4-a716-446655440000",
      "created_at": "2024-01-15T10:30:00",
      "message_count": 6
    },
    {
      "session_id": "660e8400-e29b-41d4-a716-446655440001",
      "created_at": "2024-01-15T11:00:00",
      "message_count": 2
    }
  ]
}

Get Session Info

Get detailed information about a specific session:

GET /session/{session_id}/info

Response:
{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "created_at": "2024-01-15T10:30:00",
  "message_count": 6,
  "iteration_count": 3,
  "status": "active"
}

Clear Session

Delete a specific session and its memory:

DELETE /session/clear/{session_id}

Response:
{
  "message": "Session 550e8400-e29b-41d4-a716-446655440000 cleared successfully"
}

💾 Memory Features

How Memory Works

Session Creation - Each new chat creates a ConversationManager instance
Message Storage - Questions and answers are stored as HumanMessage and AIMessage objects
Context Retrieval - Recent conversation history is automatically included when generating responses
Iteration Tracking - All refinement iterations are recorded for analysis
Independent Storage - Each session maintains its own separate memory

Memory Data Structure

Session = {
  "session_id": "uuid",
  "created_at": "timestamp",
  "conversation_manager": {
    "messages": [HumanMessage(...), AIMessage(...), ...],
    "iteration_history": [
      {"iteration": 1, "response": "...", "approved": false, "feedback": "..."},
      {"iteration": 2, "response": "...", "approved": true, "feedback": "..."}
    ]
  }
}

Accessing Memory

Via CLI:

You: history
# Shows all messages in the current session

Via API:

GET /history/{session_id}
# Returns formatted conversation history

🔧 Configuration

Model Configuration

Edit in main.py or api.py:

chatbot = IslamicRAGChatbot(
    pdf_dir="./data/pdfs",
    csv_dir="./data/csvs",
    vectorstore_dir="./vectorstore",
    max_iterations=3,                    # Max refinement iterations
    chat_model="gemma3:1b",              # Chat model
    embedding_model="nomic-embed-text"   # Embedding model
)

Memory Configuration

Edit in utils/memory.py:

class ConversationManager:
    def __init__(self):
        self.messages = []                 # Stores HumanMessage and AIMessage objects
        self.iteration_history = []        # Tracks refinement iterations

Chunk Size Configuration

Edit in utils/document_loader.py:

DocumentProcessor(
    chunk_size=1500,      # Larger = fewer chunks, less detail
    chunk_overlap=200     # Overlap between chunks
)

🧪 Testing

Test API with Python

import requests

# Create a new session
response = requests.post("http://localhost:8000/session/new")
session_id = response.json()["session_id"]
print(f"Session created: {session_id}")

# First message
response = requests.post(
    "http://localhost:8000/chat",
    json={
        "message": "What are the 5 pillars of Islam?",
        "session_id": session_id
    }
)
print(response.json()["response"])

# Second message (memory is maintained)
response = requests.post(
    "http://localhost:8000/chat",
    json={
        "message": "Tell me more about Salah",
        "session_id": session_id
    }
)
print(response.json()["response"])

# Get conversation history
response = requests.get(f"http://localhost:8000/history/{session_id}")
print(response.json()["history"])

# List all sessions
response = requests.get("http://localhost:8000/sessions")
print(response.json())

Test API with HTTPie

# Create session
http POST http://localhost:8000/session/new

# Send message
http POST http://localhost:8000/chat \
  message="What is Ramadan?" \
  session_id="your-session-id"

# Get history
http GET http://localhost:8000/history/your-session-id

# List sessions
http GET http://localhost:8000/sessions

📊 Performance

First-Time Setup

Task	Duration
PDF Processing (2800 pages)	~2-5 minutes
CSV Processing (6000+ verses)	~30 seconds
Embedding Creation	~30-60 minutes (one-time only)
Vector Store Size	~500MB-1GB

After Setup

Metric	Value
Loading Time	5-10 seconds
Query Response	5-15 seconds
Memory Usage	~2-3GB RAM
Session Memory Overhead	~1-5KB per message

🎨 Supported Content

PDF Documents

✅ Hadith collections (Sahih Bukhari, Muslim, Tirmidhi, etc.)
✅ Islamic books and texts
✅ Scholar writings
⚠️ Some PDFs may fail due to encoding issues

CSV Files

✅ Quran translations (Arabic, Urdu, English)
✅ Format: verse_num, surah, ..., arabic, urdu, english
✅ Handles UTF-8 and other encodings

🔍 Example Multi-Turn Conversations

Example 1: Progressive Learning

User: What is Zakat?
Bot: Zakat is one of the five pillars of Islam...

User: What are the conditions for paying Zakat?
Bot: Based on our discussion about Zakat, the conditions are...

User: How does this relate to Ramadan?
Bot: While we were discussing Zakat, you might be interested to know that many Muslims pay their annual Zakat during Ramadan because...

Example 2: Context Awareness

User: Tell me about Prophet Muhammad
Bot: Prophet Muhammad was born in Mecca...

User: Who were his companions?
Bot: Some of Prophet Muhammad's most notable companions were...

User: What did they do after his death?
Bot: After Prophet Muhammad's death, his companions continued to spread his teachings...

⚠️ Troubleshooting

Ollama Connection Error

Error:

ERROR: Cannot connect to Ollama!

Solution:
Make sure Ollama is running in a separate terminal:

ollama serve

Model Not Found

Error:

ERROR: Model 'gemma3:1b' not found!

Solution:
Pull the required models:

ollama pull gemma3:1b
ollama pull nomic-embed-text

Session Not Found

Error:

{"detail": "Session not found"}

Solution:
The session ID may have expired. Create a new session:

POST /session/new

Vector Store Loading Error

Error:

Error loading vector store

Solution:
Delete and recreate the vector store:

Windows:

Remove-Item -Recurse -Force vectorstore

Mac/Linux:

rm -rf vectorstore

Then run:

python main.py

Memory Not Being Maintained

Solution:

Ensure you're using the same session_id in subsequent requests
Check that the session exists: GET /sessions
Verify memory with: GET /history/{session_id}

🚀 Deployment

Docker Deployment

Create a Dockerfile:

FROM python:3.12-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8000

CMD ["uvicorn", "api:app", "--host", "0.0.0.0", "--port", "8000"]

Build and run:

docker build -t islamic-chatbot .
docker run -p 8000:8000 islamic-chatbot

Environment Variables

Create a .env file:

OLLAMA_HOST=http://localhost:11434
CHAT_MODEL=gemma3:1b
EMBEDDING_MODEL=nomic-embed-text
MAX_ITERATIONS=3

📝 Requirements

langchain>=0.1.0
langchain-community>=0.0.13
langchain-ollama>=0.0.1
langchain-core>=0.1.0
chromadb>=0.4.22
sentence-transformers>=2.3.1
pypdf>=4.0.1
pandas>=2.1.4
ollama>=0.1.6
tiktoken>=0.5.2
fastapi>=0.104.0
uvicorn>=0.24.0
python-multipart>=0.0.6
requests>=2.31.0

🤝 Contributing

Contributions are welcome! Here's how you can help:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is for educational purposes. Ensure you have the rights to use the Islamic texts you include.

Acknowledgments

Ollama - For local LLM inference
LangChain - For RAG framework
ChromaDB - For vector storage
FastAPI - For API framework
Islamic text sources and contributors

🔄 Version History

Version 2.0.0 (Current) - With Session Memory

✅ Multi-agent system with 3 specialized agents
✅ RAG implementation with ChromaDB
✅ Persistent session-based conversation memory
✅ Multi-session API support
✅ Memory endpoints for history retrieval
✅ Iteration tracking per session
✅ FastAPI REST API with session management
✅ PDF and CSV document support
✅ Multi-lingual support (Arabic, Urdu, English)

Version 1.0.0 (Previous)

✅ Basic multi-agent system
✅ RAG implementation
✅ Single session memory
✅ REST API

Made with ❤️ for the Muslim community

السلام عليكم ورحمة الله وبركاته

Peace be upon you and God's mercy and blessings

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
agents		agents
data		data
utils		utils
vectorstore/f209c456-4ad6-49c7-a6dc-f8b4052c86a5		vectorstore/f209c456-4ad6-49c7-a6dc-f8b4052c86a5
.gitignore		.gitignore
README.md		README.md
api.py		api.py
main.py		main.py
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

🌙 Islamic Knowledge Chatbot

✨ Features

🏗️ Architecture

Agent Roles

Memory System

📋 Prerequisites

🚀 Installation

Step 1: Clone or Download the Project

Step 2: Create Virtual Environment

Step 3: Install Dependencies

Step 4: Install Ollama Models

Step 5: Start Ollama Service

Step 6: Prepare Your Data

📁 Project Structure

🎯 Usage

Command-Line Interface

Available Commands

Example Session

REST API with Session Memory

📡 API Endpoints

Health Check

Create Session

Chat with Memory

Get Conversation History

List All Sessions

Get Session Info

Clear Session

💾 Memory Features

How Memory Works

Memory Data Structure

Accessing Memory

🔧 Configuration

Model Configuration

Memory Configuration

Chunk Size Configuration

🧪 Testing

Test API with Python

Test API with HTTPie

📊 Performance

First-Time Setup

After Setup

🎨 Supported Content

PDF Documents

CSV Files

🔍 Example Multi-Turn Conversations

Example 1: Progressive Learning

Example 2: Context Awareness

⚠️ Troubleshooting

Ollama Connection Error

Model Not Found

Session Not Found

Vector Store Loading Error

Memory Not Being Maintained

🚀 Deployment

Docker Deployment

Environment Variables

📝 Requirements

🤝 Contributing

📄 License

Acknowledgments

🔄 Version History

Version 2.0.0 (Current) - With Session Memory

Version 1.0.0 (Previous)

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages