QModel v7 — Islamic RAG System

Specialized Qur'an & Hadith Knowledge System with Dual LLM Support

A production-ready Retrieval-Augmented Generation system specialized exclusively in authenticated Islamic knowledge. No hallucinations, no outside knowledge—only content from verified sources.

---

Features

📖 Qur'an Capabilities

• Verse Lookup: Find verses by topic or keyword
• Word Frequency: Count occurrences with Surah breakdown
• Root Analysis: Explore verses sharing the same 3-letter Arabic root
• Bilingual: Full Arabic + English translation support
• Tafsir Integration: AI-powered contextual interpretation

📚 Hadith Capabilities

• Isnad Highlighting: Chain of narrators emphasized in responses
• Authenticity Verification: Check if Hadith is in authenticated collections
• Grade Display: Show Sahih/Hasan/Da'if authenticity levels
• Topic Search: Find relevant Hadiths across 9 major collections
• Collection Navigation: Filter by Bukhari, Muslim, Abu Dawud, etc.

🛡️ Safety Features

• Dynamic Confidence Gating: Intent-aware thresholds (stricter for authenticity)
• Reasoning Support: Capture and stream model thinking/Chain-of-Thought
• Source Attribution: Every answer cites exact verse/Hadith reference
• Verbatim Quotes: Text copied directly from data, never paraphrased
• Anti-Hallucination: Hardened prompts with citation verification

🚀 Integration

• OpenAI-Compatible API: Use with Open-WebUI, Langchain, or any OpenAI client
• OpenAI Schema: Full support for /v1/chat/completions and /v1/models
• Streaming Responses: SSE streaming for long-form answers

⚙️ Technical

• Dual LLM Backend: Ollama (dev) + HuggingFace (prod)
• Hybrid Search: Dense (FAISS) + Sparse (BM25) scoring
• Async API: FastAPI with async/await throughout
• Caching: TTL-based LRU cache for frequent queries
• Scale: 6,236 Quranic verses + 40,943 Hadiths indexed

---

Quick Start

Prerequisites

• Python 3.10+
• 16 GB RAM minimum (for embeddings + LLM)
• GPU recommended for HuggingFace backend
• Ollama installed (for local development) OR internet access (for HuggingFace)

Installation

# Clone and enter project
git clone https://github.com/Logicsoft/QModel.git && cd QModel
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# Configure (choose one backend)
# Option A — GGUF (self-contained, default):
export LLM_BACKEND=gguf
export GGUF_MODEL_PATH=./models/Qwen3.6-27B-Q4_K_M.gguf
huggingface-cli download ggml-org/Qwen3.6-27B-GGUF Qwen3.6-27B-Q4_K_M.gguf --local-dir ./models

# Option B — Ollama (local development):
export LLM_BACKEND=ollama
export OLLAMA_MODEL=qwen3.6:27b
# Make sure Ollama is running: ollama serve

# Option C — HuggingFace (production):
export LLM_BACKEND=hf
export HF_MODEL_NAME=Qwen/Qwen3-8B

# Run
python main.py

# Query
curl "http://localhost:8000/ask?q=What%20does%20Islam%20say%20about%20mercy?"

API docs: http://localhost:8000/docs

Data & Index

Pre-built data files are included:

• metadata.json — 47,179 documents (6,236 Quran verses + 40,943 hadiths from 9 canonical collections)
• QModel.index — FAISS search index

To rebuild after dataset changes:

python build_index.py

---

Example Queries

# Basic question
curl "http://localhost:8000/ask?q=What%20does%20Islam%20say%20about%20mercy?"

# Word frequency
curl "http://localhost:8000/ask?q=How%20many%20times%20is%20mercy%20mentioned?"

# Authentic Hadiths only
curl "http://localhost:8000/ask?q=prayer&source_type=hadith&grade_filter=sahih"

# Quran text search
curl "http://localhost:8000/quran/search?q=bismillah"

# Quran topic search
curl "http://localhost:8000/quran/topic?topic=patience&top_k=5"

# Quran word frequency
curl "http://localhost:8000/quran/word-frequency?word=mercy"

