# butlee27/advanced-conversational-rag architecture

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

- Interactive diagram: https://gitdiagram.com/butlee27/advanced-conversational-rag
- Repository: https://github.com/butlee27/advanced-conversational-rag

## Overview

This is a Streamlit conversational RAG application: users upload PDFs, which are indexed, then ask questions answered from retrieved document context with session memory and safety checks. Retrieval combines semantic and BM25 search, followed by reranking; the app checks groundedness, sanitizes output, and displays source pages. Evaluation with Ragas is a separate capability. The graph follows README documentation and indexed or excerpted imports/calls; unsampled implementation details and connections are omitted where evidence is limited.

Main entry points: [`app.py`](https://github.com/butlee27/advanced-conversational-rag/blob/main/app.py) (Streamlit Interface), [`src/indexer.py`](https://github.com/butlee27/advanced-conversational-rag/blob/main/src/indexer.py) (Index Builder), [`src/history_retriever.py`](https://github.com/butlee27/advanced-conversational-rag/blob/main/src/history_retriever.py) (History-Aware Search), [`src/chains.py`](https://github.com/butlee27/advanced-conversational-rag/blob/main/src/chains.py) (RAG Chain)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_streamlit["Streamlit Interface<br/>[app.py]"]
  node_guardrails["Safety and Grounding<br/>[guardrails.py]"]
  node_answer["Answer and Sources<br/>[app.py]"]
end

subgraph group_indexing["Document Indexing"]
  node_pdf_loader["PDF Loader<br/>[loader.py]"]
  node_indexer["Index Builder<br/>[indexer.py]"]
  node_splitter["Text Splitter<br/>[splitter.py]"]
  node_embeddings["Embeddings<br/>[embeddings.py]"]
  node_vector_store[("Chroma Store<br/>[vectordb.py]")]
end

subgraph group_retrieval["Retrieval and Memory"]
  node_conversation["Conversation Handler<br/>[conversation.py]"]
  node_history["Session History<br/>[history.py]"]
  node_history_retriever["History-Aware Search"]
  node_advanced_retriever["Advanced Retriever"]
  node_hybrid_retriever["Hybrid Search"]
  node_vector_retriever["Vector Search<br/>[retriever.py]"]
  node_bm25["BM25 Search<br/>[bm25.py]"]
  node_reranker["Cross-Encoder Reranker<br/>[reranker.py]"]
end

subgraph group_generation["Answer Generation"]
  node_rag_chain["RAG Chain<br/>[chains.py]"]
  node_prompts["RAG Prompts<br/>[prompts.py]"]
  node_llm["Groq Language Model<br/>[llm.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_eval_runner["Evaluation Runner<br/>[run_evaluation.py]"]
  node_eval_data["Evaluation Dataset<br/>[dataset.py]"]
  node_ragas["Ragas Metrics<br/>[evaluate_ragas.py]"]
end

node_user(("PDF User"))
node_evaluator(("Evaluation Operator"))

node_user -->|"uploads and asks"| node_streamlit
node_streamlit -->|"checks PDFs"| node_pdf_loader
node_streamlit -->|"builds index"| node_indexer
node_indexer -->|"loads documents"| node_pdf_loader
node_indexer -->|"splits documents"| node_splitter
node_indexer -->|"creates vectors"| node_embeddings
node_indexer -->|"stores chunks"| node_vector_store
node_vector_store -->|"embeds documents"| node_embeddings
node_streamlit -->|"creates conversation"| node_conversation
node_streamlit -->|"checks and sanitizes"| node_guardrails
node_streamlit -->|"checks grounding"| node_llm
node_streamlit -->|"renders answer and sources"| node_answer
node_conversation -->|"wraps chain"| node_rag_chain
node_conversation -->|"loads session history"| node_history
node_rag_chain -->|"generates answer"| node_llm
node_rag_chain -->|"uses prompt"| node_prompts
node_rag_chain -->|"retrieves context"| node_history_retriever
node_history_retriever -->|"rewrites question"| node_llm
node_history_retriever -->|"uses rewrite prompt"| node_prompts
node_history_retriever -->|"configures retriever"| node_advanced_retriever
node_advanced_retriever -->|"searches candidates"| node_hybrid_retriever
node_advanced_retriever -->|"reranks results"| node_reranker
node_hybrid_retriever -->|"combines search"| node_vector_retriever
node_hybrid_retriever -->|"combines search"| node_bm25
node_vector_retriever -->|"searches vectors"| node_vector_store
node_bm25 -->|"loads documents"| node_pdf_loader
node_bm25 -->|"uses chunks"| node_splitter
node_evaluator -->|"runs evaluation"| node_eval_runner
node_eval_runner -->|"loads dataset"| node_eval_data
node_evaluator -->|"evaluates RAG metrics"| node_ragas
node_ragas -->|"uses model"| node_llm
node_ragas -->|"uses embeddings"| node_embeddings

click node_streamlit "https://github.com/butlee27/advanced-conversational-rag/blob/main/app.py"
click node_guardrails "https://github.com/butlee27/advanced-conversational-rag/blob/main/src/guardrails.py"
click node_answer "https://github.com/butlee27/advanced-conversational-rag/blob/main/app.py"
click node_pdf_loader "https://github.com/butlee27/advanced-conversational-rag/blob/main/src/loader.py"
click node_indexer "https://github.com/butlee27/advanced-conversational-rag/blob/main/src/indexer.py"
click node_splitter "https://github.com/butlee27/advanced-conversational-rag/blob/main/src/splitter.py"
click node_embeddings "https://github.com/butlee27/advanced-conversational-rag/blob/main/src/embeddings.py"
click node_vector_store "https://github.com/butlee27/advanced-conversational-rag/blob/main/src/vectordb.py"
click node_conversation "https://github.com/butlee27/advanced-conversational-rag/blob/main/src/conversation.py"
click node_history "https://github.com/butlee27/advanced-conversational-rag/blob/main/src/history.py"
click node_rag_chain "https://github.com/butlee27/advanced-conversational-rag/blob/main/src/chains.py"
click node_history_retriever "https://github.com/butlee27/advanced-conversational-rag/blob/main/src/history_retriever.py"
click node_advanced_retriever "https://github.com/butlee27/advanced-conversational-rag/blob/main/src/custom_retriever.py"
click node_hybrid_retriever "https://github.com/butlee27/advanced-conversational-rag/blob/main/src/hybrid_retriever.py"
click node_vector_retriever "https://github.com/butlee27/advanced-conversational-rag/blob/main/src/retriever.py"
click node_bm25 "https://github.com/butlee27/advanced-conversational-rag/blob/main/src/bm25.py"
click node_reranker "https://github.com/butlee27/advanced-conversational-rag/blob/main/src/reranker.py"
click node_prompts "https://github.com/butlee27/advanced-conversational-rag/blob/main/src/prompts.py"
click node_llm "https://github.com/butlee27/advanced-conversational-rag/blob/main/src/llm.py"
click node_eval_runner "https://github.com/butlee27/advanced-conversational-rag/blob/main/eval/run_evaluation.py"
click node_eval_data "https://github.com/butlee27/advanced-conversational-rag/blob/main/eval/dataset.py"
click node_ragas "https://github.com/butlee27/advanced-conversational-rag/blob/main/eval/evaluate_ragas.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_guardrails,node_answer,node_user toneBlue
class node_pdf_loader,node_indexer,node_splitter,node_embeddings,node_vector_store toneAmber
class node_conversation,node_history,node_history_retriever,node_advanced_retriever,node_hybrid_retriever,node_vector_retriever,node_bm25,node_reranker toneMint
class node_rag_chain,node_prompts,node_llm toneRose
class node_eval_runner,node_eval_data,node_ragas,node_evaluator toneIndigo
```

## Components

### Application

- [Streamlit Interface](https://github.com/butlee27/advanced-conversational-rag/blob/main/app.py): `app.py`
- [Safety and Grounding](https://github.com/butlee27/advanced-conversational-rag/blob/main/src/guardrails.py): `src/guardrails.py`
- [Answer and Sources](https://github.com/butlee27/advanced-conversational-rag/blob/main/app.py): `app.py`

### Document Indexing

- [PDF Loader](https://github.com/butlee27/advanced-conversational-rag/blob/main/src/loader.py): `src/loader.py`
- [Index Builder](https://github.com/butlee27/advanced-conversational-rag/blob/main/src/indexer.py): `src/indexer.py`
- [Text Splitter](https://github.com/butlee27/advanced-conversational-rag/blob/main/src/splitter.py): `src/splitter.py`
- [Embeddings](https://github.com/butlee27/advanced-conversational-rag/blob/main/src/embeddings.py): `src/embeddings.py`
- [Chroma Store](https://github.com/butlee27/advanced-conversational-rag/blob/main/src/vectordb.py): `src/vectordb.py`

### Retrieval and Memory

- [Conversation Handler](https://github.com/butlee27/advanced-conversational-rag/blob/main/src/conversation.py): `src/conversation.py`
- [Session History](https://github.com/butlee27/advanced-conversational-rag/blob/main/src/history.py): `src/history.py`
- [History-Aware Search](https://github.com/butlee27/advanced-conversational-rag/blob/main/src/history_retriever.py): `src/history_retriever.py`
- [Advanced Retriever](https://github.com/butlee27/advanced-conversational-rag/blob/main/src/custom_retriever.py): `src/custom_retriever.py`
- [Hybrid Search](https://github.com/butlee27/advanced-conversational-rag/blob/main/src/hybrid_retriever.py): `src/hybrid_retriever.py`
- [Vector Search](https://github.com/butlee27/advanced-conversational-rag/blob/main/src/retriever.py): `src/retriever.py`
- [BM25 Search](https://github.com/butlee27/advanced-conversational-rag/blob/main/src/bm25.py): `src/bm25.py`
- [Cross-Encoder Reranker](https://github.com/butlee27/advanced-conversational-rag/blob/main/src/reranker.py): `src/reranker.py`

### Answer Generation

- [RAG Chain](https://github.com/butlee27/advanced-conversational-rag/blob/main/src/chains.py): `src/chains.py`
- [RAG Prompts](https://github.com/butlee27/advanced-conversational-rag/blob/main/src/prompts.py): `src/prompts.py`
- [Groq Language Model](https://github.com/butlee27/advanced-conversational-rag/blob/main/src/llm.py): `src/llm.py`

### Evaluation

- [Evaluation Runner](https://github.com/butlee27/advanced-conversational-rag/blob/main/eval/run_evaluation.py): `eval/run_evaluation.py`
- [Evaluation Dataset](https://github.com/butlee27/advanced-conversational-rag/blob/main/eval/dataset.py): `eval/dataset.py`
- [Ragas Metrics](https://github.com/butlee27/advanced-conversational-rag/blob/main/eval/evaluate_ragas.py): `eval/evaluate_ragas.py`

### Other components

- **PDF User**
- **Evaluation Operator**

## Connections

- PDF User → Streamlit Interface: uploads and asks (evidence: `README.md`)
- Streamlit Interface → PDF Loader: checks PDFs (evidence: `app.py`)
- Streamlit Interface → Index Builder: builds index (evidence: `app.py`)
- Index Builder → PDF Loader: loads documents (evidence: `src/indexer.py`)
- Index Builder → Text Splitter: splits documents (evidence: `src/indexer.py`)
- Index Builder → Embeddings: creates vectors (evidence: `src/indexer.py`)
- Index Builder → Chroma Store: stores chunks (evidence: `src/indexer.py`)
- Chroma Store → Embeddings: embeds documents (evidence: `src/vectordb.py`)
- Streamlit Interface → Conversation Handler: creates conversation (evidence: `app.py`)
- Streamlit Interface → Safety and Grounding: checks and sanitizes (evidence: `app.py`)
- Streamlit Interface → Groq Language Model: checks grounding (evidence: `app.py`)
- Streamlit Interface → Answer and Sources: renders answer and sources (evidence: `app.py`)
- Conversation Handler → RAG Chain: wraps chain (evidence: `src/conversation.py`)
- Conversation Handler → Session History: loads session history (evidence: `src/conversation.py`)
- RAG Chain → Groq Language Model: generates answer (evidence: `src/chains.py`)
- RAG Chain → RAG Prompts: uses prompt (evidence: `src/chains.py`)
- RAG Chain → History-Aware Search: retrieves context (evidence: `src/chains.py`)
- History-Aware Search → Groq Language Model: rewrites question (evidence: `src/history_retriever.py`)
- History-Aware Search → RAG Prompts: uses rewrite prompt (evidence: `src/history_retriever.py`)
- History-Aware Search → Advanced Retriever: configures retriever (evidence: `src/history_retriever.py`)
- Advanced Retriever → Hybrid Search: searches candidates (evidence: `src/custom_retriever.py`)
- Advanced Retriever → Cross-Encoder Reranker: reranks results (evidence: `src/custom_retriever.py`)
- Hybrid Search → Vector Search: combines search (evidence: `src/hybrid_retriever.py`)
- Hybrid Search → BM25 Search: combines search (evidence: `src/hybrid_retriever.py`)
- Vector Search → Chroma Store: searches vectors (evidence: `src/retriever.py`)
- BM25 Search → PDF Loader: loads documents (evidence: `src/bm25.py`)
- BM25 Search → Text Splitter: uses chunks (evidence: `src/bm25.py`)
- Evaluation Operator → Evaluation Runner: runs evaluation (evidence: `README.md`)
- Evaluation Runner → Evaluation Dataset: loads dataset (evidence: `eval/run_evaluation.py`)
- Evaluation Operator → Ragas Metrics: evaluates RAG metrics (evidence: `README.md`)
- Ragas Metrics → Groq Language Model: uses model (evidence: `eval/evaluate_ragas.py`)
- Ragas Metrics → Embeddings: uses embeddings (evidence: `eval/evaluate_ragas.py`)
