Hugging Face's logo

aelgendy
/
QModel

GGUF
Arabic
English
quran
hadith
islamic
rag
faiss
nlp
arabic
imatrix
conversational
Model card Files
xet
 Community
How to use from
Docker Model Runner
docker model run hf.co/aelgendy/QModel:Q8_0
Quick Links

QModel v8.0 — Islamic RAG System

Specialized Qur'an, Hadith & Fatwa Knowledge System with Multi-Vector RAG & 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.

Version Backend Status

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 with curated root dictionaries
  • Parent-Document Windowing: Automatic $\pm 1$ verse context expansion for complete theological context
  • Bilingual: Full Arabic + English translation support
  • Tafsir Integration: Expanded contextual interpretation (up to 1,200 characters)

📚 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
  • Matn Deduplication: Redundant narrations consolidated with Muttafaq 'Alayh detection
  • Cross-Collection References: Displays alternative canonical collections (e.g. Bukhari, Muslim, Abu Dawood)
  • Topic Search: Find relevant Hadiths across 9 major collections
  • Collection Navigation: Filter by Bukhari, Muslim, Abu Dawud, etc.

⚖️ Fatwa & Fiqh Capabilities

  • Verified Scholarly Rulings: Ingested fatwas from recognized scholars and councils (Bin Baz, Lajnah Da'imah, etc.)
  • Semantic & Source Filtering: Filter fatwas by scholar, council, or source
  • Integrated RAG Context: Rulings retrieved alongside Quran and Hadith evidence
  • Direct Lookup: Fast endpoint access via /fatwa/{id}, /fatwa/search, and /fatwa/sources

🛡️ 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, or Fatwa reference
  • Verbatim Quotes: Text verified against raw sources with support for all quote formats («...», “...”, ❝...❞, "...")
  • Anti-Hallucination: Hardened prompts with pre/post-generation 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
  • Conversational Multi-Turn Memory: Coreference resolution for continuous contextual dialogues

⚙️ Technical & RAG Architecture

  • Asymmetric E5 Embedding: Proper passage: and query: prefixes for optimal vector similarity
  • Multi-Vector Dense Retrieval: Independent Arabic and English query vectors fused adaptively
  • Inverted BM25 Sparse Index: Bilingual tokenization with stopword filtering and morphological root indexing
  • Adaptive RRF Fusion: Language-weighted Reciprocal Rank Fusion balancing dense & sparse signals
  • Cross-Encoder Reranker: Optional BAAI/bge-reranker-v2-m3 rescoring
  • Triple LLM Backend: Local GGUF, Ollama (dev), or HuggingFace (prod)
  • Async API & Caching: FastAPI with TTL-based LRU response cache

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/Qwen2.5-14B-Instruct-Q8_0.gguf
huggingface-cli download bartowski/Qwen2.5-14B-Instruct-GGUF Qwen2.5-14B-Instruct-Q8_0.gguf --local-dir ./models

# Option B — Ollama (local development):
export LLM_BACKEND=ollama
export OLLAMA_MODEL=qwen2.5:14b
# Make sure Ollama is running: ollama serve

# Option C — HuggingFace (production):
export LLM_BACKEND=hf
export HF_MODEL_NAME=Qwen/Qwen2.5-14B-Instruct

# 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 — 52,677 documents (6,236 Quran verses + 46,416 hadiths from 15 collections + Fatwas)
  • QModel.index — FAISS search index (205.77 MB, 52,677 vectors, 1024-d)

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"

# Fatwa topic search (with scholar filter)
curl "http://localhost:8000/fatwa/search?q=الوصية&source=BinBaz&top_k=3"

# Fatwa direct ID lookup
curl "http://localhost:8000/fatwa/fatwa_binbaz_4210"

# List loaded Fatwa collections
curl "http://localhost:8000/fatwa/sources"

# 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/Qwen2.5-14B-Instruct-Q8_0.gguf
GGUF_N_CTX=8192
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 bartowski/Qwen2.5-14B-Instruct-GGUF Qwen2.5-14B-Instruct-Q8_0.gguf --local-dir ./models

Model Profile

Model Size (Q8_0) RAM / VRAM Generation Speed Best Use Case
Qwen2.5-14B-Instruct (Default) ~15 GB ~16 GB Blazing (~55 tok/s) Production, Hugging Face Hub, and local GPU deployment

Ollama Backend (Development) 

LLM_BACKEND=ollama
OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=qwen2.5:14b

Requires: ollama serve running and model pulled (ollama pull qwen2.5:14b).

HuggingFace Backend (Production) 

LLM_BACKEND=hf
HF_MODEL_NAME=Qwen/Qwen2.5-14B-Instruct
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/Qwen2.5-14B-Instruct-Q8_0.gguf Path to local .gguf file
GGUF_N_CTX 8192 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 qwen2.5:14b Ollama model name
HF_MODEL_NAME Qwen/Qwen2.5-14B-Instruct 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)
USE_RERANKER false Enable cross-encoder reranker (true/false)
RERANK_MODEL BAAI/bge-reranker-v2-m3 Cross-encoder model ID
AYAH_WINDOW_SIZE 1 Number of neighboring verses for context expansion
ENABLE_HADITH_DEDUPLICATION true Cluster near-identical Hadith narrations
TAFSIR_MAX_CHARS 1200 Max Tafsir characters provided in LLM context
Generation
TEMPERATURE 0.2 Creativity (0.0–1.0, use 0.1–0.2 for religious)
MAX_TOKENS 2048 Max response length
SHOW_THINKING false Include chain-of-thought/reasoning output (true/false)
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/Qwen2.5-14B-Instruct-Q8_0.gguf
GGUF_N_CTX=8192
GGUF_N_GPU_LAYERS=-1
TEMPERATURE=0.2
CONFIDENCE_THRESHOLD=0.30

