breakpilot-compliance/docs-src/services/ai-compliance-sdk/DEVELOPER.md

AI Compliance SDK - Entwickler-Dokumentation

Inhaltsverzeichnis

1. Schnellstart
2. Architektur-Übersicht
3. Policy Engine
4. License Policy Engine
5. Legal RAG Integration
6. Wizard & Legal Assistant
7. Eskalations-System
8. API-Endpoints
9. Policy-Dateien
10. Tests ausführen

---

1. Schnellstart

Voraussetzungen

• Go 1.21+
• PostgreSQL (für Eskalations-Store)
• Qdrant (für Legal RAG)
• Ollama oder Anthropic API Key (für LLM)

Build & Run

# Build
cd ai-compliance-sdk
go build -o server ./cmd/server

# Run
./server --config config.yaml

# Alternativ: mit Docker
docker compose up -d

Erste Anfrage

# UCCA Assessment erstellen
curl -X POST http://localhost:8080/sdk/v1/ucca/assess \
  -H "Content-Type: application/json" \
  -d '{
    "use_case_text": "Chatbot für Kundenservice mit FAQ-Suche",
    "domain": "utilities",
    "data_types": {
      "personal_data": false,
      "public_data": true
    },
    "automation": "assistive",
    "model_usage": {
      "rag": true
    },
    "hosting": {
      "region": "eu"
    }
  }'

---

2. Architektur-Übersicht

┌─────────────────────────────────────────────────────────────────┐
│                        API Layer (Gin)                           │
│                    internal/api/handlers/                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                   │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │   UCCA      │  │   License   │  │      Eskalation         │  │
│  │   Handler   │  │   Handler   │  │      Handler            │  │
│  └──────┬──────┘  └──────┬──────┘  └───────────┬─────────────┘  │
│         │                │                      │                │
├─────────┼────────────────┼──────────────────────┼────────────────┤
│         ▼                ▼                      ▼                │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │   Policy    │  │   License   │  │   Escalation            │  │
│  │   Engine    │  │   Policy    │  │   Store                 │  │
│  │             │  │   Engine    │  │                         │  │
│  └──────┬──────┘  └──────┬──────┘  └───────────┬─────────────┘  │
│         │                │                      │                │
│         └────────┬───────┴──────────────────────┘                │
│                  ▼                                               │
│         ┌─────────────────────────────────────────────────┐     │
│         │              Legal RAG System                    │     │
│         │         (Qdrant + LLM Integration)              │     │
│         └─────────────────────────────────────────────────┘     │
│                                                                   │
└─────────────────────────────────────────────────────────────────┘

Kernprinzip

LLM ist NICHT die Quelle der Wahrheit!

Komponente	Entscheidet	LLM-Nutzung
Policy Engine	Feasibility, Risk Level	Nein
License Engine	Operation Mode, Stop-Lines	Nein
Gap Mapping	Facts → Gaps → Controls	Nein
Legal RAG	Erklärung generieren	Ja (nur Output)

---

3. Policy Engine

Übersicht

Die Policy Engine (internal/ucca/policy_engine.go) evaluiert Use Cases gegen deterministische Regeln.

Verwendung

import "ai-compliance-sdk/internal/ucca"

// Engine erstellen
engine, err := ucca.NewPolicyEngineFromPath("policies/ucca_policy_v1.yaml")
if err != nil {
    log.Fatal(err)
}

// Intake erstellen
intake := &ucca.UseCaseIntake{
    UseCaseText: "Chatbot für Kundenservice",
    Domain:      ucca.DomainUtilities,
    DataTypes: ucca.DataTypes{
        PersonalData: false,
        PublicData:   true,
    },
    Automation: ucca.AutomationAssistive,
    ModelUsage: ucca.ModelUsage{
        RAG: true,
    },
    Hosting: ucca.Hosting{
        Region: "eu",
    },
}

// Evaluieren
result := engine.Evaluate(intake)

// Ergebnis auswerten
fmt.Println("Feasibility:", result.Feasibility)   // YES, NO, CONDITIONAL
fmt.Println("Risk Level:", result.RiskLevel)      // MINIMAL, LOW, MEDIUM, HIGH
fmt.Println("Risk Score:", result.RiskScore)      // 0-100

