# ISNAD — Isnad–Rijal Framework

Claim-level provenance for multi-agent AI systems. Grades every agent, scraper, and model in a claim's transmission chain, adapted from classical Islamic hadith transmission science.

- **Author:** Ali Zahid Raja (ORCID: 0009-0003-7875-4590)
- **Paper:** arXiv:2607.24117 (cs.AI / cs.MA, 25 pages)
- **Code:** Apache-2.0, Python 3.12+
- **Install:** `pip install isnad` (v2.0.5)
- **Repo:** https://github.com/alizahidraja/isnad
- **Not to be confused** with unrelated projects using the word "isnad". This project has no token and no blockchain component.

## Quickstart

```bash
pip install isnad
```

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

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

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)

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)

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}")
```

## Key Concepts

ISNAD transfers the methodology of classical Islamic hadith transmission science to AI pipelines:

- **isnād** — every claim carries its transmission chain
- **rijāl** — every transmitter keeps a living, per-domain grade
- **Weakest link** — the chain's grade is capped by its weakest narrator
- **mutābaʿāt** — independent corroboration upgrades a claim (capped at ṣaḥīḥ)
- **matn** — content is criticized separately from the chain

## Decision Matrix (4×3)

| | Matn: consistent | Matn: contradiction | Matn: unverifiable |
|---|---|---|---|
| **Ṣaḥīḥ-tier** | Serve directly; cache | ʿIlal flag → human review | Serve with caveat |
| **Ḥasan-tier** | Serve with caveat; seek corroboration | Hold; do not serve | Hold in review queue |
| **Ḍaʿīf-tier** | Hold; seek corroboration | Quarantine | Hold in review queue |
| **Mawḍūʿ-tier** | Reject & quarantine narrator | Reject & quarantine narrator | Reject & quarantine narrator |

## Evaluation Summary (20,000 claims, 10 seeds)

**Validated:** weakest-link quarantine (4,057 claims, 29%), corroboration (603/603 Wikipedia, 104/104 physics, 8/8 negative controls).

**Partial:** jarḥ–taʿdīl grade recovery (3/4 narrators recovered; missed the highest-fault narrator through insufficient calibration evidence).

**Inconclusive:** matched-coverage comparison (ISNAD could not be driven above 4.8% coverage — the content critic is the binding constraint). Confidence baseline is synthetic and uninformative.

**Honest negatives:** the reference content critic catches only obvious contradictions and returns "unverifiable" on most real prose. A semantic or LLM-backed critic is the single highest-value improvement.

## Links

- Paper: https://arxiv.org/abs/2607.24117
- PDF: https://arxiv.org/pdf/2607.24117
- Software DOI: https://doi.org/10.5281/zenodo.21216873
- GitHub: https://github.com/alizahidraja/isnad
- PyPI: https://pypi.org/project/isnad/
- §8 Experiment: https://github.com/alizahidraja/isnad/tree/main/experiments/s8_gated_vs_ungated
- Corroboration v2: https://github.com/alizahidraja/isnad/tree/main/experiments/corroboration_v2
- Corroboration v3: https://github.com/alizahidraja/isnad/tree/main/experiments/corroboration_v3
- Live Verify comparison: https://github.com/live-verify/live-verify/blob/main/docs/comparison-to-isnad.md

## Cite

```bibtex
@article{raja2026grading,
  author = {Ali Zahid Raja},
  title = {Grading the Narrators: An Isnad–Rijal Framework for Claim-Level Provenance},
  year = 2026,
  doi = {10.48550/arXiv.2607.24117},
  eprint = {2607.24117},
  archivePrefix = {arXiv},
  primaryClass = {cs.AI}
}

@software{raja2026isnad,
  author = {Ali Zahid Raja},
  title = {Isnad–Rijal Framework: Reference Implementation},
  year = 2026,
  doi = {10.5281/zenodo.21216873},
  orcid = {0009-0003-7875-4590}
}
```