# ashokmanohar-ai/rag-evaluation-workbench-hf architecture

> Architecture diagram of the GitHub repository ashokmanohar-ai/rag-evaluation-workbench-hf, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ashokmanohar-ai/rag-evaluation-workbench-hf
- Repository: https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf

## Overview

This repository provides a RAG retrieval evaluation workbench in two forms: a Gradio app and a static browser interface, plus a browser-based regression comparison page. The primary workflow ingests a corpus and labelled queries, chunks documents, ranks chunks with BM25, semantic, or hybrid retrieval, evaluates document-level ranking quality and latency, and presents downloadable provenance evidence. The Gradio implementation delegates retrieval utilities and metric/hash helpers to rag_core.py; the browser implementation performs its workflow in space-static/app.js. README capabilities are included; static page wiring beyond shown excerpts is not inferred.

Main entry points: [`app.py`](https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf/blob/main/app.py) (Gradio workbench), [`space-static/regression.js`](https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf/blob/main/space-static/regression.js) (Regression page), [`space-static/app.js`](https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf/blob/main/space-static/app.js) (Browser workbench), [`rag_core.py`](https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf/blob/main/rag_core.py) (Document chunking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Evaluation inputs"]
  node_csv_inputs["Corpus and labels"]
  node_csv_loader["CSV input parsing<br/>[app.py]"]
  node_chunking["Document chunking<br/>[rag_core.py]"]
end

subgraph group_retrieval["Retrieval engines"]
  node_bm25["BM25 scoring<br/>[rag_core.py]"]
  node_semantic["Semantic embeddings<br/>[app.py]"]
  node_transformers["Transformers runtime"]
  node_hybrid["Hybrid ranking<br/>[app.py]"]
  node_ranked["Ranked chunks<br/>[rag_core.py]"]
end

subgraph group_evaluation["Evaluation and evidence"]
  node_doc_ranking["Document deduplication<br/>[rag_core.py]"]
  node_metrics["IR metrics<br/>[rag_core.py]"]
  node_latency["Latency statistics<br/>[app.py]"]
  node_evidence["Evidence artifact<br/>[app.py]"]
end

subgraph group_interfaces["Workbench interfaces"]
  node_gradio_ui["Gradio workbench<br/>[app.py]"]
  node_browser_ui["Browser workbench<br/>[app.js]"]
  node_static_html["Static interface<br/>[index.html]"]
end

subgraph group_regression["Regression comparison"]
  node_regression_ui["Regression page<br/>[regression.js]"]
  node_regression_html["Regression interface<br/>[regression.html]"]
  node_regression_eval["Baseline comparison and gates<br/>[regression.js]"]
end

node_user(("Evaluator"))
node_model_service["Hugging Face model source"]

node_user -->|"submits inputs"| node_gradio_ui
node_gradio_ui -->|"parses CSV"| node_csv_loader
node_csv_loader -->|"supplies documents"| node_chunking
node_gradio_ui -->|"chunks corpus"| node_chunking
node_gradio_ui -->|"scores queries"| node_bm25
node_gradio_ui -->|"requests embeddings"| node_semantic
node_semantic -->|"loads model"| node_transformers
node_transformers -.->|"downloads model"| node_model_service
node_gradio_ui -->|"combines scores"| node_hybrid
node_gradio_ui -->|"ranks chunks"| node_ranked
node_gradio_ui -->|"deduplicates documents"| node_doc_ranking
node_gradio_ui -->|"evaluates queries"| node_metrics
node_gradio_ui -->|"aggregates latency"| node_latency
node_gradio_ui -->|"writes run evidence"| node_evidence
node_user -->|"runs benchmark"| node_browser_ui
node_browser_ui -->|"loads embeddings"| node_transformers
node_browser_ui -.->|"fetches model"| node_model_service
node_user -->|"compares modes"| node_regression_ui
node_regression_ui -->|"loads embeddings"| node_transformers
node_regression_ui -.->|"fetches model"| node_model_service
node_static_html -.->|"hosts interface logic"| node_browser_ui
node_regression_html -.->|"hosts comparison logic"| node_regression_ui
node_csv_inputs -.->|"provides example data"| node_gradio_ui
node_regression_ui -->|"compares candidate quality"| node_regression_eval

click node_gradio_ui "https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf/blob/main/app.py"
click node_browser_ui "https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf/blob/main/space-static/app.js"
click node_regression_ui "https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf/blob/main/space-static/regression.js"
click node_csv_inputs "https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf/tree/main/data"
click node_csv_loader "https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf/blob/main/app.py"
click node_chunking "https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf/blob/main/rag_core.py"
click node_bm25 "https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf/blob/main/rag_core.py"
click node_semantic "https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf/blob/main/app.py"
click node_hybrid "https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf/blob/main/app.py"
click node_ranked "https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf/blob/main/rag_core.py"
click node_doc_ranking "https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf/blob/main/rag_core.py"
click node_metrics "https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf/blob/main/rag_core.py"
click node_latency "https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf/blob/main/app.py"
click node_evidence "https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf/blob/main/app.py"
click node_static_html "https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf/blob/main/space-static/index.html"
click node_regression_html "https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf/blob/main/space-static/regression.html"
click node_regression_eval "https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf/blob/main/space-static/regression.js"

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_csv_inputs,node_csv_loader,node_chunking toneBlue
class node_bm25,node_semantic,node_transformers,node_hybrid,node_ranked toneAmber
class node_doc_ranking,node_metrics,node_latency,node_evidence toneMint
class node_gradio_ui,node_browser_ui,node_static_html toneRose
class node_regression_ui,node_regression_html,node_regression_eval,node_user,node_model_service toneIndigo
```

## Components

### Evaluation inputs

- [Corpus and labels](https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf/tree/main/data): `data`
- [CSV input parsing](https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf/blob/main/app.py): `app.py`
- [Document chunking](https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf/blob/main/rag_core.py): `rag_core.py`

### Retrieval engines

- [BM25 scoring](https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf/blob/main/rag_core.py): `rag_core.py`
- [Semantic embeddings](https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf/blob/main/app.py): `app.py`
- **Transformers runtime**
- [Hybrid ranking](https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf/blob/main/app.py): `app.py`
- [Ranked chunks](https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf/blob/main/rag_core.py): `rag_core.py`

### Evaluation and evidence

- [Document deduplication](https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf/blob/main/rag_core.py): `rag_core.py`
- [IR metrics](https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf/blob/main/rag_core.py): `rag_core.py`
- [Latency statistics](https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf/blob/main/app.py): `app.py`
- [Evidence artifact](https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf/blob/main/app.py): `app.py`

### Workbench interfaces

- [Gradio workbench](https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf/blob/main/app.py): `app.py`
- [Browser workbench](https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf/blob/main/space-static/app.js): `space-static/app.js`
- [Static interface](https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf/blob/main/space-static/index.html): `space-static/index.html`

### Regression comparison

- [Regression page](https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf/blob/main/space-static/regression.js): `space-static/regression.js`
- [Regression interface](https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf/blob/main/space-static/regression.html): `space-static/regression.html`
- [Baseline comparison and gates](https://github.com/ashokmanohar-ai/rag-evaluation-workbench-hf/blob/main/space-static/regression.js): `space-static/regression.js`

### Other components

- **Evaluator**
- **Hugging Face model source**

## Connections

- Evaluator → Gradio workbench: submits inputs (evidence: `app.py`)
- Gradio workbench → CSV input parsing: parses CSV (evidence: `app.py`)
- CSV input parsing → Document chunking: supplies documents (evidence: `app.py`)
- Gradio workbench → Document chunking: chunks corpus (evidence: `app.py`)
- Gradio workbench → BM25 scoring: scores queries (evidence: `app.py`)
- Gradio workbench → Semantic embeddings: requests embeddings (evidence: `app.py`)
- Semantic embeddings → Transformers runtime: loads model (evidence: `app.py`)
- Transformers runtime → Hugging Face model source: downloads model
- Gradio workbench → Hybrid ranking: combines scores (evidence: `app.py`)
- Gradio workbench → Ranked chunks: ranks chunks (evidence: `app.py`)
- Gradio workbench → Document deduplication: deduplicates documents (evidence: `app.py`)
- Gradio workbench → IR metrics: evaluates queries (evidence: `app.py`)
- Gradio workbench → Latency statistics: aggregates latency (evidence: `app.py`)
- Gradio workbench → Evidence artifact: writes run evidence (evidence: `app.py`)
- Evaluator → Browser workbench: runs benchmark (evidence: `space-static/app.js`)
- Browser workbench → Transformers runtime: loads embeddings (evidence: `space-static/app.js`)
- Browser workbench → Hugging Face model source: fetches model
- Evaluator → Regression page: compares modes (evidence: `space-static/regression.js`)
- Regression page → Transformers runtime: loads embeddings (evidence: `space-static/regression.js`)
- Regression page → Hugging Face model source: fetches model
- Static interface → Browser workbench: hosts interface logic
- Regression interface → Regression page: hosts comparison logic
- Corpus and labels → Gradio workbench: provides example data
- Regression page → Baseline comparison and gates: compares candidate quality (evidence: `space-static/regression.js`)
