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.
label-column Nom de la colonne d’étiquettes dans le fichier d’entrée. Vide (le cas nominal) : l’étape evaluate est sautée. Renseignée : build-datasets la recopie dans code, elle traverse la chaîne, et le run devient mesurable. Il y avait auparavant deux modes dérivés du seul fait qu’input_file soit vide ou non ; le pipeline n’en a plus qu’un (Généralités).
eval-source-column Nom de la colonne de provenance du produit. Ajoute une ventilation de l’accuracy par source au rapport d’évaluation. Ne restreint jamais le périmètre codé.
evaluate Étape finale facultative qui mesure la qualité d’un run étiqueté : rapport HTML sur S3 et métriques dans MLflow (Evaluate).
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 (reconcile-llm).
Conciliation Étape qui choisit le code final parmi les candidats des quatre classifieurs. Deux implémentations, exclusives : reconcile-llm, un juge LLM, et reconcile-sirus, une vingtaine de règles à seuils lisibles.
reconciliation Paramètre Argo qui choisit la conciliation : llm (défaut) ou sirus. L’autre étape est Skipped. Attention, il s’est appelé conciliation : Argo accepte une clé inconnue sans rien dire, donc une faute de frappe fait silencieusement tourner le défaut.
SIRUS Stable and Interpretable RUle Set — modèle de conciliation par règles. Entraîné hors pipeline (reconcile-sirus/train.sh), livré par reconcile-sirus-model-uri (SIRUS).
Run smoke Passe préalable du DAG complet sur 100 lignes, jouée automatiquement avant chaque run réel : si elle échoue, le vrai run ne démarre pas. run_id et espace MLflow distincts. Contournement : skip-smoke (Généralités).
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 — et, pour un run d’indexation, le nom de la collection Qdrant produite. À fournir explicitement pour relancer une étape.
sample-observations Unique curseur d’échantillonnage du pipeline de codification : plafonne le jeu à coder. Tiré une seule fois à classify-regex, hérité par les quatre classifieurs. Remplace l’ancien couple sample-observations / sample-annotations.
kb-sample-size Curseur d’échantillonnage du pipeline index-annotations : plafonne le nombre de points indexés dans la collection (donc le temps d’embedding). Le nom de la collection porte alors un suffixe __sampleN.

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 build-datasets

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 sauf si le run a été lancé avec label-column.
_source_input_file Chemin du fichier d’entrée d’origine (réutilisé par export-results).

Prédictions des quatre classifieurs

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

Colonne Étape Sens
predict_code classify-regex Code attribué par une règle regex (method = "REGEX").
lcs_code classify-lcs Code du libellé de référence le plus proche.
lcs_distance classify-lcs Distance LCS, 1 − maxlen/max(n1, n2) (0 = identique).
lcs_substring classify-lcs Plus longue sous-chaîne commune trouvée.
lcs_prop classify-lcs Part du libellé de référence couverte par la sous-chaîne.
rag_code classify-rag-notices Code choisi par le LLM parmi les 10 notices candidates (Qdrant).
rag_confidence, codable classify-rag-notices Confiance déclarée par le LLM ; produit jugé codable ou non.
ragann_code classify-rag-annotations Code choisi parmi ceux des 10 produits annotés les plus proches.
ragann_confidence, ragann_codable classify-rag-annotations Confiance (∈ [0,1]) ; false = aucun candidat ne convenait.
ttc_code_1 … ttc_code_3 classify-ttc Top 3 des codes prédits par le classifieur neuronal (il en produit 10, reconcile-llm n’en lit que 3).
ttc_conf_1 … ttc_conf_3 classify-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 reconcile-llm 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 reconcile-llm Code final retenu, normalisé (tronqué niveau 4 + élagué) ; NA si l’appel LLM a échoué.
llm_libelle reconcile-llm Libellé COICOP recopié de la nomenclature.
llm_explication reconcile-llm Justification du choix (1 phrase).
llm_confiance reconcile-llm Score de confiance de 1 (très faible) à 5 (très élevé) ; 5 pour un consensus.
llm_model reconcile-llm Modèle LLM utilisé, ou "consensus" si court-circuit sans appel.
llm_error reconcile-llm Raison de l’échec quand llm_code est NA (RateLimitError, JSON invalide…).
predicted_code export-results Code livré : llm_code s’il existe, sinon predict_code (regex), sinon vide.
prediction_source export-results Origine du code : consensus > regex > llm > (vide) — un indicateur de fiabilité.
code_parent_equivalent prune-codes Code canonique d’un code replié, dans mapping_lvl4.parquet.
code_lvl4 reconcile-llm Vérité terrain canonique : code tronqué au niveau 4 puis élagué. C’est la colonne que l’étape evaluate score — son absence la fait échouer.
llm_comment export-results Copie de llm_explication dans le fichier livré.

Infrastructure

Terme Rôle dans le pipeline
Argo Workflows Orchestrateur Kubernetes. Trois workflows : argo/codif-pipeline.yaml (codification), argo/index-notices-pipeline.yaml et argo/index-annotations-pipeline.yaml (construction des collections Qdrant). Chaque étape est 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 (distance cosinus). Chaque indexation crée une collection au nom unique (voir Collection Qdrant ci-dessous) : les noms fixes coicop_lineage et coicop_annotations_without_copain_2017 n’existent plus.
Collection Qdrant Index vectoriel nommé {base}__{run_date}__{run_id}[__sampleN] — bases coicop_notices et coicop_annotations (clé qdrant.collection_base). Ex. coicop_notices__2026-09-02__index-notices-a7k2p. Désignée au pipeline de codification par les paramètres obligatoires classify-rag-notices-collection / classify-rag-annotations-collection.
Manifeste d’index JSON écrit à côté de chaque collection, sous s3://projet-budget-famille/data/vector_db_manifests/{collection_name}.json : modèle d’embedding, dimension, stratégie, taille d’échantillon, nombre de points, SHA git. Relu par les étapes classify-rag-* au démarrage pour valider la collection avant tout travail coûteux.
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 (classify-rag-notices), rag-annotation (classify-rag-annotations) et codif-coicop-eval (report, avec report.html en artefact) ; héberge aussi le modèle TTC (classify-ttc-model-uri) et le modèle SIRUS (reconcile-sirus-model-uri).
DuckDB Lecture/écriture des parquet S3 dans les étapes Python et pour inspecter un run.
uv Gestionnaire d’environnements Python : un workspace unique, un pyproject.toml par module et un seul uv.lock à la racine.
contracts.yaml Registre, à la racine du dépôt, des artefacts échangés entre étapes : inputs et outputs de chacune. Une étape ne construit plus le chemin d’une autre, elle le demande (codif_common.contracts.artifact()). En YAML parce que classify-lcs est en R et doit le lire aussi (Généralités).
common/ (codif_common) Socle Python partagé, sans étape Argo : accès au registre (contracts), chemins (paths), manipulation de codes (codes), connexions S3 (s3), nommage des collections (vector_index), contrôles de frontière (schema), métriques (metrics), URLs MLflow (tracking). Il ne dépend d’aucun autre module du workspace — c’est ce qui rend tout cycle impossible.

Retour à l’accueil