# saipawar0272/hybrid_rag architecture

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

- Interactive diagram: https://gitdiagram.com/saipawar0272/hybrid_rag
- Repository: https://github.com/saipawar0272/hybrid_rag

## Overview

This is an enterprise knowledge assistant with document indexing, conversational hybrid RAG, calculator/demo-weather function calling, and Streamlit, CLI, and HTTP entry points. Users submit a question with a thread ID; the graph routes it to knowledge retrieval, tools, or general chat, then returns an answer while retaining thread state. Ingestion builds the retrieval artifacts offline. The sampled sources show the API and graph internals; UI and CLI details and some README-described retrieval behavior are represented at their documented module level.

Main entry points: [`src/graph.py`](https://github.com/saipawar0272/hybrid_rag/blob/main/src/graph.py) (LangGraph workflow), [`src/hybrid_retriever.py`](https://github.com/saipawar0272/hybrid_rag/blob/main/src/hybrid_retriever.py) (Hybrid retriever), [`src/ingestion.py`](https://github.com/saipawar0272/hybrid_rag/blob/main/src/ingestion.py) (Document ingestion), [`api/main.py`](https://github.com/saipawar0272/hybrid_rag/blob/main/api/main.py) (FastAPI app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_streamlit["Streamlit chat<br/>[app.py]"]
  node_cli["Terminal CLI<br/>[cli.py]"]
end

subgraph group_index["Knowledge indexing"]
  node_documents["Source documents"]
  node_ingestion["Document ingestion<br/>[ingestion.py]"]
  node_faiss[("FAISS index")]
  node_chunks["Chunk metadata"]
end

subgraph group_workflow["Conversation workflow"]
  node_graph["LangGraph workflow<br/>[graph.py]"]
  node_router["Intent router<br/>[graph.py]"]
  node_rewriter["Query rewriting<br/>[graph.py]"]
  node_compressor["Context compression<br/>[graph.py]"]
  node_answer["Context answerer<br/>[graph.py]"]
  node_toolagent["Tool agent<br/>[graph.py]"]
  node_tools["Calculator and weather<br/>[tools.py]"]
  node_chat["General chat<br/>[graph.py]"]
  node_memory[("Thread checkpointer<br/>[graph.py]")]
end

subgraph group_retrieval["Hybrid retrieval"]
  node_retriever["Hybrid retriever"]
  node_reranker["Optional cross-encoder"]
end

subgraph group_support["API and configuration"]
  node_api["FastAPI app<br/>[main.py]"]
  node_query["Query endpoint<br/>[query.py]"]
  node_schemas["Request schemas<br/>[schemas.py]"]
  node_health["Health endpoint<br/>[health.py]"]
  node_dependency["Graph dependency<br/>[dependencies.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
end

node_user(("User"))
node_http(("HTTP client"))

node_user -->|"asks in"| node_streamlit
node_user -->|"asks in"| node_cli
node_user -->|"submits query"| node_http
node_http -->|"calls"| node_api
node_api -->|"registers"| node_health
node_api -->|"registers"| node_query
node_query -->|"validates and returns"| node_schemas
node_query -->|"gets graph"| node_dependency
node_api -->|"builds at startup"| node_graph
node_query -->|"invokes"| node_graph
node_streamlit -->|"invokes"| node_graph
node_cli -->|"invokes"| node_graph
node_documents -->|"loaded from"| node_ingestion
node_ingestion -->|"builds and saves"| node_faiss
node_ingestion -->|"writes"| node_chunks
node_graph -->|"dispatches to"| node_router
node_router -->|"routes RAG to"| node_rewriter
node_rewriter -->|"queries"| node_retriever
node_retriever -->|"loads and searches"| node_faiss
node_retriever -->|"loads for BM25"| node_chunks
node_retriever -.->|"optionally reranks"| node_reranker
node_retriever -->|"returns candidates to"| node_compressor
node_compressor -->|"supplies context to"| node_answer
node_router -->|"routes tools to"| node_toolagent
node_toolagent -->|"dispatches calls to"| node_tools
node_tools -->|"returns results to"| node_toolagent
node_router -->|"routes chat to"| node_chat
node_graph -->|"saves thread state"| node_memory
node_ingestion -->|"reads settings"| node_config
node_retriever -->|"reads settings"| node_config
node_graph -->|"reads model settings"| node_config

click node_streamlit "https://github.com/saipawar0272/hybrid_rag/blob/main/app.py"
click node_cli "https://github.com/saipawar0272/hybrid_rag/blob/main/src/cli.py"
click node_api "https://github.com/saipawar0272/hybrid_rag/blob/main/api/main.py"
click node_query "https://github.com/saipawar0272/hybrid_rag/blob/main/api/routes/query.py"
click node_schemas "https://github.com/saipawar0272/hybrid_rag/blob/main/api/schemas.py"
click node_health "https://github.com/saipawar0272/hybrid_rag/blob/main/api/routes/health.py"
click node_dependency "https://github.com/saipawar0272/hybrid_rag/blob/main/api/dependencies.py"
click node_config "https://github.com/saipawar0272/hybrid_rag/blob/main/src/config.py"
click node_documents "https://github.com/saipawar0272/hybrid_rag/tree/main/data"
click node_ingestion "https://github.com/saipawar0272/hybrid_rag/blob/main/src/ingestion.py"
click node_graph "https://github.com/saipawar0272/hybrid_rag/blob/main/src/graph.py"
click node_router "https://github.com/saipawar0272/hybrid_rag/blob/main/src/graph.py"
click node_rewriter "https://github.com/saipawar0272/hybrid_rag/blob/main/src/graph.py"
click node_compressor "https://github.com/saipawar0272/hybrid_rag/blob/main/src/graph.py"
click node_answer "https://github.com/saipawar0272/hybrid_rag/blob/main/src/graph.py"
click node_toolagent "https://github.com/saipawar0272/hybrid_rag/blob/main/src/graph.py"
click node_tools "https://github.com/saipawar0272/hybrid_rag/blob/main/src/tools.py"
click node_chat "https://github.com/saipawar0272/hybrid_rag/blob/main/src/graph.py"
click node_memory "https://github.com/saipawar0272/hybrid_rag/blob/main/src/graph.py"
click node_retriever "https://github.com/saipawar0272/hybrid_rag/blob/main/src/hybrid_retriever.py"
click node_reranker "https://github.com/saipawar0272/hybrid_rag/blob/main/src/hybrid_retriever.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_cli,node_user,node_http toneBlue
class node_documents,node_ingestion,node_faiss,node_chunks toneAmber
class node_graph,node_router,node_rewriter,node_compressor,node_answer,node_toolagent,node_tools,node_chat,node_memory toneMint
class node_retriever,node_reranker toneRose
class node_api,node_query,node_schemas,node_health,node_dependency,node_config toneIndigo
```

## Components

### User interfaces

- [Streamlit chat](https://github.com/saipawar0272/hybrid_rag/blob/main/app.py): `app.py`
- [Terminal CLI](https://github.com/saipawar0272/hybrid_rag/blob/main/src/cli.py): `src/cli.py`

### Knowledge indexing

- [Source documents](https://github.com/saipawar0272/hybrid_rag/tree/main/data): `data`
- [Document ingestion](https://github.com/saipawar0272/hybrid_rag/blob/main/src/ingestion.py): `src/ingestion.py`
- **FAISS index**
- **Chunk metadata**

### Conversation workflow

- [LangGraph workflow](https://github.com/saipawar0272/hybrid_rag/blob/main/src/graph.py): `src/graph.py`
- [Intent router](https://github.com/saipawar0272/hybrid_rag/blob/main/src/graph.py): `src/graph.py`
- [Query rewriting](https://github.com/saipawar0272/hybrid_rag/blob/main/src/graph.py): `src/graph.py`
- [Context compression](https://github.com/saipawar0272/hybrid_rag/blob/main/src/graph.py): `src/graph.py`
- [Context answerer](https://github.com/saipawar0272/hybrid_rag/blob/main/src/graph.py): `src/graph.py`
- [Tool agent](https://github.com/saipawar0272/hybrid_rag/blob/main/src/graph.py): `src/graph.py`
- [Calculator and weather](https://github.com/saipawar0272/hybrid_rag/blob/main/src/tools.py): `src/tools.py`
- [General chat](https://github.com/saipawar0272/hybrid_rag/blob/main/src/graph.py): `src/graph.py`
- [Thread checkpointer](https://github.com/saipawar0272/hybrid_rag/blob/main/src/graph.py): `src/graph.py`

### Hybrid retrieval

- [Hybrid retriever](https://github.com/saipawar0272/hybrid_rag/blob/main/src/hybrid_retriever.py): `src/hybrid_retriever.py`
- [Optional cross-encoder](https://github.com/saipawar0272/hybrid_rag/blob/main/src/hybrid_retriever.py): `src/hybrid_retriever.py`

### API and configuration

- [FastAPI app](https://github.com/saipawar0272/hybrid_rag/blob/main/api/main.py): `api/main.py`
- [Query endpoint](https://github.com/saipawar0272/hybrid_rag/blob/main/api/routes/query.py): `api/routes/query.py`
- [Request schemas](https://github.com/saipawar0272/hybrid_rag/blob/main/api/schemas.py): `api/schemas.py`
- [Health endpoint](https://github.com/saipawar0272/hybrid_rag/blob/main/api/routes/health.py): `api/routes/health.py`
- [Graph dependency](https://github.com/saipawar0272/hybrid_rag/blob/main/api/dependencies.py): `api/dependencies.py`
- [Runtime configuration](https://github.com/saipawar0272/hybrid_rag/blob/main/src/config.py): `src/config.py`

### Other components

- **User**
- **HTTP client**

## Connections

- User → Streamlit chat: asks in (evidence: `README.md`)
- User → Terminal CLI: asks in (evidence: `README.md`)
- User → HTTP client: submits query (evidence: `README.md`)
- HTTP client → FastAPI app: calls (evidence: `api/main.py`)
- FastAPI app → Health endpoint: registers (evidence: `api/main.py`)
- FastAPI app → Query endpoint: registers (evidence: `api/main.py`)
- Query endpoint → Request schemas: validates and returns (evidence: `api/routes/query.py`)
- Query endpoint → Graph dependency: gets graph (evidence: `api/routes/query.py`)
- FastAPI app → LangGraph workflow: builds at startup (evidence: `api/main.py`)
- Query endpoint → LangGraph workflow: invokes (evidence: `api/routes/query.py`)
- Streamlit chat → LangGraph workflow: invokes (evidence: `README.md`)
- Terminal CLI → LangGraph workflow: invokes (evidence: `README.md`)
- Source documents → Document ingestion: loaded from (evidence: `src/ingestion.py`)
- Document ingestion → FAISS index: builds and saves (evidence: `src/ingestion.py`)
- Document ingestion → Chunk metadata: writes (evidence: `src/ingestion.py`)
- LangGraph workflow → Intent router: dispatches to (evidence: `src/graph.py`)
- Intent router → Query rewriting: routes RAG to (evidence: `src/graph.py`)
- Query rewriting → Hybrid retriever: queries (evidence: `src/graph.py`)
- Hybrid retriever → FAISS index: loads and searches (evidence: `src/hybrid_retriever.py`)
- Hybrid retriever → Chunk metadata: loads for BM25 (evidence: `src/hybrid_retriever.py`)
- Hybrid retriever → Optional cross-encoder: optionally reranks (evidence: `src/hybrid_retriever.py`)
- Hybrid retriever → Context compression: returns candidates to (evidence: `src/graph.py`)
- Context compression → Context answerer: supplies context to (evidence: `src/graph.py`)
- Intent router → Tool agent: routes tools to (evidence: `src/graph.py`)
- Tool agent → Calculator and weather: dispatches calls to (evidence: `src/graph.py`)
- Calculator and weather → Tool agent: returns results to (evidence: `src/graph.py`)
- Intent router → General chat: routes chat to (evidence: `src/graph.py`)
- LangGraph workflow → Thread checkpointer: saves thread state (evidence: `src/graph.py`)
- Document ingestion → Runtime configuration: reads settings (evidence: `src/ingestion.py`)
- Hybrid retriever → Runtime configuration: reads settings (evidence: `src/hybrid_retriever.py`)
- LangGraph workflow → Runtime configuration: reads model settings (evidence: `src/graph.py`)
