# salvatoreftartaglione/diem-assistant-rag architecture

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

- Interactive diagram: https://gitdiagram.com/salvatoreftartaglione/diem-assistant-rag
- Repository: https://github.com/salvatoreftartaglione/diem-assistant-rag

## Overview

DIEM Assistant is an Italian-language university help chatbot grounded in official DIEM sources. Its principal workflow runs from a student question through Chainlit, shared conversation handling, the LangGraph guardrail/rewrite/retrieval/generation flow, and a cited response. Offline, crawled pages and PDFs are deduplicated, parent-child indexed, and made available to semantic and BM25 retrieval. The README also documents RAGAS evaluation. Some subsystem links are based on README architecture rather than sampled implementation; unsampled links are omitted where their ownership is unclear.

Main entry points: [`diem_rag/agent/graph.py`](https://github.com/salvatoreftartaglione/diem-assistant-rag/blob/main/diem_rag/agent/graph.py) (LangGraph workflow), [`diem_rag/indexing/indexer.py`](https://github.com/salvatoreftartaglione/diem-assistant-rag/blob/main/diem_rag/indexing/indexer.py) (Parent-child indexer), [`diem_rag/agent/resources.py`](https://github.com/salvatoreftartaglione/diem-assistant-rag/blob/main/diem_rag/agent/resources.py) (Loaded models and stores), [`diem_rag/agent/nodes.py`](https://github.com/salvatoreftartaglione/diem-assistant-rag/blob/main/diem_rag/agent/nodes.py) (Guardrails and generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Knowledge ingestion"]
  node_extractor["Crawler and extractor<br/>[extractor.py]"]
  node_kb["Knowledge base"]
  node_filter["Deduplication<br/>[kb_filter.py]"]
end

subgraph group_index["Indexing and stores"]
  node_indexer["Parent-child indexer<br/>[indexer.py]"]
  node_childdb[("Vector store")]
  node_parentstore[("Parent chunk store")]
  node_bmindex[("Dual BM25 indices<br/>[bm25_indexer.py]")]
end

subgraph group_agent["Agent workflow"]
  node_conversation["Turn handling<br/>[conversation.py]"]
  node_graph["LangGraph workflow<br/>[graph.py]"]
  node_state["Agent state<br/>[state.py]"]
  node_nodes["Guardrails and generation<br/>[nodes.py]"]
  node_prompts["Prompt templates<br/>[prompts.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
end

subgraph group_retrieval["Retrieval and answers"]
  node_resources["Loaded models and stores<br/>[resources.py]"]
  node_retrieval["Hybrid retrieval and reranking<br/>[retrieval.py]"]
  node_context["Context budgeting<br/>[context.py]"]
end

subgraph group_interfaces["Interfaces and evaluation"]
  node_chainlit["Chainlit UI<br/>[DIEM_assistant.py]"]
  node_cli["Terminal chat<br/>[cli.py]"]
  node_evaluation["RAGAS evaluation<br/>[ragas_eval.py]"]
end

node_student(("Student"))
node_official["University portals and PDFs"]

node_student -->|"asks"| node_chainlit
node_chainlit -->|"submits turn"| node_conversation
node_conversation -->|"invokes"| node_graph
node_graph -->|"dispatches"| node_nodes
node_graph -->|"dispatches retrieval"| node_retrieval
node_graph -->|"uses state"| node_state
node_nodes -->|"uses prompts"| node_prompts
node_nodes -->|"builds context"| node_context
node_official -->|"crawls"| node_extractor
node_extractor -->|"extracts"| node_kb
node_kb -->|"deduplicates"| node_filter
node_filter -->|"indexes"| node_indexer
node_indexer -->|"embeds children"| node_childdb
node_indexer -->|"stores parents"| node_parentstore
node_indexer -->|"builds lexical indices"| node_bmindex
node_retrieval -->|"uses loaded stores"| node_resources
node_resources -->|"opens"| node_childdb
node_resources -->|"loads"| node_parentstore
node_resources -->|"loads"| node_bmindex
node_retrieval -->|"ranks documents"| node_context
node_context -->|"provides context"| node_nodes
node_graph -->|"reads feature flags"| node_config
node_cli -->|"runs turns"| node_conversation
node_evaluation -->|"resolves retrieved chunks"| node_parentstore

click node_chainlit "https://github.com/salvatoreftartaglione/diem-assistant-rag/blob/main/DIEM_assistant.py"
click node_conversation "https://github.com/salvatoreftartaglione/diem-assistant-rag/blob/main/diem_rag/agent/conversation.py"
click node_graph "https://github.com/salvatoreftartaglione/diem-assistant-rag/blob/main/diem_rag/agent/graph.py"
click node_state "https://github.com/salvatoreftartaglione/diem-assistant-rag/blob/main/diem_rag/agent/state.py"
click node_nodes "https://github.com/salvatoreftartaglione/diem-assistant-rag/blob/main/diem_rag/agent/nodes.py"
click node_prompts "https://github.com/salvatoreftartaglione/diem-assistant-rag/blob/main/diem_rag/agent/prompts.py"
click node_config "https://github.com/salvatoreftartaglione/diem-assistant-rag/blob/main/diem_rag/config.py"
click node_extractor "https://github.com/salvatoreftartaglione/diem-assistant-rag/blob/main/diem_rag/ingestion/extractor.py"
click node_filter "https://github.com/salvatoreftartaglione/diem-assistant-rag/blob/main/diem_rag/ingestion/kb_filter.py"
click node_indexer "https://github.com/salvatoreftartaglione/diem-assistant-rag/blob/main/diem_rag/indexing/indexer.py"
click node_bmindex "https://github.com/salvatoreftartaglione/diem-assistant-rag/blob/main/diem_rag/indexing/bm25_indexer.py"
click node_resources "https://github.com/salvatoreftartaglione/diem-assistant-rag/blob/main/diem_rag/agent/resources.py"
click node_retrieval "https://github.com/salvatoreftartaglione/diem-assistant-rag/blob/main/diem_rag/agent/retrieval.py"
click node_context "https://github.com/salvatoreftartaglione/diem-assistant-rag/blob/main/diem_rag/agent/context.py"
click node_cli "https://github.com/salvatoreftartaglione/diem-assistant-rag/blob/main/diem_rag/agent/cli.py"
click node_evaluation "https://github.com/salvatoreftartaglione/diem-assistant-rag/blob/main/diem_rag/evaluation/ragas_eval.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_extractor,node_kb,node_filter toneBlue
class node_indexer,node_childdb,node_parentstore,node_bmindex toneAmber
class node_conversation,node_graph,node_state,node_nodes,node_prompts,node_config toneMint
class node_resources,node_retrieval,node_context toneRose
class node_chainlit,node_cli,node_evaluation,node_student,node_official toneIndigo
```

## Components

### Knowledge ingestion

- [Crawler and extractor](https://github.com/salvatoreftartaglione/diem-assistant-rag/blob/main/diem_rag/ingestion/extractor.py): `diem_rag/ingestion/extractor.py`
- **Knowledge base**
- [Deduplication](https://github.com/salvatoreftartaglione/diem-assistant-rag/blob/main/diem_rag/ingestion/kb_filter.py): `diem_rag/ingestion/kb_filter.py`

### Indexing and stores

- [Parent-child indexer](https://github.com/salvatoreftartaglione/diem-assistant-rag/blob/main/diem_rag/indexing/indexer.py): `diem_rag/indexing/indexer.py`
- **Vector store**
- **Parent chunk store**
- [Dual BM25 indices](https://github.com/salvatoreftartaglione/diem-assistant-rag/blob/main/diem_rag/indexing/bm25_indexer.py): `diem_rag/indexing/bm25_indexer.py`

### Agent workflow

- [Turn handling](https://github.com/salvatoreftartaglione/diem-assistant-rag/blob/main/diem_rag/agent/conversation.py): `diem_rag/agent/conversation.py`
- [LangGraph workflow](https://github.com/salvatoreftartaglione/diem-assistant-rag/blob/main/diem_rag/agent/graph.py): `diem_rag/agent/graph.py`
- [Agent state](https://github.com/salvatoreftartaglione/diem-assistant-rag/blob/main/diem_rag/agent/state.py): `diem_rag/agent/state.py`
- [Guardrails and generation](https://github.com/salvatoreftartaglione/diem-assistant-rag/blob/main/diem_rag/agent/nodes.py): `diem_rag/agent/nodes.py`
- [Prompt templates](https://github.com/salvatoreftartaglione/diem-assistant-rag/blob/main/diem_rag/agent/prompts.py): `diem_rag/agent/prompts.py`
- [Runtime configuration](https://github.com/salvatoreftartaglione/diem-assistant-rag/blob/main/diem_rag/config.py): `diem_rag/config.py`

### Retrieval and answers

- [Loaded models and stores](https://github.com/salvatoreftartaglione/diem-assistant-rag/blob/main/diem_rag/agent/resources.py): `diem_rag/agent/resources.py`
- [Hybrid retrieval and reranking](https://github.com/salvatoreftartaglione/diem-assistant-rag/blob/main/diem_rag/agent/retrieval.py): `diem_rag/agent/retrieval.py`
- [Context budgeting](https://github.com/salvatoreftartaglione/diem-assistant-rag/blob/main/diem_rag/agent/context.py): `diem_rag/agent/context.py`

### Interfaces and evaluation

- [Chainlit UI](https://github.com/salvatoreftartaglione/diem-assistant-rag/blob/main/DIEM_assistant.py): `DIEM_assistant.py`
- [Terminal chat](https://github.com/salvatoreftartaglione/diem-assistant-rag/blob/main/diem_rag/agent/cli.py): `diem_rag/agent/cli.py`
- [RAGAS evaluation](https://github.com/salvatoreftartaglione/diem-assistant-rag/blob/main/diem_rag/evaluation/ragas_eval.py): `diem_rag/evaluation/ragas_eval.py`

### Other components

- **Student**
- **University portals and PDFs**

## Connections

- Student → Chainlit UI: asks (evidence: `README.md`)
- Chainlit UI → Turn handling: submits turn (evidence: `DIEM_assistant.py`)
- Turn handling → LangGraph workflow: invokes (evidence: `diem_rag/agent/conversation.py`)
- LangGraph workflow → Guardrails and generation: dispatches (evidence: `diem_rag/agent/graph.py`)
- LangGraph workflow → Hybrid retrieval and reranking: dispatches retrieval (evidence: `diem_rag/agent/graph.py`)
- LangGraph workflow → Agent state: uses state (evidence: `diem_rag/agent/graph.py`)
- Guardrails and generation → Prompt templates: uses prompts (evidence: `diem_rag/agent/nodes.py`)
- Guardrails and generation → Context budgeting: builds context (evidence: `diem_rag/agent/nodes.py`)
- University portals and PDFs → Crawler and extractor: crawls (evidence: `README.md`)
- Crawler and extractor → Knowledge base: extracts (evidence: `README.md`)
- Knowledge base → Deduplication: deduplicates (evidence: `README.md`)
- Deduplication → Parent-child indexer: indexes (evidence: `README.md`)
- Parent-child indexer → Vector store: embeds children (evidence: `README.md`)
- Parent-child indexer → Parent chunk store: stores parents (evidence: `README.md`)
- Parent-child indexer → Dual BM25 indices: builds lexical indices (evidence: `README.md`)
- Hybrid retrieval and reranking → Loaded models and stores: uses loaded stores (evidence: `diem_rag/agent/retrieval.py`)
- Loaded models and stores → Vector store: opens (evidence: `diem_rag/agent/resources.py`)
- Loaded models and stores → Parent chunk store: loads (evidence: `diem_rag/agent/resources.py`)
- Loaded models and stores → Dual BM25 indices: loads (evidence: `diem_rag/agent/resources.py`)
- Hybrid retrieval and reranking → Context budgeting: ranks documents (evidence: `README.md`)
- Context budgeting → Guardrails and generation: provides context (evidence: `diem_rag/agent/nodes.py`)
- LangGraph workflow → Runtime configuration: reads feature flags (evidence: `diem_rag/agent/graph.py`)
- Terminal chat → Turn handling: runs turns (evidence: `diem_rag/agent/cli.py`)
- RAGAS evaluation → Parent chunk store: resolves retrieved chunks (evidence: `diem_rag/evaluation/ragas_eval.py`)
