# ictnlp/auto-rag architecture

> Architecture diagram of the GitHub repository ictnlp/auto-rag, 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/ictnlp/auto-rag
- Repository: https://github.com/ictnlp/auto-rag

## Overview

##### Main Components
a. Auto-RAG Core Module:
- This is represented by the files within the Auto-RAG directory: “autorag.py,” “prompts.py,” and “gui.py.”
- It embodies the core logic for iterative retrieval interaction, decision-making, and answer generation.
b. LLM Inference Component:
- The deployed language model (using vLLM as described in the deployment scripts). This component handles model inference.
c. Retriever Component:
- External to the core module, likely based on methods from the DPR project.
- It interacts with a knowledge base (in this case, the wiki corpus) using the configuration (e.g., FAISS index and dense retriever setup).
d. GUI Layer:
- Provided by “gui.py” and supported via scripts (e.g., run_gui.sh), this component offers a dashboard or browser-based interface that allows users to input queries and view the iterative dialogue between the Auto-RAG and the retriever.
e. FlexRAG Integration:
- As shown by the instructions in the README, Auto-RAG can operate as a FlexRAG assistant. This indicates integration points where Auto-RAG acts as a pluggable module within a larger retrieval-generation framework.
f. Scripts & Deployment:
- Deployment scripts (deploy.sh, prepare_retriever.sh, run_evaluation.sh, run_gui.sh) tie all components together, ensuring proper initialization and communication among the components. They are critical for configuring the environment, model parameters, and integrations (e.g., vLLM’s GPU settings).

##### Relationships and Interactions
- User Interaction:
- The user accesses the GUI (or initiates a command-line session) which triggers GUI components in the Auto-RAG module.
- Core Processing:
- The Auto-RAG core module processes the input and decides if additional retrieval is needed.
- It sends queries to the Retriever component.
- Retrieval Iteration:
- The retriever (using pre-built indices and configurations defined in the scripts) returns relevant external knowledge.
- The Auto-RAG core incorporates this information in an iterative dialogue with the LLM component.
- LLM Inference:
- The language model (deployed with vLLM) processes inputs based on the iterative dialogue and generates final answers.
- Optional FlexRAG Integration:
- For users running Auto-RAG as a FlexRAG assistant, there is an integration layer where Auto-RAG’s config and responses are piped into the broader FlexRAG framework.

##### Architectural Patterns and Design Principles
- Modular Design:
- Each component (GUI, core logic, retriever, LLM inference) is separated into individual modules or scripts for clarity and maintainability.
- Iterative / Autonomous Loop:
- The system is designed to perform iterative queries until it is satisfied with the external knowledge that has been gathered.
- Loose Coupling:
- There is a clear separation between the client layer (GUI) and the backend (LLM, retriever), which aids in deployment and testing.

##### Relevant Technologies and Frameworks
- Python 3.12
- flexRAG for integration
- vLLM for model deployment/inference
- FAISS (for indexing) and DPR (for retriever setup)
- Shell scripting for deployment and evaluation processes

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    User("User"):::user
    GUI("GUI Interface"):::gui

    %% Auto-RAG Core Subgraph with internal modules
    subgraph "Auto-RAG Core"
        AA["Logic (autorag.py)"]:::core
        AP["Prompts (prompts.py)"]:::core
        AG["Core GUI (gui.py)"]:::core
    end

    %% External Components
    RETR("Retriever Service"):::external
    LLM("LLM Inference (vLLM)"):::external
    FLEX("FlexRAG Integration"):::external
    SCRIPTS("Scripts & Deployment"):::script

    %% Data flow and interactions
    User -->|"uses"| GUI
    GUI -->|"initiates"| AA
    AA -->|"sends_query"| RETR
    RETR -->|"returns_data"| AA
    AA -->|"sends_input"| LLM
    LLM -->|"produces_answer"| AA
    AA -->|"integrates"| FLEX

    %% Deployment configuration arrows
    SCRIPTS -->|"configures"| AA
    SCRIPTS -->|"configures"| RETR
    SCRIPTS -->|"configures"| LLM
    SCRIPTS -->|"configures"| GUI

    %% Click Events for Component Mapping
    click AA "https://github.com/ictnlp/auto-rag/blob/main/Auto-RAG/autorag.py"
    click AP "https://github.com/ictnlp/auto-rag/blob/main/Auto-RAG/prompts.py"
    click AG "https://github.com/ictnlp/auto-rag/blob/main/Auto-RAG/gui.py"
    click GUI "https://github.com/ictnlp/auto-rag/blob/main/scripts/run_gui.sh"
    click RETR "https://github.com/ictnlp/auto-rag/blob/main/scripts/prepare_retriever.sh"
    click LLM "https://github.com/ictnlp/auto-rag/blob/main/scripts/deploy.sh"
    click FLEX "https://github.com/ictnlp/auto-rag/blob/main/scripts/deploy.sh"
    click SCRIPTS "https://github.com/ictnlp/auto-rag/blob/main/scripts/deploy.sh"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef gui fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef script fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef user fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
```
