# hocine-drioueche/randoneo-rag architecture

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

- Interactive diagram: https://gitdiagram.com/hocine-drioueche/randoneo-rag
- Repository: https://github.com/hocine-drioueche/randoneo-rag

## Overview

Randoneo RAG is a French-language customer-support assistant grounded in an outdoor-shop document corpus. The main workflow loads Markdown, splits it into overlapping chunks, indexes embeddings in Chroma, retrieves four passages per question, and generates a context-bound answer with source citations and a refusal when evidence is missing. `chat.py` exposes this workflow interactively; `evaluate.py` replays it against question sets and scores retrieval and generation with RAGAS. The README documents the stages; unsampled corpus and evaluation data are represented by their exact directories.

Main entry points: [`chat.py`](https://github.com/hocine-drioueche/randoneo-rag/blob/main/chat.py) (Interactive chat), [`evaluate.py`](https://github.com/hocine-drioueche/randoneo-rag/blob/main/evaluate.py) (Evaluation runner), [`rag.py`](https://github.com/hocine-drioueche/randoneo-rag/blob/main/rag.py) (RAG chain), [`corpus`](https://github.com/hocine-drioueche/randoneo-rag/tree/main/corpus) (Shop documents)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Chat interaction"]
  node_chat["Interactive chat<br/>[chat.py]"]
  node_answer["Cited answer<br/>[chat.py]"]
end

subgraph group_rag["RAG pipeline"]
  node_loader["Corpus loader<br/>[rag.py]"]
  node_splitter["Chunk splitter<br/>[rag.py]"]
  node_embedding["OpenAI embeddings"]
  node_index[("Chroma index<br/>[rag.py]")]
  node_retriever["Passage retriever<br/>[rag.py]"]
  node_chain["RAG chain<br/>[rag.py]"]
  node_prompt["Grounded prompt<br/>[rag.py]"]
  node_llm["Claude model"]
end

subgraph group_knowledge["Knowledge corpus"]
  node_corpus["Shop documents"]
end

subgraph group_evaluation["Evaluation"]
  node_evaluator["Evaluation runner<br/>[evaluate.py]"]
  node_questions["Question sets"]
  node_ragas["RAGAS metrics"]
end

node_customer(("Questioner"))

node_customer -->|"asks"| node_chat
node_chat -->|"loads corpus"| node_loader
node_loader -->|"reads Markdown"| node_corpus
node_chat -->|"splits documents"| node_splitter
node_chat -->|"builds index"| node_index
node_index -->|"vectorizes chunks"| node_embedding
node_chat -->|"configures retrieval"| node_retriever
node_retriever -->|"searches passages"| node_index
node_chat -->|"assembles chain"| node_chain
node_chain -->|"retrieves context"| node_retriever
node_chain -->|"formats context"| node_prompt
node_chain -->|"generates answer"| node_llm
node_chat -->|"displays response"| node_answer
node_answer -->|"returns answer"| node_customer
node_evaluator -->|"builds RAG"| node_loader
node_evaluator -->|"loads questions"| node_questions
node_evaluator -->|"retrieves contexts"| node_retriever
node_evaluator -->|"replays questions"| node_chain
node_evaluator -->|"scores samples"| node_ragas

click node_chat "https://github.com/hocine-drioueche/randoneo-rag/blob/main/chat.py"
click node_corpus "https://github.com/hocine-drioueche/randoneo-rag/tree/main/corpus"
click node_loader "https://github.com/hocine-drioueche/randoneo-rag/blob/main/rag.py"
click node_splitter "https://github.com/hocine-drioueche/randoneo-rag/blob/main/rag.py"
click node_index "https://github.com/hocine-drioueche/randoneo-rag/blob/main/rag.py"
click node_retriever "https://github.com/hocine-drioueche/randoneo-rag/blob/main/rag.py"
click node_chain "https://github.com/hocine-drioueche/randoneo-rag/blob/main/rag.py"
click node_prompt "https://github.com/hocine-drioueche/randoneo-rag/blob/main/rag.py"
click node_answer "https://github.com/hocine-drioueche/randoneo-rag/blob/main/chat.py"
click node_evaluator "https://github.com/hocine-drioueche/randoneo-rag/blob/main/evaluate.py"
click node_questions "https://github.com/hocine-drioueche/randoneo-rag/tree/main/eval"

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_chat,node_answer toneBlue
class node_loader,node_splitter,node_embedding,node_index,node_retriever,node_chain,node_prompt,node_llm toneAmber
class node_corpus toneMint
class node_evaluator,node_questions,node_ragas toneRose
class node_customer toneIndigo
```

## Components

### Chat interaction

- [Interactive chat](https://github.com/hocine-drioueche/randoneo-rag/blob/main/chat.py): `chat.py`
- [Cited answer](https://github.com/hocine-drioueche/randoneo-rag/blob/main/chat.py): `chat.py`

### RAG pipeline

- [Corpus loader](https://github.com/hocine-drioueche/randoneo-rag/blob/main/rag.py): `rag.py`
- [Chunk splitter](https://github.com/hocine-drioueche/randoneo-rag/blob/main/rag.py): `rag.py`
- **OpenAI embeddings**
- [Chroma index](https://github.com/hocine-drioueche/randoneo-rag/blob/main/rag.py): `rag.py`
- [Passage retriever](https://github.com/hocine-drioueche/randoneo-rag/blob/main/rag.py): `rag.py`
- [RAG chain](https://github.com/hocine-drioueche/randoneo-rag/blob/main/rag.py): `rag.py`
- [Grounded prompt](https://github.com/hocine-drioueche/randoneo-rag/blob/main/rag.py): `rag.py`
- **Claude model**

### Knowledge corpus

- [Shop documents](https://github.com/hocine-drioueche/randoneo-rag/tree/main/corpus): `corpus`

### Evaluation

- [Evaluation runner](https://github.com/hocine-drioueche/randoneo-rag/blob/main/evaluate.py): `evaluate.py`
- [Question sets](https://github.com/hocine-drioueche/randoneo-rag/tree/main/eval): `eval`
- **RAGAS metrics**

### Other components

- **Questioner**

## Connections

- Questioner → Interactive chat: asks (evidence: `README.md`)
- Interactive chat → Corpus loader: loads corpus (evidence: `chat.py`)
- Corpus loader → Shop documents: reads Markdown (evidence: `rag.py`)
- Interactive chat → Chunk splitter: splits documents (evidence: `chat.py`)
- Interactive chat → Chroma index: builds index (evidence: `chat.py`)
- Chroma index → OpenAI embeddings: vectorizes chunks (evidence: `README.md`)
- Interactive chat → Passage retriever: configures retrieval (evidence: `chat.py`)
- Passage retriever → Chroma index: searches passages (evidence: `README.md`)
- Interactive chat → RAG chain: assembles chain (evidence: `chat.py`)
- RAG chain → Passage retriever: retrieves context (evidence: `rag.py`)
- RAG chain → Grounded prompt: formats context (evidence: `rag.py`)
- RAG chain → Claude model: generates answer (evidence: `rag.py`)
- Interactive chat → Cited answer: displays response (evidence: `chat.py`)
- Cited answer → Questioner: returns answer (evidence: `README.md`)
- Evaluation runner → Corpus loader: builds RAG (evidence: `evaluate.py`)
- Evaluation runner → Question sets: loads questions (evidence: `evaluate.py`)
- Evaluation runner → Passage retriever: retrieves contexts (evidence: `evaluate.py`)
- Evaluation runner → RAG chain: replays questions (evidence: `evaluate.py`)
- Evaluation runner → RAGAS metrics: scores samples (evidence: `evaluate.py`)