Ergebnis-Struktur

type EvaluationResult struct {
    Feasibility           Feasibility            // YES, NO, CONDITIONAL
    RiskLevel             RiskLevel              // MINIMAL, LOW, MEDIUM, HIGH
    RiskScore             int                    // 0-100
    TriggeredRules        []TriggeredRule        // Ausgelöste Regeln
    RequiredControls      []Control              // Erforderliche Maßnahmen
    RecommendedArchitecture []Pattern            // Empfohlene Patterns
    DSFARecommended       bool                   // DSFA erforderlich?
    Art22Risk             bool                   // Art. 22 Risiko?
    TrainingAllowed       TrainingAllowed        // YES, NO, CONDITIONAL
    PolicyVersion         string                 // Version der Policy
}

Regeln hinzufügen

Neue Regeln werden in policies/ucca_policy_v1.yaml definiert:

rules:
  - id: R-CUSTOM-001
    code: R-CUSTOM-001
    category: custom
    title: Custom Rule
    title_de: Benutzerdefinierte Regel
    description: Custom rule description
    severity: WARN  # INFO, WARN, BLOCK
    gdpr_ref: "Art. 6 DSGVO"
    condition:
      all_of:
        - field: domain
          equals: custom_domain
        - field: data_types.personal_data
          equals: true
    controls:
      - C_CUSTOM_CONTROL

---

4. License Policy Engine

Übersicht

Die License Policy Engine (internal/ucca/license_policy.go) prüft die Lizenz-Compliance für Standards und Normen.

Operationsmodi

Modus	Beschreibung	Lizenzanforderung
LINK_ONLY	Nur Verweise	Keine
NOTES_ONLY	Eigene Notizen	Keine
EXCERPT_ONLY	Kurzzitate (<150 Zeichen)	Standard-Lizenz
FULLTEXT_RAG	Volltext-Embedding	Explizite KI-Lizenz
TRAINING	Modell-Training	Enterprise + Vertrag

Verwendung

import "ai-compliance-sdk/internal/ucca"

engine := ucca.NewLicensePolicyEngine()

facts := &ucca.LicensedContentFacts{
    Present:       true,
    Publisher:     "DIN_MEDIA",
    LicenseType:   "SINGLE_WORKSTATION",
    AIUsePermitted: "NO",
    ProofUploaded: false,
    OperationMode: "FULLTEXT_RAG",
}

result := engine.Evaluate(facts)

if !result.Allowed {
    fmt.Println("Blockiert:", result.StopLine.Message)
    fmt.Println("Effektiver Modus:", result.EffectiveMode)
}

Ingest-Entscheidung

// Prüfen ob Volltext-Ingest erlaubt ist
canIngest := engine.CanIngestFulltext(facts)

// Oder detaillierte Entscheidung
decision := engine.DecideIngest(facts)
fmt.Println("Fulltext:", decision.AllowFulltext)
fmt.Println("Notes:", decision.AllowNotes)
fmt.Println("Metadata:", decision.AllowMetadata)

Audit-Logging

// Audit-Entry erstellen
entry := engine.FormatAuditEntry("tenant-123", "doc-456", facts, result)

// Human-readable Summary
summary := engine.FormatHumanReadableSummary(result)
fmt.Println(summary)

Publisher-spezifische Regeln

DIN Media hat explizite Restriktionen:

// DIN Media blockiert FULLTEXT_RAG ohne AI-Lizenz
if facts.Publisher == "DIN_MEDIA" && facts.AIUsePermitted != "YES" {
    // → STOP_DIN_FULLTEXT_AI_NOT_ALLOWED
    // → Downgrade auf LINK_ONLY
}

---

5. Legal RAG Integration

Uebersicht

Das Legal RAG System (internal/ucca/legal_rag.go) stellt semantische Suche in Qdrant-Collections bereit. Es wird von mehreren Modulen konsumiert:

• UCCA Explain: LLM-Erklaerungen fuer Assessments
• Requirements AI (Python): interpret_requirement() und suggest_controls()
• DSFA Drafting (TypeScript): v1 + v2 Draft-Pipelines
• Requirements API (Python): ?include_legal_context=true Endpunkt