Development (Ollama)

LLM_BACKEND=ollama
OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=qwen2.5:14b
TEMPERATURE=0.2
CONFIDENCE_THRESHOLD=0.30
ALLOWED_ORIGINS=*

Production (HuggingFace + GPU)

LLM_BACKEND=hf
HF_MODEL_NAME=Qwen/Qwen2.5-14B-Instruct
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/Qwen2.5-14B-Instruct-Q8_0.gguf
GGUF_N_CTX=8192
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=qwen2.5:14b

Requires Ollama running on the host (ollama serve).

Docker with HuggingFace 

# .env
LLM_BACKEND=hf
HF_MODEL_NAME=Qwen/Qwen2.5-14B-Instruct
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
build_index.py             ← Dataset compilation, E5 asymmetric embedding & FAISS indexing
app/
  config.py               ← Config class (env vars)
  llm.py                  ← LLM providers (GGUF, Ollama, HuggingFace)
  cache.py                ← TTL-LRU async cache
  arabic_nlp.py           ← Arabic normalization, stopwords, Quranic root index
  search.py               ← Multi-vector FAISS + BM25, RRF, clustering, windowing, reranker
  analysis.py             ← Intent detection, analytics, counting
  prompts.py              ← Prompt engineering (persona, anti-hallucination)
  models.py               ← Pydantic schemas (Quran, Hadith, Fatwa, Chat)
  state.py                ← AppState, lifespan, multi-turn RAG pipeline
  routers/
    quran.py              ← 6 Quran endpoints
    hadith.py             ← 5 Hadith endpoints
    fatwa.py              ← 3 Fatwa endpoints
    chat.py               ← /ask + OpenAI-compatible chat
    ops.py                ← health, models, debug scores
tests/
  test_enhancements.py    ← Unit tests for multi-vector, windowing, clustering, roots
  test_fatwa.py           ← Unit tests for fatwa endpoints & RAG integration

Data Pipeline

  1. Ingest: Multi-source Islamic knowledge base:
    • Quran: 6,236 verses across 114 Surahs
    • Hadith: 40,943 hadiths across 9 canonical collections
    • Fatwa: Verified rulings from recognized scholars and fiqh councils
  2. Embed: Asymmetric encoding with intfloat/multilingual-e5-large (passage: prefix for indexing, query: prefix for inference)
  3. Index: FAISS IndexFlatIP for inner-product dense vector retrieval + inverted index for BM25

Retrieval & Ranking Pipeline

  1. Conversational Coreference Rewriting: Query rewriter accepts dialogue history to resolve ambiguous pronouns and anaphoric references into standalone topical queries.
  2. Dual-Vector Query Embedding: Encodes both Arabic (query_ar) and English (query_en) query vectors using multilingual-e5-large with the mandatory query: prefix.
  3. Multi-Vector Dense Retrieval: Independent FAISS searches against Arabic and English dense vectors.
  4. Inverted BM25 Sparse Retrieval: BM25 scoring with bilingual stopword removal and Quranic morphological root expansion.
  5. Adaptive Reciprocal Rank Fusion (RRF): Merges Arabic dense, English dense, and BM25 sparse hits with dynamic language-weighted multipliers.
  6. Hadith Deduplication & Ayah Windowing:
    • Clusters duplicate Hadith narrations ($\ge 0.85$ text similarity), tags Muttafaq 'Alayh (Bukhari + Muslim), and aggregates alternative collection references.
    • Expands top Quran verses with $\pm N$ adjacent verses (AYAH_WINDOW_SIZE) for complete theological context.
  7. Cross-Encoder Reranking (Optional): Rescores top candidates using BAAI/bge-reranker-v2-m3 when USE_RERANKER=true.
  8. Confidence Gating & Context Assembly: Gated by intent-aware confidence thresholds before assembling verified, citation-attributed LLM context.

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 (5 routers, 19 endpoints)
  • Triple LLM backend (GGUF + Ollama + HuggingFace)
  • Text search (exact substring + fuzzy matching)
  • Chain of narrators (Isnad highlighting)
  • Synonym expansion (curated Islamic thesaurus)
  • Root-word analysis (thematic Arabic roots & dictionary)
  • Fatwa & scholarly rulings corpus integration
  • Asymmetric E5 embedding prefixing (passage: / query: )
  • Multi-vector dual-language dense retrieval with adaptive RRF
  • Conversational multi-turn coreference resolution
  • Hadith matn deduplication & Muttafaq 'Alayh clustering
  • Quranic parent-document Ayah windowing
  • Cross-encoder reranking support (BAAI/bge-reranker-v2-m3)
  • Batch processing (multiple questions per request)
  • Islamic calendar integration (Hijri dates)

