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 1. **Truth & Authenticity** — Every response is grounded in verified sources (Quran and Sahih Hadith). We never fabricate or hallucinate. 2. **Fundamentals & Simplicity** — We focus on core Islamic teachings that unite. We avoid sectarian debates and controversial topics. 3. **For the Sake of Allah** — Criterion will always be free, with no monetization or organizational promotion. This is Sadaqah Jariyah. 4. **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](./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](https://nextjs.org) App Router with React 19 & Tailwind CSS - [Vercel AI SDK](https://ai-sdk.dev) for LLM integration and streaming - [XAI Grok 4](https://x.ai) for intelligent natural language responses - [PostgreSQL](https://neon.tech) with [pgvector](https://github.com/pgvector/pgvector) for vector search - [Drizzle ORM](https://orm.drizzle.team) for type-safe database access - [Google Gemini](https://ai.google.dev) text-embedding-004 (768 dimensions) - HNSW indexes for <150ms similarity search - [Auth.js](https://authjs.dev) for authentication - Deployed on [Vercel](https://vercel.com) ## 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](https://neon.tech)) - API Keys: - XAI API Key (for Grok LLM) - Google AI Studio API Key (for embeddings) ### Installation 1. **Clone the repository** ```bash git clone cd criterion ``` 2. **Install dependencies** ```bash pnpm install ``` 3. **Set up environment variables** Create a `.env.local` file: ```bash # Database POSTGRES_URL=postgresql://... # AI APIs XAI_API_KEY=xai-... GOOGLE_GENERATIVE_AI_API_KEY=... # Authentication (optional) AUTH_SECRET=... ``` 4. **Enable pgvector extension** ```bash pnpm db:enable-pgvector ``` 5. **Run database migrations** ```bash pnpm db:migrate ``` 6. **Ingest Quran data** (generates embeddings for 6,236 verses) ```bash pnpm ingest:quran ``` This will take 10-15 minutes to complete. 7. **Test the Quran search** ```bash pnpm test:quran ``` 8. **Start the development server** ```bash pnpm dev ``` Your app should now be running on [localhost:3000](http://localhost:3000). ## Available Commands ### Development ```bash pnpm dev # Start dev server pnpm build # Build for production pnpm start # Start production server ``` ### Database ```bash pnpm db:generate # Generate Drizzle schema pnpm db:migrate # Run migrations pnpm db:studio # Open Drizzle Studio (GUI) ``` ### Data Ingestion & Testing ```bash # 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:** ```json { "mcpServers": { "criterion": { "url": "https://criterion.life/api/mcp" } } } ``` **Available Tools:** - `search_quran` — Search 6,236 Quran verses - `search_hadith` — Search 21,641 authentic Hadiths from 6 collections - `get_verse` — Retrieve specific verse by reference (e.g., "2:255") 👉 **[Read full MCP documentation in MCP.md](./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](./MISSION.md)** — Our vision, values, and deeper purpose. Read this first to understand _why_ we build Criterion. - **[CRITERION_DETAILED.md](./CRITERION_DETAILED.md)** — Comprehensive technical documentation including architecture, implementation history, and performance metrics. - **[CRITERION.md](./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) ---