# ictnlp/flexrag architecture

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

- Interactive diagram: https://gitdiagram.com/ictnlp/flexrag
- Repository: https://github.com/ictnlp/flexrag

## Overview

##### Main Components Identification
The system should be divided into these core components:

a. Data Processing Layer
- Document Parsing
- Chunking
- Text Processing
- Dataset Management

b. Retrieval Layer
- Dense Retrievers
- Sparse Retrievers (BM25)
- Web Retrievers
- Index Management (FAISS, Annoy, SCANN)

c. Generation Layer
- Multiple LLM Integrations (OpenAI, Anthropic, Cohere, etc.)
- Model Management

d. Assistant Layer
- Different Assistant Types (Basic, ChatQA, Document Chat, Modular RAG)
- Assistant Configuration Management

e. Supporting Systems
- Caching System
- Metrics and Evaluation
- Configuration Management

##### Component Relationships

**[Data Layer] → [Retrieval Layer] → [Assistant Layer] ← [Generation Layer]**
- ↑
- [Supporting Systems] ─┘

##### Specific Implementation Details

- Rectangles: Core components (Data, Retrieval, Generation, Assistant)
- Hexagons: Supporting systems
- Rounded rectangles: External services (LLMs)

- Blue: Core processing components
- Green: Data management
- Orange: External integrations
- Purple: Supporting systems

##### Flow Representation

Main data flows:
**Raw Data → Processing → Indexed Storage → Retrieval → Context Selection → Generation → Response**

Parallel flows for:
- Cache hits/misses
- Multiple retrieval strategies
- Evaluation metrics collection

##### Key Technical Elements to Highlight

a. Integration Points:
- Multiple LLM providers
- Various index types
- Different retrieval strategies

b. Configuration Management:
- Hydra-core integration
- Dataclass-based configs

c. Performance Features:
- Persistent cache system
- Async operations
- Batch processing

##### Architectural Patterns

Emphasize:
- Modular design pattern
- Plugin architecture for models
- Factory pattern for assistants
- Strategy pattern for retrievers

##### Detail Level: Data flows and processing steps

- Component types
- Connection types
- Implementation options

Remember to highlight the multimodal capabilities and the ability to handle various data types, as these are key differentiating features of FlexRAG.

This architecture should be represented in a way that emphasizes both the framework's flexibility and its high-performance characteristics, while maintaining clarity about how the components interact to deliver RAG functionality.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles and classes
    classDef core fill:#3498db,stroke:#2980b9,color:white
    classDef data fill:#2ecc71,stroke:#27ae60,color:white
    classDef external fill:#e67e22,stroke:#d35400,color:white
    classDef support fill:#9b59b6,stroke:#8e44ad,color:white
    classDef storage fill:#95a5a6,stroke:#7f8c8d,color:white

    %% Data Processing Layer
    subgraph DataLayer["Data Processing Layer"]
        DocParser["Document Parser"]
        Chunking["Chunking System"]
        TextProc["Text Processing"]
        DatasetMgmt["Dataset Management"]
    end

    %% Retrieval Layer
    subgraph RetrievalLayer["Retrieval Layer"]
        DenseRet["Dense Retriever"]
        SparseRet["Sparse Retriever (BM25)"]
        WebRet["Web Retrievers"]
        IndexMgmt["Index Management"]
        IndexStore[(Index Storage)]:::storage
    end

    %% Generation Layer
    subgraph GenerationLayer["Generation Layer"]
        OpenAI["OpenAI LLM"]
        Anthropic["Anthropic LLM"]
        Cohere["Cohere LLM"]
        ModelMgmt["Model Management"]
    end

    %% Assistant Layer
    subgraph AssistantLayer["Assistant Layer"]
        BasicAsst["Basic Assistant"]
        ChatQA["ChatQA Assistant"]
        DocChat["Document Chat"]
        ModularRAG["Modular RAG"]
    end

    %% Supporting Systems
    subgraph SupportSystems["Supporting Systems"]
        Cache[(Cache System)]:::storage
        Metrics["Metrics & Evaluation"]
        ContextRefine["Context Refinement"]
        Prompts["Prompt Management"]
        Ranking["Ranking System"]
    end

    %% Relationships
    DataLayer --> RetrievalLayer
    RetrievalLayer --> AssistantLayer
    GenerationLayer --> AssistantLayer
    SupportSystems --> AssistantLayer

    %% Component Classes
    class DocParser,Chunking,TextProc,DatasetMgmt data
    class DenseRet,SparseRet,WebRet,IndexMgmt core
    class OpenAI,Anthropic,Cohere external
    class BasicAsst,ChatQA,DocChat,ModularRAG core
    class Cache,Metrics,ContextRefine,Prompts,Ranking support

    %% Click Events
    click DocParser "https://github.com/ictnlp/flexrag/tree/master/src/flexrag/data/document_parser/"
    click Chunking "https://github.com/ictnlp/flexrag/tree/master/src/flexrag/data/chunking/"
    click TextProc "https://github.com/ictnlp/flexrag/tree/master/src/flexrag/data/text_process/"
    click DatasetMgmt "https://github.com/ictnlp/flexrag/blob/master/src/flexrag/data/dataset.py"
    click DenseRet "https://github.com/ictnlp/flexrag/blob/master/src/flexrag/retriever/dense_retriever.py"
    click SparseRet "https://github.com/ictnlp/flexrag/blob/master/src/flexrag/retriever/bm25s_retriever.py"
    click WebRet "https://github.com/ictnlp/flexrag/tree/master/src/flexrag/retriever/web_retrievers/"
    click IndexMgmt "https://github.com/ictnlp/flexrag/tree/master/src/flexrag/retriever/index/"
    click OpenAI "https://github.com/ictnlp/flexrag/blob/master/src/flexrag/models/openai_model.py"
    click Anthropic "https://github.com/ictnlp/flexrag/blob/master/src/flexrag/models/anthropic_model.py"
    click Cohere "https://github.com/ictnlp/flexrag/blob/master/src/flexrag/models/cohere_model.py"
    click BasicAsst "https://github.com/ictnlp/flexrag/blob/master/src/flexrag/assistant/basic_assistant.py"
    click ChatQA "https://github.com/ictnlp/flexrag/blob/master/src/flexrag/assistant/chatqa_assistant.py"
    click DocChat "https://github.com/ictnlp/flexrag/blob/master/src/flexrag/assistant/document_chat_assistant.py"
    click ModularRAG "https://github.com/ictnlp/flexrag/blob/master/src/flexrag/assistant/modular_rag_assistant.py"
    click Cache "https://github.com/ictnlp/flexrag/tree/master/src/flexrag/cache/"
    click Metrics "https://github.com/ictnlp/flexrag/tree/master/src/flexrag/metrics/"
    click ContextRefine "https://github.com/ictnlp/flexrag/tree/master/src/flexrag/context_refine/"
    click Prompts "https://github.com/ictnlp/flexrag/tree/master/src/flexrag/prompt/"
    click Ranking "https://github.com/ictnlp/flexrag/tree/master/src/flexrag/ranker/"
```