Go SDK — SearchCollection

import "ai-compliance-sdk/internal/ucca"

client := ucca.NewLegalRAGClient()

// Standard-Suche (bp_compliance_ce)
results, err := client.Search(ctx, "DSGVO Art. 35", nil, 5)

// Suche in spezifischer Collection
results, err := client.SearchCollection(ctx, "bp_compliance_recht", "BDSG §26", nil, 3)

// Leere Collection → Fallback auf Default (bp_compliance_ce)
results, err := client.SearchCollection(ctx, "", "DSGVO Art. 35", nil, 5)

Python RAG Client (Proxy)

from compliance.services.rag_client import get_rag_client

rag = get_rag_client()

# Async-Suche via Go SDK
results = await rag.search(
    "DSGVO Art. 35 Risikobewertung",
    collection="bp_compliance_recht",
    top_k=3
)

# Fuer LLM-Prompt formatieren
context_str = rag.format_for_prompt(results)
# → "## Relevanter Rechtskontext\n1. **DSGVO** (eu_2016_679) — Art. 35\n..."

TypeScript Shared Utility (Drafting Engine)

import { queryRAG } from '@/lib/sdk/drafting-engine/rag-query'

// Sucht via ai-compliance-sdk RAG (Qdrant)
const ragContext = await queryRAG('DSFA Art. 35 DSGVO', 3)
// → "[Quelle 1: DSGVO]\nArt. 35 regelt die DSFA..."

RAG Search API

# Suche in spezifischer Collection
curl -X POST http://localhost:8090/sdk/v1/rag/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Datenschutz-Folgenabschaetzung Art. 35",
    "collection": "bp_compliance_recht",
    "top_k": 3
  }'

# Antwort
{
  "query": "Datenschutz-Folgenabschaetzung Art. 35",
  "results": [
    {
      "text": "...",
      "regulation_code": "eu_2016_679",
      "regulation_name": "DSGVO",
      "regulation_short": "DSGVO",
      "score": 0.92
    }
  ],
  "count": 1
}

Erlaubte Collections (Whitelist)

Collection	Inhalt
bp_compliance_ce	EU-Verordnungen (DSGVO, AI Act, NIS2, CRA, ...)
bp_compliance_recht	Deutsche Gesetze (BDSG, TDDDG, DDG, ...)
bp_compliance_gesetze	Regulierungstexte fuer Modul-Matching
bp_compliance_datenschutz	DSGVO Datenschutzmassnahmen
bp_dsfa_corpus	DSFA Templates & Bewertungskriterien
bp_legal_templates	Rechtsdokument-Vorlagen (DSE, AGB, AVV)

Unbekannte Collections → 400 Bad Request.

Fehlertoleranz

RAG-Ausfaelle brechen nie die Hauptfunktion:

Schicht	Verhalten bei Fehler
Go SDK (SearchCollection)	Gibt error zurueck (Caller entscheidet)
Python (ComplianceRAGClient)	Gibt [] zurueck, loggt WARNING
TypeScript (queryRAG)	Gibt '' zurueck, kein throw
Requirements API	legal_context: [] statt HTTP 500

---

6. Wizard & Legal Assistant

Wizard-Schema

Das Wizard-Schema (policies/wizard_schema_v1.yaml) definiert die Fragen für das Frontend.

Legal Assistant verwenden

// Wizard-Frage an Legal Assistant stellen
type WizardAskRequest struct {
    Question    string                 `json:"question"`
    StepNumber  int                    `json:"step_number"`
    FieldID     string                 `json:"field_id,omitempty"`
    CurrentData map[string]interface{} `json:"current_data,omitempty"`
}

// POST /sdk/v1/ucca/wizard/ask

Beispiel API-Call

curl -X POST http://localhost:8080/sdk/v1/ucca/wizard/ask \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Was sind personenbezogene Daten?",
    "step_number": 2,
    "field_id": "data_types.personal_data"
  }'

---

7. Eskalations-System

Eskalationsstufen

Level	Auslöser	Prüfer	SLA
E0	Nur INFO	Automatisch	-
E1	WARN, geringes Risiko	Team-Lead	24h
E2	Art. 9, DSFA empfohlen	DSB	8h
E3	BLOCK, hohes Risiko	DSB + Legal	4h

