# kwiikwik/rapfin_assistant architecture

> Architecture diagram of the GitHub repository kwiikwik/rapfin_assistant, 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/kwiikwik/rapfin_assistant
- Repository: https://github.com/kwiikwik/rapfin_assistant

## Overview

Ce dépôt est un prototype d’assistant de lecture de rapports financiers bancaires. Le code fourni couvre l’extraction et le nettoyage des pages PDF, leur découpage en chunks et leur indexation vectorielle Chroma. Le README décrit ensuite un parcours prévu : recherche hybride, assemblage d’un prompt avec citations, réponse par LLM et interface Streamlit, ainsi qu’une évaluation hit@5. Ces étapes futures sont conservées comme capacités documentées, mais leur implémentation n’apparaît pas dans les fichiers échantillonnés.

Main entry points: [`src/indexing.py`](https://github.com/kwiikwik/rapfin_assistant/blob/main/src/indexing.py) (Index Chroma), [`src/extraction.py`](https://github.com/kwiikwik/rapfin_assistant/blob/main/src/extraction.py) (Extraction pages), [`src/chunks.py`](https://github.com/kwiikwik/rapfin_assistant/blob/main/src/chunks.py) (Découpage en chunks)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Préparation documentaire"]
  node_extract["Extraction pages<br/>[extraction.py]"]
  node_page_data["Pages JSONL"]
  node_chunk["Découpage en chunks<br/>[chunks.py]"]
  node_config["Configuration<br/>[config.py]"]
end

subgraph group_index["Indexation"]
  node_embedding["Embeddings<br/>[indexing.py]"]
  node_chroma[("Index Chroma<br/>[indexing.py]")]
  node_bm25[("Index BM25")]
end

subgraph group_retrieval["Recherche et évaluation"]
  node_hybrid["Fusion hybride"]
  node_evaluation["Évaluation hit@5"]
end

subgraph group_answer["Réponse utilisateur"]
  node_prompt["Prompt avec sources"]
  node_answer["Réponse justifiée"]
  node_interface["Interface Streamlit"]
end

node_reports["Rapports PDF"]
node_user(("Utilisateur"))
node_llm{{"API LLM"}}

node_reports -->|"extrait les pages"| node_extract
node_extract -->|"sérialise les pages"| node_page_data
node_page_data -->|"lit et découpe"| node_chunk
node_chunk -->|"fournit les chunks"| node_embedding
node_embedding -->|"indexe les vecteurs"| node_chroma
node_user -->|"interroge"| node_chroma
node_user -->|"interroge"| node_bm25
node_chroma -->|"résultats vectoriels"| node_hybrid
node_bm25 -->|"résultats lexicaux"| node_hybrid
node_hybrid -->|"évalue hit@5"| node_evaluation
node_hybrid -->|"alimente le contexte"| node_prompt
node_prompt -->|"envoie le prompt"| node_llm
node_llm -->|"génère la réponse"| node_answer
node_answer -->|"affiche la réponse"| node_interface

click node_extract "https://github.com/kwiikwik/rapfin_assistant/blob/main/src/extraction.py"
click node_chunk "https://github.com/kwiikwik/rapfin_assistant/blob/main/src/chunks.py"
click node_config "https://github.com/kwiikwik/rapfin_assistant/blob/main/src/config.py"
click node_embedding "https://github.com/kwiikwik/rapfin_assistant/blob/main/src/indexing.py"
click node_chroma "https://github.com/kwiikwik/rapfin_assistant/blob/main/src/indexing.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_extract,node_page_data,node_chunk,node_config toneBlue
class node_embedding,node_chroma,node_bm25 toneAmber
class node_hybrid,node_evaluation,node_llm toneMint
class node_prompt,node_answer,node_interface toneRose
class node_reports,node_user toneIndigo
```

## Components

### Préparation documentaire

- [Extraction pages](https://github.com/kwiikwik/rapfin_assistant/blob/main/src/extraction.py): `src/extraction.py`
- **Pages JSONL**
- [Découpage en chunks](https://github.com/kwiikwik/rapfin_assistant/blob/main/src/chunks.py): `src/chunks.py`
- [Configuration](https://github.com/kwiikwik/rapfin_assistant/blob/main/src/config.py): `src/config.py`

### Indexation

- [Embeddings](https://github.com/kwiikwik/rapfin_assistant/blob/main/src/indexing.py): `src/indexing.py`
- [Index Chroma](https://github.com/kwiikwik/rapfin_assistant/blob/main/src/indexing.py): `src/indexing.py`
- **Index BM25**

### Recherche et évaluation

- **Fusion hybride**
- **Évaluation hit@5**

### Réponse utilisateur

- **Prompt avec sources**
- **Réponse justifiée**
- **Interface Streamlit**

### Other components

- **Rapports PDF**
- **Utilisateur**
- **API LLM**

## Connections

- Rapports PDF → Extraction pages: extrait les pages (evidence: `README.md`)
- Extraction pages → Pages JSONL: sérialise les pages (evidence: `src/extraction.py`)
- Pages JSONL → Découpage en chunks: lit et découpe (evidence: `src/chunks.py`)
- Découpage en chunks → Embeddings: fournit les chunks (evidence: `README.md`)
- Embeddings → Index Chroma: indexe les vecteurs (evidence: `src/indexing.py`)
- Utilisateur → Index Chroma: interroge (evidence: `README.md`)
- Utilisateur → Index BM25: interroge (evidence: `README.md`)
- Index Chroma → Fusion hybride: résultats vectoriels (evidence: `README.md`)
- Index BM25 → Fusion hybride: résultats lexicaux (evidence: `README.md`)
- Fusion hybride → Évaluation hit@5: évalue hit@5 (evidence: `README.md`)
- Fusion hybride → Prompt avec sources: alimente le contexte (evidence: `README.md`)
- Prompt avec sources → API LLM: envoie le prompt (evidence: `README.md`)
- API LLM → Réponse justifiée: génère la réponse (evidence: `README.md`)
- Réponse justifiée → Interface Streamlit: affiche la réponse (evidence: `README.md`)
