# labdmitriy/llm-rag architecture

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

- Interactive diagram: https://gitdiagram.com/labdmitriy/llm-rag
- Repository: https://github.com/labdmitriy/llm-rag

## Overview

##### Project type and purpose
- This is a Python library and tutorial suite for “RAG From Scratch,” a Retrieval‐Augmented Generation (RAG) framework built on top of LangGraph.
- It provides:
- An indexing subsystem (converts documents into vector embeddings)
- A collection of RAG “graph” pipelines (various query‐translation and generation strategies)
- Demo notebooks to show each RAG variant in action

##### File structure
- Top‐level:
- `.env.example`, `README.md`, `pyproject.toml`, `requirements.txt` (configuration & packaging)
- `notebooks/` (Jupyter tutorials)
- `src/llm_rag/` (core library)
- Inside `src/llm_rag/`:
- `indexing/` (article ingestion, multi‐vector, RAPTOR, self‐query, ColBERT model adapters)
- `graphs/` (one folder per RAG strategy: multi_query, rag_fusion, decomposition, step_back, hyde, routing, etc.)
- `utils.py` (shared utilities)
- No web frontend or database schemas—this is a modular Python package, not a web app.

##### README for additional insights
- Specifies how to configure `.env` for API keys, how to install via `pip` or `uv`.
- Links each graph submodule to its Jupyter demo.
- Mentions external dependencies: LLM APIs (OpenAI, Hugging Face), vector stores (FAISS, Pinecone), ColBERT.

1. Configuration & CLI
- `.env` loader
- `uv` command‐line interface or direct Python import
2. Data Stores
- Vector database (FAISS / Pinecone / Weaviate)
- (Optionally) local file store for raw documents
3. Indexing Subsystem
- `llm_rag.indexing` modules
- Embedding model(s)
- Multi‐vector / CRAG / RAPTOR adapters
- Writes to Vector DB
4. Graph Execution Engine
- `llm_rag.graphs` subpackages
- Each graph implements a retrieval‐generation pipeline:
- Query → Query‐translation (multi‐query, decomposition, routing, step_back, hyde, etc.)
- Retrieval from Vector DB
- LLM generation step(s)
- Orchestrated by LangGraph core
5. LLM Service(s)
- OpenAI / Hugging Face APIs
6. Developer Interface
- Jupyter Notebooks
- Python SDK (import `llm_rag` in scripts)

1. Config → CLI/SDK (loads API keys, settings)
2. Raw Documents → Indexing Subsystem → Vector DB
3. User Query → Graph Execution Engine
→ (1) Query‐translation modules → (2) Vector DB retrieval → (3) LLM Service
→ Graph aggregates and fuses responses → returns final answer → User
4. Notebooks ↔ CLI/SDK (invoke indexing and graph functions interactively)

c. Architectural Patterns & Design Principles
- Modular design: separate “indexing” vs. “graph” concerns
- Strategy pattern: each RAG variant is a pluggable graph subpackage
- Dependency inversion: graph modules depend on abstract embedding & retrieval interfaces
- Single responsibility: each submodule does one variant of query translation or indexing

