# jlab-nlp/retrieval-augmented-correction architecture

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

- Interactive diagram: https://gitdiagram.com/jlab-nlp/retrieval-augmented-correction
- Repository: https://github.com/jlab-nlp/retrieval-augmented-correction

## Overview

##### Project type and purpose
- This is an open-source research pipeline (“Retrieval-Augmented-Correction”) rather than a full-stack web app.
- It implements the RAC method from the paper “Efficient LLM Factuality Correction with Retrieval Augmentation.”
- Its primary use case is to ingest benchmark datasets (TruthfulQA, FactScore), perform retrieval-augmented generation and correction of statements, and then evaluate factuality.

##### File structure
- Top-level directories and files:
- data/ – raw and processed datasets and retrieval outputs
- scripts/ – shell scripts orchestrating various runs (generation, retrieval, RAG, evaluation)
- src/ – core Python modules (retriever, generator, pipeline, evaluators, utils)
- setenv.sh, setup.sh – environment and dependency setup
- README.md, LICENSE, .gitignore
- Key src modules:
- retriever.py, google_search.py – fetches external documents
- generator.py, openai_generator.py – calls LLMs for generation
- pipeline*.py, refactor-pipe*.py – glue logic orchestrating the end-to-end flow
- factscore_*.py, truthfulqa_evaluator.py – evaluation logic
- components.py, task_utils.py, tpu_variables.py, cost_estimator.py – helper functions/config
- The sheer number of scripts indicates the pipeline is driven by shell wrappers around the Python code.

##### README for additional insights
- The README outlines:
- Environment setup (setenv.sh, setup.sh)
- CLI interface of refactor-pipe.py with flags for enabling/disabling each stage (generation, breakdown, verification, correction, RAG)
- Evaluation workflows for each benchmark

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Data"
        ID["Input Data Store"]:::data
    end

    subgraph "Retrieval Service"
        RET["retriever.py\nFetch Documents"]:::pipeline
        GS["google_search.py\nSearch API Wrapper"]:::pipeline
    end

    subgraph "Pipeline Orchestrator"
        RP["refactor-pipe.py\nOrchestrator"]:::pipeline
        P1["pipeline.py"]:::pipeline
        P2["pipeline2.py"]:::pipeline
        P3["pipeline3.py"]:::pipeline
    end

    subgraph "LLM Modules"
        GEN["generator.py\nGeneration Model"]:::pipeline
        OG["openai_generator.py\nOpenAI Client"]:::pipeline
        RM["run_models.py\nModel Runner"]:::pipeline
    end

    subgraph "External APIs"
        GAPI["Google Search API"]:::external
        OAPI["OpenAI API"]:::external
    end

    subgraph "Evaluation Modules"
        TQ["truthfulqa_evaluator.py"]:::eval
        FS["factscore_evaluator.py"]:::eval
        FB["factscore_bleu_rouge.py"]:::eval
        FD["factscore_data.py"]:::eval
    end

    subgraph "Scripts/CLI"
        SCR["scripts/ (shell wrappers)"]:::scripts
    end

    ID --> RET
    ID --> GS
    GS --> GAPI
    RET --> RP
    GS --> RP

    RP --> GEN
    RP --> RM
    GEN --> OAPI
    RM --> OAPI

    RP --> TQ
    RP --> FS
    RP --> FB
    RP --> FD

    SCR --> RP
    SCR --> TQ
    SCR --> FS

    classDef data fill:#f9f,stroke:#333,stroke-width:1px;
    classDef pipeline fill:#bbf,stroke:#333,stroke-width:1px;
    classDef external fill:#bfb,stroke:#333,stroke-width:1px;
    classDef eval fill:#fbb,stroke:#333,stroke-width:1px;
    classDef scripts fill:#ddd,stroke:#333,stroke-width:1px;

    click ID "https://github.com/jlab-nlp/retrieval-augmented-correction/tree/main/data/"
    click RET "https://github.com/jlab-nlp/retrieval-augmented-correction/blob/main/src/retriever.py"
    click GS "https://github.com/jlab-nlp/retrieval-augmented-correction/blob/main/src/google_search.py"
    click RP "https://github.com/jlab-nlp/retrieval-augmented-correction/blob/main/src/refactor-pipe.py"
    click P1 "https://github.com/jlab-nlp/retrieval-augmented-correction/blob/main/src/pipeline.py"
    click P2 "https://github.com/jlab-nlp/retrieval-augmented-correction/blob/main/src/pipeline2.py"
    click P3 "https://github.com/jlab-nlp/retrieval-augmented-correction/blob/main/src/pipeline3.py"
    click GEN "https://github.com/jlab-nlp/retrieval-augmented-correction/blob/main/src/generator.py"
    click OG "https://github.com/jlab-nlp/retrieval-augmented-correction/blob/main/src/openai_generator.py"
    click RM "https://github.com/jlab-nlp/retrieval-augmented-correction/blob/main/src/run_models.py"
    click TQ "https://github.com/jlab-nlp/retrieval-augmented-correction/blob/main/src/truthfulqa_evaluator.py"
    click FS "https://github.com/jlab-nlp/retrieval-augmented-correction/blob/main/src/factscore_evaluator.py"
    click FB "https://github.com/jlab-nlp/retrieval-augmented-correction/blob/main/src/factscore_bleu_rouge.py"
    click FD "https://github.com/jlab-nlp/retrieval-augmented-correction/blob/main/src/factscore_data.py"
    click SCR "https://github.com/jlab-nlp/retrieval-augmented-correction/tree/main/scripts/"
```
