# cdzchen/rag-c09 architecture

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

- Interactive diagram: https://gitdiagram.com/cdzchen/rag-c09
- Repository: https://github.com/cdzchen/rag-c09

## Overview

This repository is a research pipeline for detecting and evaluating hallucinations in retrieval-augmented question answering (RAG). Its intended workflow loads and normalizes QA datasets, constructs normal and three challenge subsets (retrieval failure, evidence conflict, outdated answers), runs retrieval and answer generation, extracts evidence-consistency features, trains a hallucination detector, and evaluates results by challenge type and statistical tests. Shared schema, IO, seeding, and artifact validation support reproducible handoffs. The README says most modules are skeletons; several internal connections below reflect documented capabilities and run order, not inspected implementations.

Main entry points: [`src/generation/pipeline.py`](https://github.com/cdzchen/rag-c09/blob/main/src/generation/pipeline.py) (RAG pipeline), [`src/features/build_features.py`](https://github.com/cdzchen/rag-c09/blob/main/src/features/build_features.py) (Feature builder), [`src/evaluation/cli.py`](https://github.com/cdzchen/rag-c09/blob/main/src/evaluation/cli.py) (Evaluation workflow), [`src/datasets/reader.py`](https://github.com/cdzchen/rag-c09/blob/main/src/datasets/reader.py) (Dataset reader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Data preparation"]
  node_reader["Dataset reader<br/>[reader.py]"]
  node_challenge["Challenge builder"]
  node_split["Dataset split<br/>[split.py]"]
end

subgraph group_rag["RAG pipeline"]
  node_index["Passage index<br/>[index.py]"]
  node_bm25["BM25 retrieval<br/>[bm25.py]"]
  node_dense["Dense retrieval<br/>[dense.py]"]
  node_pipeline["RAG pipeline<br/>[pipeline.py]"]
  node_model["Generation model<br/>[model.py]"]
  node_decode["Answer decoding<br/>[decode.py]"]
  node_baseline["Confidence baseline"]
  node_demo["Evidence demo<br/>[app.py]"]
end

subgraph group_features["Feature extraction"]
  node_build_features["Feature builder<br/>[build_features.py]"]
  node_entailment["Entailment features<br/>[entailment.py]"]
  node_overlap["Overlap features<br/>[overlap.py]"]
  node_consistency["Consistency features<br/>[consistency.py]"]
end

subgraph group_detection["Detection"]
  node_train["Detector training<br/>[train.py]"]
  node_predict["Hallucination prediction<br/>[predict.py]"]
  node_calibrate["Probability calibration<br/>[calibrate.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_eval["Evaluation workflow<br/>[cli.py]"]
  node_metrics["Metrics<br/>[metrics.py]"]
  node_grouped["Grouped analysis<br/>[grouped.py]"]
  node_significance["Significance tests<br/>[significance.py]"]
end

node_user(("Researcher"))
node_external_data["Hugging Face datasets"]
node_common_io["Artifact IO<br/>[io.py]"]
node_schema["Data contracts<br/>[schema.py]"]
node_validate["Artifact validation<br/>[validate.py]"]

node_user -->|"selects dataset"| node_reader
node_reader -.->|"loads online"| node_external_data
node_reader -->|"normalized samples"| node_challenge
node_challenge -->|"challenge samples"| node_split
node_split -->|"corpus samples"| node_index
node_index -->|"builds corpus"| node_bm25
node_index -.->|"builds corpus"| node_dense
node_pipeline -->|"retrieves passages"| node_bm25
node_pipeline -.->|"retrieves passages"| node_dense
node_pipeline -->|"requests generation"| node_model
node_pipeline -->|"decodes answer"| node_decode
node_baseline -->|"scores confidence"| node_model
node_user -->|"requests answer"| node_demo
node_demo -->|"reuses pipeline"| node_pipeline
node_pipeline -->|"prediction records"| node_build_features
node_build_features -->|"computes features"| node_entailment
node_build_features -->|"computes features"| node_overlap
node_build_features -->|"computes features"| node_consistency
node_build_features -->|"feature records"| node_train
node_train -->|"trained detector"| node_predict
node_train -->|"calibrates scores"| node_calibrate
node_predict -->|"prediction records"| node_eval
node_eval -->|"computes metrics"| node_metrics
node_eval -->|"groups results"| node_grouped
node_eval -->|"tests differences"| node_significance
node_common_io -->|"reads artifacts"| node_validate
node_common_io -->|"uses metadata key"| node_schema
node_validate -->|"checks fields"| node_schema

click node_reader "https://github.com/cdzchen/rag-c09/blob/main/src/datasets/reader.py"
click node_challenge "https://github.com/cdzchen/rag-c09/blob/main/src/datasets/challenge_builder.py"
click node_split "https://github.com/cdzchen/rag-c09/blob/main/src/datasets/split.py"
click node_index "https://github.com/cdzchen/rag-c09/blob/main/src/retrieval/index.py"
click node_bm25 "https://github.com/cdzchen/rag-c09/blob/main/src/retrieval/bm25.py"
click node_dense "https://github.com/cdzchen/rag-c09/blob/main/src/retrieval/dense.py"
click node_pipeline "https://github.com/cdzchen/rag-c09/blob/main/src/generation/pipeline.py"
click node_model "https://github.com/cdzchen/rag-c09/blob/main/src/generation/model.py"
click node_decode "https://github.com/cdzchen/rag-c09/blob/main/src/generation/decode.py"
click node_baseline "https://github.com/cdzchen/rag-c09/blob/main/src/generation/baseline_confidence.py"
click node_demo "https://github.com/cdzchen/rag-c09/blob/main/src/demo/app.py"
click node_build_features "https://github.com/cdzchen/rag-c09/blob/main/src/features/build_features.py"
click node_entailment "https://github.com/cdzchen/rag-c09/blob/main/src/features/entailment.py"
click node_overlap "https://github.com/cdzchen/rag-c09/blob/main/src/features/overlap.py"
click node_consistency "https://github.com/cdzchen/rag-c09/blob/main/src/features/consistency.py"
click node_train "https://github.com/cdzchen/rag-c09/blob/main/src/detection/train.py"
click node_predict "https://github.com/cdzchen/rag-c09/blob/main/src/detection/predict.py"
click node_calibrate "https://github.com/cdzchen/rag-c09/blob/main/src/detection/calibrate.py"
click node_eval "https://github.com/cdzchen/rag-c09/blob/main/src/evaluation/cli.py"
click node_metrics "https://github.com/cdzchen/rag-c09/blob/main/src/evaluation/metrics.py"
click node_grouped "https://github.com/cdzchen/rag-c09/blob/main/src/evaluation/grouped.py"
click node_significance "https://github.com/cdzchen/rag-c09/blob/main/src/evaluation/significance.py"
click node_common_io "https://github.com/cdzchen/rag-c09/blob/main/src/common/io.py"
click node_schema "https://github.com/cdzchen/rag-c09/blob/main/src/common/schema.py"
click node_validate "https://github.com/cdzchen/rag-c09/blob/main/src/common/validate.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_reader,node_challenge,node_split toneBlue
class node_index,node_bm25,node_dense,node_pipeline,node_model,node_decode,node_baseline,node_demo toneAmber
class node_build_features,node_entailment,node_overlap,node_consistency toneMint
class node_train,node_predict,node_calibrate toneRose
class node_eval,node_metrics,node_grouped,node_significance,node_user,node_external_data toneIndigo
class node_common_io,node_schema,node_validate toneTeal
```

## Components

### Data preparation

- [Dataset reader](https://github.com/cdzchen/rag-c09/blob/main/src/datasets/reader.py): `src/datasets/reader.py`
- [Challenge builder](https://github.com/cdzchen/rag-c09/blob/main/src/datasets/challenge_builder.py): `src/datasets/challenge_builder.py`
- [Dataset split](https://github.com/cdzchen/rag-c09/blob/main/src/datasets/split.py): `src/datasets/split.py`

### RAG pipeline

- [Passage index](https://github.com/cdzchen/rag-c09/blob/main/src/retrieval/index.py): `src/retrieval/index.py`
- [BM25 retrieval](https://github.com/cdzchen/rag-c09/blob/main/src/retrieval/bm25.py): `src/retrieval/bm25.py`
- [Dense retrieval](https://github.com/cdzchen/rag-c09/blob/main/src/retrieval/dense.py): `src/retrieval/dense.py`
- [RAG pipeline](https://github.com/cdzchen/rag-c09/blob/main/src/generation/pipeline.py): `src/generation/pipeline.py`
- [Generation model](https://github.com/cdzchen/rag-c09/blob/main/src/generation/model.py): `src/generation/model.py`
- [Answer decoding](https://github.com/cdzchen/rag-c09/blob/main/src/generation/decode.py): `src/generation/decode.py`
- [Confidence baseline](https://github.com/cdzchen/rag-c09/blob/main/src/generation/baseline_confidence.py): `src/generation/baseline_confidence.py`
- [Evidence demo](https://github.com/cdzchen/rag-c09/blob/main/src/demo/app.py): `src/demo/app.py`

### Feature extraction

- [Feature builder](https://github.com/cdzchen/rag-c09/blob/main/src/features/build_features.py): `src/features/build_features.py`
- [Entailment features](https://github.com/cdzchen/rag-c09/blob/main/src/features/entailment.py): `src/features/entailment.py`
- [Overlap features](https://github.com/cdzchen/rag-c09/blob/main/src/features/overlap.py): `src/features/overlap.py`
- [Consistency features](https://github.com/cdzchen/rag-c09/blob/main/src/features/consistency.py): `src/features/consistency.py`

### Detection

- [Detector training](https://github.com/cdzchen/rag-c09/blob/main/src/detection/train.py): `src/detection/train.py`
- [Hallucination prediction](https://github.com/cdzchen/rag-c09/blob/main/src/detection/predict.py): `src/detection/predict.py`
- [Probability calibration](https://github.com/cdzchen/rag-c09/blob/main/src/detection/calibrate.py): `src/detection/calibrate.py`

### Evaluation

- [Evaluation workflow](https://github.com/cdzchen/rag-c09/blob/main/src/evaluation/cli.py): `src/evaluation/cli.py`
- [Metrics](https://github.com/cdzchen/rag-c09/blob/main/src/evaluation/metrics.py): `src/evaluation/metrics.py`
- [Grouped analysis](https://github.com/cdzchen/rag-c09/blob/main/src/evaluation/grouped.py): `src/evaluation/grouped.py`
- [Significance tests](https://github.com/cdzchen/rag-c09/blob/main/src/evaluation/significance.py): `src/evaluation/significance.py`

### Other components

- **Researcher**
- **Hugging Face datasets**
- [Artifact IO](https://github.com/cdzchen/rag-c09/blob/main/src/common/io.py): `src/common/io.py`
- [Data contracts](https://github.com/cdzchen/rag-c09/blob/main/src/common/schema.py): `src/common/schema.py`
- [Artifact validation](https://github.com/cdzchen/rag-c09/blob/main/src/common/validate.py): `src/common/validate.py`

## Connections

- Researcher → Dataset reader: selects dataset
- Dataset reader → Hugging Face datasets: loads online
- Dataset reader → Challenge builder: normalized samples
- Challenge builder → Dataset split: challenge samples
- Dataset split → Passage index: corpus samples
- Passage index → BM25 retrieval: builds corpus
- Passage index → Dense retrieval: builds corpus
- RAG pipeline → BM25 retrieval: retrieves passages
- RAG pipeline → Dense retrieval: retrieves passages
- RAG pipeline → Generation model: requests generation
- RAG pipeline → Answer decoding: decodes answer
- Confidence baseline → Generation model: scores confidence
- Researcher → Evidence demo: requests answer
- Evidence demo → RAG pipeline: reuses pipeline
- RAG pipeline → Feature builder: prediction records
- Feature builder → Entailment features: computes features
- Feature builder → Overlap features: computes features
- Feature builder → Consistency features: computes features
- Feature builder → Detector training: feature records
- Detector training → Hallucination prediction: trained detector
- Detector training → Probability calibration: calibrates scores
- Hallucination prediction → Evaluation workflow: prediction records
- Evaluation workflow → Metrics: computes metrics
- Evaluation workflow → Grouped analysis: groups results
- Evaluation workflow → Significance tests: tests differences
- Artifact IO → Artifact validation: reads artifacts
- Artifact IO → Data contracts: uses metadata key
- Artifact validation → Data contracts: checks fields