---
title: AI Magic Edits (Ops Runbook)
sidebar_label: AI Magic Edits
---

Dieses Runbook beschreibt den operativen Betrieb von AI Magic Edits (AI Styling) inklusive Entitlements, Provider-Betrieb, Monitoring, Recovery und Incident-Handling.

## 1. Scope und aktueller Stand

- Feature-Name im System: `ai_styling` (User-facing: "AI Magic Edits"/"AI-Styling").
- Architektur ist provider-agnostisch umgesetzt (`AiImageProvider` Interface), aktuell ist `runware.ai` als erster Provider aktiv.
- Das Guest-PWA-Rollout ist derzeit clientseitig hinter einem Flag deaktiviert:
  - `resources/js/guest-v2/lib/featureFlags.ts` → `GUEST_AI_MAGIC_EDITS_ENABLED = false`.
- Im Event Admin Control Room wird der AI-Bereich nur angezeigt, wenn das Event das Capability `ai_styling` hat.

## 2. Entitlements und Freischaltung

### 2.1 Paket-/Addon-Logik

- Erforderliches Paket-Feature: `ai_styling` (`config/ai-editing.php`).
- Standard-Addon-Key: `ai_styling_unlock` (`config/ai-editing.php`, `config/package-addons.php`).
- Entitlement wird event-spezifisch aufgelöst über:
  - aktives Event-Paket (`eventPackage.package.features`, Tabelle `event_packages`)
  - aktive, abgeschlossene Addons (`eventPackage.addons`, Tabelle `event_package_addons`, `status=completed`, optionales Ablaufdatum in `metadata`).
- Quelle der Berechtigung:
  - `granted_by=package` (Feature im Paket enthalten, z.B. Premium)
  - `granted_by=addon` (Addon für Event aktiv)
  - sonst gesperrt (`feature_locked`).

### 2.2 Superadmin-Konfiguration

- Paket-Feature-Verwaltung erfolgt über die bestehende Package-Resource (Feature `ai_styling` setzen).
- Addon-Katalog:
  - Key `ai_styling_unlock` in `config/package-addons.php`
  - kaufbar nur, wenn im Checkout-Katalog ein valider Preis hinterlegt ist.

## 3. Runtime-Steuerung (Superadmin)

Die zentrale Laufzeitsteuerung liegt in `AI Editing Settings` (Rare Admin Cluster):

- `is_enabled`: Globaler Kill-Switch.
- `status_message`: Text bei globaler Deaktivierung (`feature_disabled`).
- `default_provider`: aktuell `runware`.
- `fallback_provider`: reserviert für späteres Failover.
- `runware_mode`: `live` oder `fake`.
- `queue_auto_dispatch`: automatische Queue-Dispatches direkt nach Request-Erstellung.
- `queue_name`: Ziel-Queue für AI Jobs.
- `queue_max_polls`: maximale Poll-Versuche für Provider-Status.
- `blocked_terms`: globale Prompt-Blockliste.

Wichtiger Betriebsaspekt:
- Standard ist `queue_auto_dispatch=false`. In diesem Modus werden neue Requests zwar erstellt, aber nicht automatisch verarbeitet.
- Für Live-Betrieb muss entweder `queue_auto_dispatch=true` gesetzt oder ein separater Dispatch-Prozess etabliert sein.

## 4. Styles und Event-Policy

### 4.1 Globale Styles

- Verwaltung über `AI Styles` Resource.
- Styles definieren u.a.:
  - `provider`/`provider_model`
  - `prompt_template`/`negative_prompt_template`
  - `is_active`, `is_premium`
  - optionales Entitlement-Metadatenprofil (`metadata.entitlements.*`).

### 4.2 Event-spezifische Policy

Event-Settings unter `settings.ai_editing` unterstützen:

- `enabled` (Feature pro Event an/aus)
- `allow_custom_prompt`
- `allowed_style_keys` (leer = alle erlaubten Styles)
- `policy_message` (Rückmeldung bei Blockierung/Deaktivierung)

