# shu0209/agentic-rag architecture

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

## Overview

This is an agentic RAG chatbot for answering machine-learning questions from an ingested knowledge base, with conversational memory and guardrails. The main workflow gates a user request, plans whether retrieval is needed, optionally retrieves and reranks documents, then generates a response; the agent graph retains conversation state by thread. A separate ingestion workflow parses and chunks source documents, embeds them, and indexes them in Qdrant. Some API, UI, and integration wiring is documented in the README but their source excerpts were not available, so those edges cite the README.

Main entry points: [`app/ingestion/processor.py`](https://github.com/shu0209/agentic-rag/blob/main/app/ingestion/processor.py) (Ingestion Processor), [`app/agents/graph.py`](https://github.com/shu0209/agentic-rag/blob/main/app/agents/graph.py) (Agent Graph), [`app/agents/nodes/retriever.py`](https://github.com/shu0209/agentic-rag/blob/main/app/agents/nodes/retriever.py) (Context Retriever), [`app/agents/nodes/responder.py`](https://github.com/shu0209/agentic-rag/blob/main/app/agents/nodes/responder.py) (Answer Generator)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client"]
  node_streamlit["Chat UI<br/>[app.py]"]
end

subgraph group_request["Request Handling"]
  node_api["FastAPI API<br/>[main.py]"]
  node_rails["Guardrails Gate<br/>[rails.py]"]
  node_colang["Guardrail Flows<br/>[colang_rules.py]"]
end

subgraph group_agent["Agent Workflow"]
  node_graph["Agent Graph<br/>[graph.py]"]
  node_state["Conversation State<br/>[state.py]"]
  node_planner["Intent Planner<br/>[planner.py]"]
  node_retriever["Context Retriever<br/>[retriever.py]"]
  node_responder["Answer Generator<br/>[responder.py]"]
  node_gateway["LLM Gateway<br/>[client.py]"]
end

subgraph group_knowledge["Knowledge Ingestion"]
  node_ingest["Ingestion Processor<br/>[processor.py]"]
  node_pdf["PDF Loader<br/>[pdf_loader.py]"]
  node_html["HTML Loader<br/>[html_loader.py]"]
  node_office["Office Loader<br/>[office_loader.py]"]
  node_text["Text Loader<br/>[text_loader.py]"]
  node_chunker["Text Chunker<br/>[splitter.py]"]
end

subgraph group_retrieval["Retrieval Services"]
  node_embeddings["Embedding Service<br/>[embeddings.py]"]
  node_qdrant["Vector Search<br/>[qdrant_service.py]"]
  node_ranker["Document Reranker<br/>[ranking_service.py]"]
  node_vectordb[("Qdrant Store")]
end

node_user(("User"))
node_source_docs["Knowledge Sources"]

node_user -->|"asks"| node_streamlit
node_streamlit -->|"submits query"| node_api
node_user -->|"queries"| node_api
node_api -->|"gates request"| node_rails
node_rails -->|"uses flows"| node_colang
node_rails -->|"passes allowed query"| node_graph
node_graph -->|"runs first"| node_planner
node_graph -->|"routes technical query"| node_retriever
node_graph -->|"routes conversational query"| node_responder
node_graph -->|"routes after retrieval"| node_responder
node_graph -->|"checks state"| node_state
node_planner -->|"reads and updates"| node_state
node_retriever -->|"reads and updates"| node_state
node_responder -->|"reads and updates"| node_state
node_planner -->|"gets LLM"| node_gateway
node_responder -->|"uses gateway"| node_gateway
node_retriever -->|"searches"| node_qdrant
node_retriever -->|"reranks results"| node_ranker
node_qdrant -->|"embeds query"| node_embeddings
node_qdrant -->|"queries"| node_vectordb
node_ingest -->|"parses PDF"| node_pdf
node_ingest -->|"parses HTML"| node_html
node_ingest -->|"parses Office"| node_office
node_ingest -->|"parses text"| node_text
node_ingest -->|"chunks text"| node_chunker
node_ingest -->|"embeds chunks"| node_embeddings
node_ingest -->|"upserts vectors"| node_vectordb
node_source_docs -->|"provides files"| node_ingest

click node_streamlit "https://github.com/shu0209/agentic-rag/blob/main/ui/app.py"
click node_api "https://github.com/shu0209/agentic-rag/blob/main/app/main.py"
click node_rails "https://github.com/shu0209/agentic-rag/blob/main/app/guardrails/rails.py"
click node_colang "https://github.com/shu0209/agentic-rag/blob/main/app/guardrails/colang_rules.py"
click node_graph "https://github.com/shu0209/agentic-rag/blob/main/app/agents/graph.py"
click node_state "https://github.com/shu0209/agentic-rag/blob/main/app/agents/state.py"
click node_planner "https://github.com/shu0209/agentic-rag/blob/main/app/agents/nodes/planner.py"
click node_retriever "https://github.com/shu0209/agentic-rag/blob/main/app/agents/nodes/retriever.py"
click node_responder "https://github.com/shu0209/agentic-rag/blob/main/app/agents/nodes/responder.py"
click node_gateway "https://github.com/shu0209/agentic-rag/blob/main/app/gateways/client.py"
click node_ingest "https://github.com/shu0209/agentic-rag/blob/main/app/ingestion/processor.py"
click node_pdf "https://github.com/shu0209/agentic-rag/blob/main/app/ingestion/loaders/pdf_loader.py"
click node_html "https://github.com/shu0209/agentic-rag/blob/main/app/ingestion/loaders/html_loader.py"
click node_office "https://github.com/shu0209/agentic-rag/blob/main/app/ingestion/loaders/office_loader.py"
click node_text "https://github.com/shu0209/agentic-rag/blob/main/app/ingestion/loaders/text_loader.py"
click node_chunker "https://github.com/shu0209/agentic-rag/blob/main/app/ingestion/chunking/splitter.py"
click node_embeddings "https://github.com/shu0209/agentic-rag/blob/main/app/services/retrieval/embeddings.py"
click node_qdrant "https://github.com/shu0209/agentic-rag/blob/main/app/services/retrieval/qdrant_service.py"
click node_ranker "https://github.com/shu0209/agentic-rag/blob/main/app/services/retrieval/ranking_service.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_user toneBlue
class node_api,node_rails,node_colang toneAmber
class node_graph,node_state,node_planner,node_retriever,node_responder,node_gateway toneMint
class node_ingest,node_pdf,node_html,node_office,node_text,node_chunker toneRose
class node_embeddings,node_qdrant,node_ranker,node_vectordb,node_source_docs toneIndigo
```

## Components

### Client

- [Chat UI](https://github.com/shu0209/agentic-rag/blob/main/ui/app.py): `ui/app.py`

### Request Handling

- [FastAPI API](https://github.com/shu0209/agentic-rag/blob/main/app/main.py): `app/main.py`
- [Guardrails Gate](https://github.com/shu0209/agentic-rag/blob/main/app/guardrails/rails.py): `app/guardrails/rails.py`
- [Guardrail Flows](https://github.com/shu0209/agentic-rag/blob/main/app/guardrails/colang_rules.py): `app/guardrails/colang_rules.py`

### Agent Workflow

- [Agent Graph](https://github.com/shu0209/agentic-rag/blob/main/app/agents/graph.py): `app/agents/graph.py`
- [Conversation State](https://github.com/shu0209/agentic-rag/blob/main/app/agents/state.py): `app/agents/state.py`
- [Intent Planner](https://github.com/shu0209/agentic-rag/blob/main/app/agents/nodes/planner.py): `app/agents/nodes/planner.py`
- [Context Retriever](https://github.com/shu0209/agentic-rag/blob/main/app/agents/nodes/retriever.py): `app/agents/nodes/retriever.py`
- [Answer Generator](https://github.com/shu0209/agentic-rag/blob/main/app/agents/nodes/responder.py): `app/agents/nodes/responder.py`
- [LLM Gateway](https://github.com/shu0209/agentic-rag/blob/main/app/gateways/client.py): `app/gateways/client.py`

### Knowledge Ingestion

- [Ingestion Processor](https://github.com/shu0209/agentic-rag/blob/main/app/ingestion/processor.py): `app/ingestion/processor.py`
- [PDF Loader](https://github.com/shu0209/agentic-rag/blob/main/app/ingestion/loaders/pdf_loader.py): `app/ingestion/loaders/pdf_loader.py`
- [HTML Loader](https://github.com/shu0209/agentic-rag/blob/main/app/ingestion/loaders/html_loader.py): `app/ingestion/loaders/html_loader.py`
- [Office Loader](https://github.com/shu0209/agentic-rag/blob/main/app/ingestion/loaders/office_loader.py): `app/ingestion/loaders/office_loader.py`
- [Text Loader](https://github.com/shu0209/agentic-rag/blob/main/app/ingestion/loaders/text_loader.py): `app/ingestion/loaders/text_loader.py`
- [Text Chunker](https://github.com/shu0209/agentic-rag/blob/main/app/ingestion/chunking/splitter.py): `app/ingestion/chunking/splitter.py`

### Retrieval Services

- [Embedding Service](https://github.com/shu0209/agentic-rag/blob/main/app/services/retrieval/embeddings.py): `app/services/retrieval/embeddings.py`
- [Vector Search](https://github.com/shu0209/agentic-rag/blob/main/app/services/retrieval/qdrant_service.py): `app/services/retrieval/qdrant_service.py`
- [Document Reranker](https://github.com/shu0209/agentic-rag/blob/main/app/services/retrieval/ranking_service.py): `app/services/retrieval/ranking_service.py`
- **Qdrant Store**

### Other components

- **User**
- **Knowledge Sources**

## Connections

- User → Chat UI: asks (evidence: `README.md`)
- Chat UI → FastAPI API: submits query (evidence: `README.md`)
- User → FastAPI API: queries (evidence: `README.md`)
- FastAPI API → Guardrails Gate: gates request (evidence: `README.md`)
- Guardrails Gate → Guardrail Flows: uses flows (evidence: `app/guardrails/rails.py`)
- Guardrails Gate → Agent Graph: passes allowed query (evidence: `README.md`)
- Agent Graph → Intent Planner: runs first (evidence: `app/agents/graph.py`)
- Agent Graph → Context Retriever: routes technical query (evidence: `app/agents/graph.py`)
- Agent Graph → Answer Generator: routes conversational query (evidence: `app/agents/graph.py`)
- Agent Graph → Answer Generator: routes after retrieval (evidence: `app/agents/graph.py`)
- Agent Graph → Conversation State: checks state (evidence: `app/agents/graph.py`)
- Intent Planner → Conversation State: reads and updates (evidence: `app/agents/nodes/planner.py`)
- Context Retriever → Conversation State: reads and updates (evidence: `app/agents/nodes/retriever.py`)
- Answer Generator → Conversation State: reads and updates (evidence: `app/agents/nodes/responder.py`)
- Intent Planner → LLM Gateway: gets LLM (evidence: `app/agents/nodes/planner.py`)
- Answer Generator → LLM Gateway: uses gateway (evidence: `README.md`)
- Context Retriever → Vector Search: searches (evidence: `app/agents/nodes/retriever.py`)
- Context Retriever → Document Reranker: reranks results (evidence: `app/agents/nodes/retriever.py`)
- Vector Search → Embedding Service: embeds query (evidence: `app/services/retrieval/qdrant_service.py`)
- Vector Search → Qdrant Store: queries (evidence: `app/services/retrieval/qdrant_service.py`)
- Ingestion Processor → PDF Loader: parses PDF (evidence: `app/ingestion/processor.py`)
- Ingestion Processor → HTML Loader: parses HTML (evidence: `app/ingestion/processor.py`)
- Ingestion Processor → Office Loader: parses Office (evidence: `app/ingestion/processor.py`)
- Ingestion Processor → Text Loader: parses text (evidence: `app/ingestion/processor.py`)
- Ingestion Processor → Text Chunker: chunks text (evidence: `app/ingestion/processor.py`)
- Ingestion Processor → Embedding Service: embeds chunks (evidence: `app/ingestion/processor.py`)
- Ingestion Processor → Qdrant Store: upserts vectors (evidence: `app/ingestion/processor.py`)
- Knowledge Sources → Ingestion Processor: provides files (evidence: `README.md`)
