ISNAD
ISNAD grades who handled a claim in an AI pipeline (the transmitters and the chain) and can export each verdict as an audit record you can sign and verify.
Site: https://isnadhq.com/ · Docs: https://isnadhq.com/docs
Install
pip install isnad
Status
3.2 is the stable release of the 3.x line. The release/3.x branch receives security
fixes only. If you depend on the current API, pin isnad>=3.2,<4.
30-second example
from isnad import Registry, grade
from isnad.types import NarratorGrade
reg = Registry()
reg.register("openstax", "physics", grade=NarratorGrade.RELIABLE)
reg.register("pdf-scraper", "physics", grade=NarratorGrade.UNGRADED)
reg.register("ingest-model", "physics", grade=NarratorGrade.ACCEPTABLE)
verdict = grade("p = mv", ["openstax", "pdf-scraper", "ingest-model"], reg, domain="physics")
print(verdict.why)
# claim 'p = mv' → chain DAIF (weakest: pdf-scraper, ungraded)
A new pipeline starts with every narrator UNGRADED, so nothing serves; seed grades
with Registry.seed().
A JavaScript/TypeScript verifier (npm install isnad) checks audit records from JS —
verifier only; grading stays in the Python core.
How it works
A claim passes through a chain of transmitters — a scraper, a model, a tool. ISNAD:
- records the chain, in order;
- grades each transmitter in a registry (rijāl), on integrity and precision;
- caps the chain at its weakest link;
- combines chain grade with content criticism in a decision matrix — serve, review, or quarantine;
- exports the result as an audit record you can sign and verify.
How it differs
Most tools grade the output; ISNAD grades the chain that produced it.
| Tool | What it grades | Records the chain (lineage)? | Grades the transmitters / chain? |
|---|---|---|---|
| Cleanlab TLM | Trustworthiness of the LLM response | No | No |
| Galileo / Patronus / TruLens / RAGAS | Output faithfulness vs retrieved context | No | No |
| LangSmith / Langfuse / Arize | Traces + output evals | Yes | No |
| OpenLineage / Marquez / DataHub | Data lineage | Yes | No |
| ISNAD | The transmitters and the chain — weakest-link grading, corroboration with madār discounting, tamper-detecting audit | Yes | Yes |
Three objections, answered up front:
- "Tracers already record who handled it." They record the order; they don't grade each transmitter, propagate a weakest-link verdict, or gate on it.
- "Your grades are operator-assigned, so it's garbage-in-garbage-out." Grades are priors + audited observations + corroboration, propagated by a documented method. ISNAD makes trust explicit and auditable; it doesn't auto-measure it, and it doesn't pretend to.
- "Claim critics measure truth better than you." Correct — ISNAD composes with them. It grades the chain that carried the claim, not the claim's truth.
What's validated and what isn't
| Component | Status | Notes |
|---|---|---|
| Weakest-link quarantine | Validated | Every COMPROMISED-integrity chain grades MAWDU and is blocked; a SUSPECT narrator grades ḍaʿīf jiddan — both quarantine. The SUSPECT→ḍaʿīf jiddan path is exercised in the gated-vs-ungated experiment; the COMPROMISED→mawḍūʿ path is unit-tested. |
| ISNAD-Bench | Measured | κ = 0.871 (3-way) / 0.8667 (5-way, mapping v2, post-hoc) / 0.761 (lenient) vs 575,060 chains graded by a rule-based convention. κ is conformance, not agreement with scholars; narrator-grade agreement κ = 0.331 (a different task, not a ceiling); shuffled control −0.0066 |
| Corroboration (mutābaʿāt, shawāhid) | Validated | 603/603 Wikipedia + 104/104 physics matched pairs; 8/8 + 9/9 negative controls; requires attested distinct lineage |
| Chain-scoped grounding | Partial | Flags a claim grounded only off its own chain — evidence, not an action. Inert with the default critic (contradiction-only); false-positive rate not yet measured |
| Content-madār fingerprint calibration | Measured | FP 0.375 on independent agreement (down from 0.750), token-bearing recall 1.0; near-miss boundary separated (0/4 false positives) |
| Seed-grade bootstrapping | Validated | Evidence-backed Registry.seed(); coverage is critic-bound — the offline EmbeddingCritic serves 0% (contradiction-only), so the LLM critic is the ceiling |
| Content criticism | Partial | The main constraint. LLM critic 1.000 recall / 0.000 false-consistent on the 60-case eval, but 39.1% false-consistent on the gated-vs-ungated content corruption; offline critics recall 0.36–0.76 |
| jarḥ–taʿdīl discovery | Partial | Finds injected weak narrators; good narrators need seed grades |
| Bayesian grading | Default | Beta posterior per (narrator, role, domain) |
| Confidence-gating | Useless | Model self-confidence is uncorrelated with defects |
| Tamper-detecting audit | Implemented | Self-hash + detached signatures + Merkle log; tail-truncation and forger limits disclosed |
| Period-sliced grades | Implemented | get_grade_as_of() — the ikhtilāṭ (decline) remedy |
| Integrity ladder + recoverability | Implemented | Integrity strikes are permanent; precision-driven REJECTED is recoverable |
Grades are ordinal-only (ṣaḥīḥ > ḥasan > ḍaʿīf > ḍaʿīf jiddan > mawḍūʿ, never a numeric
confidence). Cold-start is worse per-role; integrity is domain-scoped, not global; chain
independence cannot be proven from topology — only assumed from attested lineage, then
discounted; correlated errors across model families (shared training data) cannot be
detected; the content critic is the coverage ceiling; corroboration rarely fires on dense
technical corpora where genuine cross-source overlap is rare; the serving index is
in-memory (single-node; multi-worker HA is not yet supported).
Resolving a review item records the human decision as oversight evidence; it does not
change narrator grades. To move a grade, submit evidence with Registry.record_evidence()
or POST /v1/evidence.
Decision matrix
Chain grade × content verdict → action:
| CONSISTENT | CONTRADICTION | UNVERIFIABLE | |
|---|---|---|---|
| Ṣaḥīḥ (sound) | SERVE — cache | REVIEW — contradiction (highest-value case) | SERVE WITH CAVEAT |
| Ḥasan (good) | SERVE WITH CAVEAT | REVIEW — hold | REVIEW |
| Ḍaʿīf (weak) | REVIEW — seek corroboration | QUARANTINE | REVIEW |
| Ḍaʿīf jiddan (very weak) | QUARANTINE | QUARANTINE | QUARANTINE |
| Mawḍūʿ (fabricated) | REJECT + QUARANTINE NARRATOR | REJECT + QUARANTINE NARRATOR | REJECT + QUARANTINE NARRATOR |
Contradictions go to a human by default; ṣaḥīḥ × contradiction is the highest-value signal,
not an error state. Two serve-side gates apply on top (both demote, never promote): the
prior-only gate — a narrator graded from a population prior alone can SERVE WITH CAVEAT at
most (plain SERVE requires observation- or human-backed narrators) — and hold-mode
UNVERIFIABLE, on with ISNAD_SERVE_GATE=hold or ISNAD_SERVE_HOLD_DOMAINS=medical,legal.
Audit records
isnad export --claim <id> --format json # jsonl|csv; --verify; --sign; --redact; --chain-log
A record contains the full chain (a DAG via upstream_ids), the weakest link, source-document
hashes, human-oversight evidence, the environment, and a SHA-256 integrity hash over the
RFC 8785-canonical payload — plus an optional detached signature (HMAC/Ed25519), a hash
chain, and a PII-redaction hook. The API signs with HMAC only when ISNAD_HMAC_SECRET is
set; otherwise records are emitted audit_signed: false (a self-hash a forger can recompute).
Two logs — a linear hash chain and a Merkle batch log — detect modification, middle-deletion, and reordering. Neither detects tail truncation, and both commit to a self-hash, so they detect post-hoc modification, not a forger who rebuilds the chain.
ISNAD produces evidence artifacts; it does not confer conformity with any regulation. See docs/evidence-mapping.md.
Integrations
- LangChain / LangGraph — callback handler, tracer, middleware. The callback handler is the stable capture path; the AgentMiddleware wiring targets a forward-looking LangChain API.
- CrewAI / LlamaIndex — adapters
- OpenTelemetry —
isnad ingest --otlpgrades an existing GenAI trace - MCP — grade MCP servers as narrators; tool narrators stay UNGRADED by default
- Live Verify — consume a
verify:seal as a high-trust narrator (proves authenticity, not truth) - Chain viewer —
viewer/index.htmlrenders chains in the browser
LangChain callback, in five lines:
from isnad.integrations.langchain import IsnadCallbackHandler, seed_registry
reg = seed_registry({"source:docs": "reliable", "model:gpt-4o": "acceptable"})
handler = IsnadCallbackHandler(registry=reg, domain="physics")
chain.invoke("What is F=ma?", config={"callbacks": [handler]})
trace = handler.to_trace() # isnad_trace v0.1 JSON
Scope and limitations
ISNAD grades post-entry provenance — who handled a claim after it entered the pipeline, and how much you trust them — not whether the upstream source or the final answer is true. It covers ordered chains + grades, weakest-link grading + the decision matrix, content criticism against your corpus, and corroboration. It does not cover:
- Source legitimacy at the boundary — grades are operator-assigned assertions, not auto-verified facts.
- Novel claim truth — new, unverifiable claims are not auto-fact-checked.
- Faithful transmission of bad input — a RELIABLE fake publisher + a clean pipeline can still yield a high chain grade.
Boundary vetting is the operator's responsibility: vet sources before registering them as RELIABLE; register unknowns as UNGRADED; use matn, corroboration, and human review as downstream gates, not a replacement for it.
Glossary
| Term | Meaning |
|---|---|
| isnād | The transmission chain — who handled a claim, in order |
| rijāl | The registry of transmitters and their grades |
| jarḥ–taʿdīl | The criticism-and-accreditation loop that moves grades with evidence |
| ʿadālah | Integrity — can this transmitter be trusted not to lie? |
| ḍabṭ | Precision — how often is this transmitter accurate? |
| ittiṣāl | Chain continuity (no gaps) |
| mutābaʿāt / shawāhid | Corroboration: other routes that agree with a claim, through the same source (mutābaʿāt) or a different one (shawāhid). ISNAD counts only routes with attested distinct lineage. |
| madār | The common link where chains converge: "independent" chains that actually share an upstream |
| matn | The claim content, criticized separately from the chain |
| ṣaḥīḥ / ḥasan / ḍaʿīf / ḍaʿīf jiddan / mawḍūʿ | Sound / good / weak / very weak / fabricated |
| ʿilal | Hidden defects that survive surface grading — not implemented; routed to review |
| contradiction (taʿāruḍ) | A sound chain whose content contradicts the corpus — routed to review |
Research
Paper: arXiv:2607.24117 · Software DOI: 10.5281/zenodo.21216872
ISNAD-Bench. ISNAD's weakest-link chain grading conforms to a rule-based grading convention derived from Ibn Hajar's 12 narrator tiers at Cohen's κ = 0.871 (strict default), across 575,060 chains, with a shuffled-rank control at κ = −0.0066. ISNAD conforms to the rule-based convention; it is not "better than the scholars." The narrator-grade agreement — how contested the underlying tiers are — is κ = 0.331; the 0.331 is narrator-grade context, not a ceiling. The 5-way 0.8667 (mapping v2) is post-hoc. Full write-up: bench/docs/RESULTS.md.
Transfer to AI pipelines. On RAGTruth, the grounding critic ISNAD composes with transfers at κ = 0.4345 over all 1,800 responses (57 unparseable, 3.2%, scored fail-closed) — 96.0% hallucination recall at 60.4% precision, a 49.9% false-positive rate on grounded responses, vs a 55.8% majority-class baseline. That number belongs to the composed critic, not to chain grading. The weak bi-encoder signal (κ ≈ 0.1) is reported alongside. Case study: G1_CASE_STUDY.md.
Datasets: alizahidraja/isnad-bench · each folder under experiments/ has its own RESULTS.md.
Contributing and security
CONTRIBUTING.md · CODE_OF_CONDUCT.md · SECURITY.md · THREAT_MODEL.md
Citation
@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},
}
License and author
Code: Apache 2.0 (see LICENSING.md) · Paper & docs: CC BY 4.0. The core
(src/isnad/) stays Apache-2.0.
Built by Ali Zahid Raja · ORCID 0009-0003-7875-4590. The method belongs to fourteen centuries of muḥaddithūn; the transfer to AI systems is the contribution claimed here.
Metadata
Release files for isnad 3.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| isnad-3.2.0.tar.gz | 219.2 kB | With provenance | Details for isnad-3.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| isnad-3.2.0-py3-none-any.whl | Python 3 | none | any | Details for isnad-3.2.0-py3-none-any.whl |
Total release size: 470.1 kB
Release files / isnad-3.2.0.tar.gz
| Download URL | isnad-3.2.0.tar.gz |
|---|---|
| Size | 219.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c4d2453b652c8ed64ac1bcd6b9c251edc9de15a62c09e02d034978fa0c2adeea
|
|
BLAKE2b-256 checksum How to use checksums |
e5c94777bc89f8c737593ca5760dcce3015da44d2e111168c07325860e0f318f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.
Transparency logRelease files / isnad-3.2.0-py3-none-any.whl
| Download URL | isnad-3.2.0-py3-none-any.whl |
|---|---|
| Size | 251.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1777d9490f3701b456a74caf30d52d585458596c2af23acdfb2b33d9129e73d7
|
|
BLAKE2b-256 checksum How to use checksums |
3367116844b9e255821f1a4e8f752a1764daa390dc682947ecf2694ae554708a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.
Transparency logSecurity for isnad 3.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for isnad-3.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 27, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.