Benjamin Admin
a3053c3c86
9 docs + index in docs-src/architecture/ documenting the deterministic retrieval engine: retrieval pipeline, authority rerank, source_class, source_role, control-intent + diversity, assessment, confidence, explainability + supersede, framework_* layer. Each doc carries the exact constants, the rationale behind them, code refs, and the failure class it addresses. Audit/onboarding reference. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
3.7 KiB
RAG-Retrieval-Engine — Architektur
Diese Sektion dokumentiert die deterministische, regelbasierte Retrieval-Engine des Compliance-SDK (ai-compliance-sdk/internal/ucca/). Sie beantwortet für jede Nutzerfrage: Welche Norm/Quelle ist relevant — und warum?
Warum diese Doku existiert: Die Engine trifft viele bewusste
+0.05 / +0.10-Entscheidungen. Jede Konstante kodiert eine gemessene Entscheidung (Golden-Harness, Fehlerklasse) — nicht eine willkürliche Stellschraube. Ohne das Warum sind sie in sechs Monaten nicht mehr nachvollziehbar; diese Doku ist die Referenz für Wartung, Onboarding und Audit-/Investoren-Nachweis.
Leitprinzip
Nicht raten, nicht erzwingen, sondern relevante Quellenarten sichtbar machen.
Der LLM entscheidet nicht, was Recht ist — nur, wie eine bereits versionierte, zitierte Norm auf einen Sachverhalt gemappt wird. Wo möglich ist die Engine deterministisch (Marker, Gewichte, Schwellen), nicht modellbasiert. Nichts wird gelöscht — Re-Ranking ist reine Reihenfolge, alles bleibt auffindbar.
Zwei orthogonale Achsen
Der Kern des Modells: zwei unabhängige Achsen, die in der Literatur meist vermischt werden.
| Achse | Frage | Wirkung | Doku |
|---|---|---|---|
source_class (Rechtsnatur) |
Wie bindend ist die Quelle? | bestimmt den Rang | 03 |
source_role (Funktion) |
Was tut die Quelle im Dokument? | bestimmt die Control-Pool-Zugehörigkeit | 04 |
Beispiel: NIST ist technical_standard (source_class) und control_standard (source_role). ENISA-Good-Practices sind supervisory_guidance und implementation_guidance — sie bleiben guidance, dürfen aber bei Umsetzungsfragen in den Control-Pool.
Pipeline (Überblick)
Query
│ bge-m3 Embedding
▼
Retrieval-Pool ── hybrid (RRF) + binding-Augmentation + control-Augmentation + (graph) → 01
▼
Authority-Rerank ── source_class → Rang (bindendes Recht der passenden Jurisdiktion oben) → 02, 03
▼
Control-Intent ── source_role → Control-Pool + Diversity (Quellenarten sichtbar machen) → 04, 05
▼
Assessment ── PrimaryNorm · ConnectedNorms · WinnerMargin · CrossRegime → 06
▼
Confidence/Explainability ── HumanReviewFlag · Zitate · Graph-Kanten · Supersede → 07, 08
framework_* (09) ist die Daten-Brücke zur nächsten Stufe (Control → Evidence) — heute in der Qdrant-Payload, noch nicht im Retrieval-Code verdrahtet.
Dokumente
| # | Dokument | Inhalt |
|---|---|---|
| 01 | Retrieval-Pipeline | Pool-Aufbau: hybrid + binding + control + graph |
| 02 | Authority-Re-Ranking | source_class → Rang, Bonus/Penalty-System |
| 03 | source_class | Rechtsnatur, Gewichte, Marker, Standard-Name-Override |
| 04 | source_role | 7 Rollen, Control-Pool, Klassifikation |
| 05 | Control-Intent + Diversity | Intent-Erkennung, Rollen-Bonus, Diversity-Regel |
| 06 | Assessment | Auditierbare Begründungsschicht |
| 07 | Confidence | WinnerMargin, HumanReviewFlag |
| 08 | Explainability + Supersede | Zitate, Graph-Kanten, Supersede |
| 09 | framework_*-Layer | Control-Mapping-Brücke (CRA Annex → OWASP V6.x) |
Fehlerklassen-These: Modell und Korpus sind austauschbar; die Fehlerklassen + Hebel sind das IP. Jede Konstante unten adressiert eine benannte Fehlerklasse (z.B. „Guidance verdrängt Gesetz", „Standard als guidance mistagged"). Die Kalibrierung ist sublinear: wenige Klassen, viele Module.