Eskalation erstellen

import "ai-compliance-sdk/internal/ucca"

store := ucca.NewEscalationStore(db)

escalation := &ucca.Escalation{
    AssessmentID:    "assess-123",
    Level:           ucca.EscalationE2,
    TriggerReason:   "Art. 9 Daten betroffen",
    RequiredReviews: 1,
}

err := store.CreateEscalation(ctx, escalation)

SLA-Monitor

monitor := ucca.NewSLAMonitor(store, notificationService)

// Im Hintergrund starten
go monitor.Start(ctx)

---

8. API-Endpoints

UCCA Endpoints

Method	Endpoint	Beschreibung
POST	/sdk/v1/ucca/assess	Assessment erstellen
GET	/sdk/v1/ucca/assess/:id	Assessment abrufen
POST	/sdk/v1/ucca/explain	Erklärung generieren
GET	/sdk/v1/ucca/wizard/schema	Wizard-Schema abrufen
POST	/sdk/v1/ucca/wizard/ask	Legal Assistant fragen

RAG Endpoints

Method	Endpoint	Beschreibung
POST	/sdk/v1/rag/search	Multi-Collection RAG-Suche
GET	/sdk/v1/rag/regulations	Verfuegbare Regulierungen
GET	/sdk/v1/rag/corpus-status	Corpus-Versions-Status
GET	/sdk/v1/rag/corpus-versions/:collection	Versionshistorie

License Endpoints

Method	Endpoint	Beschreibung
POST	/sdk/v1/license/evaluate	Lizenz-Prüfung
POST	/sdk/v1/license/decide-ingest	Ingest-Entscheidung

Eskalations-Endpoints

Method	Endpoint	Beschreibung
GET	/sdk/v1/escalations	Offene Eskalationen
GET	/sdk/v1/escalations/:id	Eskalation abrufen
POST	/sdk/v1/escalations/:id/decide	Entscheidung treffen

---

9. Policy-Dateien

Dateistruktur

policies/
├── ucca_policy_v1.yaml        # Haupt-Policy (Regeln, Controls, Patterns)
├── wizard_schema_v1.yaml      # Wizard-Fragen und Legal Assistant
├── controls_catalog.yaml      # Detaillierte Control-Beschreibungen
├── gap_mapping.yaml           # Facts → Gaps → Controls
├── licensed_content_policy.yaml # Standards/Normen Compliance
└── scc_legal_corpus.yaml      # SCC Rechtsquellen

Policy-Version

Jede Policy hat eine Version:

metadata:
  version: "1.0.0"
  effective_date: "2025-01-01"
  author: "Compliance Team"

---

10. Tests ausführen

Alle Tests

cd ai-compliance-sdk
go test -v ./...

Spezifische Tests

# Policy Engine Tests
go test -v ./internal/ucca/policy_engine_test.go

# License Policy Tests
go test -v ./internal/ucca/license_policy_test.go

# Eskalation Tests
go test -v ./internal/ucca/escalation_test.go

Test-Coverage

go test -cover ./...

# HTML-Report
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

Beispiel: Neuen Test hinzufügen

func TestMyNewFeature(t *testing.T) {
    engine := NewLicensePolicyEngine()

    facts := &LicensedContentFacts{
        Present:       true,
        Publisher:     "DIN_MEDIA",
        OperationMode: "FULLTEXT_RAG",
    }

    result := engine.Evaluate(facts)

    if result.Allowed {
        t.Error("Expected blocked for DIN_MEDIA FULLTEXT_RAG")
    }
}

---

11. Generic Obligations Framework

Übersicht

Das Obligations Framework ermöglicht die automatische Ableitung regulatorischer Pflichten aus NIS2, DSGVO und AI Act.

Verwendung

import "ai-compliance-sdk/internal/ucca"

// Registry erstellen (lädt alle Module)
registry := ucca.NewObligationsRegistry()

