Benjamin Admin
e1b270c36e
Sichert die validierte Obligation Discovery Pipeline aus /tmp als dauerhaftes, committetes Tooling (scripts/obligation_discovery/) — der eigentliche Vermögenswert. Stufen: precluster (Embedding-Cache + Mikro-Cluster) → meta_cluster (Review Units, Skalierungs-Fix) → synthesize_obligations (Opus, Key aus ENV, Streaming, harte Tier-Regel, Provenance) → validate_registry → merge_review_diff. Reine Helfer in _core.py, 16 Unit-Tests. Doku docs-src/development/obligation_discovery_pipeline_v1.md mit Meilensteinen (SBOM/Vuln reproduziert, Auth 4408→170 Review Units→54→kuriert 29) und der Architekturregel: Runtime deterministisch, Discovery LLM-gestützt. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
78 lines
4.0 KiB
Markdown
78 lines
4.0 KiB
Markdown
# 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
|
||
```
|