d. Relevant Technologies
- Python 3.x, `pip`, `uv` (packaging & CLI)
- LangGraph (core orchestration)
- Vector DBs: FAISS, Pinecone, Weaviate (configurable)
- LLM APIs: OpenAI, Hugging Face
- ColBERT (optional late‐interaction retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Configuration & Packaging
    subgraph "Configuration & Packaging"
        envLoader[".env Loader"]:::blue
        envExample[".env.example"]:::blue
        pyproject["pyproject.toml"]:::blue
        requirements["requirements.txt"]:::blue
    end

    %% Developer Interface
    subgraph "Developer Interface"
        notebooks["Jupyter Notebooks"]:::orange
        pythonSDK["Python SDK (import llm_rag)"]:::orange
    end

    %% Indexing Subsystem
    subgraph "Indexing Subsystem" 
        article["article.py"]:::blue
        colbertIdx["colbert_model.py"]:::blue
        reflection["reflection.py"]:::blue
        selfQueryIdx["self_query.py"]:::blue
        subgraph "Multi‐Vector Indexing"
            mvSummary["summary.py"]:::blue
            mvChunks["chunks.py"]:::blue
            mvHypo["hypothetical_questions.py"]:::blue
        end
        subgraph "RAPTOR Indexing"
            raptor["raptor.py"]:::blue
            raptorUtils["utils.py"]:::blue
        end
    end

    %% Graph Execution Engine
    subgraph "Graph Execution Engine"
        subgraph "RAG Strategies"
            mq["multi_query.py"]:::blue
            rf["rag_fusion.py"]:::blue
            decRec["recursive.py"]:::blue
            decPar["parallel.py"]:::blue
            stepBack["step_back.py"]:::blue
            hyde["hyde.py"]:::blue
            routeLog["logical.py"]:::blue
            routeSem["semantic.py"]:::blue
            selfRAG["self_rag.py"]:::blue
            crag["crag.py"]:::blue
            colbertGraph["colbert_model.py"]:::blue
            subgraph "Multi‐Vector Retrieval"
                gvSummary["summary.py"]:::blue
                gvChunks["chunks.py"]:::blue
                gvHypo["hypothetical_questions.py"]:::blue
            end
            qcSelf["self_query.py"]:::blue
        end
    end

    %% External Services
    VectorDB(("Vector DB")):::green
    LLMService(("LLM APIs")):::green

    %% Data Flow
    envLoader -->|loads config| pythonSDK
    notebooks -->|invoke SDK| pythonSDK
    pythonSDK -->|raw documents| article
    article -->|documents| mvSummary
    reflection --> mvChunks
    selfQueryIdx --> mvHypo
    raptor --> raptorUtils
    mvSummary -->|embeddings| VectorDB
    mvChunks -->|embeddings| VectorDB
    mvHypo -->|embeddings| VectorDB
    raptorUtils -->|embeddings| VectorDB
    colbertIdx -->|embeddings| VectorDB

    pythonSDK -->|user query| mq
    mq -->|query| VectorDB
    rf -->|query| VectorDB
    decRec -->|query| VectorDB
    decPar -->|query| VectorDB
    stepBack -->|query| VectorDB
    hyde -->|query| VectorDB
    routeLog -->|query| VectorDB
    routeSem -->|query| VectorDB
    selfRAG -->|query| VectorDB
    crag -->|query| VectorDB
    colbertGraph -->|query| VectorDB
    gvSummary -->|query| VectorDB
    gvChunks -->|query| VectorDB
    gvHypo -->|query| VectorDB
    qcSelf -->|query| VectorDB

    VectorDB -->|retrieved docs| mq
    VectorDB --> rf
    VectorDB --> decRec
    VectorDB --> decPar
    VectorDB --> stepBack
    VectorDB --> hyde
    VectorDB --> routeLog
    VectorDB --> routeSem
    VectorDB --> selfRAG
    VectorDB --> crag
    VectorDB --> colbertGraph
    VectorDB --> gvSummary
    VectorDB --> gvChunks
    VectorDB --> gvHypo
    VectorDB --> qcSelf

    mq -->|prompt| LLMService
    rf -->|prompt| LLMService
    decRec -->|prompt| LLMService
    decPar -->|prompt| LLMService
    stepBack -->|prompt| LLMService
    hyde -->|prompt| LLMService
    routeLog -->|prompt| LLMService
    routeSem -->|prompt| LLMService
    selfRAG -->|prompt| LLMService
    crag -->|prompt| LLMService
    colbertGraph -->|prompt| LLMService
    gvSummary -->|prompt| LLMService
    gvChunks -->|prompt| LLMService
    gvHypo -->|prompt| LLMService
    qcSelf -->|prompt| LLMService

    LLMService -->|generated text| mq
    LLMService --> rf
    LLMService --> decRec
    LLMService --> decPar
    LLMService --> stepBack
    LLMService --> hyde
    LLMService --> routeLog
    LLMService --> routeSem
    LLMService --> selfRAG
    LLMService --> crag
    LLMService --> colbertGraph
    LLMService --> gvSummary
    LLMService --> gvChunks
    LLMService --> gvHypo
    LLMService --> qcSelf

    mq -->|response| pythonSDK
    rf -->|response| pythonSDK
    decRec -->|response| pythonSDK
    decPar -->|response| pythonSDK
    stepBack -->|response| pythonSDK
    hyde -->|response| pythonSDK
    routeLog -->|response| pythonSDK
    routeSem -->|response| pythonSDK
    selfRAG -->|response| pythonSDK
    crag -->|response| pythonSDK
    colbertGraph -->|response| pythonSDK
    gvSummary -->|response| pythonSDK
    gvChunks -->|response| pythonSDK
    gvHypo -->|response| pythonSDK
    qcSelf -->|response| pythonSDK

    %% Click Events
    click envExample "https://github.com/labdmitriy/llm-rag/blob/master/.env.example"
    click pyproject "https://github.com/labdmitriy/llm-rag/blob/master/pyproject.toml"
    click requirements "https://github.com/labdmitriy/llm-rag/blob/master/requirements.txt"
    click notebooks "https://github.com/labdmitriy/llm-rag/tree/master/notebooks/rag-from-scratch/"
    click article "https://github.com/labdmitriy/llm-rag/blob/master/src/llm_rag/indexing/article.py"
    click colbertIdx "https://github.com/labdmitriy/llm-rag/blob/master/src/llm_rag/indexing/colbert_model.py"
    click reflection "https://github.com/labdmitriy/llm-rag/blob/master/src/llm_rag/indexing/reflection.py"
    click selfQueryIdx "https://github.com/labdmitriy/llm-rag/blob/master/src/llm_rag/indexing/self_query.py"
    click mvSummary "https://github.com/labdmitriy/llm-rag/blob/master/src/llm_rag/indexing/multi_vector/summary.py"
    click mvChunks "https://github.com/labdmitriy/llm-rag/blob/master/src/llm_rag/indexing/multi_vector/chunks.py"
    click mvHypo "https://github.com/labdmitriy/llm-rag/blob/master/src/llm_rag/indexing/multi_vector/hypothetical_questions.py"
    click raptor "https://github.com/labdmitriy/llm-rag/blob/master/src/llm_rag/indexing/raptor/raptor.py"
    click raptorUtils "https://github.com/labdmitriy/llm-rag/blob/master/src/llm_rag/indexing/raptor/utils.py"
    click mq "https://github.com/labdmitriy/llm-rag/blob/master/src/llm_rag/graphs/multi_query/multi_query.py"
    click rf "https://github.com/labdmitriy/llm-rag/blob/master/src/llm_rag/graphs/rag_fusion/rag_fusion.py"
    click decRec "https://github.com/labdmitriy/llm-rag/blob/master/src/llm_rag/graphs/decomposition/recursive.py"
    click decPar "https://github.com/labdmitriy/llm-rag/blob/master/src/llm_rag/graphs/decomposition/parallel.py"
    click stepBack "https://github.com/labdmitriy/llm-rag/blob/master/src/llm_rag/graphs/step_back/step_back.py"
    click hyde "https://github.com/labdmitriy/llm-rag/blob/master/src/llm_rag/graphs/hyde/hyde.py"
    click routeLog "https://github.com/labdmitriy/llm-rag/blob/master/src/llm_rag/graphs/routing/logical.py"
    click routeSem "https://github.com/labdmitriy/llm-rag/blob/master/src/llm_rag/graphs/routing/semantic.py"
    click selfRAG "https://github.com/labdmitriy/llm-rag/blob/master/src/llm_rag/graphs/self_rag/self_rag.py"
    click colbertGraph "https://github.com/labdmitriy/llm-rag/blob/master/src/llm_rag/graphs/colbert/colbert_model.py"
    click crag "https://github.com/labdmitriy/llm-rag/blob/master/src/llm_rag/graphs/crag/crag.py"
    click gvSummary "https://github.com/labdmitriy/llm-rag/blob/master/src/llm_rag/graphs/multi_vector/summary.py"
    click gvChunks "https://github.com/labdmitriy/llm-rag/blob/master/src/llm_rag/graphs/multi_vector/chunks.py"
    click gvHypo "https://github.com/labdmitriy/llm-rag/blob/master/src/llm_rag/graphs/multi_vector/hypothetical_questions.py"
    click qcSelf "https://github.com/labdmitriy/llm-rag/blob/master/src/llm_rag/graphs/query_construction/self_query.py"

    %% Styles
    classDef blue fill:#D6EFFF,stroke:#6A8FB1,color:#000
    classDef green fill:#D5F5E3,stroke:#2E7D32,color:#000
    classDef orange fill:#FFE5B4,stroke:#FFA500,color:#000
```
