Guide des instruments

Les instruments sont des artefacts analytiques déclaratifs qui se compilent en SQL. Ils forment la pyramide analytique — chaque couche s’appuie sur celle du dessous.

La pyramide

Parallèlement à la pyramide, deux systèmes indépendants capturent les connaissances humaines :

• SMEbits — observations et checks atomiques d’experts (libres, liés par des ancres)
• BitBundles — narratifs curés regroupant des SMEbits

Workflow

Tous les instruments suivent le même workflow :

# 1. Create or edit the YAML in the AFS (probes/, theses/, smebits/, etc.)
#    Note: signals are still declared in probes/ directory using probe_id

# 2. Build — make handles validation, compilation, and dbt automatically
jin make

C’est tout. make exécute tous les validateurs et compilateurs dans le bon ordre comme partie de son DAG de build. Vous n’avez jamais besoin d’exécuter les compilateurs manuellement.

Pour vérifier ce qui est désynchronisé sans construire, exécutez les compilateurs individuels avec --check :

python3 scripts/probecompile.py --check
python3 scripts/thesiscompile.py --check
python3 scripts/verdictcompile.py --check
python3 scripts/smebitcompile.py --check
python3 scripts/bitbundlecompile.py --check
python3 scripts/reportcompile.py --check

Signals

Un Signal (anciennement appelé probe) est une requête diagnostique déclarative qui scanne les données Gold pour un pattern spécifique. Chaque Signal produit des findings avec un score continu (0-100), une évaluation d’impact, et optionnellement une polarity (positive/negative/neutral) et une direction (improving/stable/worsening).

Emplacement : probes/probe_*.yaml (ou assessment_*.yaml) — le format YAML utilise toujours probe_id comme nom de champ

Types : balance, ratio, duplicate, distribution_outlier, temporal_sequence, mandatory_item, trend, silver_audit, entity_filter, enrichment, reconciliation, hand_written, assessment

Sortie : Findings standardisés avec finding_id, score (0-100), entity_id, impact (valeur + unité + dimension), evidence

Theses

Une Thesis (anciennement appelée hypothesis) est une question métier testable qui agrège des preuves depuis plusieurs Signals.

Emplacement : theses/thesis_*.yaml

Statuts Thesis : confirmed, plausible, not_observed, insufficient

Rôles de preuve : primary (poids 3), supporting (poids 2), context (poids 1), counter (réduit le score)

Verdicts

Un Verdict (anciennement appelé diagnosis) explique pourquoi une Thesis confirmée est vraie, avec des causes racines et des recommandations.

Emplacement : verdicts/verdict_*.yaml

Catégories de cause racine : process_failure, system_failure, data_quality, behavioral, structural, external

SMEbits

Un SMEbit est une pièce atomique de connaissance experte — attribuée, délimitée, avec un check testable optionnel.

Emplacement : smebits/smebit_*.yaml

Niveaux :

• Level 0 (Observation) : documentation uniquement, pas de SQL
• Level 1 (Check) : assertion testable, produit un verdict confirmed/violated/no_data

Catégories : data_quality, mapping, business_rule, process, system, seasonal, historical, structural

BitBundles

Un BitBundle regroupe des SMEbits liés dans un narratif — la couche « histoire ».

Emplacement : bitbundles/bb_*.yaml

Perspectives

Une Perspective (anciennement appelée assessment) est un Signal spécial qui agrège les findings d’autres Signals en scores de santé au niveau entité.

Emplacement : probes/assessment_*.yaml (type: assessment, contract: findings.v1) — le format YAML utilise toujours le préfixe assessment

Reports

Un Report est un document défini déclarativement qui se compile en SQL dbt et se rend en PDF via WeasyPrint.

Emplacement : reports/report_*.yaml

Types de section : kpi_grid, callout, severity_bar, table, text, footer, chart_bar, chart_trend

Sortie : Registre + tables de données dans le KLS, PDF stocké comme BLOB dans la table report_pdfs. Consultable et téléchargeable dans l’Explorer à /{tenant}/reports.

Les requêtes utilisent des template helpers : {{ gold('entity') }}, {{ silver('entity') }}, {{ ref('model') }}, {{ var("tenant_id") }}

Contracts

Chaque type d’instrument a un Contract JSON définissant le schéma :

• contracts/gold_contract.v1.json — entités Gold (les Signals référencent ceci)
• contracts/silver_contract.v1.json — entités Silver
• contracts/findings_contract.v1.json — Signal Findings
• contracts/diagnosis_contract.v1.json — Verdict Findings
• contracts/smebit_contract.v1.json — registre SMEbit + verdicts
• contracts/bitbundle_contract.v1.json — registre BitBundle
• contracts/report_contract.v1.json — registre Report + données

Le cycle Make-Explore-Evolve

make → build KLS from data + instruments
explore → browse findings, test theses, review evidence
evolve → adjust signals, refine theses, capture SMEbits
→ make again (each cycle deepens understanding)