# mugil0095/verity-rag architecture

> Architecture diagram of the GitHub repository mugil0095/verity-rag, 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/mugil0095/verity-rag
- Repository: https://github.com/mugil0095/verity-rag

## Overview

VerityRAG is a real-time, agentic retrieval-augmented question-answering system. Users submit questions through the Streamlit app or FastAPI backend; the pipeline delegates bounded retrieval and reformulation to an agent, which checks evidence sufficiency, generates an answer when warranted, and verifies grounding before returning an answer or abstaining. Documents enter through bulk or streaming ingestion and are chunked, embedded, and indexed for hybrid search. Evaluation and optional model/index backends are separate capabilities. The map follows the README and supplied excerpts; unsampled API and agent internals are represented only at documented subsystem level.

Main entry points: [`src/verityrag/agent.py`](https://github.com/mugil0095/verity-rag/blob/master/src/verityrag/agent.py) (Agent Controller), [`src/verityrag/pipeline.py`](https://github.com/mugil0095/verity-rag/blob/master/src/verityrag/pipeline.py) (RAG Pipeline), [`src/verityrag/indexing.py`](https://github.com/mugil0095/verity-rag/blob/master/src/verityrag/indexing.py) (Live Index), [`app.py`](https://github.com/mugil0095/verity-rag/blob/master/app.py) (Streamlit UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_serving["Serving"]
  node_streamlit["Streamlit UI<br/>[app.py]"]
  node_fastapi["FastAPI API<br/>[api.py]"]
  node_pipeline["RAG Pipeline<br/>[pipeline.py]"]
end

subgraph group_ingestion["Ingestion"]
  node_live_stream["Live Stream<br/>[streaming.py]"]
  node_chunking["Chunking<br/>[chunking.py]"]
  node_embedding["Embedding<br/>[embedding.py]"]
  node_live_index[("Live Index<br/>[indexing.py]")]
  node_elastic[("Elasticsearch Backend")]
end

subgraph group_retrieval["Retrieval"]
  node_agent["Agent Controller<br/>[agent.py]"]
  node_reformulate["Query Reformulation"]
  node_retrieval["Hybrid Retrieval<br/>[retrieval.py]"]
  node_reranker["Reranker<br/>[reranker.py]"]
  node_sufficiency["Sufficiency Gate<br/>[sufficiency.py]"]
end

subgraph group_answering["Answering"]
  node_generation["Answer Generation<br/>[generation.py]"]
  node_providers["LLM Providers<br/>[llm_providers.py]"]
  node_grounding["Grounding Check<br/>[grounding.py]"]
  node_result["Answer or Abstention"]
end

subgraph group_evaluation["Evaluation"]
  node_eval["Evaluation Harness<br/>[eval.py]"]
end

node_user(("Questioner"))

node_user -->|"asks"| node_streamlit
node_user -->|"asks"| node_fastapi
node_streamlit -->|"queries"| node_pipeline
node_fastapi -->|"delegates"| node_pipeline
node_pipeline -->|"queries"| node_agent
node_pipeline -->|"chunks documents"| node_chunking
node_pipeline -->|"adds chunks"| node_live_index
node_live_stream -->|"ingests documents"| node_pipeline
node_chunking -->|"produces text chunks"| node_embedding
node_live_index -->|"embeds chunks"| node_embedding
node_live_index -.->|"optional lexical backend"| node_elastic
node_agent -->|"retrieves candidates"| node_retrieval
node_retrieval -->|"reads snapshot"| node_live_index
node_retrieval -->|"embeds query"| node_embedding
node_agent -->|"reranks candidates"| node_reranker
node_agent -->|"checks evidence"| node_sufficiency
node_agent -->|"reformulates query"| node_reformulate
node_agent -->|"generates answer"| node_generation
node_generation -.->|"optional model calls"| node_providers
node_agent -->|"checks answer"| node_grounding
node_agent -->|"returns answer or abstention"| node_result
node_streamlit -->|"renders"| node_result
node_fastapi -->|"returns"| node_result
node_eval -->|"evaluates queries"| node_pipeline

click node_streamlit "https://github.com/mugil0095/verity-rag/blob/master/app.py"
click node_fastapi "https://github.com/mugil0095/verity-rag/blob/master/src/verityrag/api.py"
click node_pipeline "https://github.com/mugil0095/verity-rag/blob/master/src/verityrag/pipeline.py"
click node_live_stream "https://github.com/mugil0095/verity-rag/blob/master/src/verityrag/streaming.py"
click node_chunking "https://github.com/mugil0095/verity-rag/blob/master/src/verityrag/chunking.py"
click node_embedding "https://github.com/mugil0095/verity-rag/blob/master/src/verityrag/embedding.py"
click node_live_index "https://github.com/mugil0095/verity-rag/blob/master/src/verityrag/indexing.py"
click node_elastic "https://github.com/mugil0095/verity-rag/blob/master/src/verityrag/elasticsearch_index.py"
click node_agent "https://github.com/mugil0095/verity-rag/blob/master/src/verityrag/agent.py"
click node_reformulate "https://github.com/mugil0095/verity-rag/blob/master/src/verityrag/agent_reformulate.py"
click node_retrieval "https://github.com/mugil0095/verity-rag/blob/master/src/verityrag/retrieval.py"
click node_reranker "https://github.com/mugil0095/verity-rag/blob/master/src/verityrag/reranker.py"
click node_sufficiency "https://github.com/mugil0095/verity-rag/blob/master/src/verityrag/sufficiency.py"
click node_generation "https://github.com/mugil0095/verity-rag/blob/master/src/verityrag/generation.py"
click node_providers "https://github.com/mugil0095/verity-rag/blob/master/src/verityrag/llm_providers.py"
click node_grounding "https://github.com/mugil0095/verity-rag/blob/master/src/verityrag/grounding.py"
click node_eval "https://github.com/mugil0095/verity-rag/blob/master/src/verityrag/eval.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_streamlit,node_fastapi,node_pipeline toneBlue
class node_live_stream,node_chunking,node_embedding,node_live_index,node_elastic toneAmber
class node_agent,node_reformulate,node_retrieval,node_reranker,node_sufficiency toneMint
class node_generation,node_providers,node_grounding,node_result toneRose
class node_eval,node_user toneIndigo
```

## Components

### Serving

- [Streamlit UI](https://github.com/mugil0095/verity-rag/blob/master/app.py): `app.py`
- [FastAPI API](https://github.com/mugil0095/verity-rag/blob/master/src/verityrag/api.py): `src/verityrag/api.py`
- [RAG Pipeline](https://github.com/mugil0095/verity-rag/blob/master/src/verityrag/pipeline.py): `src/verityrag/pipeline.py`

### Ingestion

- [Live Stream](https://github.com/mugil0095/verity-rag/blob/master/src/verityrag/streaming.py): `src/verityrag/streaming.py`
- [Chunking](https://github.com/mugil0095/verity-rag/blob/master/src/verityrag/chunking.py): `src/verityrag/chunking.py`
- [Embedding](https://github.com/mugil0095/verity-rag/blob/master/src/verityrag/embedding.py): `src/verityrag/embedding.py`
- [Live Index](https://github.com/mugil0095/verity-rag/blob/master/src/verityrag/indexing.py): `src/verityrag/indexing.py`
- [Elasticsearch Backend](https://github.com/mugil0095/verity-rag/blob/master/src/verityrag/elasticsearch_index.py): `src/verityrag/elasticsearch_index.py`

### Retrieval

- [Agent Controller](https://github.com/mugil0095/verity-rag/blob/master/src/verityrag/agent.py): `src/verityrag/agent.py`
- [Query Reformulation](https://github.com/mugil0095/verity-rag/blob/master/src/verityrag/agent_reformulate.py): `src/verityrag/agent_reformulate.py`
- [Hybrid Retrieval](https://github.com/mugil0095/verity-rag/blob/master/src/verityrag/retrieval.py): `src/verityrag/retrieval.py`
- [Reranker](https://github.com/mugil0095/verity-rag/blob/master/src/verityrag/reranker.py): `src/verityrag/reranker.py`
- [Sufficiency Gate](https://github.com/mugil0095/verity-rag/blob/master/src/verityrag/sufficiency.py): `src/verityrag/sufficiency.py`

### Answering

- [Answer Generation](https://github.com/mugil0095/verity-rag/blob/master/src/verityrag/generation.py): `src/verityrag/generation.py`
- [LLM Providers](https://github.com/mugil0095/verity-rag/blob/master/src/verityrag/llm_providers.py): `src/verityrag/llm_providers.py`
- [Grounding Check](https://github.com/mugil0095/verity-rag/blob/master/src/verityrag/grounding.py): `src/verityrag/grounding.py`
- **Answer or Abstention**

### Evaluation

- [Evaluation Harness](https://github.com/mugil0095/verity-rag/blob/master/src/verityrag/eval.py): `src/verityrag/eval.py`

### Other components

- **Questioner**

## Connections

- Questioner → Streamlit UI: asks
- Questioner → FastAPI API: asks
- Streamlit UI → RAG Pipeline: queries
- FastAPI API → RAG Pipeline: delegates
- RAG Pipeline → Agent Controller: queries
- RAG Pipeline → Chunking: chunks documents
- RAG Pipeline → Live Index: adds chunks
- Live Stream → RAG Pipeline: ingests documents
- Chunking → Embedding: produces text chunks
- Live Index → Embedding: embeds chunks
- Live Index → Elasticsearch Backend: optional lexical backend
- Agent Controller → Hybrid Retrieval: retrieves candidates
- Hybrid Retrieval → Live Index: reads snapshot
- Hybrid Retrieval → Embedding: embeds query
- Agent Controller → Reranker: reranks candidates
- Agent Controller → Sufficiency Gate: checks evidence
- Agent Controller → Query Reformulation: reformulates query
- Agent Controller → Answer Generation: generates answer
- Answer Generation → LLM Providers: optional model calls
- Agent Controller → Grounding Check: checks answer
- Agent Controller → Answer or Abstention: returns answer or abstention
- Streamlit UI → Answer or Abstention: renders
- FastAPI API → Answer or Abstention: returns
- Evaluation Harness → RAG Pipeline: evaluates queries