# nepseli/langchain-rag-agent architecture

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

- Interactive diagram: https://gitdiagram.com/nepseli/langchain-rag-agent
- Repository: https://github.com/nepseli/langchain-rag-agent

## Overview

This is a Streamlit-based financial-document RAG agent. Users upload documents for extraction and indexing, then ask questions; the agent may clarify ambiguity, retrieve evidence, fetch structured tables, execute calculations, and generate cited answers. The graph preserves the documented workflow and major OCR, table, HyDE, comparative-retrieval, and per-document-cap capabilities. Some feature details and call paths are documented rather than shown in sampled source, so unverified relationships are omitted.

Main entry points: [`core/agent/graph.py`](https://github.com/nepseli/langchain-rag-agent/blob/main/core/agent/graph.py) (Agent workflow), [`core/ingestion/pipeline.py`](https://github.com/nepseli/langchain-rag-agent/blob/main/core/ingestion/pipeline.py) (Ingestion pipeline), [`app/streamlit_app.py`](https://github.com/nepseli/langchain-rag-agent/blob/main/app/streamlit_app.py) (Chat and uploads), [`core/retrieval/vector_store.py`](https://github.com/nepseli/langchain-rag-agent/blob/main/core/retrieval/vector_store.py) (Vector index)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_streamlit["Chat and uploads<br/>[streamlit_app.py]"]
  node_config["Runtime settings<br/>[config.py]"]
end

subgraph group_ingestion["Document ingestion"]
  node_pipeline["Ingestion pipeline<br/>[pipeline.py]"]
  node_loader["Document loaders<br/>[document_loader.py]"]
  node_ocr["OCR supplement<br/>[ocr.py]"]
  node_tables["Table extraction<br/>[table_extractor.py]"]
  node_chunker["Text and table chunks<br/>[chunker.py]"]
end

subgraph group_agent["Question answering"]
  node_workflow["Agent workflow<br/>[graph.py]"]
  node_clarity["Clarity check<br/>[nodes.py]"]
  node_clarify["Clarification response<br/>[nodes.py]"]
  node_classify["Query classification<br/>[nodes.py]"]
  node_rewrite["HyDE rewriting<br/>[nodes.py]"]
  node_retrieve["Chunk retrieval<br/>[nodes.py]"]
  node_fetch_tables["Table data fetch<br/>[nodes.py]"]
  node_calculate["Calculation execution<br/>[nodes.py]"]
  node_generate["Answer generation<br/>[nodes.py]"]
end

subgraph group_storage["Retrieval and state"]
  node_schemas["Document data models<br/>[schemas.py]"]
  node_metadata[("Metadata and chat store<br/>[metadata_store.py]")]
  node_vectors[("Vector index<br/>[vector_store.py]")]
end

node_user(("User"))
node_llm{{"OpenAI models"}}

node_user -->|"uploads and asks"| node_streamlit
node_streamlit -->|"ingests uploads"| node_pipeline
node_streamlit -->|"invokes questions"| node_workflow
node_streamlit -->|"lists documents"| node_metadata
node_streamlit -->|"deletes indexed chunks"| node_vectors
node_pipeline -->|"loads files"| node_loader
node_pipeline -->|"supplements page text"| node_ocr
node_pipeline -->|"extracts tables"| node_tables
node_pipeline -->|"creates chunks"| node_chunker
node_pipeline -->|"records documents and tables"| node_metadata
node_pipeline -->|"indexes chunks"| node_vectors
node_workflow -->|"registers first node"| node_clarity
node_workflow -->|"routes unclear queries"| node_clarify
node_workflow -->|"routes clear queries"| node_classify
node_workflow -->|"routes classified queries"| node_rewrite
node_workflow -->|"routes rewritten queries"| node_retrieve
node_workflow -->|"routes table queries"| node_fetch_tables
node_workflow -->|"routes calculations"| node_calculate
node_workflow -->|"routes answer generation"| node_generate
node_clarity -->|"checks indexed documents"| node_metadata
node_classify -->|"classifies query"| node_llm
node_rewrite -->|"generates hypothetical answer"| node_llm
node_retrieve -->|"searches chunks"| node_vectors
node_fetch_tables -->|"loads table data"| node_metadata
node_calculate -->|"generates calculation code"| node_llm
node_generate -->|"generates cited answer"| node_llm
node_streamlit -->|"creates chat session"| node_metadata
node_pipeline -->|"creates document records"| node_schemas
node_vectors -->|"embeds chunks and queries"| node_llm
node_config -->|"configures embedding model"| node_vectors

click node_streamlit "https://github.com/nepseli/langchain-rag-agent/blob/main/app/streamlit_app.py"
click node_config "https://github.com/nepseli/langchain-rag-agent/blob/main/config.py"
click node_pipeline "https://github.com/nepseli/langchain-rag-agent/blob/main/core/ingestion/pipeline.py"
click node_loader "https://github.com/nepseli/langchain-rag-agent/blob/main/core/ingestion/document_loader.py"
click node_ocr "https://github.com/nepseli/langchain-rag-agent/blob/main/core/ingestion/ocr.py"
click node_tables "https://github.com/nepseli/langchain-rag-agent/blob/main/core/ingestion/table_extractor.py"
click node_chunker "https://github.com/nepseli/langchain-rag-agent/blob/main/core/ingestion/chunker.py"
click node_schemas "https://github.com/nepseli/langchain-rag-agent/blob/main/models/schemas.py"
click node_workflow "https://github.com/nepseli/langchain-rag-agent/blob/main/core/agent/graph.py"
click node_clarity "https://github.com/nepseli/langchain-rag-agent/blob/main/core/agent/nodes.py"
click node_clarify "https://github.com/nepseli/langchain-rag-agent/blob/main/core/agent/nodes.py"
click node_classify "https://github.com/nepseli/langchain-rag-agent/blob/main/core/agent/nodes.py"
click node_rewrite "https://github.com/nepseli/langchain-rag-agent/blob/main/core/agent/nodes.py"
click node_retrieve "https://github.com/nepseli/langchain-rag-agent/blob/main/core/agent/nodes.py"
click node_fetch_tables "https://github.com/nepseli/langchain-rag-agent/blob/main/core/agent/nodes.py"
click node_calculate "https://github.com/nepseli/langchain-rag-agent/blob/main/core/agent/nodes.py"
click node_generate "https://github.com/nepseli/langchain-rag-agent/blob/main/core/agent/nodes.py"
click node_metadata "https://github.com/nepseli/langchain-rag-agent/blob/main/core/retrieval/metadata_store.py"
click node_vectors "https://github.com/nepseli/langchain-rag-agent/blob/main/core/retrieval/vector_store.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_config,node_user toneBlue
class node_pipeline,node_loader,node_ocr,node_tables,node_chunker toneAmber
class node_workflow,node_clarity,node_clarify,node_classify,node_rewrite,node_retrieve,node_fetch_tables,node_calculate,node_generate toneMint
class node_schemas,node_metadata,node_vectors toneRose
class node_llm toneIndigo
```

## Components

### User interface

- [Chat and uploads](https://github.com/nepseli/langchain-rag-agent/blob/main/app/streamlit_app.py): `app/streamlit_app.py`
- [Runtime settings](https://github.com/nepseli/langchain-rag-agent/blob/main/config.py): `config.py`

### Document ingestion

- [Ingestion pipeline](https://github.com/nepseli/langchain-rag-agent/blob/main/core/ingestion/pipeline.py): `core/ingestion/pipeline.py`
- [Document loaders](https://github.com/nepseli/langchain-rag-agent/blob/main/core/ingestion/document_loader.py): `core/ingestion/document_loader.py`
- [OCR supplement](https://github.com/nepseli/langchain-rag-agent/blob/main/core/ingestion/ocr.py): `core/ingestion/ocr.py`
- [Table extraction](https://github.com/nepseli/langchain-rag-agent/blob/main/core/ingestion/table_extractor.py): `core/ingestion/table_extractor.py`
- [Text and table chunks](https://github.com/nepseli/langchain-rag-agent/blob/main/core/ingestion/chunker.py): `core/ingestion/chunker.py`

### Question answering

- [Agent workflow](https://github.com/nepseli/langchain-rag-agent/blob/main/core/agent/graph.py): `core/agent/graph.py`
- [Clarity check](https://github.com/nepseli/langchain-rag-agent/blob/main/core/agent/nodes.py): `core/agent/nodes.py`
- [Clarification response](https://github.com/nepseli/langchain-rag-agent/blob/main/core/agent/nodes.py): `core/agent/nodes.py`
- [Query classification](https://github.com/nepseli/langchain-rag-agent/blob/main/core/agent/nodes.py): `core/agent/nodes.py`
- [HyDE rewriting](https://github.com/nepseli/langchain-rag-agent/blob/main/core/agent/nodes.py): `core/agent/nodes.py`
- [Chunk retrieval](https://github.com/nepseli/langchain-rag-agent/blob/main/core/agent/nodes.py): `core/agent/nodes.py`
- [Table data fetch](https://github.com/nepseli/langchain-rag-agent/blob/main/core/agent/nodes.py): `core/agent/nodes.py`
- [Calculation execution](https://github.com/nepseli/langchain-rag-agent/blob/main/core/agent/nodes.py): `core/agent/nodes.py`
- [Answer generation](https://github.com/nepseli/langchain-rag-agent/blob/main/core/agent/nodes.py): `core/agent/nodes.py`

### Retrieval and state

- [Document data models](https://github.com/nepseli/langchain-rag-agent/blob/main/models/schemas.py): `models/schemas.py`
- [Metadata and chat store](https://github.com/nepseli/langchain-rag-agent/blob/main/core/retrieval/metadata_store.py): `core/retrieval/metadata_store.py`
- [Vector index](https://github.com/nepseli/langchain-rag-agent/blob/main/core/retrieval/vector_store.py): `core/retrieval/vector_store.py`

### Other components

- **User**
- **OpenAI models**

## Connections

- User → Chat and uploads: uploads and asks (evidence: `README.md`)
- Chat and uploads → Ingestion pipeline: ingests uploads (evidence: `app/streamlit_app.py`)
- Chat and uploads → Agent workflow: invokes questions (evidence: `app/streamlit_app.py`)
- Chat and uploads → Metadata and chat store: lists documents (evidence: `app/streamlit_app.py`)
- Chat and uploads → Vector index: deletes indexed chunks (evidence: `app/streamlit_app.py`)
- Ingestion pipeline → Document loaders: loads files (evidence: `core/ingestion/pipeline.py`)
- Ingestion pipeline → OCR supplement: supplements page text (evidence: `core/ingestion/pipeline.py`)
- Ingestion pipeline → Table extraction: extracts tables (evidence: `core/ingestion/pipeline.py`)
- Ingestion pipeline → Text and table chunks: creates chunks (evidence: `core/ingestion/pipeline.py`)
- Ingestion pipeline → Metadata and chat store: records documents and tables (evidence: `core/ingestion/pipeline.py`)
- Ingestion pipeline → Vector index: indexes chunks (evidence: `core/ingestion/pipeline.py`)
- Agent workflow → Clarity check: registers first node (evidence: `core/agent/graph.py`)
- Agent workflow → Clarification response: routes unclear queries (evidence: `core/agent/graph.py`)
- Agent workflow → Query classification: routes clear queries (evidence: `core/agent/graph.py`)
- Agent workflow → HyDE rewriting: routes classified queries (evidence: `core/agent/graph.py`)
- Agent workflow → Chunk retrieval: routes rewritten queries (evidence: `core/agent/graph.py`)
- Agent workflow → Table data fetch: routes table queries (evidence: `core/agent/graph.py`)
- Agent workflow → Calculation execution: routes calculations (evidence: `core/agent/graph.py`)
- Agent workflow → Answer generation: routes answer generation (evidence: `core/agent/graph.py`)
- Clarity check → Metadata and chat store: checks indexed documents (evidence: `core/agent/nodes.py`)
- Query classification → OpenAI models: classifies query (evidence: `core/agent/nodes.py`)
- HyDE rewriting → OpenAI models: generates hypothetical answer (evidence: `README.md`)
- Chunk retrieval → Vector index: searches chunks (evidence: `core/agent/nodes.py`)
- Table data fetch → Metadata and chat store: loads table data (evidence: `core/agent/graph.py`)
- Calculation execution → OpenAI models: generates calculation code (evidence: `core/agent/nodes.py`)
- Answer generation → OpenAI models: generates cited answer (evidence: `core/agent/nodes.py`)
- Chat and uploads → Metadata and chat store: creates chat session (evidence: `app/streamlit_app.py`)
- Ingestion pipeline → Document data models: creates document records (evidence: `core/ingestion/pipeline.py`)
- Vector index → OpenAI models: embeds chunks and queries (evidence: `core/retrieval/vector_store.py`)
- Runtime settings → Vector index: configures embedding model (evidence: `config.py`)
