# 4d4mkhalil/rag-against-the-machine architecture

> Architecture diagram of the GitHub repository 4d4mkhalil/rag-against-the-machine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/4d4mkhalil/rag-against-the-machine
- Repository: https://github.com/4d4mkhalil/rag-against-the-machine

## Overview

This is a local RAG application for answering questions about the vLLM codebase. A user invokes the CLI, whose Pipeline builds or reuses indexes, searches with hybrid BM25 and FAISS retrieval, and can augment retrieved context into an answer; batch search, answer generation, and recall@k evaluation are also supported. Chunking, index construction, retrieval, augmentation, and generation are distinct stages. The graph follows documented workflows and sampled calls; batch/evaluation details not visible in the excerpts are linked only where the README documents them.

Main entry points: [`src/pipeline.py`](https://github.com/4d4mkhalil/rag-against-the-machine/blob/master/src/pipeline.py) (RAG workflows), [`src/indexer.py`](https://github.com/4d4mkhalil/rag-against-the-machine/blob/master/src/indexer.py) (Index construction), [`src/retriever.py`](https://github.com/4d4mkhalil/rag-against-the-machine/blob/master/src/retriever.py) (Hybrid retrieval), [`src/settings.py`](https://github.com/4d4mkhalil/rag-against-the-machine/blob/master/src/settings.py) (Runtime settings)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["CLI and orchestration"]
  node_cli["Command entry<br/>[__main__.py]"]
  node_pipeline["RAG workflows<br/>[pipeline.py]"]
  node_settings["Runtime settings<br/>[settings.py]"]
  node_models["Data models<br/>[models.py]"]
end

subgraph group_indexing["Corpus indexing"]
  node_chunker["Document chunking<br/>[chunker.py]"]
  node_indexer["Index construction<br/>[indexer.py]"]
  node_bm25[("BM25 index")]
  node_faiss[("FAISS index")]
  node_chunk_records[("Chunk records")]
end

subgraph group_retrieval["Hybrid retrieval"]
  node_retriever["Hybrid retrieval<br/>[retriever.py]"]
end

subgraph group_answers["Answering and evaluation"]
  node_augmenter["Context augmentation<br/>[aug_generator.py]"]
  node_llm["Local language model<br/>[llm.py]"]
  node_evaluation["Recall evaluation<br/>[pipeline.py]"]
end

node_user(("CLI user"))
node_source_docs["Source documents"]
node_questioner(("Questioner"))
node_datasets["Question datasets"]
node_results["Search and answer files"]

node_user -->|"invokes"| node_cli
node_cli -->|"dispatches"| node_pipeline
node_pipeline -->|"checks settings"| node_settings
node_pipeline -->|"builds index"| node_indexer
node_indexer -->|"loads chunks"| node_chunker
node_chunker -->|"reads files"| node_source_docs
node_indexer -->|"writes index"| node_bm25
node_indexer -->|"writes vectors"| node_faiss
node_indexer -->|"writes records"| node_chunk_records
node_indexer -->|"creates chunks"| node_models
node_pipeline -->|"requests search"| node_retriever
node_retriever -->|"searches index"| node_bm25
node_retriever -->|"searches vectors"| node_faiss
node_retriever -->|"loads records"| node_chunk_records
node_retriever -->|"returns chunks"| node_models
node_questioner -.->|"asks question"| node_pipeline
node_pipeline -->|"requests answer"| node_augmenter
node_augmenter -->|"generates text"| node_llm
node_pipeline -->|"reads context"| node_source_docs
node_pipeline -.->|"loads questions"| node_datasets
node_pipeline -.->|"writes outputs"| node_results
node_pipeline -.->|"evaluates recall"| node_evaluation
node_evaluation -.->|"compares ground truth"| node_datasets
node_evaluation -.->|"reads search results"| node_results
node_indexer -->|"uses configuration"| node_settings
node_retriever -->|"uses configuration"| node_settings
node_augmenter -->|"uses defaults"| node_settings
node_llm -->|"uses model config"| node_settings

click node_cli "https://github.com/4d4mkhalil/rag-against-the-machine/blob/master/src/__main__.py"
click node_pipeline "https://github.com/4d4mkhalil/rag-against-the-machine/blob/master/src/pipeline.py"
click node_settings "https://github.com/4d4mkhalil/rag-against-the-machine/blob/master/src/settings.py"
click node_models "https://github.com/4d4mkhalil/rag-against-the-machine/blob/master/src/models.py"
click node_chunker "https://github.com/4d4mkhalil/rag-against-the-machine/blob/master/src/chunker.py"
click node_indexer "https://github.com/4d4mkhalil/rag-against-the-machine/blob/master/src/indexer.py"
click node_retriever "https://github.com/4d4mkhalil/rag-against-the-machine/blob/master/src/retriever.py"
click node_augmenter "https://github.com/4d4mkhalil/rag-against-the-machine/blob/master/src/aug_generator.py"
click node_llm "https://github.com/4d4mkhalil/rag-against-the-machine/blob/master/src/llm.py"
click node_evaluation "https://github.com/4d4mkhalil/rag-against-the-machine/blob/master/src/pipeline.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_pipeline,node_settings,node_models,node_user toneBlue
class node_chunker,node_indexer,node_bm25,node_faiss,node_chunk_records toneAmber
class node_retriever toneMint
class node_augmenter,node_llm,node_evaluation toneRose
class node_source_docs,node_questioner,node_datasets,node_results toneIndigo
```

## Components

### CLI and orchestration

- [Command entry](https://github.com/4d4mkhalil/rag-against-the-machine/blob/master/src/__main__.py): `src/__main__.py`
- [RAG workflows](https://github.com/4d4mkhalil/rag-against-the-machine/blob/master/src/pipeline.py): `src/pipeline.py`
- [Runtime settings](https://github.com/4d4mkhalil/rag-against-the-machine/blob/master/src/settings.py): `src/settings.py`
- [Data models](https://github.com/4d4mkhalil/rag-against-the-machine/blob/master/src/models.py): `src/models.py`

### Corpus indexing

- [Document chunking](https://github.com/4d4mkhalil/rag-against-the-machine/blob/master/src/chunker.py): `src/chunker.py`
- [Index construction](https://github.com/4d4mkhalil/rag-against-the-machine/blob/master/src/indexer.py): `src/indexer.py`
- **BM25 index**
- **FAISS index**
- **Chunk records**

### Hybrid retrieval

- [Hybrid retrieval](https://github.com/4d4mkhalil/rag-against-the-machine/blob/master/src/retriever.py): `src/retriever.py`

### Answering and evaluation

- [Context augmentation](https://github.com/4d4mkhalil/rag-against-the-machine/blob/master/src/aug_generator.py): `src/aug_generator.py`
- [Local language model](https://github.com/4d4mkhalil/rag-against-the-machine/blob/master/src/llm.py): `src/llm.py`
- [Recall evaluation](https://github.com/4d4mkhalil/rag-against-the-machine/blob/master/src/pipeline.py): `src/pipeline.py`

### Other components

- **CLI user**
- **Source documents**
- **Questioner**
- **Question datasets**
- **Search and answer files**

## Connections

- CLI user → Command entry: invokes (evidence: `src/__main__.py`)
- Command entry → RAG workflows: dispatches (evidence: `src/__main__.py`)
- RAG workflows → Runtime settings: checks settings (evidence: `src/pipeline.py`)
- RAG workflows → Index construction: builds index (evidence: `src/pipeline.py`)
- Index construction → Document chunking: loads chunks (evidence: `src/indexer.py`)
- Document chunking → Source documents: reads files (evidence: `src/chunker.py`)
- Index construction → BM25 index: writes index (evidence: `src/indexer.py`)
- Index construction → FAISS index: writes vectors (evidence: `src/indexer.py`)
- Index construction → Chunk records: writes records (evidence: `src/indexer.py`)
- Index construction → Data models: creates chunks (evidence: `src/indexer.py`)
- RAG workflows → Hybrid retrieval: requests search (evidence: `src/pipeline.py`)
- Hybrid retrieval → BM25 index: searches index (evidence: `src/retriever.py`)
- Hybrid retrieval → FAISS index: searches vectors (evidence: `src/retriever.py`)
- Hybrid retrieval → Chunk records: loads records (evidence: `src/retriever.py`)
- Hybrid retrieval → Data models: returns chunks (evidence: `src/retriever.py`)
- Questioner → RAG workflows: asks question
- RAG workflows → Context augmentation: requests answer (evidence: `src/pipeline.py`)
- Context augmentation → Local language model: generates text (evidence: `src/aug_generator.py`)
- RAG workflows → Source documents: reads context (evidence: `src/pipeline.py`)
- RAG workflows → Question datasets: loads questions (evidence: `README.md`)
- RAG workflows → Search and answer files: writes outputs (evidence: `README.md`)
- RAG workflows → Recall evaluation: evaluates recall (evidence: `README.md`)
- Recall evaluation → Question datasets: compares ground truth (evidence: `README.md`)
- Recall evaluation → Search and answer files: reads search results (evidence: `README.md`)
- Index construction → Runtime settings: uses configuration (evidence: `src/indexer.py`)
- Hybrid retrieval → Runtime settings: uses configuration (evidence: `src/retriever.py`)
- Context augmentation → Runtime settings: uses defaults (evidence: `src/aug_generator.py`)
- Local language model → Runtime settings: uses model config (evidence: `src/llm.py`)