# Single chapter
curl "http://localhost:8000/quran/chapter/2"

# Exact verse
curl "http://localhost:8000/quran/verse/2:255"

# Root-word analysis
curl "http://localhost:8000/quran/root/رحم"

# Hadith text search
curl "http://localhost:8000/hadith/search?q=actions+are+judged+by+intentions"

# Hadith topic search (Sahih only)
curl "http://localhost:8000/hadith/topic?topic=fasting&grade_filter=sahih"

# Verify Hadith authenticity
curl "http://localhost:8000/hadith/verify?q=Actions%20are%20judged%20by%20intentions"

# Browse a collection
curl "http://localhost:8000/hadith/collection/bukhari?limit=5"

# Streaming (OpenAI-compatible)
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"QModel","messages":[{"role":"user","content":"What does Islam say about charity?"}],"stream":true}'

---

Configuration

All configuration via environment variables (.env file or exported directly):

Backend Selection

Backend	Pros	Cons	When to Use
GGUF	Self-contained, no external daemon, bundles with the repo/Space	Larger image/repo size	HF Spaces, offline/portable deployment
Ollama	Fast setup, no GPU, free	Smaller models, requires separate daemon	Development, testing
HuggingFace	Larger models, better quality	Requires GPU or significant RAM	Production

GGUF Backend (Self-contained)

LLM_BACKEND=gguf
GGUF_MODEL_PATH=./models/Qwen3.6-27B-Q4_K_M.gguf
GGUF_N_CTX=4096
GGUF_N_GPU_LAYERS=-1             # -1 = offload all layers to GPU, 0 = CPU-only

Requires the .gguf file to be present at GGUF_MODEL_PATH — download with:

huggingface-cli download ggml-org/Qwen3.6-27B-GGUF Qwen3.6-27B-Q4_K_M.gguf --local-dir ./models

Ollama Backend (Development)

LLM_BACKEND=ollama
OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=qwen3.6:27b

Requires: ollama serve running and model pulled (ollama pull qwen3.6:27b).

HuggingFace Backend (Production)

LLM_BACKEND=hf
HF_MODEL_NAME=Qwen/Qwen3-8B
HF_DEVICE=auto                   # auto | cuda | cpu
HF_MAX_NEW_TOKENS=2048

All Environment Variables

Variable	Default	Description
Backend
LLM_BACKEND	gguf	gguf, ollama, or hf
GGUF_MODEL_PATH	./models/Qwen3.6-27B-Q4_K_M.gguf	Path to local .gguf file
GGUF_N_CTX	4096	Context window size
GGUF_N_GPU_LAYERS	-1	Layers to offload to GPU (-1 = all, 0 = CPU-only)
OLLAMA_HOST	http://localhost:11434	Ollama server URL
OLLAMA_MODEL	qwen3.6:27b	Ollama model name
HF_MODEL_NAME	Qwen/Qwen3-8B	HuggingFace model ID
HF_DEVICE	auto	auto, cuda, or cpu
HF_MAX_NEW_TOKENS	2048	Max output length
Embedding & Data
EMBED_MODEL	intfloat/multilingual-e5-large	Embedding model
FAISS_INDEX	QModel.index	Index file path
METADATA_FILE	metadata.json	Dataset file
Retrieval
TOP_K_SEARCH	20	Candidate pool (5–100)
TOP_K_RETURN	5	Results shown to user (1–20)
RERANK_ALPHA	0.6	Dense vs Sparse weight (0.0–1.0)
Generation
TEMPERATURE	0.2	Creativity (0.0–1.0, use 0.1–0.2 for religious)
MAX_TOKENS	2048	Max response length
Safety
CONFIDENCE_THRESHOLD	0.30	Min score to call LLM (higher = fewer hallucinations)
HADITH_BOOST	0.08	Score boost for hadith on hadith queries
QURAN_BOOST	0.12	Score boost for Quran verses on tafsir/quran queries
Other
CACHE_SIZE	512	Query response cache entries
CACHE_TTL	3600	Cache expiry in seconds
ALLOWED_ORIGINS	*	CORS origins
MAX_EXAMPLES	3	Few-shot examples in system prompt