// UnifiedFacts aufbauen
facts := &ucca.UnifiedFacts{
    Organization: ucca.OrganizationFacts{
        EmployeeCount:  150,
        AnnualRevenue:  30000000,
        Country:        "DE",
        EUMember:       true,
    },
    Sector: ucca.SectorFacts{
        PrimarySector:    "digital_infrastructure",
        SpecialServices:  []string{"cloud", "msp"},
        IsKRITIS:         false,
    },
    DataProtection: ucca.DataProtectionFacts{
        ProcessesPersonalData: true,
    },
    AIUsage: ucca.AIUsageFacts{
        UsesAI:             true,
        HighRiskCategories: []string{"employment"},
        IsGPAIProvider:     false,
    },
}

// Alle anwendbaren Pflichten evaluieren
overview := registry.EvaluateAll(facts, "Muster GmbH")

// Ergebnis auswerten
fmt.Println("Anwendbare Regulierungen:", len(overview.ApplicableRegulations))
fmt.Println("Gesamtzahl Pflichten:", len(overview.Obligations))
fmt.Println("Kritische Pflichten:", overview.ExecutiveSummary.CriticalObligations)

Neues Regulierungsmodul erstellen

// 1. Module-Interface implementieren
type MyRegulationModule struct {
    obligations       []ucca.Obligation
    controls          []ucca.ObligationControl
    incidentDeadlines []ucca.IncidentDeadline
}

func (m *MyRegulationModule) ID() string { return "my_regulation" }
func (m *MyRegulationModule) Name() string { return "My Regulation" }

func (m *MyRegulationModule) IsApplicable(facts *ucca.UnifiedFacts) bool {
    // Prüflogik implementieren
    return facts.Organization.Country == "DE"
}

func (m *MyRegulationModule) DeriveObligations(facts *ucca.UnifiedFacts) []ucca.Obligation {
    // Pflichten basierend auf Facts ableiten
    return m.obligations
}

// 2. In Registry registrieren
func NewMyRegulationModule() (*MyRegulationModule, error) {
    m := &MyRegulationModule{}
    // YAML laden oder hardcoded Pflichten definieren
    return m, nil
}

// In obligations_registry.go:
// r.Register(NewMyRegulationModule())

YAML-basierte Pflichten

# policies/obligations/my_regulation_obligations.yaml
regulation: my_regulation
name: "My Regulation"

obligations:
  - id: "MYREG-OBL-001"
    title: "Compliance-Pflicht"
    description: "Beschreibung der Pflicht"
    applies_when: "classification != 'nicht_betroffen'"
    legal_basis:
      - norm: "§ 1 MyReg"
    category: "Governance"
    responsible: "Geschäftsführung"
    deadline:
      type: "relative"
      duration: "12 Monate"
    sanctions:
      max_fine: "1 Mio. EUR"
    priority: "high"

controls:
  - id: "MYREG-CTRL-001"
    name: "Kontrollmaßnahme"
    category: "Technical"
    when_applicable: "immer"
    what_to_do: "Maßnahme implementieren"
    evidence_needed:
      - "Dokumentation"

PDF Export

import "ai-compliance-sdk/internal/ucca"

// Exporter erstellen
exporter := ucca.NewPDFExporter("de")

// PDF generieren
response, err := exporter.ExportManagementMemo(overview)
if err != nil {
    log.Fatal(err)
}

// base64-kodierter PDF-Inhalt
fmt.Println("Content-Type:", response.ContentType)  // application/pdf
fmt.Println("Filename:", response.Filename)

// PDF speichern
decoded, _ := base64.StdEncoding.DecodeString(response.Content)
os.WriteFile("memo.pdf", decoded, 0644)

// Alternativ: Markdown
mdResponse, err := exporter.ExportMarkdown(overview)
fmt.Println(mdResponse.Content)  // Markdown-Text

API-Endpoints

# Assessment erstellen
curl -X POST http://localhost:8090/sdk/v1/ucca/obligations/assess \
  -H "Content-Type: application/json" \
  -d '{
    "facts": {
      "organization": {"employee_count": 150, "country": "DE"},
      "sector": {"primary_sector": "healthcare"},
      "data_protection": {"processes_personal_data": true},
      "ai_usage": {"uses_ai": false}
    },
    "organization_name": "Test GmbH"
  }'

# PDF Export (direkt)
curl -X POST http://localhost:8090/sdk/v1/ucca/obligations/export/direct \
  -H "Content-Type: application/json" \
  -d '{
    "overview": { ... },
    "format": "pdf",
    "language": "de"
  }'

