Instrumente Guide

Instrumente sind deklarative analytische Artefakte, die zu SQL kompiliert werden. Sie bilden die analytische Pyramide — jede Ebene baut auf der darunterliegenden auf.

Die Pyramide

Neben der Pyramide erfassen zwei unabhaengige Systeme menschliches Wissen:

• SMEbits — atomare Expertenbeobachtungen und Checks (freischwebend, verlinkt durch Anker)
• BitBundles — kuratierte Narrative, die SMEbits gruppieren

Workflow

Alle Instrumente folgen demselben Workflow:

# 1. YAML im AFS erstellen oder bearbeiten (probes/, theses/, smebits/, usw.)
#    Hinweis: Signals werden weiterhin im probes/ Verzeichnis mit probe_id deklariert

# 2. Bauen — make uebernimmt Validierung, Kompilierung und dbt automatisch
jin make

Das ist alles. make fuehrt alle Validatoren und Compiler in der richtigen Reihenfolge als Teil seines Build-DAG aus. Du musst Compiler nie manuell ausfuehren.

Um zu pruefen was nicht synchron ist ohne zu bauen, fuehre einzelne Compiler mit --check aus:

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

Ein Signal (frueher Probe genannt) ist eine deklarative diagnostische Abfrage, die Gold-Daten nach einem bestimmten Muster durchsucht. Jedes Signal produziert Findings mit einem kontinuierlichen Score (0-100), Impact-Bewertung und optionaler Polarity (positive/negative/neutral) und Direction (improving/stable/worsening).

Ort: probes/probe_*.yaml (oder assessment_*.yaml) — das YAML-Format verwendet weiterhin probe_id als Feldname

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

Ausgabe: Standardisierte Findings mit finding_id, score (0-100), entity_id, impact (Wert + Einheit + Dimension), evidence

Theses

Eine Thesis (frueher Hypothesis genannt) ist eine testbare Geschaeftsfrage, die Evidenz aus mehreren Signals aggregiert.

Ort: theses/thesis_*.yaml

Thesis Status: confirmed, plausible, not_observed, insufficient

Evidence Roles: primary (Gewicht 3), supporting (Gewicht 2), context (Gewicht 1), counter (reduziert Score)

Verdicts

Ein Verdict (frueher Diagnosis genannt) erklaert warum eine bestaetigte Thesis wahr ist, mit Root Causes und Empfehlungen.

Ort: verdicts/verdict_*.yaml

Root Cause Categories: process_failure, system_failure, data_quality, behavioral, structural, external

SMEbits

Ein SMEbit ist ein atomares Stueck Expertenwissen — zugeschrieben, begrenzt, mit einem optionalen testbaren Check.

Ort: smebits/smebit_*.yaml

Level:

• Level 0 (Beobachtung): nur Dokumentation, kein SQL
• Level 1 (Check): testbare Behauptung, produziert confirmed/violated/no_data Verdict

Kategorien: data_quality, mapping, business_rule, process, system, seasonal, historical, structural

BitBundles

Ein BitBundle gruppiert verwandte SMEbits in ein Narrativ — die “Story”-Ebene.

Ort: bitbundles/bb_*.yaml

Perspectives

Eine Perspective (frueher Assessment genannt) ist ein spezielles Signal, das Findings aus anderen Signals in Entity-Level Health Scores aggregiert.

Ort: probes/assessment_*.yaml (type: assessment, contract: findings.v1) — das YAML-Format verwendet weiterhin das Assessment-Praefix

Reports

Ein Report ist ein deklarativ definiertes Dokument, das zu dbt SQL kompiliert und via WeasyPrint zu PDF gerendert wird.

Ort: reports/report_*.yaml

Abschnittstypen: kpi_grid, callout, severity_bar, table, text, footer, chart_bar, chart_trend

Ausgabe: Registry + Datentabellen im KLS, PDF gespeichert als BLOB in report_pdfs Tabelle. Im Explorer anzeigbar und herunterladbar unter /{tenant}/reports.

Abfragen verwenden Template-Helfer: {{ gold('entity') }}, {{ silver('entity') }}, {{ ref('model') }}, {{ var("tenant_id") }}

Contracts

Jeder Instrumententyp hat einen JSON Contract, der das Schema definiert:

• contracts/gold_contract.v1.json — Gold Entities (Signals referenzieren dies)
• contracts/silver_contract.v1.json — Silver Entities
• contracts/findings_contract.v1.json — Signal Findings
• contracts/diagnosis_contract.v1.json — Verdict Findings
• contracts/smebit_contract.v1.json — SMEbit Registry + Verdicts
• contracts/bitbundle_contract.v1.json — BitBundle Registry
• contracts/report_contract.v1.json — Report Registry + Daten

Der Make–Explore–Evolve-Zyklus

make → KLS aus Daten + Instrumenten bauen
explore → Findings durchsuchen, Theses testen, Evidenz pruefen
evolve → Signals anpassen, Theses verfeinern, SMEbits erfassen
→ erneut make (jeder Zyklus vertieft das Verstaendnis)