Building an Agent That Can't Afford to Be Wrong: Quran Sanity Agent

This is a submission for the Sanity Challenge, Path One: Ship an Agent That Queries Real Content

When I first opened the Sanity Challenge announcement, one sentence in the Path One brief immediately grabbed my attention:

"Build anything that needs an answer it can't afford to get wrong."

That one line defined this entire project.

If you ask an AI chatbot for movie recommendations or a recipe, a small hallucination is harmless. But if you ask it about the Quran, religious scripture, or classical commentary, getting things wrong is not an option.

Yet that is exactly what standard LLMs do every day:

• They drop words from verses or invent Arabic grammar on the fly.
• When two classical scholars disagree, the model either invents a fake consensus or blends both opinions into a confusing, contradictory mess.
• It cites famous books and scholars with total confidence, even when the quote never existed in that book.

Traditional RAG (Retrieval-Augmented Generation) doesn't fix this either, because dumping raw chunks into a prompt still leaves the model free to summarize, blur, and paraphrase whatever it wants.

I wanted to see what happens when you treat the problem differently: what if the AI literally cannot generate Quranic text? What if the agent only has access to verified, structured records in Sanity, and conflicting historical opinions are modeled cleanly as data rather than smoothed over?

That is what Quran Sanity Agent is built to do.

What I Built

Quran Sanity Agent is a bilingual (Arabic & English) web research workspace where every single verse, translation, and scholarly commentary is anchored to an immutable record in Sanity.

How It Works in Practice