Configuration Examples

Self-contained (GGUF, e.g. HF Spaces)

LLM_BACKEND=gguf
GGUF_MODEL_PATH=./models/Qwen3.6-27B-Q4_K_M.gguf
GGUF_N_CTX=4096
GGUF_N_GPU_LAYERS=-1
TEMPERATURE=0.2
CONFIDENCE_THRESHOLD=0.30

Development (Ollama)

LLM_BACKEND=ollama
OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=qwen3.6:27b
TEMPERATURE=0.2
CONFIDENCE_THRESHOLD=0.30
ALLOWED_ORIGINS=*

Production (HuggingFace + GPU)

LLM_BACKEND=hf
HF_MODEL_NAME=Qwen/Qwen3-8B
HF_DEVICE=cuda
TOP_K_SEARCH=30
TEMPERATURE=0.1
CONFIDENCE_THRESHOLD=0.35
ALLOWED_ORIGINS=yourdomain.com,api.yourdomain.com

Tuning Tips

• Better results: Increase TOP_K_SEARCH, lower CONFIDENCE_THRESHOLD, use TEMPERATURE=0.1
• Faster performance: Lower TOP_K_SEARCH and TOP_K_RETURN, reduce MAX_TOKENS, use Ollama
• More conservative: Increase CONFIDENCE_THRESHOLD, lower TEMPERATURE

---

Docker Deployment

Docker Compose (Recommended)

docker-compose.yml is production-safe by default: it does not bind-mount the repo, and it mounts QModel.index/metadata.json read-only so a dataset update doesn't require an image rebuild. docker-compose.override.yml is picked up automatically for local dev and layers a full repo bind-mount on top for live code reload.

cp .env.example .env   # Configure backend (see Configuration section)

# Development (live code reload via docker-compose.override.yml)
docker-compose up

# Production (base file only, no bind-mount — runs the image's own code)
docker-compose -f docker-compose.yml up -d

Docker CLI

docker build -t qmodel .

# With Ollama backend
docker run -p 8000:8000 \
  --env-file .env \
  --add-host host.docker.internal:host-gateway \
  qmodel

# With HuggingFace backend
docker run -p 8000:8000 \
  --env-file .env \
  --env HF_TOKEN=your_token_here \
  qmodel

Docker with GGUF

# .env
LLM_BACKEND=gguf
GGUF_MODEL_PATH=./models/Qwen3.6-27B-Q4_K_M.gguf
GGUF_N_CTX=4096
GGUF_N_GPU_LAYERS=-1

The .gguf file must be present under ./models/ before building/running the image (see download command in GGUF Backend) — no external daemon or network access needed at runtime, which is what makes this backend suitable for bundling directly into an HF Space.

Docker with Ollama

# .env
LLM_BACKEND=ollama
OLLAMA_HOST=http://host.docker.internal:11434
OLLAMA_MODEL=qwen3.6:27b

Requires Ollama running on the host (ollama serve).

Docker with HuggingFace

# .env
LLM_BACKEND=hf
HF_MODEL_NAME=Qwen/Qwen3-8B
HF_DEVICE=auto

# Pass HF token
export HF_TOKEN=hf_xxxxxxxxxxxxx
docker-compose up

Docker Compose with GPU (Linux)

