# raywincruz07-collab/context-matters-diversity-aware-rag architecture

> Architecture diagram of the GitHub repository raywincruz07-collab/context-matters-diversity-aware-rag, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/raywincruz07-collab/context-matters-diversity-aware-rag
- Repository: https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag

## Overview

This is a reproducibility package for research evaluating whether diverse retrieval contexts improve RAG answers across PubMedQA, HotpotQA, and ASQA. Its principal workflow retrieves Top-20 candidates, selects a fixed Top-5 context using a diversification condition, generates an answer, then evaluates it in Phase 4 and analyzes cross-metric relationships in Phase 5. The graph also includes provenance/artifact and metric-contract layers. Several experimental subsystems are represented at their documented directory level because their implementation was not sampled; those links rely on README statements rather than inspected runtime calls.

Main entry points: [`sprint2_diversification/src/diversification`](https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/tree/main/sprint2_diversification/src/diversification) (Diversification), [`sprint1_baseline/asqa/src/retrieval_artifacts/producer.py`](https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/blob/main/sprint1_baseline/asqa/src/retrieval_artifacts/producer.py) (Candidate artifacts), [`sprint3_evaluation/src/evaluation`](https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/tree/main/sprint3_evaluation/src/evaluation) (Phase 4 metrics), [`sprint1_baseline/hotpotqa/src/generation/selected_context.py`](https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/blob/main/sprint1_baseline/hotpotqa/src/generation/selected_context.py) (Top-5 context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_retrieval["Retrieval and provenance"]
  node_retrievers["Retriever families"]
  node_candidate_artifacts["Candidate artifacts<br/>[producer.py]"]
  node_artifact_contracts["Artifact contracts<br/>[contracts.py]"]
  node_corpus_runtime["Corpus manifests<br/>[runtime_corpus.py]"]
  node_retriever_configs["Retriever configs"]
end

subgraph group_selection["Context selection"]
  node_diversification["Diversification"]
  node_mmr["MMR selection<br/>[mmr.py]"]
  node_dpp["DPP selection<br/>[dpp.py]"]
  node_cluster_selection["Cluster selection<br/>[clustering.py]"]
  node_selected_context["Top-5 context"]
end

subgraph group_generation["Answer generation"]
  node_generator["LLM generation"]
  node_generation_runtime["Generation runtime<br/>[maki.py]"]
  node_generation_io["Artifact I/O<br/>[_io.py]"]
  node_answer["Generated answer"]
end

subgraph group_evaluation["Evaluation and analysis"]
  node_phase4["Phase 4 metrics"]
  node_metric_registry["Metric registry<br/>[metric_registry.py]"]
  node_metric_contracts["Metric contracts<br/>[contracts.py]"]
  node_phase5["Phase 5 analysis"]
end

subgraph group_governance["Experiment governance"]
  node_run_registry[("Run provenance<br/>[run_registry.py]")]
end

node_question(("Question"))

node_question -->|"queries"| node_retrievers
node_retrievers -->|"produce candidates"| node_candidate_artifacts
node_candidate_artifacts -->|"candidate pool"| node_diversification
node_diversification -->|"selects Top-5"| node_selected_context
node_diversification -.->|"dispatches"| node_mmr
node_diversification -.->|"dispatches"| node_dpp
node_diversification -.->|"dispatches"| node_cluster_selection
node_selected_context -->|"supplies context"| node_generator
node_generator -->|"generates"| node_answer
node_generation_runtime -->|"uses"| node_generation_io
node_generator -.->|"runs through"| node_generation_runtime
node_answer -->|"evaluated in"| node_phase4
node_selected_context -->|"evaluates evidence"| node_phase4
node_phase4 -->|"cross-metric analysis"| node_phase5
node_phase4 -->|"checks applicability"| node_metric_registry
node_phase4 -->|"validates results"| node_metric_contracts
node_candidate_artifacts -->|"validates artifacts"| node_artifact_contracts
node_corpus_runtime -->|"uses producers"| node_candidate_artifacts
node_candidate_artifacts -->|"records provenance"| node_retriever_configs

click node_retrievers "https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/tree/main/sprint1_baseline"
click node_candidate_artifacts "https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/blob/main/sprint1_baseline/asqa/src/retrieval_artifacts/producer.py"
click node_artifact_contracts "https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/blob/main/sprint1_baseline/asqa/src/retrieval_artifacts/contracts.py"
click node_corpus_runtime "https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/blob/main/sprint1_baseline/asqa/src/retrieval_artifacts/runtime_corpus.py"
click node_retriever_configs "https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/tree/main/sprint1_baseline/asqa/src/retrievers"
click node_diversification "https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/tree/main/sprint2_diversification/src/diversification"
click node_mmr "https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/blob/main/sprint2_diversification/src/diversification/mmr.py"
click node_dpp "https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/blob/main/sprint2_diversification/src/diversification/dpp.py"
click node_cluster_selection "https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/blob/main/sprint2_diversification/src/diversification/clustering.py"
click node_selected_context "https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/blob/main/sprint1_baseline/hotpotqa/src/generation/selected_context.py"
click node_generator "https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/tree/main/sprint2_diversification/src/generation"
click node_generation_runtime "https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/blob/main/sprint1_baseline/asqa/src/generation/maki.py"
click node_generation_io "https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/blob/main/sprint1_baseline/asqa/src/generation/_io.py"
click node_phase4 "https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/tree/main/sprint3_evaluation/src/evaluation"
click node_metric_registry "https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/blob/main/sprint3_evaluation/src/evaluation/metric_registry.py"
click node_metric_contracts "https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/blob/main/sprint3_evaluation/src/evaluation/contracts.py"
click node_phase5 "https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/tree/main/sprint3_evaluation/src/evaluation"
click node_run_registry "https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/blob/main/sprint1_baseline/asqa/src/run_registry.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_retrievers,node_candidate_artifacts,node_artifact_contracts,node_corpus_runtime,node_retriever_configs toneBlue
class node_diversification,node_mmr,node_dpp,node_cluster_selection,node_selected_context toneAmber
class node_generator,node_generation_runtime,node_generation_io,node_answer toneMint
class node_phase4,node_metric_registry,node_metric_contracts,node_phase5 toneRose
class node_run_registry,node_question toneIndigo
```

## Components

### Retrieval and provenance

- [Retriever families](https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/tree/main/sprint1_baseline): `sprint1_baseline`
- [Candidate artifacts](https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/blob/main/sprint1_baseline/asqa/src/retrieval_artifacts/producer.py): `sprint1_baseline/asqa/src/retrieval_artifacts/producer.py`
- [Artifact contracts](https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/blob/main/sprint1_baseline/asqa/src/retrieval_artifacts/contracts.py): `sprint1_baseline/asqa/src/retrieval_artifacts/contracts.py`
- [Corpus manifests](https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/blob/main/sprint1_baseline/asqa/src/retrieval_artifacts/runtime_corpus.py): `sprint1_baseline/asqa/src/retrieval_artifacts/runtime_corpus.py`
- [Retriever configs](https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/tree/main/sprint1_baseline/asqa/src/retrievers): `sprint1_baseline/asqa/src/retrievers`

### Context selection

- [Diversification](https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/tree/main/sprint2_diversification/src/diversification): `sprint2_diversification/src/diversification`
- [MMR selection](https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/blob/main/sprint2_diversification/src/diversification/mmr.py): `sprint2_diversification/src/diversification/mmr.py`
- [DPP selection](https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/blob/main/sprint2_diversification/src/diversification/dpp.py): `sprint2_diversification/src/diversification/dpp.py`
- [Cluster selection](https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/blob/main/sprint2_diversification/src/diversification/clustering.py): `sprint2_diversification/src/diversification/clustering.py`
- [Top-5 context](https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/blob/main/sprint1_baseline/hotpotqa/src/generation/selected_context.py): `sprint1_baseline/hotpotqa/src/generation/selected_context.py`

### Answer generation

- [LLM generation](https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/tree/main/sprint2_diversification/src/generation): `sprint2_diversification/src/generation`
- [Generation runtime](https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/blob/main/sprint1_baseline/asqa/src/generation/maki.py): `sprint1_baseline/asqa/src/generation/maki.py`
- [Artifact I/O](https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/blob/main/sprint1_baseline/asqa/src/generation/_io.py): `sprint1_baseline/asqa/src/generation/_io.py`
- **Generated answer**

### Evaluation and analysis

- [Phase 4 metrics](https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/tree/main/sprint3_evaluation/src/evaluation): `sprint3_evaluation/src/evaluation`
- [Metric registry](https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/blob/main/sprint3_evaluation/src/evaluation/metric_registry.py): `sprint3_evaluation/src/evaluation/metric_registry.py`
- [Metric contracts](https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/blob/main/sprint3_evaluation/src/evaluation/contracts.py): `sprint3_evaluation/src/evaluation/contracts.py`
- [Phase 5 analysis](https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/tree/main/sprint3_evaluation/src/evaluation): `sprint3_evaluation/src/evaluation`

### Experiment governance

- [Run provenance](https://github.com/raywincruz07-collab/context-matters-diversity-aware-rag/blob/main/sprint1_baseline/asqa/src/run_registry.py): `sprint1_baseline/asqa/src/run_registry.py`

### Other components

- **Question**

## Connections

- Question → Retriever families: queries (evidence: `README.md`)
- Retriever families → Candidate artifacts: produce candidates (evidence: `README.md`)
- Candidate artifacts → Diversification: candidate pool (evidence: `README.md`)
- Diversification → Top-5 context: selects Top-5 (evidence: `README.md`)
- Diversification → MMR selection: dispatches
- Diversification → DPP selection: dispatches (evidence: `sprint2_diversification/src/diversification/dpp.py`)
- Diversification → Cluster selection: dispatches
- Top-5 context → LLM generation: supplies context (evidence: `README.md`)
- LLM generation → Generated answer: generates (evidence: `README.md`)
- Generation runtime → Artifact I/O: uses (evidence: `sprint1_baseline/asqa/src/generation/maki.py`)
- LLM generation → Generation runtime: runs through (evidence: `sprint2_diversification/src/generation/cli_support.py`)
- Generated answer → Phase 4 metrics: evaluated in (evidence: `README.md`)
- Top-5 context → Phase 4 metrics: evaluates evidence (evidence: `README.md`)
- Phase 4 metrics → Phase 5 analysis: cross-metric analysis (evidence: `README.md`)
- Phase 4 metrics → Metric registry: checks applicability (evidence: `sprint3_evaluation/src/evaluation/query_evaluator.py`)
- Phase 4 metrics → Metric contracts: validates results (evidence: `sprint3_evaluation/src/evaluation/query_evaluator.py`)
- Candidate artifacts → Artifact contracts: validates artifacts (evidence: `sprint1_baseline/asqa/src/retrieval_artifacts/producer.py`)
- Corpus manifests → Candidate artifacts: uses producers (evidence: `sprint1_baseline/asqa/src/retrieval_artifacts/runtime_corpus.py`)
- Candidate artifacts → Retriever configs: records provenance (evidence: `sprint1_baseline/asqa/src/retrieval_artifacts/producer.py`)
