# af011/technical-manual-rag-comparison architecture

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

- Interactive diagram: https://gitdiagram.com/af011/technical-manual-rag-comparison
- Repository: https://github.com/af011/technical-manual-rag-comparison

## Overview

##### Project Type and Purpose
- This is a research‐oriented Jupyter Notebook project comparing two Retrieval-Augmented Generation (RAG) techniques—reranking and fusion retrieval—applied to the Fervi T999 technical manual.
- The “rag_techniques_comparison.ipynb” drives the entire workflow: loading docs, building indices, running retrieval pipelines, evaluating answer quality.

##### Core Components
a. Data Ingestion & Preprocessing
- Raw technical manual (PDF or text)
- Text split/parsing module
- Tokenization & normalization
b. Indexing Layer
- BM25 index (e.g., Whoosh, Elasticsearch)
- Vector index (e.g., FAISS, Annoy)
c. Retrieval Pipelines
- Baseline RAG (simple vector search + generative model)
- Reranking pipeline
– First pass: initial retrieval (BM25 or vector)
– Cross-encoder model for reordering top-K docs
- Fusion retrieval pipeline
– Parallel BM25 + vector retrieval
– Score fusion (weighted by α parameter)
d. Language Model / Generator
- LLM interface (e.g., OpenAI, local transformer)
- Prompt templating & response formatting
e. Evaluation & Analysis
- Answer quality metrics (precision, recall, relevance)
- Parameter sweep for α values
- Comparative charts & qualitative summaries
f. Orchestration & Notebook Interface
- Jupyter notebook as control plane
- Sequence of cells driving each pipeline and logging results

##### Relationships & Data Flows
- Two parallel flows from Query Input:
- Flow A: Query → BM25 index → Top-K docs → Cross-encoder → Reranked docs → LLM → Reranking answers
- Flow B: Query → BM25 & Vector indices in parallel → Score fusion (α) → Top-K fused docs → LLM → Fusion answers
- Evaluation block consumes outputs from Baseline, Reranking, and Fusion pipelines and produces comparative plots and tables

##### Architectural Patterns & Design Principles
- Modular retrieval components, enabling plug-and-play of different indexers or reranker models
- Separation of concerns: indexing, retrieval, reranking/fusion, generation, and evaluation are distinct layers
- Parameterization: α value controlling fusion behavior, top-K sizing for reranker

- Baseline (→ Vector Index → LLM → Baseline Answers)
- Reranking (→ BM25 or Vector → Cross-Encoder → LLM → Reranking Answers)
- Fusion (→ BM25 & Vector → Fusion Scorer [α] → LLM → Fusion Answers)
5. Fusion component with “α parameter sweep” and the Reranking component with “top-K reordering.”

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "rag_techniques_comparison.ipynb – Orchestration Layer"
        style Notebook stroke:#000,stroke-dasharray:5 5
        Notebook["Jupyter Notebook Orchestration"]:::orchestration

        TechManual["Technical Manual (Fervi T999)"]:::preprocess
        Preprocessing["Preprocessing (Split, Tokenize)"]:::preprocess
        BM25["BM25 Index"]:::preprocess
        Vector["Vector Index (FAISS)"]:::preprocess

        Query["User Query"]:::retrieve

        Baseline_Retrieval["Baseline: Vector Search"]:::retrieve
        Initial_Retrieval["Initial Retrieval (BM25/Vector)"]:::retrieve
        CrossEncoder["Cross-Encoder Reranker (top-K reordering)"]:::retrieve

        Fusion_Retrieval["Parallel BM25 & Vector Retrieval"]:::fusion
        FusionScorer["Fusion Scorer (α parameter sweep)"]:::fusion

        LLM["LLM Interface & Generation"]:::genEval

        Baseline_Ans["Baseline Answers"]:::genEval
        Rerank_Ans["Reranking Answers"]:::genEval
        Fusion_Ans["Fusion Answers"]:::genEval

        Evaluation["Evaluation & Analysis"]:::genEval

        Notebook --> TechManual
        Notebook --> Query
        Notebook --> Evaluation

        TechManual --> Preprocessing
        Preprocessing --> BM25
        Preprocessing --> Vector

        Query --> Baseline_Retrieval
        Baseline_Retrieval --> LLM
        LLM --> Baseline_Ans

        Query --> Initial_Retrieval
        Initial_Retrieval --> CrossEncoder
        CrossEncoder --> LLM
        LLM --> Rerank_Ans

        Query --> Fusion_Retrieval
        Fusion_Retrieval --> FusionScorer
        FusionScorer --> LLM
        LLM --> Fusion_Ans

        Baseline_Ans --> Evaluation
        Rerank_Ans --> Evaluation
        Fusion_Ans --> Evaluation
    end

    Overview["Project Overview & Instructions"]:::orchestration

    classDef preprocess fill:#ADD8E6,stroke:#000;
    classDef retrieve fill:#90EE90,stroke:#000;
    classDef fusion fill:#FFA500,stroke:#000;
    classDef genEval fill:#DDA0DD,stroke:#000;
    classDef orchestration fill:#FFFFFF,stroke:#000;

    click Notebook "https://github.com/af011/technical-manual-rag-comparison/blob/AF-011/rag_techniques_comparison.ipynb"
    click Preprocessing "https://github.com/af011/technical-manual-rag-comparison/blob/AF-011/rag_techniques_comparison.ipynb"
    click BM25 "https://github.com/af011/technical-manual-rag-comparison/blob/AF-011/rag_techniques_comparison.ipynb"
    click Vector "https://github.com/af011/technical-manual-rag-comparison/blob/AF-011/rag_techniques_comparison.ipynb"
    click Baseline_Retrieval "https://github.com/af011/technical-manual-rag-comparison/blob/AF-011/rag_techniques_comparison.ipynb"
    click Initial_Retrieval "https://github.com/af011/technical-manual-rag-comparison/blob/AF-011/rag_techniques_comparison.ipynb"
    click CrossEncoder "https://github.com/af011/technical-manual-rag-comparison/blob/AF-011/rag_techniques_comparison.ipynb"
    click Fusion_Retrieval "https://github.com/af011/technical-manual-rag-comparison/blob/AF-011/rag_techniques_comparison.ipynb"
    click FusionScorer "https://github.com/af011/technical-manual-rag-comparison/blob/AF-011/rag_techniques_comparison.ipynb"
    click LLM "https://github.com/af011/technical-manual-rag-comparison/blob/AF-011/rag_techniques_comparison.ipynb"
    click Evaluation "https://github.com/af011/technical-manual-rag-comparison/blob/AF-011/rag_techniques_comparison.ipynb"
    click Overview "https://github.com/af011/technical-manual-rag-comparison/blob/AF-011/README.md"
```
