breakpilot-pwa/backend/docs/compliance_ai_integration.md

Compliance AI Integration - Sprint 4

Ubersicht

Die Compliance AI Integration bietet KI-gestutzte Funktionen zur automatischen Interpretation von regulatorischen Anforderungen, Vorschlagen von Controls und Risikobewertung fur Breakpilot-Module.

Architektur

Client → FastAPI Routes → AIComplianceAssistant → LLMProvider
                                                    ├─ AnthropicProvider (Claude API)
                                                    ├─ SelfHostedProvider (Ollama/vLLM)
                                                    └─ MockProvider (Testing)

Komponenten

1. LLM Provider Abstraction (llm_provider.py)

Abstrakte Basisklasse: LLMProvider

• complete(): Einzelne Completion
• batch_complete(): Batch-Verarbeitung mit Rate-Limiting

Implementierungen:

AnthropicProvider

• Verwendet Claude API (https://api.anthropic.com)
• Empfohlen fur Produktion (beste Qualitat)
• Model: claude-sonnet-4-20250514 (Standard)
• Benotigt: ANTHROPIC_API_KEY

SelfHostedProvider

• Unterstutzung fur Ollama, vLLM, LocalAI
• Auto-Detection von API-Formaten (Ollama vs. OpenAI-kompatibel)
• Kostengunstige Alternative fur Self-Hosting
• Benotigt: SELF_HOSTED_LLM_URL

MockProvider

• Fur Unit-Tests ohne echte API-Calls
• Vordefinierte Antworten moglich

Factory Function: get_llm_provider(config?: LLMConfig) -> LLMProvider

2. AI Compliance Assistant (ai_compliance_assistant.py)

Hauptklasse fur alle KI-Funktionen:

from compliance.services.ai_compliance_assistant import get_ai_assistant

assistant = get_ai_assistant()

Methoden

interpret_requirement()

• Ubersetzt rechtliche Anforderungen in technische Anleitung
• Identifiziert betroffene Breakpilot-Module
• Bewertet Risiko-Level
• Gibt Implementierungs-Hinweise

suggest_controls()

• Schlagt 1-3 passende Controls vor
• Domain-Zuordnung (priv, iam, sdlc, crypto, ops, ai, cra, gov, aud)
• Gibt Implementierungs-Guidance und Pass-Criteria
• Erkennt automatisierbare Controls

assess_module_risk()

• Bewertet Compliance-Risiko fur Service-Module
• Berucksichtigt: PII-Verarbeitung, KI-Komponenten, Kritikalitat
• Identifiziert Compliance-Lucken
• Gibt Empfehlungen zur Risikominderung

analyze_gap()

• Analysiert Coverage zwischen Requirements und Controls
• Identifiziert fehlende Abdeckung
• Schlagt konkrete Massnahmen vor

batch_interpret_requirements()

• Verarbeitet mehrere Requirements mit Rate-Limiting
• Fur Bulk-Processing von Regulations

3. API Endpoints (routes.py)

Alle Endpoints unter /api/v1/compliance/ai/:

GET /ai/status

Pruft Status des AI Providers

Response:

{
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "is_available": true,
  "is_mock": false,
  "error": null
}

POST /ai/interpret

Interpretiert eine Anforderung

Request:

{
  "requirement_id": "uuid",
  "force_refresh": false
}

Response:

{
  "requirement_id": "uuid",
  "summary": "Kurze Zusammenfassung",
  "applicability": "Wie dies auf Breakpilot anwendbar ist",
  "technical_measures": ["Massnahme 1", "Massnahme 2"],
  "affected_modules": ["consent-service", "klausur-service"],
  "risk_level": "high",
  "implementation_hints": ["Hinweis 1", "Hinweis 2"],
  "confidence_score": 0.85,
  "error": null
}

POST /ai/suggest-controls

Schlagt Controls fur eine Anforderung vor

Request:

{
  "requirement_id": "uuid"
}

Response:

{
  "requirement_id": "uuid",
  "suggestions": [
    {
      "control_id": "PRIV-042",
      "domain": "priv",
      "title": "Verschlusselung personenbezogener Daten",
      "description": "...",
      "pass_criteria": "Alle PII sind AES-256 verschlusselt",
      "implementation_guidance": "...",
      "is_automated": true,
      "automation_tool": "SOPS + Age",
      "priority": "high",
      "confidence_score": 0.9
    }
  ]
}

POST /ai/assess-risk

Bewertet Risiko fur ein Modul

Request:

{
  "module_id": "consent-service"
}

Response:

{
  "module_name": "consent-service",
  "overall_risk": "high",
  "risk_factors": [
    {
      "factor": "Verarbeitet personenbezogene Daten",
      "severity": "high",
      "likelihood": "high"
    }
  ],
  "recommendations": ["Empfehlung 1", "Empfehlung 2"],
  "compliance_gaps": ["Lucke 1", "Lucke 2"],
  "confidence_score": 0.8
}

POST /ai/gap-analysis

Analysiert Coverage-Lucken

Request:

{
  "requirement_id": "uuid"
}

Response:

{
  "requirement_id": "uuid",
  "requirement_title": "Art. 32 DSGVO - Sicherheit der Verarbeitung",
  "coverage_level": "partial",
  "existing_controls": ["PRIV-001", "PRIV-002"],
  "missing_coverage": ["Fehlende Massnahme 1"],
  "suggested_actions": ["Aktion 1", "Aktion 2"]
}

POST /ai/batch-interpret

Batch-Interpretation mehrerer Requirements

Request:

{
  "requirement_ids": ["uuid1", "uuid2"],
  "regulation_code": "GDPR",
  "rate_limit": 1.0
}

Response:

{
  "total": 10,
  "processed": 10,
  "interpretations": [...]
}

Konfiguration

Environment Variables

Grundeinstellungen

# Provider-Auswahl
COMPLIANCE_LLM_PROVIDER=anthropic  # oder: self_hosted, mock

# LLM-Parameter
COMPLIANCE_LLM_MAX_TOKENS=4096
COMPLIANCE_LLM_TEMPERATURE=0.3
COMPLIANCE_LLM_TIMEOUT=60.0

Anthropic Claude (empfohlen)

ANTHROPIC_API_KEY=sk-ant-...
ANTHROPIC_MODEL=claude-sonnet-4-20250514

Self-Hosted Alternative

COMPLIANCE_LLM_PROVIDER=self_hosted
SELF_HOSTED_LLM_URL=http://localhost:11434
SELF_HOSTED_LLM_MODEL=llama3.1:8b
SELF_HOSTED_LLM_KEY=optional-api-key

Prompts

Alle Prompts sind auf Deutsch und Breakpilot-spezifisch:

• Berucksichtigt EdTech-Kontext (Schulverwaltung, Noten, Zeugnisse)
• Kennt KI-Funktionen (Klausurkorrektur, Feedback)
• Berucksichtigt DSGVO-Anforderungen
• Versteht Breakpilot-Module (consent-service, klausur-service, etc.)

Verwendung

Beispiel 1: Requirement interpretieren

from compliance.services.ai_compliance_assistant import get_ai_assistant

assistant = get_ai_assistant()

result = await assistant.interpret_requirement(
    requirement_id="req-123",
    article="Art. 32",
    title="Sicherheit der Verarbeitung",
    requirement_text="Der Verantwortliche muss...",
    regulation_code="GDPR",
    regulation_name="DSGVO"
)

print(f"Risiko: {result.risk_level}")
print(f"Betroffene Module: {', '.join(result.affected_modules)}")

Beispiel 2: Controls vorschlagen

suggestions = await assistant.suggest_controls(
    requirement_title="Verschlusselung in Ruhe und bei Ubertragung",
    requirement_text="Personenbezogene Daten mussen...",
    regulation_name="DSGVO",
    affected_modules=["consent-service", "klausur-service"]
)

for control in suggestions:
    print(f"{control.control_id}: {control.title}")
    print(f"  Domain: {control.domain}")
    print(f"  Automatisierbar: {control.is_automated}")

Beispiel 3: Batch-Processing

requirements = [
    {"id": "req-1", "article": "Art. 32", ...},
    {"id": "req-2", "article": "Art. 33", ...},
]

results = await assistant.batch_interpret_requirements(
    requirements=requirements,
    rate_limit=1.0  # 1 Sekunde zwischen Calls
)

for r in results:
    if r.error:
        print(f"Fehler bei {r.requirement_id}: {r.error}")
    else:
        print(f"{r.requirement_id}: {r.summary}")

Rate Limiting

• Anthropic: 1 Request/Sekunde (Standard)
• Self-Hosted: 0.5 Sekunden (kann schneller sein)
• Konfigurierbar uber rate_limit Parameter

Error Handling

Alle Methoden fangen Exceptions ab und geben valide Responses zuruck:

result = await assistant.interpret_requirement(...)

if result.error:
    print(f"Fehler aufgetreten: {result.error}")
    print(f"Confidence: {result.confidence_score}")  # 0.0 bei Fehler
else:
    print(f"Erfolgreich: {result.summary}")

Testing

Unit Tests mit MockProvider

from compliance.services.llm_provider import MockProvider, LLMConfig, LLMProviderType

# Mock-Provider erstellen
config = LLMConfig(provider_type=LLMProviderType.MOCK)
provider = MockProvider(config)

# Vordefinierte Antworten
provider.set_responses([
    '{"summary": "Test-Antwort", "risk_level": "low"}'
])

# AI Assistant mit Mock
assistant = AIComplianceAssistant(llm_provider=provider)
result = await assistant.interpret_requirement(...)

Integration Tests

# Mock-Provider verwenden
export COMPLIANCE_LLM_PROVIDER=mock

# Backend starten
cd backend && uvicorn main:app --reload

# Tests ausfuhren
pytest tests/test_compliance_ai.py -v

Best Practices

1. Provider-Auswahl

• Produktion: Anthropic Claude (beste Qualitat)
• Entwicklung: Self-Hosted Ollama (kostenlos)
• Tests: MockProvider (schnell, deterministisch)

2. Caching

Die AI-Interpretationen sollten gecached werden:

• Speichere result.raw_response in DB
• Setze force_refresh=True nur bei Bedarf
• Reduziert API-Kosten erheblich

3. Batch-Processing

Fur initiales Setup von Regulations:

• Verwende batch_interpret_requirements()
• Setze rate_limit entsprechend Provider
• Verarbeite maximal 50 Requirements pro Batch

4. Fehlerbehandlung

Immer result.error prufen:

if result.error:
    logger.warning(f"AI failed, using fallback: {result.error}")
    # Fallback-Logik
else:
    # Verwende AI-Ergebnis

5. Monitoring

Tracke folgende Metriken:

• Response Times
• Error Rates
• Confidence Scores
• Token Usage (bei Anthropic)

Roadmap

Bereits implementiert (Sprint 4)

• LLM Provider Abstraction
• Anthropic + Self-Hosted Support
• AI Compliance Assistant
• Alle API Endpoints
• Batch-Processing

Geplant (Sprint 5+)

• Response Caching in DB
• Background Job Queue fur Batch-Processing
• Webhook-Support fur Async Processing
• Fine-Tuning auf Breakpilot-Daten
• Multi-Model Ensemble (kombiniert mehrere LLMs)
• Automatisches Re-Training basierend auf Auditor-Feedback

Support

Bei Fragen oder Problemen:

1. Prufe /api/v1/compliance/ai/status
2. Prufe Logs: docker logs breakpilot-backend
3. Teste mit MockProvider: COMPLIANCE_LLM_PROVIDER=mock

Lizenz

Teil des BreakPilot Compliance Frameworks. Alle Rechte vorbehalten.