io.github.BalajSaleem/criterion
Semantic search across 6,236 Quran verses and 12,416 authentic Hadiths for Islamic guidance.
Ask AI about io.github.BalajSaleem/criterion
Powered by Claude Β· Grounded in docs
I know everything about io.github.BalajSaleem/criterion. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Criterion - Islamic Knowledge Assistant
An AI-powered Da'i (invitor to Islam) bringing authentic Islamic guidance to seekers worldwide.
Built on the Quran and authentic Hadith. Free forever. For the sake of Allah.
Mission Β· Features Β· Tech Stack Β· Getting Started Β· MCP Server Β· Documentation
Mission
Criterion exists to bring authentic Islamic knowledge to anyone seeking truth, using modern technology to make divine guidance accessible to all of humanity β freely, forever, for the sake of Allah alone.
Our Four Pillars
- Truth & Authenticity β Every response is grounded in verified sources (Quran and Sahih Hadith). We never fabricate or hallucinate.
- Fundamentals & Simplicity β We focus on core Islamic teachings that unite. We avoid sectarian debates and controversial topics.
- For the Sake of Allah β Criterion will always be free, with no monetization or organizational promotion. This is Sadaqah Jariyah.
- State of the Art β We use cutting-edge AI to deliver Islamic guidance effectively to the masses.
π Read the full mission and vision in MISSION.md
Key Differentiators
Mission-Aligned:
- β¨ Free Forever β No paywalls, no ads, no monetization. Built fi sabilillah (for Allah's sake)
- π Fundamentals-Focused β Avoids sectarian debates, focuses on universally accepted Islamic teachings
- π‘οΈ Trust-First β Grade-filtered authentic Hadith (defaults to Sahih), verified sources only
- π€ Seeker-Oriented β Designed for curious minds, new Muslims, and students of knowledge
- π Da'i Personality β Compassionate, knowledgeable, humble guidance
Technical Excellence:
- π― Semantic Search β Natural language queries return relevant verses from 6,236 Quran verses + 21,641 Hadith narrations
- π Contextual Retrieval β Top results include Β±2 surrounding verses/narrations for proper context
- π Multilingual β Read in English (fast) + Slovak (expandable to 10+ languages)
- π Accurate Citations β All responses include source references with hyperlinks (Quran.com, Sunnah.com)
- β‘ Fast β <150ms query response time
Features
What Criterion Does
β
Semantic Quran Search β Ask natural language questions, get relevant verses
β
Semantic Hadith Search β Search authentic Hadith with grade & collection filtering
β
Contextual Understanding β Top results include surrounding context for proper meaning
β
Accurate Citations β Every response cites real sources with hyperlinks
β
Multilingual Reading β English (fast) + Slovak (single JOIN <200ms)
β
Shareable URLs β /quran/search?q=patience, /hadith/search?q=charity, and /quran/2/255 with metadata
β
Real-time Streaming β Progressive response generation with token-by-token delivery
β
Tool-Based RAG β LLM autonomously decides when to retrieve from Quran/Hadith
Technical Stack
- Next.js 15 App Router with React 19 & Tailwind CSS
- Vercel AI SDK for LLM integration and streaming
- XAI Grok 4 for intelligent natural language responses
- PostgreSQL with pgvector for vector search
- Drizzle ORM for type-safe database access
- Google Gemini text-embedding-004 (768 dimensions)
- HNSW indexes for <150ms similarity search
- Auth.js for authentication
- Deployed on Vercel
How It Works
The RAG Pipeline
User Question
β
XAI Grok 4 LLM (decides which tools to use)
β
Tool Selection:
- queryQuran β 6,236 verses (top 7 for chat, top 20 for search)
- queryHadith β 21,641 hadiths from 6 collections (top 3 for chat, top 15 for search, with grade filtering)
β
Vector Search (768-dim Gemini embeddings)
β
Context Enhancement (top 3 get Β±2 surrounding verses)
β
LLM Generates Response with Citations
β
Real-time Stream to User (Server-Sent Events)
Data
-
6,236 Quran verses from all 114 Surahs
- Arabic text (Tanzil Quran)
- English translation (master)
- Slovak translation (expandable)
- 768-dimensional embeddings (Gemini text-embedding-004)
-
21,641 Hadith narrations from 6 major collections (Kutub al-Sittah subset)
- Sahih Bukhari (7,558)
- Sahih Muslim (2,920)
- Jami` at-Tirmidhi (3,951)
- Sunan Abi Dawud (5,274)
- 40 Hadith Nawawi (42)
- Riyad as-Salihin (1,896)
- Grade filtering (Sahih, Hasan, Da'if)
- 768-dimensional embeddings
Performance
- Quran search: <150ms (English), <200ms (translated)
- Hadith search: <150ms
- Vector search: Powered by HNSW indexes
- Streaming: Real-time token-by-token delivery
Getting Started
Prerequisites
- Node.js 18+ and pnpm
- PostgreSQL database (recommend Neon)
- API Keys:
- XAI API Key (for Grok LLM)
- Google AI Studio API Key (for embeddings)
Installation
- Clone the repository
git clone <repo-url>
cd criterion
- Install dependencies
pnpm install
- Set up environment variables
Create a .env.local file:
# Database
POSTGRES_URL=postgresql://...
# AI APIs
XAI_API_KEY=xai-...
GOOGLE_GENERATIVE_AI_API_KEY=...
# Authentication (optional)
AUTH_SECRET=...
- Enable pgvector extension
pnpm db:enable-pgvector
- Run database migrations
pnpm db:migrate
- Ingest Quran data (generates embeddings for 6,236 verses)
pnpm ingest:quran
This will take 10-15 minutes to complete.
- Test the Quran search
pnpm test:quran
- Start the development server
pnpm dev
Your app should now be running on localhost:3000.
Available Commands
Development
pnpm dev # Start dev server
pnpm build # Build for production
pnpm start # Start production server
Database
pnpm db:generate # Generate Drizzle schema
pnpm db:migrate # Run migrations
pnpm db:studio # Open Drizzle Studio (GUI)
Data Ingestion & Testing
# Quran
pnpm clear:quran # Clear all Quran data
pnpm ingest:quran # Ingest Quran verses and generate embeddings
pnpm ingest:quran:slovak # Ingest Slovak translation
pnpm test:quran # Test Quran search functionality
# Hadith
pnpm clear:hadith # Clear all Hadith data
pnpm ingest:hadith # Ingest Hadith and generate embeddings
MCP Server
Criterion exposes its semantic search capabilities through the Model Context Protocol (MCP), allowing AI assistants like Claude Desktop and Cursor to search Quran and Hadith directly.
Quick Setup:
{
"mcpServers": {
"criterion": {
"url": "https://criterion.life/api/mcp"
}
}
}
Available Tools:
search_quranβ Search 6,236 Quran versessearch_hadithβ Search 21,641 authentic Hadiths from 6 collectionsget_verseβ Retrieve specific verse by reference (e.g., "2:255")
π Read full MCP documentation in MCP.md
Project Structure
criterion/
βββ app/
β βββ (auth)/ # Authentication routes
β βββ (chat)/ # Chat interface and API
β β βββ api/chat/ # Main chat endpoint
β βββ search/ # Quran search page
β β βββ api/ # Quran search API
β βββ hadith/
β β βββ search/ # Hadith search page and API
β βββ quran/ # Quran reading pages
βββ lib/
β βββ ai/
β β βββ embeddings.ts # Core RAG logic
β β βββ prompts.ts # Da'i system prompts
β β βββ tools/
β β βββ query-quran.ts # Quran search tool
β β βββ query-hadith.ts # Hadith search tool
β βββ db/
β βββ schema.ts # Database schema
β βββ migrations/ # SQL migrations
βββ components/
β βββ chat.tsx # Main chat UI
β βββ quran-verses.tsx # Quran display component
β βββ hadith-narrations.tsx # Hadith carousel
β βββ hadith/
β βββ hadith-card.tsx # Reusable hadith card
βββ scripts/
β βββ ingest-quran.ts # Quran data ingestion
β βββ ingest-hadith.ts # Hadith data ingestion
β βββ test-*.ts # Test scripts
βββ data/
βββ quran*.txt # Quran translations
βββ *-full.json # Hadith collections
Documentation
Understanding Criterion
- MISSION.md β Our vision, values, and deeper purpose. Read this first to understand why we build Criterion.
- CRITERION_DETAILED.md β Comprehensive technical documentation including architecture, implementation history, and performance metrics.
- CRITERION.md β Quick reference guide for setup and key concepts.
Key Sections
| Document | Purpose |
|---|---|
| MISSION.md | Vision, values, pillars, and long-term goals |
| CRITERION_DETAILED.md | Technical architecture, database schema, components, and best practices |
| CRITERION.md | Quick start, commands, and core concepts |
| README.md | Getting started, features, and project overview |
Architecture Overview
components/
βββ Chat UI (QuranVerses, HadithNarrations, MessageActions)
βββ Search Pages (Quran and Hadith semantic search with filters)
βββ Hadith Components (reusable HadithCard for search and chat)
βββ Quran Pages (shared components for context, language selection)
βββ UI Components (buttons, inputs, etc.)
lib/
βββ ai/
β βββ embeddings.ts (vector search logic)
β βββ prompts.ts (Da'i system prompts)
β βββ tools/ (queryQuran, queryHadith, requestSuggestions)
βββ db/
β βββ schema.ts (Drizzle ORM definitions)
β βββ queries.ts (database functions)
βββ monitoring/ (performance tracking)
app/
βββ (chat)/api/chat (main chat endpoint)
βββ quran/search/ (Quran search page and API)
βββ hadith/search/ (Hadith search page and API)
βββ quran/ (Quran reading pages)
βββ (auth)/ (authentication)
Data Attribution
- Quran Text: Tanzil.net β Creative Commons Attribution 3.0
- Quran Translations: Multiple sources with proper attribution
- Hadith Collections: Sunnah.com, IslamicNetwork.com
- Embeddings: Google Gemini text-embedding-004
Our Commitment
Criterion is built with these commitments:
- β Never monetize Islamic knowledge
- β Always cite sources with proper references
- β Never fabricate verses or hadiths
- β Focus on fundamentals β avoid sectarian debates
- β Build for the community β this belongs to all Muslims and benefits all humanity
- β Stay at the forefront β leverage state-of-the-art technology
Contributing
We welcome contributions from developers, scholars, and community members who share our mission. Please see CONTRIBUTING.md for guidelines.
License
- Quran Text: Creative Commons Attribution 3.0 (Tanzil.net)
- Hadith Data: From verified Islamic sources with proper attribution
- Code: See LICENSE file for details
"Invite to the way of your Lord with wisdom and good instruction, and argue with them in a way that is best." β Quran 16:125
May Allah accept this work and make it a means of guidance for seekers everywhere. Ameen.