---

12. Tests für Obligations Framework

# Alle Obligations-Tests
go test -v ./internal/ucca/..._module_test.go

# NIS2 Module Tests
go test -v ./internal/ucca/nis2_module_test.go

# DSGVO Module Tests
go test -v ./internal/ucca/dsgvo_module_test.go

# AI Act Module Tests
go test -v ./internal/ucca/ai_act_module_test.go

# PDF Export Tests
go test -v ./internal/ucca/pdf_export_test.go

Beispiel-Tests

func TestNIS2Module_LargeCompanyInAnnexISector(t *testing.T) {
    module, _ := ucca.NewNIS2Module()

    facts := &ucca.UnifiedFacts{
        Organization: ucca.OrganizationFacts{
            EmployeeCount: 500,
            AnnualRevenue: 100000000,
            Country:       "DE",
        },
        Sector: ucca.SectorFacts{
            PrimarySector: "energy",
        },
    }

    if !module.IsApplicable(facts) {
        t.Error("Expected NIS2 to apply to large energy company")
    }

    classification := module.Classify(facts)
    if classification != "besonders_wichtige_einrichtung" {
        t.Errorf("Expected 'besonders_wichtige_einrichtung', got '%s'", classification)
    }
}

func TestAIActModule_HighRiskEmploymentAI(t *testing.T) {
    module, _ := ucca.NewAIActModule()

    facts := &ucca.UnifiedFacts{
        AIUsage: ucca.AIUsageFacts{
            UsesAI:             true,
            HighRiskCategories: []string{"employment"},
        },
    }

    if !module.IsApplicable(facts) {
        t.Error("Expected AI Act to apply")
    }

    riskLevel := module.ClassifyRisk(facts)
    if riskLevel != ucca.AIActHighRisk {
        t.Errorf("Expected 'high_risk', got '%s'", riskLevel)
    }
}

---

Anhang: Wichtige Dateien

Datei	Beschreibung
internal/ucca/policy_engine.go	Haupt-Policy-Engine
internal/ucca/license_policy.go	License Policy Engine
internal/ucca/legal_rag.go	Legal RAG Client (Multi-Collection Search)
internal/ucca/legal_rag_test.go	Tests fuer SearchCollection, Fallback
internal/api/handlers/rag_handlers.go	RAG Search API (Collection-Whitelist)
internal/api/handlers/rag_handlers_test.go	Tests fuer RAG Handler
internal/ucca/obligations_framework.go	Obligations Interfaces & Typen
internal/ucca/obligations_registry.go	Modul-Registry
internal/ucca/nis2_module.go	NIS2 Decision Tree
internal/ucca/dsgvo_module.go	DSGVO Pflichten
internal/ucca/ai_act_module.go	AI Act Risk Classification
internal/ucca/pdf_export.go	PDF/Markdown Export
internal/api/handlers/obligations_handlers.go	Obligations API
policies/obligations/*.yaml	Pflichten-Kataloge

Python Backend (RAG-Integration)

Datei	Beschreibung
backend-compliance/compliance/services/rag_client.py	ComplianceRAGClient (Proxy zum Go SDK)
backend-compliance/compliance/services/ai_compliance_assistant.py	AI Assistant mit RAG-Anreicherung
backend-compliance/compliance/api/routes.py	Requirements API mit ?include_legal_context
backend-compliance/tests/test_rag_client.py	Tests fuer RAG Client + Collection Mapping
backend-compliance/tests/test_routes_legal_context.py	Tests fuer Legal Context API

TypeScript Frontend (Drafting Engine RAG)

Datei	Beschreibung
admin-compliance/lib/sdk/drafting-engine/rag-query.ts	Shared queryRAG() Utility
admin-compliance/lib/sdk/drafting-engine/__tests__/rag-query.test.ts	Tests fuer queryRAG
admin-compliance/app/api/sdk/drafting-engine/draft/route.ts	Draft v1/v2 mit RAG-Kontext
admin-compliance/app/api/sdk/drafting-engine/chat/route.ts	Chat mit shared queryRAG Import

---

Dokumentationsstand: 2026-03-02