# vaisax/refrag architecture

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

- Interactive diagram: https://gitdiagram.com/vaisax/refrag
- Repository: https://github.com/vaisax/refrag

## Overview

REFRAG is a compact RAG context-compression implementation. Its main workflow accepts retrieved passages, chunks them, encodes chunks, selects chunks for expansion, and returns compressed representations with statistics. The README also documents decoder-space projection and decoder use, plus a three-stage training simulation; these capabilities are represented at the level supported by documentation. The source excerpt omits parts of refrag.py, so uncertain internal wiring and any generated-response path are not detailed.

Main entry points: [`refrag.py`](https://github.com/vaisax/refrag/blob/main/refrag.py) (SimpleREFRAG)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_compression["Context Compression"]
  node_refrag["SimpleREFRAG<br/>[refrag.py]"]
  node_chunking["Passage Chunking<br/>[refrag.py]"]
  node_policy["Expansion Policy<br/>[refrag.py]"]
  node_result["Compressed Result<br/>[refrag.py]"]
  node_stats["Performance Estimates<br/>[refrag.py]"]
end

subgraph group_models["Model Components"]
  node_encoding["Chunk Encoding<br/>[refrag.py]"]
  node_projection["Decoder Projection<br/>[refrag.py]"]
  node_decoder["Decoder Model<br/>[refrag.py]"]
end

subgraph group_training["Training Simulation"]
  node_training_sim["Training Simulation<br/>[refrag.py]"]
end

node_user(("RAG caller"))
node_transformers["Pretrained Models"]

node_user -->|"submits passages"| node_refrag
node_refrag -->|"chunks passages"| node_chunking
node_refrag -->|"encodes chunks"| node_encoding
node_refrag -->|"selects expansion"| node_policy
node_refrag -->|"projects embeddings"| node_projection
node_refrag -->|"assembles result"| node_result
node_refrag -->|"estimates metrics"| node_stats
node_refrag -.->|"uses compressed context"| node_decoder
node_encoding -->|"loads encoder"| node_transformers
node_refrag -->|"loads tokenizer"| node_transformers
node_user -.->|"runs simulation"| node_training_sim
node_refrag -->|"provides model"| node_training_sim

click node_refrag "https://github.com/vaisax/refrag/blob/main/refrag.py"
click node_chunking "https://github.com/vaisax/refrag/blob/main/refrag.py"
click node_encoding "https://github.com/vaisax/refrag/blob/main/refrag.py"
click node_policy "https://github.com/vaisax/refrag/blob/main/refrag.py"
click node_projection "https://github.com/vaisax/refrag/blob/main/refrag.py"
click node_decoder "https://github.com/vaisax/refrag/blob/main/refrag.py"
click node_result "https://github.com/vaisax/refrag/blob/main/refrag.py"
click node_stats "https://github.com/vaisax/refrag/blob/main/refrag.py"
click node_training_sim "https://github.com/vaisax/refrag/blob/main/refrag.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_refrag,node_chunking,node_policy,node_result,node_stats toneBlue
class node_encoding,node_projection,node_decoder toneAmber
class node_training_sim toneMint
class node_user,node_transformers toneIndigo
```

## Components

### Context Compression

- [SimpleREFRAG](https://github.com/vaisax/refrag/blob/main/refrag.py): `refrag.py`
- [Passage Chunking](https://github.com/vaisax/refrag/blob/main/refrag.py): `refrag.py`
- [Expansion Policy](https://github.com/vaisax/refrag/blob/main/refrag.py): `refrag.py`
- [Compressed Result](https://github.com/vaisax/refrag/blob/main/refrag.py): `refrag.py`
- [Performance Estimates](https://github.com/vaisax/refrag/blob/main/refrag.py): `refrag.py`

### Model Components

- [Chunk Encoding](https://github.com/vaisax/refrag/blob/main/refrag.py): `refrag.py`
- [Decoder Projection](https://github.com/vaisax/refrag/blob/main/refrag.py): `refrag.py`
- [Decoder Model](https://github.com/vaisax/refrag/blob/main/refrag.py): `refrag.py`

### Training Simulation

- [Training Simulation](https://github.com/vaisax/refrag/blob/main/refrag.py): `refrag.py`

### Other components

- **RAG caller**
- **Pretrained Models**

## Connections

- RAG caller → SimpleREFRAG: submits passages
- SimpleREFRAG → Passage Chunking: chunks passages
- SimpleREFRAG → Chunk Encoding: encodes chunks
- SimpleREFRAG → Expansion Policy: selects expansion
- SimpleREFRAG → Decoder Projection: projects embeddings
- SimpleREFRAG → Compressed Result: assembles result
- SimpleREFRAG → Performance Estimates: estimates metrics
- SimpleREFRAG → Decoder Model: uses compressed context
- Chunk Encoding → Pretrained Models: loads encoder
- SimpleREFRAG → Pretrained Models: loads tokenizer
- RAG caller → Training Simulation: runs simulation
- SimpleREFRAG → Training Simulation: provides model