## 5. API/Queue-Verarbeitung

### 5.1 Endpunkte

- Guest:
  - `POST /api/v1/events/{token}/photos/{photo}/ai-edits`
  - `GET /api/v1/events/{token}/ai-edits/{requestId}`
  - `GET /api/v1/events/{token}/ai-styles`
- Tenant:
  - `GET /api/v1/tenant/events/{eventSlug}/ai-edits`
  - `GET /api/v1/tenant/events/{eventSlug}/ai-edits/summary`
  - `POST /api/v1/tenant/events/{eventSlug}/ai-edits`
  - `GET /api/v1/tenant/events/{eventSlug}/ai-edits/{aiEditRequest}`
  - `GET /api/v1/tenant/events/{eventSlug}/ai-styles`

### 5.2 Schutzschichten pro Request

Reihenfolge der Kernprüfungen:

1. Global aktiviert (`is_enabled`)
2. Entitlement vorhanden (Paket/Addon)
3. Event-Policy erlaubt Request
4. Budget erlaubt Request (Soft/Hard Cap)
5. Style-Zulässigkeit
6. Prompt-Safety (blocked terms)
7. Queue/Provider-Verarbeitung

### 5.3 Queue-Jobs

- `ProcessAiEditRequest`: Provider-Submit und ggf. Übergang in Polling.
- `PollAiEditRequest`: Provider-Statusabfrage bis `queue_max_polls`.
- Terminalstatus:
  - `succeeded`
  - `failed`
  - `blocked`

### 5.4 Output-Speicherung und Wasserzeichen

- Bei erfolgreichem Provider-Result versucht das Backend, den Output lokal zu persistieren:
  - Download von `provider_url`
  - Speicherung unter Event-Pfad (`events/{eventSlug}/ai-edits/...`)
  - Watermark-Anwendung über dieselbe Logik wie normale Uploads (`WatermarkConfigResolver` + `ImageHelper`).
- Primäre Auslieferung erfolgt über lokale `storage_path`/`url`; `provider_url` bleibt als Fallback erhalten.
- Backfill für Alt-Daten ohne lokale Pfade:
  - `php artisan ai-edits:backfill-storage`

## 6. Provider-Betrieb (Runware)

### 6.1 Erforderliche ENV/Config

- `RUNWARE_API_KEY`
- `RUNWARE_BASE_URL` (Default `https://api.runware.ai/v1`)
- `RUNWARE_TIMEOUT` (Sekunden)
- `AI_EDITING_DEFAULT_PROVIDER` (Default `runware`)
- `AI_EDITING_RUNWARE_MODE` (`live` oder `fake`)

### 6.2 Fake-Mode

- `runware_mode=fake` liefert synthetische Antworten ohne externen API-Call.
- Geeignet für interne Validierung von Flow/UI/Queue-Logik.
- Nicht für Kosten- oder Qualitätsaussagen nutzen.

## 7. Monitoring und Alerts

### 7.1 Wichtige Kennzahlen

- Request-Statusverteilung je Event (`queued`, `processing`, `succeeded`, `failed`, `blocked`)
- Failure-Rate
- Moderation-Hit-Rate
- Provider-Failure-Rate
- durchschnittliche Provider-Latenz
- Monatsausgaben (`ai_usage_ledgers`)

Das Tenant-Summary-Endpoint liefert diese Daten inkl. Alert-Flags:
- `observability.alerts.failure_rate_threshold_reached`
- `observability.alerts.latency_threshold_reached`

### 7.2 Schwellenwerte aus Config

- `ai-editing.observability.failure_rate_alert_threshold` (Default `0.35`)
- `ai-editing.observability.failure_rate_min_samples` (Default `10`)
- `ai-editing.observability.latency_warning_ms` (Default `15000`)
- Budget-Alert-Cooldown: `ai-editing.billing.budget.alert_cooldown_minutes` (Default `30`)
- Abuse-Eskalation: `ai-editing.abuse.escalation_threshold_per_hour` (Default `25`)

