# kottoization/rag-llm architecture

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

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

## Overview

##### Project Type & Purpose
- The project is an artificial intelligence application that uses a combination of Retrieval-Augmented Generation (RAG) and a Large Language Model (LLM) to answer questions using data from Medium articles.
- Its main purpose is to handle user queries and generate answers by processing and embedding content from a CSV file (data/medium.csv).

##### File Structure Analysis
- The project contains a few key components:
- main.py: Acts as the entry point of the application. It likely manages the overall flow of receiving a query, processing data, retrieving relevant content, and generating responses.
- data_operations.py: Likely responsible for handling operations on the data file (CSV), such as reading or writing embedded data.
- tools/embeddings.py and tools/prompts.py: These modules are used to create embeddings and manage prompt templates, which are critical to the RAG process. There is also a __pycache__ folder here indicating that these are executed Python modules.
- data/medium.csv: Contains the Medium articles data which the application uses to respond to queries.
- requirements.txt, .env configuration, and README indicate dependencies, environmental settings, and installation instructions, emphasizing the need for an external LLM service (i.e., the OpenAI API).

##### Key Architectural Components
a. User Interface/Entry Point:
- "User" sending input (questions) to the system.
- The main.py file drives this aspect where the user interacts with the application.

b. Data Management:
- The "Data" component showing the CSV file (data/medium.csv) storing Medium articles.
- data_operations.py for handling any processing or manipulation of the CSV content.

c. Core Processing Modules:
- The "Tools" module includes:
- embeddings.py: For generating or handling embeddings for the data.
- prompts.py: For managing the formulation of queries/prompts to be sent to the LLM.
- These tools are crucial as they bridge the gap between raw data and LLM input.

d. Integration with LLM and External Service:
- The system relies on an external LLM service (via the OpenAI API as seen from the .env configuration for OPENAI_API_KEY). This should be shown as an external block labeled "LLM Service" or "OpenAI API".
- That the application sends prompt/embedding issues to the LLM for generating final responses.

##### Relationships & Interactions
- A directional flow starting from the User initiating a query.
- main.py then calls functions within tools/embeddings.py and tools/prompts.py to convert data and formulate a proper query.
- The processed query is then sent to the external LLM service (OpenAI API) via an API call.
- The response from the LLM is then routed back through the main module to the user.
- Optionally, indicate that after processing, new embedded values may be saved in the CSV, reflecting a feedback loop.

##### Architectural Patterns & Design Principles
- Although the project structure is relatively simple, consider the following:
- Separation of Concerns: The main file only coordinates actions while data operations and tool modules handle specific tasks.
- Modularity: Each Python module (for data operations, embeddings, and prompts) is a distinct component, which can be easily extended or replaced.
- External Configuration: Emphasize the use of a .env file for secret configuration, reinforcing security and portability.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        UI["User/Input Interface (main.py)"]:::controller
    end

    %% Data Layer
    subgraph "Data Layer"
        CSV["Data Storage/CSV File (data/medium.csv)"]:::data
        DO["Data Operations Module (data_operations.py)"]:::core
    end

    %% Processing Tools Layer
    subgraph "Processing Tools"
        EMB["Embedding Module (tools/embeddings.py)"]:::tool
        PROM["Prompt Management Module (tools/prompts.py)"]:::tool
    end

    %% External Services Layer
    subgraph "External Services"
        LLM["LLM Service (OpenAI API)"]:::external
    end

    %% Data Flow
    UI -->|"triggers"| DO
    DO -->|"accesses"| CSV
    UI -->|"invokes"| EMB
    UI -->|"invokes"| PROM
    UI -->|"sendsQuery"| LLM
    LLM -->|"returnsResponse"| UI
    UI -->|"updatesData"| CSV

    %% Click Events
    click UI "https://github.com/kottoization/rag-llm/blob/new-main/main.py"
    click CSV "https://github.com/kottoization/rag-llm/blob/new-main/data/medium.csv"
    click DO "https://github.com/kottoization/rag-llm/blob/new-main/data_operations.py"
    click EMB "https://github.com/kottoization/rag-llm/blob/new-main/tools/embeddings.py"
    click PROM "https://github.com/kottoization/rag-llm/blob/new-main/tools/prompts.py"
    click LLM "https://github.com/kottoization/rag-llm/blob/new-main/.env"

    %% Styles
    classDef controller fill:#f9f,stroke:#333,stroke-width:2px;
    classDef data fill:#BBDEFB,stroke:#333,stroke-width:2px;
    classDef core fill:#C5CAE9,stroke:#333,stroke-width:2px;
    classDef tool fill:#C8E6C9,stroke:#333,stroke-width:2px;
    classDef external fill:#FFCDD2,stroke:#333,stroke-width:2px;
```
