Glossaire

Les termes et colonnes qui reviennent dans toute la documentation, regroupés par famille.

Concepts

Terme Définition
COICOP Classification of Individual Consumption According to Purpose — nomenclature hiérarchique des dépenses de consommation (voir l’accueil).
BDF Enquête Budget de Famille : collecte des tickets de caisse des ménages ; chaque ligne de ticket est un produit à coder.
Mode prédiction / mode évaluation Prédiction : le fichier d’entrée n’a pas de vérité terrain (cas du CSV BDF) ; évaluation : une colonne code de référence existe et permet de calculer l’exactitude (Généralités).
LCS Longest Common Substring — codification par plus longue sous-chaîne commune avec un pool de libellés déjà codés (Codif LCS).
RAG Retrieval-Augmented Generation — recherche sémantique puis choix par un LLM. Deux branches : sur les notices de la nomenclature (RAG COICOP) et sur des exemples déjà codifiés (RAG annotations).
TTC Classifieur neuronal de texte (package torchTextClassifiers), pré-entraîné sur des données de caisses (TTC).
LLM-as-judge Arbitrage final : un LLM compare les prédictions des quatre classifieurs et tranche (Decide).
Consensus Court-circuit de l’arbitrage : si tous les codes disponibles (lcs_code, rag_code, ragann_code) sont égaux à ttc_code_1 et que ttc_conf_1 ≥ 0,90, la décision est prise sans appel LLM (llm_model = "consensus", llm_confiance = 5).
Suggester Pool de libellés de référence déjà codés à la main (issu de la table COPAIN), auquel LCS compare les libellés à coder ; également indexé dans la base vectorielle des RAG annotations.
Troncature Réduction d’un code à ses 4 premiers segments (01.1.1.3.2 → 01.1.1.3) : le niveau 5 n’est jamais prédit (Prune).
Pruning / élagage Repli des hiérarchies linéaires : un parent à enfant unique est équivalent à cet enfant, la chaîne est ramenée à son code canonique (Prune).
Fil rouge Les quatre libellés réels du CSV BDF suivis de bout en bout dans chaque page d’étape (accueil).
run_id / run_date Identifiant et date du run de pipeline ; ils déterminent le dossier S3 du run. À fournir explicitement pour relancer une étape.

Codes

Code / valeur Sens
01 → 01.1.1.1 Code COICOP « produit », du niveau 1 (section) au niveau 4 (classe, le plus fin conservé).
Niveau 5 (01.1.1.1.x) Poste — supprimé à la troncature, jamais prédit par le pipeline.
98.1 Courses / alimentation non détaillée.
98.3 Carte bancaire (ligne « Ticket CB » standardisée).
98.4 Prélèvement ; aussi utilisé pour illisible.
98.5 Remises / réductions.
99.x Hors champ COICOP (cadeaux, épargne, impôts…).
Reprise manuelle Valeur littérale (pas un code) renvoyée par certaines règles regex : ligne à recoder à la main (Codif regex).
Code canonique (code_parent_equivalent) Représentant d’un groupe de codes équivalents replié à l’élagage ; nom de la colonne dans mapping_lvl4.parquet (Prune).

Colonnes du pipeline

Produites par preprocessing

Colonne Sens
id UUID unique de la ligne, clé de jointure de toutes les étapes.
raw_product Libellé produit d’origine (colonne text_column du fichier d’entrée, ex. NAT_DEP).
l_pr_product Normalisation légère (minuscules, accents/ligatures retirés) — utilisée par RAG et TTC.
s_pr_product Normalisation forte (bruit, stopwords retirés) — utilisée par les regex et LCS.
shop, budget, annee, source Enseigne, montant (€), année, source — renommées depuis le mappage de colonnes.
shop_type_code / shop_type_name Type de magasin déduit de l’enseigne (supermarché, restauration rapide…).
code Vérité terrain COICOP brute, telle qu’annotée (NA en mode prédiction).
_source_input_file Chemin du fichier d’entrée d’origine (réutilisé par final-output).

Prédictions des quatre classifieurs