### 7.3 Relevante Log-Signale

- `AI provider latency warning`
- `AI failure-rate alert threshold reached`
- `AI budget threshold reached`
- `AI abuse escalation threshold reached`

## 8. Betriebs-Kommandos

### 8.1 Stuck Requests analysieren/recovern

- Dry-run:
  - `php artisan ai-edits:recover-stuck --minutes=30`
- Requeue:
  - `php artisan ai-edits:recover-stuck --minutes=30 --requeue`
- Hart auf failed setzen:
  - `php artisan ai-edits:recover-stuck --minutes=30 --fail`

### 8.2 Retention-Pruning

- Dry-run:
  - `php artisan ai-edits:prune --pretend`
- Ausführen (mit optionalen Overrides):
  - `php artisan ai-edits:prune --request-days=90 --ledger-days=365`

Retention Defaults:
- Requests: `AI_EDITING_REQUEST_RETENTION_DAYS` (90)
- Ledger: `AI_EDITING_USAGE_LEDGER_RETENTION_DAYS` (365)

Hinweis:
- `ai-edits:prune` läuft täglich per Scheduler (`02:30`), kann aber bei Bedarf manuell ausgeführt werden.

### 8.3 Backfill lokaler AI-Outputs

- Dry-run:
  - `php artisan ai-edits:backfill-storage --pretend`
- Ausführen:
  - `php artisan ai-edits:backfill-storage --limit=200`
- Für einzelne Request-ID:
  - `php artisan ai-edits:backfill-storage --request-id=123`

## 9. Incident-Playbooks

### 9.1 Provider-Ausfall / hohe Failure-Rate

1. `is_enabled=false` als Kill-Switch setzen (optional mit `status_message`).
2. `runware_mode=fake` nur für interne Funktionstests aktivieren.
3. Queue-Backlog prüfen, ggf. `ai-edits:recover-stuck --requeue` nach Stabilisierung.
4. Fehlerraten im Summary pro Event kontrollieren.

### 9.2 Kostenanstieg / Budget-Hard-Cap

1. Budget-Alerts (`ai_budget_soft_cap`/`ai_budget_hard_cap`) prüfen.
2. Tenant-Budget in `tenant.settings.ai_editing.budget.*` validieren.
3. Bei Bedarf zeitweises Override `override_until` setzen.
4. Bei Missbrauchsspitzen zusätzlich Abuse-Signale prüfen.

### 9.3 Safety-/Abuse-Spike

1. `blocked_terms` nachschärfen.
2. Event-Policy enger setzen (`allow_custom_prompt=false`, `allowed_style_keys` einschränken).
3. Warn-Logs mit `scope_hash`, `event_id`, `tenant_id` korrelieren.

## 10. Datenschutz und Datenhaltung

- Keine Secrets in Logs/Docs schreiben (`RUNWARE_API_KEY`, `.env`).
- Prompt-/Negativprompt-Inhalte liegen in `ai_edit_requests`; mit PII vorsichtig umgehen.
- Nur notwendige Aufbewahrungsdauer halten; Pruning regelmäßig durchführen.
- Keine Erweiterung der Retention ohne abgestimmte Privacy-Änderung.

## 11. Go-Live-Checkliste

1. Paket-/Addon-Freischaltung verifiziert (`ai_styling`, `ai_styling_unlock`).
2. `RUNWARE_API_KEY` gesetzt und Provider-Erreichbarkeit geprüft.
3. `queue_auto_dispatch=true` und Worker auf korrekter Queue aktiv.
4. Budget-Limits und Alerting pro Tenant geprüft.
5. Safety-Baseline (`blocked_terms`) gesetzt.
6. Recovery- und Prune-Commands in Ops-Routine aufgenommen.