The shipped Dockerfile installs the CPU-only torch wheel (paired with faiss-cpu) to keep the image small. That build cannot use a GPU even if one is passed through. For real GPU acceleration, build a variant that installs the CUDA-enabled torch wheel instead (drop the --extra-index-url https://download.pytorch.org/whl/cpu line in the builder stage), then add:

services:
  qmodel:
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

Production Tips

• Deploy with docker-compose -f docker-compose.yml up -d so the dev-only docker-compose.override.yml (full repo bind-mount) isn't applied — the base file already omits it, restarts with on-failure:5, and mounts the data files read-only.
• Use specific ALLOWED_ORIGINS instead of *

---

Open-WebUI Integration

QModel is fully OpenAI-compatible and works out of the box with Open-WebUI.

Setup

# Start QModel
python main.py

# Start Open-WebUI
docker run -d -p 3000:8080 --name open-webui ghcr.io/open-webui/open-webui:latest

Connect

1. Settings → Models → Manage Models
2. Click "Connect to OpenAI-compatible API"
3. API Base URL: http://localhost:8000/v1
4. Model Name: QModel
5. API Key: Leave blank
6. Save & Test → ✅ Connected

Docker Compose (QModel + Ollama + Open-WebUI)

version: '3.8'
services:
  qmodel:
    build: .
    ports:
      - "8000:8000"
    environment:
      - LLM_BACKEND=ollama
      - OLLAMA_HOST=http://ollama:11434

  ollama:
    image: ollama/ollama:latest
    ports:
      - "11434:11434"

  web-ui:
    image: ghcr.io/open-webui/open-webui:latest
    ports:
      - "3000:8080"
    depends_on:
      - qmodel

Supported Features

Feature	Status
Chat	✅ Full support
Streaming	✅ stream: true
Multi-turn context	✅ Handled by Open-WebUI
Temperature	✅ Configurable
Token limits	✅ max_tokens
Model listing	✅ /v1/models
Source attribution	✅ x_metadata.sources

---

Architecture

Module Structure

main.py                    ← FastAPI app + router registration
app/
  config.py               ← Config class (env vars)
  llm.py                  ← LLM providers (Ollama, HuggingFace)
  cache.py                ← TTL-LRU async cache
  arabic_nlp.py           ← Arabic normalization, stemming, language detection
  search.py               ← Hybrid FAISS+BM25, text search, query rewriting
  analysis.py             ← Intent detection, analytics, counting
  prompts.py              ← Prompt engineering (persona, anti-hallucination)
  models.py               ← Pydantic schemas
  state.py                ← AppState, lifespan, RAG pipeline
  routers/
    quran.py              ← 6 Quran endpoints
    hadith.py             ← 5 Hadith endpoints
    chat.py               ← /ask + OpenAI-compatible chat
    ops.py                ← health, models, debug scores

Data Pipeline

1. Ingest: 47,179 documents (6,236 Quran verses + 40,943 Hadiths from 9 collections)
2. Embed: Encode with multilingual-e5-large (Arabic + English dual embeddings)
3. Index: FAISS IndexFlatIP for dense retrieval

Retrieval & Ranking

1. Dense retrieval (FAISS semantic scoring)
2. Sparse retrieval (BM25 term-frequency)
3. Fusion: 60% dense + 40% sparse
4. Intent-aware boost (+0.08 to Hadith when intent=hadith)
5. Type filter (quran_only / hadith_only / authenticated_only)
6. Text search fallback (exact phrase + word-overlap)

Anti-Hallucination Measures

• Few-shot examples including "not found" refusal path
• Hardcoded citation format rules
• Verbatim copy rules (no text reconstruction)
• Confidence threshold gating (default: 0.30)
• Post-generation citation verification
• Grade inference from collection name

Performance

Operation	Time	Backend
Query (cached)	~50ms	Both
Query (Ollama)	400–800ms	Ollama
Query (HF GPU)	500–1500ms	CUDA
Query (HF CPU)	2–5s	CPU

---

Troubleshooting

"Cannot connect to Ollama"

ollama serve                      # Ensure Ollama is running on host
# In Docker, use OLLAMA_HOST=http://host.docker.internal:11434

"HuggingFace model not found"

export HF_TOKEN=hf_xxxxxxxxxxxxx  # Set token for gated models

"Out of memory"

• Use smaller model: HF_MODEL_NAME=mistralai/Mistral-7B-Instruct-v0.2
• Use Ollama with neural-chat
• Reduce MAX_TOKENS to 1024
• Increase Docker memory limit in docker-compose.yml

"Assistant returns 'Not found'"

This is expected — QModel rejects low-confidence queries. Try:

• More specific queries
• Lower CONFIDENCE_THRESHOLD in .env
• Check raw scores: GET /debug/scores?q=your+query

"Port already in use"

docker-compose down && docker system prune
# Or change port: ports: ["8001:8000"]

---

Roadmap

• Grade-based filtering
• Streaming responses (SSE)
• Modular architecture (4 routers, 16 endpoints)
• Dual LLM backend (Ollama + HuggingFace)
• Text search (exact substring + fuzzy matching)
• Chain of narrators (Isnad highlighting)
• Synonym expansion (curated Islamic thesaurus)
• Root-word analysis (thematic Arabic roots)
• Batch processing (multiple questions per request)
• Islamic calendar integration (Hijri dates)
• Tafsir endpoint with scholar citations

---

Data Sources

• Qur'an: risan/quran-json — 114 Surahs, 6,236 verses
• Hadith: AhmedBaset/hadith-json — 9 canonical collections, 40,943 hadiths

---

Architecture Overview

User Query
    ↓
Query Rewriting & Intent Detection
    ↓
Hybrid Search (FAISS dense + BM25 sparse)
    ↓
Filtering & Ranking
    ↓
Confidence Gate (skip LLM if low-scoring)
    ↓
LLM Generation (Ollama or HuggingFace)
    ↓
Formatted Response with Sources

See ARCHITECTURE.md for detailed system design.

---

Troubleshooting

Issue	Solution
"Service is initialising"	Wait 60-90s for embeddings model to load
Low retrieval scores	Check /debug/scores, try synonyms, lower threshold
"Model not found" (HF)	Run huggingface-cli login
Out of memory	Use smaller model or CPU backend
No results	Verify data files exist: metadata.json and QModel.index

See SETUP.md and DOCKER.md for more detailed troubleshooting.

---

What's New in v7

✨ Inverted BM25 Index — Full-dataset sparse retrieval built at startup (replaces per-candidate linear BM25 scoring) ✨ Reciprocal Rank Fusion — Dense (FAISS) + sparse (BM25) results merged via RRF instead of fixed-weight scoring ✨ Quran Boost — New QURAN_BOOST config counterbalances HADITH_BOOST so Hadiths don't outrank relevant Quran verses on tafsir/quran-intent queries ✨ Query Embedding Cache — Repeated query vectors served from cache instead of re-encoding ✨ Fast-Path Query Rewrite — Direct Quran references (e.g. "2:255", surah names) and verse-count questions skip the LLM rewrite roundtrip ✨ Improved Arabic Root Extraction — extract_arabic_root() strips augmented letters for more accurate 3-letter root matching; root variants now included in tokenization ✨ Hardened Docker Image — Multi-stage build (compiler toolchain isolated to builder stage), runs as non-root user, smaller runtime image ✨ Production-Safe Compose — docker-compose.yml no longer bind-mounts the repo by default; data files mounted read-only; live-reload dev setup moved to docker-compose.override.yml

---

What's New in v6

✨ Reasoning Support — Capture and stream model thinking/CoT ✨ Root Analysis — Explore Quran via 3-letter Arabic roots ✨ Isnad Highlighting — Narrators emphasized in Hadith responses ✨ Synonym Expansion — Curated Islamic thesaurus for broader search ✨ Dynamic Gating — Intent-aware confidence thresholds ✨ Dual LLM Backend — Ollama (dev) + HuggingFace (prod) ✨ Grade Filtering — Return only Sahih/Hasan authenticated Hadiths ✨ Source Filtering — Quran-only or Hadith-only queries ✨ Hadith Verification — /hadith/verify endpoint ✨ Enhanced Frequency — Word counts by Surah ✨ OpenAI Compatible — Use with any OpenAI client ✨ Production Ready — Structured logging, error handling, async throughout

---

Next Steps

1. Get Started: See SETUP.md
2. Integrate with Open-WebUI: See OPEN_WEBUI.md
3. Deploy with Docker: See DOCKER.md
4. Understand Architecture: See ARCHITECTURE.md

---

License

This project uses open-source data from:

• Qur'an JSON — Open source
• Hadith API — Open source

See individual repositories for license details.

---

Made with ❤️ for Islamic scholarship.

Version 7.0.0 | July 2026 | Production-Ready