io.github.BalajSaleem/criterion
Semantic search across 6,236 Quran verses and 12,416 authentic Hadiths for Islamic guidance.
Open source Repository Open in the app JSON README (API)
About
Semantic search across 6,236 Quran verses and 12,416 authentic Hadiths for Islamic guidance.
Details
- Kind
- MCP servers
- Topic
- AI, RAG & memory
- Publisher
- balajsaleem
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 1.0.0
- Stars
- 20
- Forks
- 8
- Last push
- 2026-09-05T13:30:04Z
- Repository state
- ativo
- Language
- TypeScript
- License
- NOASSERTION
- Added
- 2026-08-29 03:01:42
- Updated
- 2026-08-29 03:01:42
- Origin id
io.github.BalajSaleem/criterion
README
<h1 align="center">Criterion - Islamic Knowledge Assistant</h1>
<p align="center">
<strong>An AI-powered Da'i (invitor to Islam)</strong> bringing authentic Islamic guidance to seekers worldwide.
</p>
<p align="center">
Built on the Quran and authentic Hadith. Free forever. For the sake of Allah.
</p>
<p align="center">
<a href="#mission"><strong>Mission</strong></a> ·
<a href="#features"><strong>Features</strong></a> ·
<a href="#tech-stack"><strong>Tech Stack</strong></a> ·
<a href="#getting-started"><strong>Getting Started</strong></a> ·
<a href="#mcp-server"><strong>MCP Server</strong></a> ·
<a href="#documentation"><strong>Documentation</strong></a>
</p>
<br/>
## 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 <repo-url>
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)
├── 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](http://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](./CONTRIBUTING.md) for guidelines.
## License
- **Quran Text**: Creative Commons Attribution 3.0 ([Tanzil.net](http://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._