Give AI context from classical texts with Nusus

I had my AI agents build Nusus, a TypeScript SDK and CLI that connects agents to classical Islamic and Arabic source texts from Turath.

Agents give better answers when you give them better context. I use mine a lot for Islamic text research, so this was a way to feed them real passages with citations instead of vibes.

Nusus talks to Turath. Turath holds the books. One npm package has both the SDK (for app code) and the nusus CLI (for agents). Each result includes the source text, a citation, a page locator, and a Turath URL. Nusus does not rank madhhabs, issue fatwas, or grade hadith. Retrieval is also not a substitute for reading the sources yourself or asking a qualified scholar.

The project was inspired by turath-sdk. I wanted features aimed at AI research workflows: find books and authors by name (not only numeric IDs), pull passages with surrounding context, generate citations and locators, and return bounded agent-ready context through a single retrieve() call.

Install

npm install nusus
# or
bun add nusus

# global CLI:
npm install -g nusus
# or without a global install: npx nusus ...

CLI for agents

Point the agent at the nusus binary and ask it to search before it writes. Stdout defaults to JSONL: one JSON object per line.

nusus --help

# Offline discovery (bundled catalog)
nusus find-books "الأربعون النووية" --limit 5
nusus find-authors "النووي" --limit 5

# Live search / retrieve
nusus search "إنما الأعمال بالنيات" --book-id 147927
nusus retrieve "النية" --max-passages 3 --max-chars 2000

Example prompt: "Find classical sources on intention in wudu. Run nusus retrieve, keep the JSONL passages and citations, and explain only what those passages say."

SDK in application code

import { createTurathClient } from "nusus/turath";

const turath = createTurathClient({ timeout: 10_000 });

const context = await turath.retrieve("النية", {
  maxPassages: 5,
  maxCharsPerPassage: 2_000,
});

for (const passage of context.passages) {
  console.log(passage.citation);
  console.log(passage.locator);
  console.log(passage.provenance);
}

Store the retrieved text and citations with whatever answer you generate from them. Each passage keeps the original Arabic, book metadata, citation, location, and source URL so you can check the agent when you do not trust the paraphrase.

Checking citations

Open each cited page in Turath and read it. Confirm the passage matches the claim. Check nearby pages for context the agent skipped, and separate the quoted text from the agent's paraphrase.

Limits

Retrieval can still miss the right passage, mistranslate Arabic, or invent claims the sources do not support. Book discovery uses a bundled Turath catalog snapshot, so books added after the snapshot may be absent until you refresh it. Do not treat the output as a fatwa, madhhab ranking, or hadith grade.

Links: npm, GitHub, project page