# alizahidraja/isnad architecture

> Architecture diagram of the GitHub repository alizahidraja/isnad, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alizahidraja/isnad
- Repository: https://github.com/alizahidraja/isnad

## Overview

ISNAD is a Python framework for claim-level provenance and trust grading in RAG and multi-agent systems, with an API, CLI, integrations, and a JavaScript audit-record verifier. The principal workflow registers transmitter grades, records an ordered claim chain, grades its weakest link, critiques claim content, and routes the combined verdict to serve, review, or quarantine; audit records make the judgment verifiable. The graph preserves documented corroboration, grounding, persistence, and integration capabilities. Source-index references and README statements support some links; unsampled implementation details are not assumed.

Main entry points: [`src/isnad/core/chain.py`](https://github.com/alizahidraja/isnad/blob/main/src/isnad/core/chain.py) (Claim and chain), [`src/isnad/core/registry.py`](https://github.com/alizahidraja/isnad/blob/main/src/isnad/core/registry.py) (Narrator registry), [`src/isnad/core/grading.py`](https://github.com/alizahidraja/isnad/blob/main/src/isnad/core/grading.py) (Weakest-link grading), [`src/isnad/critics/embedding.py`](https://github.com/alizahidraja/isnad/blob/main/src/isnad/critics/embedding.py) (Content critics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_trust["Trust and provenance"]
  node_claim["Claim and chain<br/>[chain.py]"]
  node_registry[("Narrator registry<br/>[registry.py]")]
  node_identity["Narrator identity<br/>[identity.py]"]
  node_grading["Weakest-link grading<br/>[grading.py]"]
  node_grounding["Chain grounding<br/>[chain_grounding.py]"]
  node_corroboration["Corroboration<br/>[corroboration.py]"]
  node_policies["Trust policies<br/>[policies.py]"]
  node_decision["Action decision<br/>[decision.py]"]
end

subgraph group_critique["Content criticism"]
  node_critics["Content critics<br/>[embedding.py]"]
  node_critic_base["Critic protocol<br/>[base.py]"]
  node_llm_critic["LLM criticism<br/>[llm.py]"]
  node_nli_critic["NLI criticism<br/>[nli.py]"]
  node_recompute["Numeric recomputation<br/>[recompute.py]"]
  node_matn["Matn rules<br/>[matn.py]"]
end

subgraph group_interfaces["API and operations"]
  node_api["Claim API<br/>[claims.py]"]
  node_app["API application<br/>[app.py]"]
  node_cli["CLI<br/>[main.py]"]
  node_storage[("SQLAlchemy persistence<br/>[sqlalchemy.py]")]
  node_models["Claim data models<br/>[models.py]"]
end

subgraph group_evidence["Audit evidence"]
  node_audit[("Audit records<br/>[merkle_log.py]")]
  node_sign["Record signatures<br/>[sign.py]"]
  node_jsverify["JS record verifier<br/>[verify.ts]"]
end

subgraph group_ecosystem["Integrations"]
  node_integrations["Framework integrations<br/>[callback.py]"]
  node_otel["OTel ingestion<br/>[ingest.py]"]
  node_mcp["MCP interface<br/>[mcp.py]"]
end

node_operator(("Pipeline operator"))

node_operator -->|"submits claim"| node_claim
node_operator -->|"registers grades"| node_registry
node_claim -->|"looks up narrators"| node_registry
node_registry -->|"resolves identities"| node_identity
node_claim -->|"grades chain"| node_grading
node_grading -->|"uses grades"| node_registry
node_corroboration -->|"supports grading"| node_grading
node_claim -->|"checks grounding"| node_grounding
node_registry -->|"applies policies"| node_policies
node_claim -->|"critiques content"| node_critics
node_critics -->|"implements protocol"| node_critic_base
node_llm_critic -->|"implements protocol"| node_critic_base
node_nli_critic -->|"implements protocol"| node_critic_base
node_critics -->|"combines with"| node_recompute
node_claim -->|"can use rules"| node_matn
node_grading -->|"supplies chain grade"| node_decision
node_critics -->|"supplies content verdict"| node_decision
node_decision -->|"routes action"| node_api
node_app -->|"mounts routes"| node_api
node_api -->|"persists claims"| node_storage
node_storage -->|"uses models"| node_models
node_api -->|"creates audit evidence"| node_audit
node_cli -->|"exports and verifies"| node_audit
node_audit -->|"supports signatures"| node_sign
node_jsverify -->|"verifies records"| node_audit
node_integrations -->|"captures traces"| node_claim
node_otel -->|"grades ingested links"| node_grading
node_mcp -.->|"exposes tools"| node_operator

click node_claim "https://github.com/alizahidraja/isnad/blob/main/src/isnad/core/chain.py"
click node_registry "https://github.com/alizahidraja/isnad/blob/main/src/isnad/core/registry.py"
click node_identity "https://github.com/alizahidraja/isnad/blob/main/src/isnad/core/identity.py"
click node_grading "https://github.com/alizahidraja/isnad/blob/main/src/isnad/core/grading.py"
click node_grounding "https://github.com/alizahidraja/isnad/blob/main/src/isnad/core/chain_grounding.py"
click node_corroboration "https://github.com/alizahidraja/isnad/blob/main/src/isnad/core/corroboration.py"
click node_policies "https://github.com/alizahidraja/isnad/blob/main/src/isnad/core/policies.py"
click node_critics "https://github.com/alizahidraja/isnad/blob/main/src/isnad/critics/embedding.py"
click node_critic_base "https://github.com/alizahidraja/isnad/blob/main/src/isnad/critics/base.py"
click node_llm_critic "https://github.com/alizahidraja/isnad/blob/main/src/isnad/critics/llm.py"
click node_nli_critic "https://github.com/alizahidraja/isnad/blob/main/src/isnad/critics/nli.py"
click node_recompute "https://github.com/alizahidraja/isnad/blob/main/src/isnad/critics/recompute.py"
click node_matn "https://github.com/alizahidraja/isnad/blob/main/src/isnad/matn.py"
click node_decision "https://github.com/alizahidraja/isnad/blob/main/src/isnad/core/decision.py"
click node_api "https://github.com/alizahidraja/isnad/blob/main/src/isnad/api/endpoints/claims.py"
click node_app "https://github.com/alizahidraja/isnad/blob/main/src/isnad/api/app.py"
click node_cli "https://github.com/alizahidraja/isnad/blob/main/src/isnad/cli/main.py"
click node_storage "https://github.com/alizahidraja/isnad/blob/main/src/isnad/storage/sqlalchemy.py"
click node_models "https://github.com/alizahidraja/isnad/blob/main/src/isnad/models.py"
click node_audit "https://github.com/alizahidraja/isnad/blob/main/src/isnad/audit/merkle_log.py"
click node_sign "https://github.com/alizahidraja/isnad/blob/main/src/isnad/audit/sign.py"
click node_jsverify "https://github.com/alizahidraja/isnad/blob/main/js/src/verify.ts"
click node_integrations "https://github.com/alizahidraja/isnad/blob/main/src/isnad/integrations/langchain/callback.py"
click node_otel "https://github.com/alizahidraja/isnad/blob/main/src/isnad/integrations/otel/ingest.py"
click node_mcp "https://github.com/alizahidraja/isnad/blob/main/src/isnad/integrations/mcp.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_claim,node_registry,node_identity,node_grading,node_grounding,node_corroboration,node_policies,node_decision toneBlue
class node_critics,node_critic_base,node_llm_critic,node_nli_critic,node_recompute,node_matn toneAmber
class node_api,node_app,node_cli,node_storage,node_models toneMint
class node_audit,node_sign,node_jsverify toneRose
class node_integrations,node_otel,node_mcp,node_operator toneIndigo
```

## Components

### Trust and provenance

- [Claim and chain](https://github.com/alizahidraja/isnad/blob/main/src/isnad/core/chain.py): `src/isnad/core/chain.py`
- [Narrator registry](https://github.com/alizahidraja/isnad/blob/main/src/isnad/core/registry.py): `src/isnad/core/registry.py`
- [Narrator identity](https://github.com/alizahidraja/isnad/blob/main/src/isnad/core/identity.py): `src/isnad/core/identity.py`
- [Weakest-link grading](https://github.com/alizahidraja/isnad/blob/main/src/isnad/core/grading.py): `src/isnad/core/grading.py`
- [Chain grounding](https://github.com/alizahidraja/isnad/blob/main/src/isnad/core/chain_grounding.py): `src/isnad/core/chain_grounding.py`
- [Corroboration](https://github.com/alizahidraja/isnad/blob/main/src/isnad/core/corroboration.py): `src/isnad/core/corroboration.py`
- [Trust policies](https://github.com/alizahidraja/isnad/blob/main/src/isnad/core/policies.py): `src/isnad/core/policies.py`
- [Action decision](https://github.com/alizahidraja/isnad/blob/main/src/isnad/core/decision.py): `src/isnad/core/decision.py`

### Content criticism

- [Content critics](https://github.com/alizahidraja/isnad/blob/main/src/isnad/critics/embedding.py): `src/isnad/critics/embedding.py`
- [Critic protocol](https://github.com/alizahidraja/isnad/blob/main/src/isnad/critics/base.py): `src/isnad/critics/base.py`
- [LLM criticism](https://github.com/alizahidraja/isnad/blob/main/src/isnad/critics/llm.py): `src/isnad/critics/llm.py`
- [NLI criticism](https://github.com/alizahidraja/isnad/blob/main/src/isnad/critics/nli.py): `src/isnad/critics/nli.py`
- [Numeric recomputation](https://github.com/alizahidraja/isnad/blob/main/src/isnad/critics/recompute.py): `src/isnad/critics/recompute.py`
- [Matn rules](https://github.com/alizahidraja/isnad/blob/main/src/isnad/matn.py): `src/isnad/matn.py`

### API and operations

- [Claim API](https://github.com/alizahidraja/isnad/blob/main/src/isnad/api/endpoints/claims.py): `src/isnad/api/endpoints/claims.py`
- [API application](https://github.com/alizahidraja/isnad/blob/main/src/isnad/api/app.py): `src/isnad/api/app.py`
- [CLI](https://github.com/alizahidraja/isnad/blob/main/src/isnad/cli/main.py): `src/isnad/cli/main.py`
- [SQLAlchemy persistence](https://github.com/alizahidraja/isnad/blob/main/src/isnad/storage/sqlalchemy.py): `src/isnad/storage/sqlalchemy.py`
- [Claim data models](https://github.com/alizahidraja/isnad/blob/main/src/isnad/models.py): `src/isnad/models.py`

### Audit evidence

- [Audit records](https://github.com/alizahidraja/isnad/blob/main/src/isnad/audit/merkle_log.py): `src/isnad/audit/merkle_log.py`
- [Record signatures](https://github.com/alizahidraja/isnad/blob/main/src/isnad/audit/sign.py): `src/isnad/audit/sign.py`
- [JS record verifier](https://github.com/alizahidraja/isnad/blob/main/js/src/verify.ts): `js/src/verify.ts`

### Integrations

- [Framework integrations](https://github.com/alizahidraja/isnad/blob/main/src/isnad/integrations/langchain/callback.py): `src/isnad/integrations/langchain/callback.py`
- [OTel ingestion](https://github.com/alizahidraja/isnad/blob/main/src/isnad/integrations/otel/ingest.py): `src/isnad/integrations/otel/ingest.py`
- [MCP interface](https://github.com/alizahidraja/isnad/blob/main/src/isnad/integrations/mcp.py): `src/isnad/integrations/mcp.py`

### Other components

- **Pipeline operator**

## Connections

- Pipeline operator → Claim and chain: submits claim (evidence: `README.md`)
- Pipeline operator → Narrator registry: registers grades (evidence: `README.md`)
- Claim and chain → Narrator registry: looks up narrators (evidence: `src/isnad/core/chain.py`)
- Narrator registry → Narrator identity: resolves identities (evidence: `src/isnad/core/registry.py`)
- Claim and chain → Weakest-link grading: grades chain (evidence: `src/isnad/__init__.py`)
- Weakest-link grading → Narrator registry: uses grades (evidence: `src/isnad/core/chain.py`)
- Corroboration → Weakest-link grading: supports grading (evidence: `README.md`)
- Claim and chain → Chain grounding: checks grounding (evidence: `src/isnad/api/endpoints/claims.py`)
- Narrator registry → Trust policies: applies policies (evidence: `src/isnad/core/registry.py`)
- Claim and chain → Content critics: critiques content (evidence: `README.md`)
- Content critics → Critic protocol: implements protocol (evidence: `src/isnad/critics/__init__.py`)
- LLM criticism → Critic protocol: implements protocol (evidence: `src/isnad/critics/__init__.py`)
- NLI criticism → Critic protocol: implements protocol (evidence: `src/isnad/critics/__init__.py`)
- Content critics → Numeric recomputation: combines with (evidence: `src/isnad/critics/__init__.py`)
- Claim and chain → Matn rules: can use rules (evidence: `src/isnad/__init__.py`)
- Weakest-link grading → Action decision: supplies chain grade (evidence: `README.md`)
- Content critics → Action decision: supplies content verdict (evidence: `README.md`)
- Action decision → Claim API: routes action (evidence: `src/isnad/api/endpoints/claims.py`)
- API application → Claim API: mounts routes (evidence: `src/isnad/api/app.py`)
- Claim API → SQLAlchemy persistence: persists claims (evidence: `src/isnad/api/app.py`)
- SQLAlchemy persistence → Claim data models: uses models (evidence: `src/isnad/storage/sqlalchemy.py`)
- Claim API → Audit records: creates audit evidence (evidence: `src/isnad/api/endpoints/claims.py`)
- CLI → Audit records: exports and verifies (evidence: `src/isnad/cli/main.py`)
- Audit records → Record signatures: supports signatures (evidence: `src/isnad/cli/main.py`)
- JS record verifier → Audit records: verifies records (evidence: `README.md`)
- Framework integrations → Claim and chain: captures traces (evidence: `README.md`)
- OTel ingestion → Weakest-link grading: grades ingested links (evidence: `src/isnad/integrations/otel/ingest.py`)
- MCP interface → Pipeline operator: exposes tools
