# kalikousik-14/simple-rag-pipeline architecture

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

- Interactive diagram: https://gitdiagram.com/kalikousik-14/simple-rag-pipeline
- Repository: https://github.com/kalikousik-14/simple-rag-pipeline

## Overview

##### Project type and purpose
- This is a Python‐based Retrieval-Augmented Generation (RAG) pipeline exposed as a Flask web API.
- Purpose: accept user-uploaded documents (PDF/TXT), chunk and embed them into a FAISS vector store, then answer user queries using either a local LLM or the OpenAI API.

##### File structure
Top-level files and directories:
- app.py            – Flask application defining three endpoints
- ingest.py         – Document ingestion and chunking logic
- embed.py          – Embedding logic (sentence-transformers)
- index/            – Serialized vector store (faiss.index) and chunk metadata (chunks.pkl)
- model_loader.py   – Loads local quantized LLM (Mistral)
- query_local.py    – Query pipeline invoking the local LLM
- query_openai.py   – Query pipeline invoking OpenAI’s GPT-3.5-turbo
- data/             – Storage for raw uploaded files (e.g., data/resume.pdf)
- .env, requirements.txt, README.md

##### Key architecture points from the README
- Upload API (/upload) performs parsing (PyPDF2/fopen), chunking (~300–500 tokens), embedding, FAISS indexing.
- Query APIs (/ask_local, /ask_openai) perform:
a. Vector similarity search against FAISS
b. Prompt assembly with relevant chunks
c. LLM invocation (local vs. OpenAI) → answer

##### Main components and their interactions
a. Clients
- Users or API clients (curl, Postman, frontend)
- Send POST /upload, /ask_local, /ask_openai
b. Flask API layer (app.py)
- Routes requests to the ingestion or query submodules
c. Ingestion pipeline
- ingest.py → parse → chunk
- embed.py → sentence-transformers embedding
- FAISS vector store in index/
d. Retrieval pipeline
- FAISS similarity search
- Returns top-k chunk embeddings + text
e. LLM inference
- model_loader.py loads local Mistral with transformers
- query_local.py builds prompt & runs local LLM
- query_openai.py builds prompt & calls OpenAI API
f. Persistence
- data/ for original documents
- index/ for vector index and chunk metadata
g. External services
- OpenAI API (gpt-3.5-turbo)
- (Optionally) any hosted local LLM dependencies

##### Architectural patterns
- Modular pipeline: ingestion, vector store, retrieval, inference
- Separation of concerns: parsing/chunking vs. embedding vs. indexing vs. querying
- Simple service façade (Flask) exposing HTTP endpoints

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    Client["Client\n(curl, Postman, Frontend)"]:::external

    %% Flask API Façade
    API["Flask API Layer\napp.py\nEndpoints: /upload, /ask_local, /ask_openai"]:::compute
    click API "https://github.com/kalikousik-14/simple-rag-pipeline/blob/main/app.py"

    %% Ingestion Subsystem
    subgraph "Ingestion Subsystem" 
        direction TB
        Ingest["Parsing & Chunking\ningest.py\n(PyPDF2)"]:::compute
        click Ingest "https://github.com/kalikousik-14/simple-rag-pipeline/blob/main/ingest.py"
        Embed["Embedding\nembed.py\n(sentence-transformers)"]:::compute
        click Embed "https://github.com/kalikousik-14/simple-rag-pipeline/blob/main/embed.py"
    end

    %% Storage
    DataStore["Raw Document Storage\ndata/\n(data/resume.pdf)"]:::storage
    click DataStore "https://github.com/kalikousik-14/simple-rag-pipeline/tree/main/data/"
    IndexStore["FAISS Vector Store\nindex/\n(faiss.index, chunks.pkl)"]:::storage
    click IndexStore "https://github.com/kalikousik-14/simple-rag-pipeline/tree/main/index/"

    %% Retrieval Subsystem
    subgraph "Retrieval Subsystem"
        direction TB
        Retrieve["Vector Similarity Search\n+ Prompt Assembly"]:::compute
        QueryLocal["Local LLM Query\nquery_local.py"]:::compute
        click QueryLocal "https://github.com/kalikousik-14/simple-rag-pipeline/blob/main/query_local.py"
        QueryOpenAI["OpenAI LLM Query\nquery_openai.py"]:::compute
        click QueryOpenAI "https://github.com/kalikousik-14/simple-rag-pipeline/blob/main/query_openai.py"
    end

    %% LLM Subsystem
    subgraph "LLM Subsystem"
        direction TB
        Loader["Local LLM Loader\nmodel_loader.py\n(transformers)"]:::optional
        click Loader "https://github.com/kalikousik-14/simple-rag-pipeline/blob/main/model_loader.py"
        LocalLLM["Quantized Mistral\n(local)"]:::optional
        ExternalAPI["OpenAI API\n(gpt-3.5-turbo)"]:::external
    end

    %% Flows
    Client -->|"POST /upload\nPDF/TXT file"| API
    API -->|"Invoke Ingestion"| Ingest
    Ingest -->|"Raw file"| DataStore
    Ingest -->|"Chunks"| Embed
    Embed -->|"Embeddings"| IndexStore

    Client -->|"POST /ask_local\nQuery"| API
    Client -->|"POST /ask_openai\nQuery"| API

    API -->|"Perform Retrieval"| Retrieve
    Retrieve -->|"Top-k chunks"| QueryLocal
    Retrieve -->|"Top-k chunks"| QueryOpenAI

    Loader -->|"Loads model"| LocalLLM
    LocalLLM --> QueryLocal
    ExternalAPI --> QueryOpenAI

    QueryLocal -->|"Answer JSON"| API
    QueryOpenAI -->|"Answer JSON"| API
    API -->|"Response"| Client

    %% Styles
    classDef compute fill:#BBDEFB,stroke:#1E88E5,stroke-width:1px
    classDef storage fill:#C8E6C9,stroke:#2E7D32,stroke-width:1px
    classDef external fill:#FFCC80,stroke:#E65100,stroke-width:1px
    classDef optional fill:#E1BEE7,stroke:#8E24AA,stroke-width:2px,stroke-dasharray: 5 5
```
