# 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](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

```bash
# 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
```