# aarthireddyyy/selfheal_rag architecture

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

- Interactive diagram: https://gitdiagram.com/aarthireddyyy/selfheal_rag
- Repository: https://github.com/aarthireddyyy/selfheal_rag

## Overview

This repository is a self-healing retrieval-augmented question-answering service. Its main workflow validates a user question, retrieves and reranks knowledge-base chunks, generates an answer, and grades groundedness; incomplete answers get a caveat, while failures trigger query rewrites and bounded retries before an honest fallback. A separate ingestion workflow loads and semantically chunks documents into persistent vector storage. The graph preserves the README’s hybrid-search, security, and API capabilities. Relationships involving the omitted portions of the agent are supported by its excerpts or README; no unshown implementation details are assumed.

Main entry points: [`src/rag_agent.py`](https://github.com/aarthireddyyy/selfheal_rag/blob/main/src/rag_agent.py) (Grade Router), [`src/retriever.py`](https://github.com/aarthireddyyy/selfheal_rag/blob/main/src/retriever.py) (Hybrid Search), [`src/ingest.py`](https://github.com/aarthireddyyy/selfheal_rag/blob/main/src/ingest.py) (Chroma Store), [`src/api.py`](https://github.com/aarthireddyyy/selfheal_rag/blob/main/src/api.py) (REST API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["API and Security"]
  node_api["REST API<br/>[api.py]"]
  node_guardrails["Input Guardrails<br/>[guardrails.py]"]
end

subgraph group_ingestion["Knowledge Ingestion"]
  node_ingest["Document Ingestion<br/>[ingest.py]"]
  node_documents["Knowledge Documents"]
  node_chunking["Semantic Chunking<br/>[ingest.py]"]
  node_vectorstore[("Chroma Store<br/>[ingest.py]")]
end

subgraph group_answering["Self-Healing Answering"]
  node_agent["RAG Agent<br/>[rag_agent.py]"]
  node_retrieve["Retrieve Node<br/>[rag_agent.py]"]
  node_generate["Answer Generation<br/>[rag_agent.py]"]
  node_grader["Groundedness Grader<br/>[rag_agent.py]"]
  node_router["Grade Router<br/>[rag_agent.py]"]
  node_rewrite["Query Rewrite<br/>[rag_agent.py]"]
  node_partial["Partial Answer<br/>[rag_agent.py]"]
  node_fallback["Give-Up Response<br/>[rag_agent.py]"]
end

subgraph group_retrieval["Hybrid Retrieval"]
  node_hybrid["Hybrid Search<br/>[retriever.py]"]
  node_vectorsearch["Vector Search<br/>[retriever.py]"]
  node_bm25["BM25 Search<br/>[retriever.py]"]
  node_reranker["Cross-Encoder Reranker<br/>[retriever.py]"]
end

node_user(("Questioner"))
node_groq{{"Groq LLM"}}
node_answer["Answer and Sources"]

node_user -->|"submits question"| node_api
node_api -->|"checks input"| node_guardrails
node_api -->|"invokes query"| node_agent
node_agent -->|"starts workflow"| node_retrieve
node_retrieve -->|"calls retrieval"| node_hybrid
node_hybrid -->|"searches vectors"| node_vectorsearch
node_hybrid -->|"searches keywords"| node_bm25
node_hybrid -->|"reranks candidates"| node_reranker
node_retrieve -->|"opens store"| node_vectorstore
node_vectorsearch -->|"searches store"| node_vectorstore
node_bm25 -->|"reads chunks"| node_vectorstore
node_retrieve -->|"then generates"| node_generate
node_generate -->|"requests completion"| node_groq
node_generate -->|"grades answer"| node_grader
node_grader -->|"requests judgment"| node_groq
node_grader -->|"routes by grade"| node_router
node_router -->|"retries failures"| node_rewrite
node_rewrite -->|"rewrites query"| node_groq
node_rewrite -->|"retries retrieval"| node_retrieve
node_router -->|"returns partial"| node_partial
node_router -->|"ends exhausted"| node_fallback
node_router -->|"returns passing answer"| node_answer
node_partial -->|"adds caveat"| node_answer
node_fallback -->|"returns fallback"| node_answer
node_agent -->|"returns result"| node_answer
node_documents -->|"loads files"| node_ingest
node_ingest -->|"splits semantically"| node_chunking
node_chunking -->|"stores chunks"| node_vectorstore
node_answer -->|"serves response"| node_user

click node_api "https://github.com/aarthireddyyy/selfheal_rag/blob/main/src/api.py"
click node_guardrails "https://github.com/aarthireddyyy/selfheal_rag/blob/main/src/guardrails.py"
click node_ingest "https://github.com/aarthireddyyy/selfheal_rag/blob/main/src/ingest.py"
click node_chunking "https://github.com/aarthireddyyy/selfheal_rag/blob/main/src/ingest.py"
click node_vectorstore "https://github.com/aarthireddyyy/selfheal_rag/blob/main/src/ingest.py"
click node_agent "https://github.com/aarthireddyyy/selfheal_rag/blob/main/src/rag_agent.py"
click node_retrieve "https://github.com/aarthireddyyy/selfheal_rag/blob/main/src/rag_agent.py"
click node_hybrid "https://github.com/aarthireddyyy/selfheal_rag/blob/main/src/retriever.py"
click node_vectorsearch "https://github.com/aarthireddyyy/selfheal_rag/blob/main/src/retriever.py"
click node_bm25 "https://github.com/aarthireddyyy/selfheal_rag/blob/main/src/retriever.py"
click node_reranker "https://github.com/aarthireddyyy/selfheal_rag/blob/main/src/retriever.py"
click node_generate "https://github.com/aarthireddyyy/selfheal_rag/blob/main/src/rag_agent.py"
click node_grader "https://github.com/aarthireddyyy/selfheal_rag/blob/main/src/rag_agent.py"
click node_router "https://github.com/aarthireddyyy/selfheal_rag/blob/main/src/rag_agent.py"
click node_rewrite "https://github.com/aarthireddyyy/selfheal_rag/blob/main/src/rag_agent.py"
click node_partial "https://github.com/aarthireddyyy/selfheal_rag/blob/main/src/rag_agent.py"
click node_fallback "https://github.com/aarthireddyyy/selfheal_rag/blob/main/src/rag_agent.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_api,node_guardrails toneBlue
class node_ingest,node_documents,node_chunking,node_vectorstore toneAmber
class node_agent,node_retrieve,node_generate,node_grader,node_router,node_rewrite,node_partial,node_fallback toneMint
class node_hybrid,node_vectorsearch,node_bm25,node_reranker toneRose
class node_user,node_groq,node_answer toneIndigo
```

## Components

### API and Security

- [REST API](https://github.com/aarthireddyyy/selfheal_rag/blob/main/src/api.py): `src/api.py`
- [Input Guardrails](https://github.com/aarthireddyyy/selfheal_rag/blob/main/src/guardrails.py): `src/guardrails.py`

### Knowledge Ingestion

- [Document Ingestion](https://github.com/aarthireddyyy/selfheal_rag/blob/main/src/ingest.py): `src/ingest.py`
- **Knowledge Documents**
- [Semantic Chunking](https://github.com/aarthireddyyy/selfheal_rag/blob/main/src/ingest.py): `src/ingest.py`
- [Chroma Store](https://github.com/aarthireddyyy/selfheal_rag/blob/main/src/ingest.py): `src/ingest.py`

### Self-Healing Answering

- [RAG Agent](https://github.com/aarthireddyyy/selfheal_rag/blob/main/src/rag_agent.py): `src/rag_agent.py`
- [Retrieve Node](https://github.com/aarthireddyyy/selfheal_rag/blob/main/src/rag_agent.py): `src/rag_agent.py`
- [Answer Generation](https://github.com/aarthireddyyy/selfheal_rag/blob/main/src/rag_agent.py): `src/rag_agent.py`
- [Groundedness Grader](https://github.com/aarthireddyyy/selfheal_rag/blob/main/src/rag_agent.py): `src/rag_agent.py`
- [Grade Router](https://github.com/aarthireddyyy/selfheal_rag/blob/main/src/rag_agent.py): `src/rag_agent.py`
- [Query Rewrite](https://github.com/aarthireddyyy/selfheal_rag/blob/main/src/rag_agent.py): `src/rag_agent.py`
- [Partial Answer](https://github.com/aarthireddyyy/selfheal_rag/blob/main/src/rag_agent.py): `src/rag_agent.py`
- [Give-Up Response](https://github.com/aarthireddyyy/selfheal_rag/blob/main/src/rag_agent.py): `src/rag_agent.py`

### Hybrid Retrieval

- [Hybrid Search](https://github.com/aarthireddyyy/selfheal_rag/blob/main/src/retriever.py): `src/retriever.py`
- [Vector Search](https://github.com/aarthireddyyy/selfheal_rag/blob/main/src/retriever.py): `src/retriever.py`
- [BM25 Search](https://github.com/aarthireddyyy/selfheal_rag/blob/main/src/retriever.py): `src/retriever.py`
- [Cross-Encoder Reranker](https://github.com/aarthireddyyy/selfheal_rag/blob/main/src/retriever.py): `src/retriever.py`

### Other components

- **Questioner**
- **Groq LLM**
- **Answer and Sources**

## Connections

- Questioner → REST API: submits question (evidence: `src/api.py`)
- REST API → Input Guardrails: checks input (evidence: `src/api.py`)
- REST API → RAG Agent: invokes query (evidence: `src/api.py`)
- RAG Agent → Retrieve Node: starts workflow (evidence: `src/rag_agent.py`)
- Retrieve Node → Hybrid Search: calls retrieval (evidence: `src/rag_agent.py`)
- Hybrid Search → Vector Search: searches vectors (evidence: `src/retriever.py`)
- Hybrid Search → BM25 Search: searches keywords (evidence: `src/retriever.py`)
- Hybrid Search → Cross-Encoder Reranker: reranks candidates (evidence: `src/retriever.py`)
- Retrieve Node → Chroma Store: opens store (evidence: `src/rag_agent.py`)
- Vector Search → Chroma Store: searches store (evidence: `src/retriever.py`)
- BM25 Search → Chroma Store: reads chunks (evidence: `src/retriever.py`)
- Retrieve Node → Answer Generation: then generates (evidence: `src/rag_agent.py`)
- Answer Generation → Groq LLM: requests completion (evidence: `src/rag_agent.py`)
- Answer Generation → Groundedness Grader: grades answer (evidence: `src/rag_agent.py`)
- Groundedness Grader → Groq LLM: requests judgment (evidence: `src/rag_agent.py`)
- Groundedness Grader → Grade Router: routes by grade (evidence: `src/rag_agent.py`)
- Grade Router → Query Rewrite: retries failures (evidence: `src/rag_agent.py`)
- Query Rewrite → Groq LLM: rewrites query (evidence: `src/rag_agent.py`)
- Query Rewrite → Retrieve Node: retries retrieval (evidence: `src/rag_agent.py`)
- Grade Router → Partial Answer: returns partial (evidence: `src/rag_agent.py`)
- Grade Router → Give-Up Response: ends exhausted (evidence: `src/rag_agent.py`)
- Grade Router → Answer and Sources: returns passing answer (evidence: `README.md`)
- Partial Answer → Answer and Sources: adds caveat (evidence: `src/rag_agent.py`)
- Give-Up Response → Answer and Sources: returns fallback (evidence: `src/rag_agent.py`)
- RAG Agent → Answer and Sources: returns result (evidence: `src/rag_agent.py`)
- Knowledge Documents → Document Ingestion: loads files (evidence: `README.md`)
- Document Ingestion → Semantic Chunking: splits semantically (evidence: `src/ingest.py`)
- Semantic Chunking → Chroma Store: stores chunks (evidence: `src/ingest.py`)
- Answer and Sources → Questioner: serves response (evidence: `README.md`)
