Grade the narrators, not just log them. Claim-level provenance for multi-agent knowledge systems — adapted from classical hadith transmission science.

Paper: arXiv:2607.24117 | Paper DOI: 10.48550/arXiv.2607.24117 | Software DOI: 10.5281/zenodo.21216873

🌐 Full project home: https://alizahidraja.com/isnad

In modern AI pipelines, a factual claim passes through many hands — a scraper extracts it, a model compiles it, another serves it. Each hand can drop, distort, or invent. Existing tools record what happened. ISNAD grades who transformed the claim, so it can tell you how much to trust the result.

The framework adapts hadith transmission science — one of history's most rigorous epistemologies, refined over twelve centuries — into a Python library for AI systems. Every claim carries its complete chain of transmitters (isnād); each transmitter is graded in a living registry (rijāl); chains are evaluated by their weakest link; content is criticized independently of transmission quality; and the two combine in a decision matrix that routes claims to serve, review, or quarantine.

pip install isnad

from isnad import Registry, Chain, ChainLinkSpec, grade_chain, decide
from isnad.types import NarratorGrade, ContentVerdict
from isnad.critics import EmbeddingCritic

# Build a chain: source → scraper → model
chain = Chain([
    ChainLinkSpec("openstax-textbook", 0, domain="physics"),
    ChainLinkSpec("pdf-scraper-v2", 1),
    ChainLinkSpec("ingest-model-v3", 2),
])

# Seed-grade known narrators (required for coverage — see §8 experiment)
reg = Registry()
reg.register("openstax-textbook", "physics", grade=NarratorGrade.RELIABLE)
reg.register("pdf-scraper-v2", "physics", grade=NarratorGrade.RELIABLE)
reg.register("ingest-model-v3", "physics", grade=NarratorGrade.ACCEPTABLE)

# Grade the chain
grades = [reg.get_grade(l.narrator_id, l.domain) for l in chain.links]
transforms = [l.transform_type for l in chain.links]
chain_grade = grade_chain(grades, transforms, is_complete=True)

# Content criticism (now functional — embedding-based)
critic = EmbeddingCritic()
verdict = critic.evaluate("p = h/λ", "p = h/lambda", ["p = mv"])
action = decide(chain_grade, verdict)

print(f"Chain: {chain_grade.value.upper()} | Content: {verdict.value} | Action: {action.value}")

pip install isnad[langchain]

from isnad.integrations.langchain import IsnadTracer, seed_registry
from isnad.critics import EmbeddingCritic

reg = seed_registry({"source:docs": "reliable", "model:gpt-4o": "acceptable"})
tracer = IsnadTracer(registry=reg, critic=EmbeddingCritic())
chain.invoke("What is F=ma?", config={"callbacks": [tracer]})
print(tracer.report())

If you use ISNAD in your research, please cite:

@article{raja2026grading,
  author  = {Ali Zahid Raja},
  title   = {Grading the Narrators: An Isnād–Rijāl Framework for
             Claim-Level Provenance in Multi-Agent Knowledge Systems},
  year    = 2026,
  doi     = {10.48550/arXiv.2607.24117},
  eprint  = {2607.24117},
  archivePrefix = {arXiv},
}

@software{raja2026isnad,
  author  = {Ali Zahid Raja},
  title   = {Isnād–Rijāl Framework: Reference Implementation},
  year    = 2026,
  doi     = {10.5281/zenodo.21216873},
  orcid   = {0009-0003-7875-4590},
}

GitHub users: click "Cite this repository" on the repo sidebar (powered by CITATION.cff).

The honesty box is a feature. We tell you exactly what works, what's limited, and where you need to supply your own components.

🗺️ Full architecture diagram: docs/ARCHITECTURE.drawio — 3 tabs: System Architecture, Claim Lifecycle (data flow), and Validation Matrix (what's proven vs what's not). Open in draw.io or VS Code Draw.io extension.

The framework leaves key parameters open by design (paper §4.2/§4.3). Swap any:

Swap a critic in one line:

from isnad.critics import EmbeddingCritic, LLMCritic

critic = EmbeddingCritic()                            # offline, fast
critic = LLMCritic(api_key="sk-...")                  # LLM-backed, higher quality

Good first issues:

• Implement an alternative critic (sentence-transformers embedding, CrewAI integration)
• Seed-grade bootstrapper from published benchmark data
• Extend semantic corroboration to multi-source corpora (ArXiv, textbooks, news)

Status: Empirically validated on real data.

The framework's most distinctive contribution — independent-chain corroboration (mutābaʿāt) — has been validated on two corpora of increasing difficulty:

Combined: 603 + 104 = 707 claim pairs tested across both corpora. 100% corroboration fire rate. 8/8 negative controls. Zero false positives. Source URLs for every claim.

1. Corroboration fires on semantically-matched cross-source data — different text, same meaning, genuinely independent sources
2. Independence detector correctly identifies madār — chains with shared model families or upstream sources are blocked from upgrade
3. HASAN cap enforced — corroboration never falsely reaches SAHIH
4. Information-theoretic weights calibrated — effective weight scales with chain quality (1.5 for single HASAN corroborator, 2.5+ for multiple)

cd experiments/corroboration_v2
pip install isnad sentence-transformers scikit-learn requests
python run.py               # Fetch Wikipedia + semantic match + corroborate
python negative_controls.py  # Verify all 8 gates
python analyze.py            # Statistical analysis

Full methodology, results, negative controls, and paper gap analysis in:

• experiments/corroboration_v2/README.md
• experiments/PAPER_GAP_ANALYSIS.md

• 🌐 Site: https://alizahidraja.com/isnad
• 📄 Paper (arXiv): https://arxiv.org/abs/2607.24117
• 📄 Paper (DOI): https://doi.org/10.48550/arXiv.2607.24117
• 💾 Software (DOI): https://doi.org/10.5281/zenodo.21216873
• 📦 PyPI: https://pypi.org/project/isnad/
• 📝 Companion gist: https://gist.github.com/alizahidraja/56beaadf493976182f38aa602b8958e2
• 🧪 §8 Experiment & results: experiments/s8_gated_vs_ungated/
• 🔬 Semantic Corroboration v2 (Wikipedia): experiments/corroboration_v2/
• 📚 Corroboration v3 (Physics Textbooks): experiments/corroboration_v3/ — 104/104 on s8 corpus
• 🗺️ Architecture Diagram: docs/ARCHITECTURE.drawio — 3 tabs: System, Data Flow, Validation Matrix
• 🔌 LangChain integration: src/isnad/integrations/langchain/
• 📊 Critic evaluation: src/isnad/critics/CRITIC_EVAL.md

@article{raja2026grading,
  author  = {Ali Zahid Raja},
  title   = {Grading the Narrators: An Isnād–Rijāl Framework for
             Claim-Level Provenance in Multi-Agent Knowledge Systems},
  year    = 2026,
  doi     = {10.48550/arXiv.2607.24117},
  eprint  = {2607.24117},
  archivePrefix = {arXiv},
}

@software{raja2026isnad,
  author  = {Ali Zahid Raja},
  title   = {Isnād–Rijāl Framework: Reference Implementation},
  year    = 2026,
  doi     = {10.5281/zenodo.21216873},
  orcid   = {0009-0003-7875-4590},
}

Built by Ali Zahid Raja · ORCID 0009-0003-7875-4590

The rigor belongs to twelve centuries of muḥaddithūn. The transfer to AI systems is the contribution claimed here. Built in public — collaborators welcome.

License: Code — Apache 2.0 · Paper & docs — CC BY 4.0