# rahulanand1103/rag-citation architecture

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

- Interactive diagram: https://gitdiagram.com/rahulanand1103/rag-citation
- Repository: https://github.com/rahulanand1103/rag-citation

## Overview

##### Project Type and Purpose
- RAG Citation is an open-source Python library (not a web app) that augments Retrieval-Augmented Generation (RAG) pipelines by generating automatic citations via NLP and embedding-based semantic search.
- It exposes two key entry-points: the `CiteItem` data model (input container) and the `Inference` class (pipeline orchestrator).

##### File Structure Analysis
- Top level:
- `rag_citation/` – main package
- `test/` – unit tests
- Inside `rag_citation/`:
- `base_model/` – abstract and concrete embedding & spaCy NER models
- `focus_word/` – logic to extract and schema-validate NER focus words
- `score/` – scoring module to rank citation candidates & detect hallucination
- `schema.py` & `cite_item.py` – Pydantic-style data models
- `inference.py` – pipeline controller
- Configuration files: `requirements.txt`, `setup.py`, `makefile`

##### Key Insights from README
- Pipeline stages: format input → load spaCy & embedding model → NER extraction → semantic search → pair generation → scoring & hallucination check → output

##### Main Components and Their Interactions
a. Input Layer
- User / client code constructs a `CiteItem(answer, context[])`.
b. Inference Orchestrator (`inference.py`)
- Initializes spaCy model & embedding model (via factory methods in `base_model/`).
- Drives sequential sub-components.
c. Preprocessing & NER (`focus_word/`)
- Uses spaCy model to extract named entities from the answer.
d. Embedding & Semantic Search (`base_model/embedding_model.py`)
- Encodes context documents and answer sentences to vector space.
- Computes similarity scores against context.
e. Pair Generation (`pair/`)
- Matches answer sentences to top-k context chunks.
- Constructs intermediate pair objects with metadata.
f. Scoring & Hallucination Detection (`score/score.py`)
- Ranks candidate citations, applies threshold.
- Compares entities in answer vs. those found in context to flag hallucination / missing entities.
g. Output Layer
- Returns a structured result:
– `citation`: list of answer-sentence → cite_document mappings
– `hallucination`: boolean
– `missing`: list of un-matched entities

##### Architectural Patterns and Design Principles
- Modular pipeline: each stage in its own package folder
- Strategy/factory pattern for model selection (embeddings & spaCy)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Input & Schema"
        CiteItem["CiteItem\n(rag_citation/cite_item.py)"]:::core
        Schema["Core Schema\n(rag_citation/schema.py)"]:::core
    end

    subgraph "Inference"
        Inference["Inference Orchestrator\n(rag_citation/inference.py)"]:::core
    end

    subgraph "Preprocessing & NER"
        FocusWord["FocusWord Extraction\n(rag_citation/focus_word/focus_word.py)"]:::core
        FWSchema["FocusWord Schema\n(rag_citation/focus_word/schema.py)"]:::core
    end

    subgraph "Embedding & Semantic Search"
        BaseModel["BaseModel\n(rag_citation/base_model/base.py)"]:::core
        EmbeddingModel["EmbeddingModel\n(rag_citation/base_model/embedding_model.py)"]:::core
        SpacyModel["SpacyModel\n(rag_citation/base_model/spacy_model.py)"]:::core
    end

    subgraph "Pair Generation"
        GenPair["GeneratePair\n(rag_citation/pair/generate_pair.py)"]:::core
        PairFocus["FocusWordInCiteData\n(rag_citation/pair/focus_word_in_cite_data.py)"]:::core
        PairSchema["Pair Schema\n(rag_citation/pair/schema.py)"]:::core
    end

    Score["Scoring & Hallucination\n(rag_citation/score/score.py)"]:::core
    Output["Output Result\n(citation, hallucination, missing)"]:::io

    subgraph "External Libraries"
        SpaCy["spaCy"]:::ext
        SentTrans["SentenceTransformers"]:::ext
    end

    %% Data Flow
    CiteItem --> Inference
    Schema --> Inference

    Inference --> SpacyModel
    Inference --> EmbeddingModel
    Inference --> FocusWord

    SpaCy --> SpacyModel
    SpacyModel --> FocusWord
    FWSchema --> FocusWord

    EmbeddingModel --> GenPair
    FocusWord --> GenPair
    GenPair --> PairFocus
    GenPair --> PairSchema

    PairFocus --> Score
    PairSchema --> Score
    Score --> Output

    SentTrans --> EmbeddingModel

    %% Click Events
    click CiteItem "https://github.com/rahulanand1103/rag-citation/blob/main/rag_citation/cite_item.py"
    click Schema "https://github.com/rahulanand1103/rag-citation/blob/main/rag_citation/schema.py"
    click Inference "https://github.com/rahulanand1103/rag-citation/blob/main/rag_citation/inference.py"
    click FocusWord "https://github.com/rahulanand1103/rag-citation/blob/main/rag_citation/focus_word/focus_word.py"
    click FWSchema "https://github.com/rahulanand1103/rag-citation/blob/main/rag_citation/focus_word/schema.py"
    click BaseModel "https://github.com/rahulanand1103/rag-citation/blob/main/rag_citation/base_model/base.py"
    click EmbeddingModel "https://github.com/rahulanand1103/rag-citation/blob/main/rag_citation/base_model/embedding_model.py"
    click SpacyModel "https://github.com/rahulanand1103/rag-citation/blob/main/rag_citation/base_model/spacy_model.py"
    click GenPair "https://github.com/rahulanand1103/rag-citation/blob/main/rag_citation/pair/generate_pair.py"
    click PairFocus "https://github.com/rahulanand1103/rag-citation/blob/main/rag_citation/pair/focus_word_in_cite_data.py"
    click PairSchema "https://github.com/rahulanand1103/rag-citation/blob/main/rag_citation/pair/schema.py"
    click Score "https://github.com/rahulanand1103/rag-citation/blob/main/rag_citation/score/score.py"

    %% Styles
    classDef core fill:#D6E9F8,stroke:#1E4E8C,color:#1E4E8C
    classDef ext fill:#DFF0D8,stroke:#3C763D,color:#3C763D
    classDef io fill:#FCF8E3,stroke:#8A6D3B,color:#8A6D3B
```
