{
  "markdown": "<h1 align=\"center\">Criterion - Islamic Knowledge Assistant</h1>\n\n<p align=\"center\">\n    <strong>An AI-powered Da'i (invitor to Islam)</strong> bringing authentic Islamic guidance to seekers worldwide.\n</p>\n\n<p align=\"center\">\n    Built on the Quran and authentic Hadith. Free forever. For the sake of Allah.\n</p>\n\n<p align=\"center\">\n  <a href=\"#mission\"><strong>Mission</strong></a> ·\n  <a href=\"#features\"><strong>Features</strong></a> ·\n  <a href=\"#tech-stack\"><strong>Tech Stack</strong></a> ·\n  <a href=\"#getting-started\"><strong>Getting Started</strong></a> ·\n  <a href=\"#mcp-server\"><strong>MCP Server</strong></a> ·\n  <a href=\"#documentation\"><strong>Documentation</strong></a>\n</p>\n<br/>\n\n## Mission\n\nCriterion 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.**\n\n### Our Four Pillars\n\n1. **Truth & Authenticity** — Every response is grounded in verified sources (Quran and Sahih Hadith). We never fabricate or hallucinate.\n2. **Fundamentals & Simplicity** — We focus on core Islamic teachings that unite. We avoid sectarian debates and controversial topics.\n3. **For the Sake of Allah** — Criterion will always be free, with no monetization or organizational promotion. This is Sadaqah Jariyah.\n4. **State of the Art** — We use cutting-edge AI to deliver Islamic guidance effectively to the masses.\n\n👉 **[Read the full mission and vision in MISSION.md](./MISSION.md)**\n\n## Key Differentiators\n\n**Mission-Aligned:**\n\n- ✨ **Free Forever** — No paywalls, no ads, no monetization. Built fi sabilillah (for Allah's sake)\n- 📚 **Fundamentals-Focused** — Avoids sectarian debates, focuses on universally accepted Islamic teachings\n- 🛡️ **Trust-First** — Grade-filtered authentic Hadith (defaults to Sahih), verified sources only\n- 🤝 **Seeker-Oriented** — Designed for curious minds, new Muslims, and students of knowledge\n- 🕌 **Da'i Personality** — Compassionate, knowledgeable, humble guidance\n\n**Technical Excellence:**\n\n- 🎯 **Semantic Search** — Natural language queries return relevant verses from 6,236 Quran verses + 21,641 Hadith narrations\n- 📖 **Contextual Retrieval** — Top results include ±2 surrounding verses/narrations for proper context\n- 🌐 **Multilingual** — Read in English (fast) + Slovak (expandable to 10+ languages)\n- 🔗 **Accurate Citations** — All responses include source references with hyperlinks (Quran.com, Sunnah.com)\n- ⚡ **Fast** — <150ms query response time\n\n## Features\n\n### What Criterion Does\n\n✅ **Semantic Quran Search** — Ask natural language questions, get relevant verses  \n✅ **Semantic Hadith Search** — Search authentic Hadith with grade & collection filtering  \n✅ **Contextual Understanding** — Top results include surrounding context for proper meaning  \n✅ **Accurate Citations** — Every response cites real sources with hyperlinks  \n✅ **Multilingual Reading** — English (fast) + Slovak (single JOIN <200ms)  \n✅ **Shareable URLs** — `/quran/search?q=patience`, `/hadith/search?q=charity`, and `/quran/2/255` with metadata  \n✅ **Real-time Streaming** — Progressive response generation with token-by-token delivery  \n✅ **Tool-Based RAG** — LLM autonomously decides when to retrieve from Quran/Hadith\n\n### Technical Stack\n\n- [Next.js 15](https://nextjs.org) App Router with React 19 & Tailwind CSS\n- [Vercel AI SDK](https://ai-sdk.dev) for LLM integration and streaming\n- [XAI Grok 4](https://x.ai) for intelligent natural language responses\n- [PostgreSQL](https://neon.tech) with [pgvector](https://github.com/pgvector/pgvector) for vector search\n- [Drizzle ORM](https://orm.drizzle.team) for type-safe database access\n- [Google Gemini](https://ai.google.dev) text-embedding-004 (768 dimensions)\n- HNSW indexes for <150ms similarity search\n- [Auth.js](https://authjs.dev) for authentication\n- Deployed on [Vercel](https://vercel.com)\n\n## How It Works\n\n### The RAG Pipeline\n\n```\nUser Question\n    ↓\nXAI Grok 4 LLM (decides which tools to use)\n    ↓\nTool Selection:\n  - queryQuran → 6,236 verses (top 7 for chat, top 20 for search)\n  - queryHadith → 21,641 hadiths from 6 collections (top 3 for chat, top 15 for search, with grade filtering)\n    ↓\nVector Search (768-dim Gemini embeddings)\n    ↓\nContext Enhancement (top 3 get ±2 surrounding verses)\n    ↓\nLLM Generates Response with Citations\n    ↓\nReal-time Stream to User (Server-Sent Events)\n```\n\n### Data\n\n- **6,236 Quran verses** from all 114 Surahs\n\n  - Arabic text (Tanzil Quran)\n  - English translation (master)\n  - Slovak translation (expandable)\n  - 768-dimensional embeddings (Gemini text-embedding-004)\n\n- **21,641 Hadith narrations** from 6 major collections (Kutub al-Sittah subset)\n  - Sahih Bukhari (7,558)\n  - Sahih Muslim (2,920)\n  - Jami` at-Tirmidhi (3,951)\n  - Sunan Abi Dawud (5,274)\n  - 40 Hadith Nawawi (42)\n  - Riyad as-Salihin (1,896)\n  - Grade filtering (Sahih, Hasan, Da'if)\n  - 768-dimensional embeddings\n\n### Performance\n\n- **Quran search**: <150ms (English), <200ms (translated)\n- **Hadith search**: <150ms\n- **Vector search**: Powered by HNSW indexes\n- **Streaming**: Real-time token-by-token delivery\n\n## Getting Started\n\n### Prerequisites\n\n- Node.js 18+ and pnpm\n- PostgreSQL database (recommend [Neon](https://neon.tech))\n- API Keys:\n  - XAI API Key (for Grok LLM)\n  - Google AI Studio API Key (for embeddings)\n\n### Installation\n\n1. **Clone the repository**\n\n```bash\ngit clone <repo-url>\ncd criterion\n```\n\n2. **Install dependencies**\n\n```bash\npnpm install\n```\n\n3. **Set up environment variables**\n\nCreate a `.env.local` file:\n\n```bash\n# Database\nPOSTGRES_URL=postgresql://...\n\n# AI APIs\nXAI_API_KEY=xai-...\nGOOGLE_GENERATIVE_AI_API_KEY=...\n\n# Authentication (optional)\nAUTH_SECRET=...\n```\n\n4. **Enable pgvector extension**\n\n```bash\npnpm db:enable-pgvector\n```\n\n5. **Run database migrations**\n\n```bash\npnpm db:migrate\n```\n\n6. **Ingest Quran data** (generates embeddings for 6,236 verses)\n\n```bash\npnpm ingest:quran\n```\n\nThis will take 10-15 minutes to complete.\n\n7. **Test the Quran search**\n\n```bash\npnpm test:quran\n```\n\n8. **Start the development server**\n\n```bash\npnpm dev\n```\n\nYour app should now be running on [localhost:3000](http://localhost:3000).\n\n## Available Commands\n\n### Development\n\n```bash\npnpm dev          # Start dev server\npnpm build        # Build for production\npnpm start        # Start production server\n```\n\n### Database\n\n```bash\npnpm db:generate  # Generate Drizzle schema\npnpm db:migrate   # Run migrations\npnpm db:studio    # Open Drizzle Studio (GUI)\n```\n\n### Data Ingestion & Testing\n\n```bash\n# Quran\npnpm clear:quran         # Clear all Quran data\npnpm ingest:quran        # Ingest Quran verses and generate embeddings\npnpm ingest:quran:slovak # Ingest Slovak translation\npnpm test:quran          # Test Quran search functionality\n\n# Hadith\npnpm clear:hadith  # Clear all Hadith data\npnpm ingest:hadith # Ingest Hadith and generate embeddings\n```\n\n## MCP Server\n\nCriterion 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.\n\n**Quick Setup:**\n\n```json\n{\n  \"mcpServers\": {\n    \"criterion\": {\n      \"url\": \"https://criterion.life/api/mcp\"\n    }\n  }\n}\n```\n\n**Available Tools:**\n\n- `search_quran` — Search 6,236 Quran verses\n- `search_hadith` — Search 21,641 authentic Hadiths from 6 collections\n- `get_verse` — Retrieve specific verse by reference (e.g., \"2:255\")\n\n👉 **[Read full MCP documentation in MCP.md](./MCP.md)**\n\n## Project Structure\n\n```\ncriterion/\n├── app/\n│   ├── (auth)/          # Authentication routes\n│   ├── (chat)/          # Chat interface and API\n│   │   └── api/chat/    # Main chat endpoint\n│   ├── search/          # Quran search page\n│   │   └── api/         # Quran search API\n│   ├── hadith/\n│   │   └── search/      # Hadith search page and API\n│   └── quran/           # Quran reading pages\n├── lib/\n│   ├── ai/\n│   │   ├── embeddings.ts     # Core RAG logic\n│   │   ├── prompts.ts        # Da'i system prompts\n│   │   └── tools/\n│   │       ├── query-quran.ts   # Quran search tool\n│   │       └── query-hadith.ts  # Hadith search tool\n│   └── db/\n│       ├── schema.ts         # Database schema\n│       └── migrations/       # SQL migrations\n├── components/\n│   ├── chat.tsx              # Main chat UI\n│   ├── quran-verses.tsx      # Quran display component\n│   ├── hadith-narrations.tsx # Hadith carousel\n│   └── hadith/\n│       └── hadith-card.tsx   # Reusable hadith card\n├── scripts/\n│   ├── ingest-quran.ts       # Quran data ingestion\n│   ├── ingest-hadith.ts      # Hadith data ingestion\n│   └── test-*.ts             # Test scripts\n└── data/\n    ├── quran*.txt            # Quran translations\n    └── *-full.json           # Hadith collections\n```\n\n## Documentation\n\n### Understanding Criterion\n\n- **[MISSION.md](./MISSION.md)** — Our vision, values, and deeper purpose. Read this first to understand _why_ we build Criterion.\n- **[CRITERION_DETAILED.md](./CRITERION_DETAILED.md)** — Comprehensive technical documentation including architecture, implementation history, and performance metrics.\n- **[CRITERION.md](./CRITERION.md)** — Quick reference guide for setup and key concepts.\n\n### Key Sections\n\n| Document                  | Purpose                                                                 |\n| ------------------------- | ----------------------------------------------------------------------- |\n| **MISSION.md**            | Vision, values, pillars, and long-term goals                            |\n| **CRITERION_DETAILED.md** | Technical architecture, database schema, components, and best practices |\n| **CRITERION.md**          | Quick start, commands, and core concepts                                |\n| **README.md**             | Getting started, features, and project overview                         |\n\n## Architecture Overview\n\n```\ncomponents/\n├── Chat UI (QuranVerses, HadithNarrations, MessageActions)\n├── Search Pages (Quran and Hadith semantic search with filters)\n├── Hadith Components (reusable HadithCard for search and chat)\n├── Quran Pages (shared components for context, language selection)\n└── UI Components (buttons, inputs, etc.)\n\nlib/\n├── ai/\n│   ├── embeddings.ts (vector search logic)\n│   ├── prompts.ts (Da'i system prompts)\n│   └── tools/ (queryQuran, queryHadith, requestSuggestions)\n├── db/\n│   ├── schema.ts (Drizzle ORM definitions)\n│   └── queries.ts (database functions)\n└── monitoring/ (performance tracking)\n\napp/\n├── (chat)/api/chat (main chat endpoint)\n├── quran/search/ (Quran search page and API)\n├── hadith/search/ (Hadith search page and API)\n├── quran/ (Quran reading pages)\n└── (auth)/ (authentication)\n```\n\n## Data Attribution\n\n- **Quran Text**: [Tanzil.net](http://tanzil.net/) — Creative Commons Attribution 3.0\n- **Quran Translations**: Multiple sources with proper attribution\n- **Hadith Collections**: Sunnah.com, IslamicNetwork.com\n- **Embeddings**: Google Gemini text-embedding-004\n\n## Our Commitment\n\nCriterion is built with these commitments:\n\n- ✅ **Never monetize** Islamic knowledge\n- ✅ **Always cite sources** with proper references\n- ✅ **Never fabricate** verses or hadiths\n- ✅ **Focus on fundamentals** — avoid sectarian debates\n- ✅ **Build for the community** — this belongs to all Muslims and benefits all humanity\n- ✅ **Stay at the forefront** — leverage state-of-the-art technology\n\n## Contributing\n\nWe welcome contributions from developers, scholars, and community members who share our mission. Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.\n\n## License\n\n- **Quran Text**: Creative Commons Attribution 3.0 ([Tanzil.net](http://tanzil.net/))\n- **Hadith Data**: From verified Islamic sources with proper attribution\n- **Code**: See LICENSE file for details\n\n---\n\n**\"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\n\n_May Allah accept this work and make it a means of guidance for seekers everywhere. Ameen._\n",
  "bytes": 12052,
  "sha": "f58541f0512ff4b6bfab4bbdfd423053fae08a2afb473a84a25fea7a20c19113",
  "repo_slug": "balajsaleem/criterion",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_balajsaleem_criterion_ba822fd7/readme"
}