# alebbboy/trustless-rag-di architecture

> Architecture diagram of the GitHub repository alebbboy/trustless-rag-di, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alebbboy/trustless-rag-di
- Repository: https://github.com/alebbboy/trustless-rag-di

## Overview

Trustless RAG-DI audits whether an owner’s canary document was ingested and influenced a third-party RAG answer, using black-box queries and commitments intended to prevent post-hoc selection. The main path runs from canary creation and document indexing, through RAG retrieval and generation, to detection and ranking; a separate chain path commits candidate sets and reveals the selected canary. README documents additional experiments and contract capabilities. Some subsystem links are based on those descriptions, since their source was not sampled.

Main entry points: [`rag_di/bridge.py`](https://github.com/alebbboy/trustless-rag-di/blob/master/rag_di/bridge.py) (Web3 bridge), [`rag_di/pipeline.py`](https://github.com/alebbboy/trustless-rag-di/blob/master/rag_di/pipeline.py) (RAG pipeline), [`rag_di/ranking_test.py`](https://github.com/alebbboy/trustless-rag-di/blob/master/rag_di/ranking_test.py) (Ranking test), [`scripts/build_index.py`](https://github.com/alebbboy/trustless-rag-di/blob/master/scripts/build_index.py) (Index builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_rag["RAG system"]
  node_indexer["Index builder<br/>[build_index.py]"]
  node_faiss[("FAISS index<br/>[pipeline.py]")]
  node_pipeline["RAG pipeline<br/>[pipeline.py]"]
  node_embedmodel["Embedding model"]
  node_genmodel["Generation model"]
end

subgraph group_audit["Canary audit"]
  node_semantic["Semantic canary<br/>[semantic_canary.py]"]
  node_unicode["Unicode canary<br/>[unicode_canary.py]"]
  node_ranking["Ranking test<br/>[ranking_test.py]"]
  node_detector["Canary detection"]
end

subgraph group_commit["Commitment protocol"]
  node_merkle["Merkle proofs<br/>[merkle.py]"]
  node_vrf["Beacon randomness<br/>[vrf.py]"]
end

subgraph group_chain["Chain backends"]
  node_mockchain[("Mock chain<br/>[mockchain.py]")]
  node_bridge["Web3 bridge<br/>[bridge.py]"]
  node_registry[("Canary registry<br/>[CanaryRegistry.sol]")]
  node_commitregistry[("Commit-reveal registry")]
  node_commitment[("Time-bound commitment<br/>[Commitment.sol]")]
  node_beacon[("Random beacon<br/>[RandomBeacon.sol]")]
  node_beaconbound[("Beacon-bound commitment")]
end

subgraph group_experiments["Experiments"]
  node_experiments["Audit experiments"]
end

node_owner(("Document owner"))
node_auditor(("Auditor"))
node_corpus["Source documents"]

node_owner -->|"creates candidates"| node_semantic
node_owner -->|"creates candidates"| node_unicode
node_semantic -->|"embeds fact"| node_indexer
node_unicode -->|"embeds reply"| node_indexer
node_corpus -->|"supplies documents"| node_indexer
node_indexer -->|"writes index"| node_faiss
node_auditor -->|"asks question"| node_pipeline
node_pipeline -->|"encodes query"| node_embedmodel
node_pipeline -->|"searches index"| node_faiss
node_pipeline -->|"generates answer"| node_genmodel
node_auditor -->|"starts audit"| node_ranking
node_ranking -->|"queries black box"| node_pipeline
node_ranking -->|"scores responses"| node_detector
node_detector -->|"checks semantic cue"| node_semantic
node_detector -->|"checks invisible reply"| node_unicode
node_owner -->|"hashes candidates"| node_merkle
node_merkle -->|"commits root"| node_mockchain
node_owner -->|"commits seed"| node_vrf
node_vrf -->|"selects candidate"| node_beaconbound
node_bridge -.->|"falls back to"| node_mockchain
node_bridge -->|"calls"| node_registry
node_bridge -->|"calls"| node_commitregistry
node_bridge -->|"assigns and reveals"| node_commitment
node_bridge -->|"deploys and calls"| node_beacon
node_bridge -->|"deploys and calls"| node_beaconbound
node_beaconbound -->|"reads randomness"| node_beacon
node_experiments -->|"evaluates"| node_ranking
node_experiments -->|"exercises protocol"| node_bridge

click node_indexer "https://github.com/alebbboy/trustless-rag-di/blob/master/scripts/build_index.py"
click node_faiss "https://github.com/alebbboy/trustless-rag-di/blob/master/rag_di/pipeline.py"
click node_pipeline "https://github.com/alebbboy/trustless-rag-di/blob/master/rag_di/pipeline.py"
click node_semantic "https://github.com/alebbboy/trustless-rag-di/blob/master/rag_di/canaries/semantic_canary.py"
click node_unicode "https://github.com/alebbboy/trustless-rag-di/blob/master/rag_di/canaries/unicode_canary.py"
click node_ranking "https://github.com/alebbboy/trustless-rag-di/blob/master/rag_di/ranking_test.py"
click node_detector "https://github.com/alebbboy/trustless-rag-di/tree/master/rag_di/canaries"
click node_merkle "https://github.com/alebbboy/trustless-rag-di/blob/master/rag_di/merkle.py"
click node_vrf "https://github.com/alebbboy/trustless-rag-di/blob/master/rag_di/vrf.py"
click node_mockchain "https://github.com/alebbboy/trustless-rag-di/blob/master/rag_di/mockchain.py"
click node_bridge "https://github.com/alebbboy/trustless-rag-di/blob/master/rag_di/bridge.py"
click node_registry "https://github.com/alebbboy/trustless-rag-di/blob/master/contracts/src/CanaryRegistry.sol"
click node_commitregistry "https://github.com/alebbboy/trustless-rag-di/blob/master/contracts/src/CommitRevealCanaryRegistry.sol"
click node_commitment "https://github.com/alebbboy/trustless-rag-di/blob/master/contracts/src/Commitment.sol"
click node_beacon "https://github.com/alebbboy/trustless-rag-di/blob/master/contracts/src/RandomBeacon.sol"
click node_beaconbound "https://github.com/alebbboy/trustless-rag-di/blob/master/contracts/src/BeaconBoundCommitment.sol"
click node_experiments "https://github.com/alebbboy/trustless-rag-di/tree/master/scripts"

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_indexer,node_faiss,node_pipeline,node_embedmodel,node_genmodel toneBlue
class node_semantic,node_unicode,node_ranking,node_detector toneAmber
class node_merkle,node_vrf toneMint
class node_mockchain,node_bridge,node_registry,node_commitregistry,node_commitment,node_beacon,node_beaconbound toneRose
class node_experiments,node_owner,node_auditor,node_corpus toneIndigo
```

## Components

### RAG system

- [Index builder](https://github.com/alebbboy/trustless-rag-di/blob/master/scripts/build_index.py): `scripts/build_index.py`
- [FAISS index](https://github.com/alebbboy/trustless-rag-di/blob/master/rag_di/pipeline.py): `rag_di/pipeline.py`
- [RAG pipeline](https://github.com/alebbboy/trustless-rag-di/blob/master/rag_di/pipeline.py): `rag_di/pipeline.py`
- **Embedding model**
- **Generation model**

### Canary audit

- [Semantic canary](https://github.com/alebbboy/trustless-rag-di/blob/master/rag_di/canaries/semantic_canary.py): `rag_di/canaries/semantic_canary.py`
- [Unicode canary](https://github.com/alebbboy/trustless-rag-di/blob/master/rag_di/canaries/unicode_canary.py): `rag_di/canaries/unicode_canary.py`
- [Ranking test](https://github.com/alebbboy/trustless-rag-di/blob/master/rag_di/ranking_test.py): `rag_di/ranking_test.py`
- [Canary detection](https://github.com/alebbboy/trustless-rag-di/tree/master/rag_di/canaries): `rag_di/canaries`

### Commitment protocol

- [Merkle proofs](https://github.com/alebbboy/trustless-rag-di/blob/master/rag_di/merkle.py): `rag_di/merkle.py`
- [Beacon randomness](https://github.com/alebbboy/trustless-rag-di/blob/master/rag_di/vrf.py): `rag_di/vrf.py`

### Chain backends

- [Mock chain](https://github.com/alebbboy/trustless-rag-di/blob/master/rag_di/mockchain.py): `rag_di/mockchain.py`
- [Web3 bridge](https://github.com/alebbboy/trustless-rag-di/blob/master/rag_di/bridge.py): `rag_di/bridge.py`
- [Canary registry](https://github.com/alebbboy/trustless-rag-di/blob/master/contracts/src/CanaryRegistry.sol): `contracts/src/CanaryRegistry.sol`
- [Commit-reveal registry](https://github.com/alebbboy/trustless-rag-di/blob/master/contracts/src/CommitRevealCanaryRegistry.sol): `contracts/src/CommitRevealCanaryRegistry.sol`
- [Time-bound commitment](https://github.com/alebbboy/trustless-rag-di/blob/master/contracts/src/Commitment.sol): `contracts/src/Commitment.sol`
- [Random beacon](https://github.com/alebbboy/trustless-rag-di/blob/master/contracts/src/RandomBeacon.sol): `contracts/src/RandomBeacon.sol`
- [Beacon-bound commitment](https://github.com/alebbboy/trustless-rag-di/blob/master/contracts/src/BeaconBoundCommitment.sol): `contracts/src/BeaconBoundCommitment.sol`

### Experiments

- [Audit experiments](https://github.com/alebbboy/trustless-rag-di/tree/master/scripts): `scripts`

### Other components

- **Document owner**
- **Auditor**
- **Source documents**

## Connections

- Document owner → Semantic canary: creates candidates
- Document owner → Unicode canary: creates candidates
- Semantic canary → Index builder: embeds fact
- Unicode canary → Index builder: embeds reply
- Source documents → Index builder: supplies documents
- Index builder → FAISS index: writes index
- Auditor → RAG pipeline: asks question
- RAG pipeline → Embedding model: encodes query
- RAG pipeline → FAISS index: searches index
- RAG pipeline → Generation model: generates answer
- Auditor → Ranking test: starts audit
- Ranking test → RAG pipeline: queries black box
- Ranking test → Canary detection: scores responses
- Canary detection → Semantic canary: checks semantic cue
- Canary detection → Unicode canary: checks invisible reply
- Document owner → Merkle proofs: hashes candidates
- Merkle proofs → Mock chain: commits root
- Document owner → Beacon randomness: commits seed
- Beacon randomness → Beacon-bound commitment: selects candidate
- Web3 bridge → Mock chain: falls back to
- Web3 bridge → Canary registry: calls
- Web3 bridge → Commit-reveal registry: calls
- Web3 bridge → Time-bound commitment: assigns and reveals
- Web3 bridge → Random beacon: deploys and calls
- Web3 bridge → Beacon-bound commitment: deploys and calls
- Beacon-bound commitment → Random beacon: reads randomness
- Audit experiments → Ranking test: evaluates
- Audit experiments → Web3 bridge: exercises protocol