1. Verses Are Read, Never Generated: The LLM is never asked to recite or recall Quranic text from memory. Every Ayah displayed in the interface is pulled directly from a verified Sanity document matching the authoritative Tanzil Uthmani 1.1 reference standard.
2. Scholarly Differences as Structured Data: In classical Islamic exegesis (Tafsir), scholars have debated linguistic nuances and legal rulings for over a thousand years. Instead of hiding these differences, the application structures them into two distinct categories:
   • Contradictory (Ikhtilaf Tadadd): True conflicting positions (e.g., whether the opening Basmalah is counted as a verse of Al-Fatihah).
   • Complementary (Ikhtilaf Tanawwu'): Multi-faceted meanings that coexist (e.g., whether Al-Asr refers to time itself or the afternoon prayer).
3. The Evidence Drawer: Every verse and commentary card has an interactive citation badge. Clicking it opens a side drawer showing the exact Sanity Document ID, the physical book locator (chapter, volume, and primary URL), and the raw JSON payload straight from the Content Lake.
4. Honest Evidence Gaps: If you ask a question outside the curated dataset (like modern cryptocurrency rulings), the agent doesn't try to guess or produce an ungrounded opinion. It explicitly reports an Evidence Gap, showing what records it searched and clarifying that no authoritative source is available.

Demo

The app is live, publicly accessible, and backed by a hosted Sanity Studio:

• 🌐 Live Web Application: https://quran-sanity.omar-afifi.com
• 🏛️ Hosted Sanity Studio: https://quran-evidence-studio.sanity.studio/
• 💻 GitHub Repository: https://github.com/OmarAfifi-CSE/quran-sanity-agent

Zero-Trust Transparency: The Live Evidence Drawer

Inspect real-time Sanity Document IDs, physical book locators, and raw JSON payloads straight from the Content Lake.

Queries You Can Test Right Now

Here are four questions you can paste into the live app to see the structured pipeline in action:

1. Exact Verse Integrity:
   • Query: 2:255 (or switch the UI to Arabic and type البقرة ٢٥٥).
   • What to look for: Instant retrieval of Ayat al-Kursi with verified Uthmani script and Saheeh International translation. Click the citation badge to view ayah-2-255 in the Evidence Drawer.
2. Contradictory Divergence:
   • Query: Compare interpretations of Al-Fatiha Basmalah
   • What to look for: Surfaces the opposing classical positions between Ibn Kathir / Al-Qurtubi vs. Fakhr al-Din al-Razi side-by-side, without the model taking a side or muddying the waters.
3. Complementary Divergence:
   • Query: Compare interpretations of Al-Asr
   • What to look for: Shows how Al-Tabari, Ibn Kathir, and Al-Qurtubi each highlight complementary dimensions of the word (time, human deeds, afternoon prayer).
4. Semantic Retrieval via Sanity Context MCP:
   • Query: What does the Quran say about justice even against oneself?
   • What to look for: The agent queries the Sanity Context MCP endpoint, ranks Ayah 4:135 at the top, and provides grounded notes quoting the primary text verbatim.

Code

The entire codebase is open-source and available on GitHub:

👉 github.com/OmarAfifi-CSE/quran-sanity-agent

The project is structured as a TypeScript monorepo:

• web/: Next.js 15 (App Router) interface with full Arabic RTL support and the Sanity Context MCP integration.
• studio/: Sanity Studio v3 with custom Desk Structure and dedicated Islamic hermeneutic schemas.
• scripts/: Verification tools ensuring zero character drift against reference text standards.

How I Used Sanity

This project is built around the idea that an agent is only as reliable as the structure behind its content.

Here is how Sanity handles every layer of the architecture:

┌──────────────────────────────────────────────────────────┐
│                   SANITY CONTENT LAKE                    │
│   • 114 Surahs (Surah number, names, revelation type)    │
│   • 6,236 Ayahs (Uthmani text, translation, keywords)    │
│   • 6 Tafsir Authorities (Scholar, death year, school)   │
│   • 12 Audited Interpretive Claims with primary excerpts │
└────────────┬─────────────────────────────┬───────────────┘
             │                             │
    Exact Lookups (GROQ)          Semantic Queries (MCP)
             │                             │
             ▼                             ▼
┌──────────────────────────┐  ┌─────────────────────────────┐
│ Deterministic Lake Fetch │  │ Sanity Context MCP Endpoint │
│  • Sub-50ms response     │  │  • 21,398 library chunks    │
│  • Direct schema joins   │  │  • Vector embeddings rank   │
└────────────┬─────────────┘  └────────────┬────────────────┘
             │                             │
             └──────────────┬──────────────┘
                            ▼
┌──────────────────────────────────────────────────────────┐
│                 NEXT.JS AGENT WORKSPACE                  │
│   • Verifies all candidate IDs against Content Lake      │
│   • Rejects AI notes that lack verbatim source quotes    │
│   • Renders bilingual cards & Evidence Drawer            │
└──────────────────────────────────────────────────────────┘

1. The Content Model (studio/schemaTypes/)

Instead of generic blog or article schemas, Sanity Studio manages structured Quranic and classical commentary data:

• surah: Core chapter metadata (number, Arabic name, English name, revelation type, verse count).
• ayah: Individual verse records containing Tanzil Uthmani text, verified English translations, and references to parent chapters.
• tafsirSource: Classical authorities (e.g. Al-Tabari d. 310 AH, Al-Qurtubi d. 671 AH, Ibn Kathir d. 774 AH) with their specific methodology (athari, juridical, rational, linguistic).
• interpretiveClaim: An atomic claim linking an ayah to a tafsirSource. It stores the primary excerpt (primaryExcerpt), the physical book locator (sourceLocator), the divergence classification (contradictory, complementary, consensus), and editorial status.
• sourceEdition & libraryChunk: Ingestion schemas representing 21,398 chunks across classical commentaries for semantic retrieval.

2. The Editorial Review Gate

One of the most practical things about Sanity Studio is how easily you can customize the Desk Structure to enforce editorial discipline.

In studio/deskStructure.ts, I added a custom "Needs source review" filter:
If an editor enters a new claim but forgets the primary book excerpt, the exact source URL, or the reviewer sign-off, Sanity immediately catches it and moves it into this review queue.

More importantly, the Next.js agent's GROQ queries strictly filter for reviewStatus in ["source_checked", "reviewed"]. If a claim hasn't passed the editorial gate, the AI agent is physically unable to see it or use it in an answer.

3. Sanity Context MCP & Semantic Retrieval

While exact verse numbers (e.g. 2:255) are resolved instantly via deterministic GROQ queries, thematic questions (e.g. "What does the Quran say about justice?") require semantic understanding.

To handle this, I pointed Sanity Context at the imported library of 21,398 chunks and enabled Content Lake embeddings:

1. When a user asks a conceptual question, the agent queries the remote Sanity Context MCP endpoint.
2. The MCP server ranks relevant chunks based on semantic similarity and returns their document IDs.
3. The Grounding Rule: The agent never relies solely on the LLM's summary. It uses those document IDs to re-fetch the raw records directly from the Content Lake.
4. Verbatim Quotation Enforcement: If the model generates an explanatory note, the application validates that the note quotes words directly from the retrieved source text. If it fails this check, the UI falls back to displaying the raw verified excerpt.

Sanity Project Details

• Sanity Project ID: qkca243t
• Dataset: production
• Hosted Studio: https://quran-evidence-studio.sanity.studio/
• Sanity Context MCP Endpoint: https://api.sanity.io/v1/context/organizations/o831wcpb9/mcp/quran-evidence-mcp
• Content Lake Stats: 6,369 primary documents (114 Surahs, 6,236 Ayahs, 6 Tafsir Sources, 12 Curated Interpretive Claims) and 21,398 indexed library chunks.

What Building This Taught Me

Building this project made one thing very clear:

The solution to AI hallucination in high-stakes domains isn't "better prompts" or larger models. It's structured content.

When you treat texts as unstructured strings dumped into a vector database, the AI is always one step away from fabricating an answer. But when you model your domain properly—distinguishing chapters from verses, authorities from editions, and consensus from disagreement—the AI stops guessing and starts acting as an interface to verified knowledge.

Sanity was uniquely suited for this: having schemas, the Content Lake, GROQ, and the Context MCP in one unified ecosystem meant I could build a zero-hallucination agent that remains completely transparent with every answer it gives.

Check out the live project at quran-sanity.omar-afifi.com and explore the code on GitHub.