# gargi-09/museum-qa-agent architecture

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

- Interactive diagram: https://gitdiagram.com/gargi-09/museum-qa-agent
- Repository: https://github.com/gargi-09/museum-qa-agent
- Video tour (about a minute): https://gitdiagram.com/gargi-09/museum-qa-agent/video

## Overview

Museum Records QA ingests museum-catalogue data, then answers natural-language questions with hybrid local retrieval and one bounded model call. The query workflow enriches retrieved records with curator corrections, duplicate/entity grouping, and contradiction checks before deterministic verification and confidence scoring; results retain cited, used, and unused records. The README documents persistent normalized data, embedding-cache invalidation, and correction overrides. Edges reflect the excerpts and README; unsampled implementation details are not inferred beyond documented capabilities.

Main entry points: [`src/reasoning.py`](https://github.com/gargi-09/museum-qa-agent/blob/main/src/reasoning.py) (Answer orchestration), [`src/main.py`](https://github.com/gargi-09/museum-qa-agent/blob/main/src/main.py) (CLI commands), [`src/retrieval.py`](https://github.com/gargi-09/museum-qa-agent/blob/main/src/retrieval.py) (Hybrid retrieval), [`src/ingest.py`](https://github.com/gargi-09/museum-qa-agent/blob/main/src/ingest.py) (Record normalization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Corpus preparation"]
  node_normalizer["Record normalization<br/>[ingest.py]"]
  node_normalized[("Normalized corpus")]
end

subgraph group_query["Question answering"]
  node_cli["CLI commands<br/>[main.py]"]
  node_retriever["Hybrid retrieval<br/>[retrieval.py]"]
  node_embedding_cache[("Embedding cache")]
  node_reasoner["Answer orchestration<br/>[reasoning.py]"]
  node_answer["Verified answer<br/>[reasoning.py]"]
end

subgraph group_quality["Record quality"]
  node_entity_resolution["Entity resolution"]
  node_contradiction["Prose contradiction checks<br/>[contradiction.py]"]
end

subgraph group_state["State and services"]
  node_corrections["Correction persistence<br/>[memory.py]"]
  node_correction_store[("Correction records")]
  node_api_client["Model API client<br/>[api_client.py]"]
end

node_curator(("Curator"))
node_cli_user(("Questioner"))
node_model_endpoint["Model endpoint"]

node_curator -->|"adds corrections"| node_cli
node_cli_user -->|"asks question"| node_cli
node_cli -->|"runs ingest"| node_normalizer
node_normalizer -->|"fallback extraction"| node_api_client
node_normalizer -->|"writes records"| node_normalized
node_cli -->|"loads for queries"| node_retriever
node_normalized -->|"loads corpus"| node_retriever
node_cli -->|"dispatches question"| node_reasoner
node_retriever -->|"caches embeddings"| node_embedding_cache
node_reasoner -->|"ranks candidates"| node_retriever
node_reasoner -->|"applies overrides"| node_corrections
node_corrections -->|"reads and writes"| node_correction_store
node_reasoner -->|"groups records"| node_entity_resolution
node_reasoner -->|"checks descriptions"| node_contradiction
node_reasoner -->|"requests generation"| node_api_client
node_api_client -->|"sends model request"| node_model_endpoint
node_reasoner -->|"verifies and scores"| node_answer
node_cli -->|"prints result"| node_answer

click node_cli "https://github.com/gargi-09/museum-qa-agent/blob/main/src/main.py"
click node_normalizer "https://github.com/gargi-09/museum-qa-agent/blob/main/src/ingest.py"
click node_retriever "https://github.com/gargi-09/museum-qa-agent/blob/main/src/retrieval.py"
click node_reasoner "https://github.com/gargi-09/museum-qa-agent/blob/main/src/reasoning.py"
click node_entity_resolution "https://github.com/gargi-09/museum-qa-agent/blob/main/src/entity_resolution.py"
click node_contradiction "https://github.com/gargi-09/museum-qa-agent/blob/main/src/contradiction.py"
click node_corrections "https://github.com/gargi-09/museum-qa-agent/blob/main/src/memory.py"
click node_api_client "https://github.com/gargi-09/museum-qa-agent/blob/main/src/api_client.py"
click node_answer "https://github.com/gargi-09/museum-qa-agent/blob/main/src/reasoning.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_normalizer,node_normalized toneBlue
class node_cli,node_retriever,node_embedding_cache,node_reasoner,node_answer toneAmber
class node_entity_resolution,node_contradiction toneMint
class node_corrections,node_correction_store,node_api_client toneRose
class node_curator,node_cli_user,node_model_endpoint toneIndigo
```

## Components

### Corpus preparation

- [Record normalization](https://github.com/gargi-09/museum-qa-agent/blob/main/src/ingest.py): `src/ingest.py`
- **Normalized corpus**

### Question answering

- [CLI commands](https://github.com/gargi-09/museum-qa-agent/blob/main/src/main.py): `src/main.py`
- [Hybrid retrieval](https://github.com/gargi-09/museum-qa-agent/blob/main/src/retrieval.py): `src/retrieval.py`
- **Embedding cache**
- [Answer orchestration](https://github.com/gargi-09/museum-qa-agent/blob/main/src/reasoning.py): `src/reasoning.py`
- [Verified answer](https://github.com/gargi-09/museum-qa-agent/blob/main/src/reasoning.py): `src/reasoning.py`

### Record quality

- [Entity resolution](https://github.com/gargi-09/museum-qa-agent/blob/main/src/entity_resolution.py): `src/entity_resolution.py`
- [Prose contradiction checks](https://github.com/gargi-09/museum-qa-agent/blob/main/src/contradiction.py): `src/contradiction.py`

### State and services

- [Correction persistence](https://github.com/gargi-09/museum-qa-agent/blob/main/src/memory.py): `src/memory.py`
- **Correction records**
- [Model API client](https://github.com/gargi-09/museum-qa-agent/blob/main/src/api_client.py): `src/api_client.py`

### Other components

- **Curator**
- **Questioner**
- **Model endpoint**

## Connections

- Curator → CLI commands: adds corrections (evidence: `README.md`)
- Questioner → CLI commands: asks question (evidence: `README.md`)
- CLI commands → Record normalization: runs ingest (evidence: `src/main.py`)
- Record normalization → Model API client: fallback extraction (evidence: `src/ingest.py`)
- Record normalization → Normalized corpus: writes records (evidence: `README.md`)
- CLI commands → Hybrid retrieval: loads for queries (evidence: `src/main.py`)
- Normalized corpus → Hybrid retrieval: loads corpus (evidence: `README.md`)
- CLI commands → Answer orchestration: dispatches question (evidence: `src/main.py`)
- Hybrid retrieval → Embedding cache: caches embeddings (evidence: `README.md`)
- Answer orchestration → Hybrid retrieval: ranks candidates (evidence: `src/reasoning.py`)
- Answer orchestration → Correction persistence: applies overrides (evidence: `README.md`)
- Correction persistence → Correction records: reads and writes (evidence: `src/memory.py`)
- Answer orchestration → Entity resolution: groups records (evidence: `src/reasoning.py`)
- Answer orchestration → Prose contradiction checks: checks descriptions (evidence: `src/reasoning.py`)
- Answer orchestration → Model API client: requests generation (evidence: `src/reasoning.py`)
- Model API client → Model endpoint: sends model request (evidence: `README.md`)
- Answer orchestration → Verified answer: verifies and scores (evidence: `src/reasoning.py`)
- CLI commands → Verified answer: prints result (evidence: `src/main.py`)