Les noms ci-dessous sont ceux après renommage par decide-coicop (les modules produisent predict_code / code_predict / predicted_code selon les cas).

Colonne Étape Sens
predict_code codif-regex Code attribué par une règle regex (method = "REGEX").
lcs_code codif-lcs Code du libellé de référence le plus proche.
lcs_distance codif-lcs Distance LCS, 1 − maxlen/max(n1, n2) (0 = identique).
lcs_substring codif-lcs Plus longue sous-chaîne commune trouvée.
lcs_prop codif-lcs Part du libellé de référence couverte par la sous-chaîne.
rag_code run-rag Code choisi par le LLM parmi les 10 notices candidates (Qdrant).
rag_confidence, codable run-rag Confiance déclarée par le LLM ; produit jugé codable ou non.
ragann_code run-rag-annotations Code choisi parmi ceux des 10 produits annotés les plus proches.
ragann_confidence, ragann_codable run-rag-annotations Confiance (∈ [0,1]) ; false = aucun candidat ne convenait.
ttc_code_1 … ttc_code_3 run-ttc Top 3 des codes prédits par le classifieur neuronal (il en produit 10, decide-coicop n’en lit que 3).
ttc_conf_1 … ttc_conf_3 run-ttc Confiances associées, décroissantes ; ttc_conf_1 ≥ 0,90 conditionne le consensus.

Tous ces codes sont tronqués au niveau 4 et élagués par decide-coicop quand --mapping-file est fourni (Prune). La vérité terrain, elle, est dupliquée : code reste brut, code_lvl4 porte sa forme canonique.

Décision et livrable

Colonne Étape Sens
llm_code decide-coicop Code final retenu, normalisé (tronqué niveau 4 + élagué) ; NA si l’appel LLM a échoué.
llm_libelle decide-coicop Libellé COICOP recopié de la nomenclature.
llm_explication decide-coicop Justification du choix (1 phrase).
llm_confiance decide-coicop Score de confiance de 1 (très faible) à 5 (très élevé) ; 5 pour un consensus.
llm_model decide-coicop Modèle LLM utilisé, ou "consensus" si court-circuit sans appel.
llm_error decide-coicop Raison de l’échec quand llm_code est NA (RateLimitError, JSON invalide…).
predicted_code final-output Code livré : llm_code s’il existe, sinon predict_code (regex), sinon vide.
prediction_source final-output Origine du code : consensus > regex > llm > (vide) — un indicateur de fiabilité.
code_parent_equivalent prune Code canonique d’un code replié, dans mapping_lvl4.parquet.
code_lvl4 decide-coicop Vérité terrain canonique : code tronqué au niveau 4 puis élagué. C’est la colonne que le rapport score.
llm_comment final-output Copie de llm_explication dans le fichier livré.

Infrastructure

Terme Rôle dans le pipeline
Argo Workflows Orchestrateur Kubernetes : le pipeline est un DAG (argo/codif-pipeline.yaml), chaque étape un conteneur.
S3 (run root) Stockage de tous les artefacts : s3://projet-budget-famille/data/workflow_runs/{run_date}/{run_id}/<étape>/.
Qdrant Base vectorielle hébergeant deux collections : coicop_lineage (notices COICOP prunées) et coicop_annotations_without_copain_2017 (exemples annotés + suggester), distance cosinus.
LLMLab Endpoint OpenAI-compatible servant tous les modèles du pipeline — embeddings (qwen3-embedding-8b) et génération (gemma4-26b-moe) — via LLMLAB_URL / LLMLAB_API_KEY.
Langfuse Traçage des appels LLM des deux branches RAG et gestion des gabarits de prompt (prompt-multi-level v12, prompt-annotation-rag v2).
MLflow Suivi des runs : expériences test (run-rag), rag-annotation (run-rag-annotations) et codif-coicop-eval (report, avec report.html en artefact) ; héberge aussi le modèle TTC (ttc-model-uri).
DuckDB Lecture/écriture des parquet S3 dans les étapes Python et pour inspecter un run.
uv Gestionnaire d’environnements Python : chaque sous-dossier a son pyproject.toml/uv.lock.

Retour à l’accueil