breakpilot-compliance/docs-src/development/obligation_discovery_pipeline_v1.md

Obligation Discovery Pipeline v1

Ein generisches Verfahren zur Ableitung einer regulatorischen Ontologie (Legal Obligation Registry) aus großen Compliance-Korpora. Validiert über drei Domänen (SBOM, Vulnerability Handling, Authentication). Erzeugt die zitierfähige Mitte aus obligation_registry_v1.md.

Architekturregel (nicht verhandelbar)

RUNTIME bleibt deterministisch          (Document → Embedding → LLM-Judge → Finding)
DISCOVERY darf LLM-gestützt sein        (Controls → … → LLM-Synthese → Obligation Registry)

Discovery läuft einmalig/offline mit dem stärksten Modell; die Runtime-Prüf-Engine wird davon nicht berührt. Zwei getrennte Probleme, eine gemeinsame Sprache (die Obligation).

Stufen (scripts/obligation_discovery/)

Stufe	Skript	Aufgabe	Key
1	precluster.py	Controls (scope) → Embedding (gecacht) → Mikro-Cluster	–
2	meta_cluster.py	Mikro → Review Units (Skalierungs-Fix für große Domänen)	–
3	synthesize_obligations.py	Review Units → Opus → Obligation Candidates	ENV
4	validate_registry.py	Belastbarkeits-Checks	–
5	merge_review_diff.py	vorgeschlagene Beziehungskanten dedupliziert mergen	–

Reine, unit-getestete Helfer in _core.py. Ausführung im bp-compliance-backend-Container (PYTHONPATH=/app); der Key kommt aus ANTHROPIC_API_KEY (nie hartcodiert).

Zwei-Stufen-Clustering = der Skalierungs-Fix

Ein flacher Single-Threshold-Pre-Cluster + EIN LLM-Synthese-Call skaliert NICHT auf große Domänen. Lösung: eine Hierarchiestufe. Review Unit ≠ Meta-Cluster — die Review Unit ist das, was der LLM sieht (entkoppelt vom Clustering, später merge/split-bar).

Belegte Meilensteine

Domäne	Controls	→ Cluster/Review Units	→ Obligations	vs Ground Truth
SBOM	258	86 Mikro	12 (→ 11 final)	manuell ~10 — reproduziert + verfeinert
Vulnerability	531	200 Mikro	8	manuell ~7 — reproduziert
Authentication	4408	2134 Mikro → 170 Review Units	54 → Kuration 29	Skalierung — generalisiert

Harte Tier-Regel generalisiert

LEGAL_MINIMUM nur mit Primärrechts-Anker (legal_basis), sonst BEST_PRACTICE / IMPLEMENTATION_GUIDANCE / EVIDENCE. Authentication zeigt den Wert: nur 6 harte Pflichten (CRA fordert „angemessene Authentisierung"), MFA/Passwort/Session/Krypto sind guidance_basis. So kann der Advisor sagen: „Gesetzlich gefordert ist Schutz vor unbefugtem Zugriff; MFA ist anerkannte Umsetzung, aber keine CRA-Wortlautpflicht."

Kuration (große Domänen)

Die Synthese darf über-splitten; ein key-freier, regelbasierter Kurations-Pass verdichtet: Krypto-Mikro-Mechanismen → guidance_basis; Prüf-/Nachweis-Themen → evidence-Facette; Mechanismus-Familien bleiben; domänenfremdes (eID/PSD2) → out_of_scope; LEGAL_MINIMUM unangetastet.

Lessons

• Große Opus-Calls brauchen Streaming (messages.stream); der SDK blockt non-streaming bei max_tokens > ~8k mit „Streaming is required for operations that may take longer than 10 minutes".
• Provenance pro Obligation (source_meta_cluster, discovery_confidence, llm_model, synthesis_version) — für spätere Evolution (CRA-Update, Modellwechsel).
• >8 Obligations / Review Unit → automatische Review-Warnung (Over-Split-Indikator).
• Embedding-Cache (pickle) → THR2-Sweeps ohne Re-Embed.

End-to-End-Beispiel

# im bp-compliance-backend-Container, PYTHONPATH=/app, cwd = scripts/obligation_discovery
python3 precluster.py  --scope auth
python3 meta_cluster.py --scope auth --meta-thr 0.62          # → /tmp/auth_review_units.json (inspizieren!)
ANTHROPIC_API_KEY=… python3 synthesize_obligations.py \
    --units /tmp/auth_review_units.json --regulation CRA --theme "Authentisierung" --out /tmp/auth_registry.json
python3 validate_registry.py /tmp/auth_registry.json