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:

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.

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.

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

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

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

2:255 (or switch the UI to Arabic and type البقرة ٢٥٥). ayah-2-255 in the Evidence Drawer.Compare interpretations of Al-Fatiha Basmalah Compare interpretations of Al-Asr What does the Quran say about justice even against oneself? 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/: studio/: scripts/: 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            │
└──────────────────────────────────────────────────────────┘

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

surah: ayah: tafsirSource: athari, juridical, rational, linguistic). interpretiveClaim: primaryExcerpt), the physical book locator ( sourceLocator), the divergence classification ( contradictory, complementary, consensus), and editorial status. sourceEdition & libraryChunk: 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.

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:

qkca243t production https://api.sanity.io/v1/context/organizations/o831wcpb9/mcp/quran-evidence-mcp 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.