# ahmadalameri-0/rag_against_the_machine architecture

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

- Interactive diagram: https://gitdiagram.com/ahmadalameri-0/rag_against_the_machine
- Repository: https://github.com/ahmadalameri-0/rag_against_the_machine

## Overview

This repository is a small retrieval-augmented generation application over a vLLM source corpus. Its workflow indexes source files into validated chunks with character spans, retrieves top-k matches using BM25, then uses those source spans and the query to generate grounded answers with a local Qwen model. The README also documents batch search, answer generation, and recall evaluation. Relationship evidence comes from the README and SOURCE INDEX; implementation details beyond the shown excerpts are not inferred.

Main entry points: [`src/generator.py`](https://github.com/ahmadalameri-0/rag_against_the_machine/blob/main/src/generator.py) (Answer Generator), [`src/__main__.py`](https://github.com/ahmadalameri-0/rag_against_the_machine/blob/main/src/__main__.py) (CLI Workflows), [`src/retriever.py`](https://github.com/ahmadalameri-0/rag_against_the_machine/blob/main/src/retriever.py) (BM25 Retriever), [`src/indexer.py`](https://github.com/ahmadalameri-0/rag_against_the_machine/blob/main/src/indexer.py) (Indexer and Chunker)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_index["Indexing"]
  node_corpus["vLLM Corpus<br/>[vllm-0.10.1]"]
  node_indexer["Indexer and Chunker<br/>[indexer.py]"]
  node_index_store[("Processed Index")]
end

subgraph group_query["Retrieval"]
  node_retriever["BM25 Retriever<br/>[retriever.py]"]
  node_context["Ranked Source Spans"]
end

subgraph group_answer["Generation"]
  node_generator["Answer Generator<br/>[generator.py]"]
  node_qwen["Qwen Model"]
  node_answer_result["Grounded Answer"]
end

subgraph group_contracts["Schemas and CLI"]
  node_schemas["Pydantic Schemas<br/>[models.py]"]
  node_cli["CLI Workflows<br/>[__main__.py]"]
  node_evaluation["Recall Evaluation"]
end

node_user(("User"))

node_user -->|"runs commands"| node_cli
node_cli -->|"starts indexing"| node_indexer
node_corpus -->|"provides files"| node_indexer
node_indexer -->|"persists chunks"| node_index_store
node_cli -->|"starts search"| node_retriever
node_index_store -->|"supplies chunks"| node_retriever
node_retriever -->|"ranks top-k"| node_context
node_cli -->|"starts answering"| node_generator
node_context -->|"provides spans"| node_generator
node_user -->|"provides query"| node_generator
node_generator -->|"prompts model"| node_qwen
node_qwen -->|"generates answer"| node_answer_result
node_generator -->|"formats result"| node_answer_result
node_indexer -.->|"validates chunks"| node_schemas
node_retriever -->|"validates results"| node_schemas
node_generator -->|"validates answer"| node_schemas
node_cli -->|"runs evaluation"| node_evaluation
node_retriever -.->|"provides rankings"| node_evaluation

click node_corpus "https://github.com/ahmadalameri-0/rag_against_the_machine/tree/main/data/raw/vllm-0.10.1"
click node_indexer "https://github.com/ahmadalameri-0/rag_against_the_machine/blob/main/src/indexer.py"
click node_retriever "https://github.com/ahmadalameri-0/rag_against_the_machine/blob/main/src/retriever.py"
click node_generator "https://github.com/ahmadalameri-0/rag_against_the_machine/blob/main/src/generator.py"
click node_schemas "https://github.com/ahmadalameri-0/rag_against_the_machine/blob/main/src/models.py"
click node_cli "https://github.com/ahmadalameri-0/rag_against_the_machine/blob/main/src/__main__.py"
click node_evaluation "https://github.com/ahmadalameri-0/rag_against_the_machine/tree/main/src"

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_corpus,node_indexer,node_index_store,node_user toneBlue
class node_retriever,node_context toneAmber
class node_generator,node_qwen,node_answer_result toneMint
class node_schemas,node_cli,node_evaluation toneRose
```

## Components

### Indexing

- [vLLM Corpus](https://github.com/ahmadalameri-0/rag_against_the_machine/tree/main/data/raw/vllm-0.10.1): `data/raw/vllm-0.10.1`
- [Indexer and Chunker](https://github.com/ahmadalameri-0/rag_against_the_machine/blob/main/src/indexer.py): `src/indexer.py`
- **Processed Index**

### Retrieval

- [BM25 Retriever](https://github.com/ahmadalameri-0/rag_against_the_machine/blob/main/src/retriever.py): `src/retriever.py`
- **Ranked Source Spans**

### Generation

- [Answer Generator](https://github.com/ahmadalameri-0/rag_against_the_machine/blob/main/src/generator.py): `src/generator.py`
- **Qwen Model**
- **Grounded Answer**

### Schemas and CLI

- [Pydantic Schemas](https://github.com/ahmadalameri-0/rag_against_the_machine/blob/main/src/models.py): `src/models.py`
- [CLI Workflows](https://github.com/ahmadalameri-0/rag_against_the_machine/blob/main/src/__main__.py): `src/__main__.py`
- [Recall Evaluation](https://github.com/ahmadalameri-0/rag_against_the_machine/tree/main/src): `src`

### Other components

- **User**

## Connections

- User → CLI Workflows: runs commands
- CLI Workflows → Indexer and Chunker: starts indexing (evidence: `src/__main__.py`)
- vLLM Corpus → Indexer and Chunker: provides files
- Indexer and Chunker → Processed Index: persists chunks
- CLI Workflows → BM25 Retriever: starts search (evidence: `src/__main__.py`)
- Processed Index → BM25 Retriever: supplies chunks
- BM25 Retriever → Ranked Source Spans: ranks top-k
- CLI Workflows → Answer Generator: starts answering
- Ranked Source Spans → Answer Generator: provides spans
- User → Answer Generator: provides query
- Answer Generator → Qwen Model: prompts model
- Qwen Model → Grounded Answer: generates answer
- Answer Generator → Grounded Answer: formats result
- Indexer and Chunker → Pydantic Schemas: validates chunks
- BM25 Retriever → Pydantic Schemas: validates results (evidence: `src/retriever.py`)
- Answer Generator → Pydantic Schemas: validates answer (evidence: `src/generator.py`)
- CLI Workflows → Recall Evaluation: runs evaluation (evidence: `src/__main__.py`)
- BM25 Retriever → Recall Evaluation: provides rankings (evidence: `src/retriever.py`)