Data Sources

  • Qur'an: risan/quran-json & semarketir/quranjson — 114 Surahs, 6,236 verses with Arabic text, transliteration, and English translation.
  • Tafsir: Tafseer Dataset & Quran.com — 5,430 verses enriched with classical Arabic commentaries (Tafsir al-Sa'di, Tafsir al-Mukhtasar, Tafsir al-Jalalayn) + English Tafsir Ibn Kathir.
  • Hadith: AhmedBaset/hadith-json & fawazahmed0/hadith-api — 15 authoritative collections (9 canonical + Riyad al-Salihin, Bulugh al-Maram, Al-Adab al-Mufrad, Ash-Shama'il al-Muhammadiyyah, An-Nawawi's 40 Hadith, Hadith Qudsi), 46,416 hadiths with 21,264 scholar authenticity grades.
  • Fatwa: Verified rulings and answers from renowned scholars and councils (Ibn Baz, Lajnah Da'imah, Ibn Uthaymeen, Islamweb, Al-Badr).

What's New in v8

✨ 15 Authoritative Hadith Collections (46,416 Narrations) — Expanded beyond the 9 canonical books by ingesting core thematic fiqh and ethical collections: Riyad al-Salihin (1,896 hadiths), Bulugh al-Maram (1,767 hadiths), Al-Adab al-Mufrad (1,326 hadiths), Ash-Shama'il al-Muhammadiyyah (402 hadiths), An-Nawawi's 40 Hadith (42 hadiths), and Hadith Qudsi (40 hadiths), with 21,264 scholar authenticity grades. ✨ Classical Arabic Tafsir Enrichment (5,430 Verses) — Enriched Quranic entries with verse-by-verse Tafsir al-Sa'di (تفسير السعدي) and Tafsir al-Mukhtasar (التفسير المختصر) alongside English Tafsir snippets, enabling precise semantic retrieval for theological and interpretative queries. ✨ Fatwa & Fiqh Corpus Integration — Full integration of authenticated Islamic legal rulings and scholarly answers with dedicated /fatwa search, source, and ID lookup endpoints. ✨ Asymmetric E5 Embedding Alignment — Prefixed indexed passages with passage: while keeping queries prefixed with query: , maximizing dense semantic retrieval accuracy with multilingual-e5-large. ✨ Multi-Vector Dual-Language Dense Retrieval — Executes independent vector searches for Arabic and English translations and blends them via adaptive Reciprocal Rank Fusion (RRF) based on input script. ✨ Conversational Multi-Turn Coreference Resolution — Query rewriter now ingests prior conversation history to resolve pronouns and implicit subject references into standalone, unambiguous queries. ✨ Hadith Matn Deduplication & Muttafaq 'Alayh Clustering — Identifies near-identical Hadith narrations across canonical collections ($\ge 0.85$ text similarity), labels narrations recorded by both Bukhari and Muslim as Muttafaq 'Alayh, and aggregates alternative cross-references in context. ✨ Quranic Parent-Document Ayah Windowing — Automatically expands retrieved Quranic verses with surrounding $\pm 1$ verses (AYAH_WINDOW_SIZE) so the LLM receives complete theological context. ✨ Bilingual Stopwords & Curated Quranic Roots — Built-in morphological Quranic root dictionary for primary Islamic concepts (صوم, صلاة, زكاة, ربا, طهر, etc.) and bilingual stopword filtering for high-precision BM25 scoring. ✨ Cross-Encoder Reranker Support — Added optional second-stage neural reranking with BAAI/bge-reranker-v2-m3 via USE_RERANKER=true. ✨ Hardware-Accelerated Index Builder — Enhanced build_index.py with automatic Apple Silicon Metal (MPS) and CUDA detection, increasing indexing throughput to 64 items/batch. ✨ Extended Tafsir Capacity & Multi-Style Quote Verification — Increased Tafsir context snippet size to 1,200 characters and hardened quote verification regex to support Arabic guillemets «...», typographic quotes “...”, and standard quotes. ✨ Corpus Scale Expansion — Total knowledge base expanded to 52,677 authenticated documents across Quran, Hadith, and Fatwa, with a 205.77 MB FAISS inner-product index.

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:

See individual repositories for license details.

Made with ❤️ for Islamic scholarship.

Version 8.0.0 | October 2026 | Production-Ready

Downloads last month
52
GGUF
Model size
15B params
Architecture
qwen2
Hardware compatibility
Log In to add your hardware

8-bit

Inference Providers NEW
This model isn't deployed by any Inference Provider. 🙋 Ask for provider support