194 lines
27 KiB
Markdown
194 lines
27 KiB
Markdown
# Boilerplate-Abgleich: M18 — KI-Layer / LLM-Gateway
|
|
|
|
> Faktischer Abgleich der HiveGrid-Detail-Spec (M18) gegen die Boilerplate.
|
|
> Boilerplate-Wurzel (NUR LESEN): `/Users/raffaelsheikh/Documents/GitHub/boilerplate`
|
|
> Spec-Quelle: `/Users/raffaelsheikh/Documents/GitHub/HiveGrid-Cloud/_bmad-output/specs/M18-ki-layer.md`
|
|
> Alle Pfade absolut. Nichts erfunden — jeder Eintrag verweist auf konkrete Datei(en); fehlt etwas, ist es klar als Lücke markiert.
|
|
|
|
## Kopf
|
|
|
|
| Feld | Wert |
|
|
| --- | --- |
|
|
| Modul-ID | M18 |
|
|
| Name | KI-Layer / LLM-Gateway |
|
|
| Milestones | M083 (EU-Provider-Layer), M084 (Multi-Provider-Fallback), M085 (Promptfoo-Eval-Suite), M086 (Sprach-zu-Automation), M087 (RAG + Aktions-Grenze), M088 (Token-Limits + Pay-as-you-go) |
|
|
| Block | Block 4 — Integrationen, Automation & KI (`_bmad-output/pflichtenheft/blocks/block4.md`, Modul 18) |
|
|
| Reuse-Level | **HIGH** |
|
|
|
|
**Kernaussage:** Das ist die USP-Säule mit dem höchsten Wiederverwendungs-Grad im KI-Bereich. Die Boilerplate liefert den kompletten **EU-Provider-Layer** (Mistral/Scaleway/Aleph Alpha — exakt der von der Spec geforderte Stack, KEIN OpenAI/Anthropic im aktiven Pfad), den **30-Min-Multi-Provider-Fallback** (M084 quasi fertig), die **RAG/Embeddings-Pipeline + pgvector-Store** (M087-Retrieval), die **Promptfoo-Eval-Suite mit OWASP-Injection-Vektoren + Gitea-CI-Workflow** (M085 quasi fertig), das **Cost-/Quota-Tracking inkl. Pay-as-you-go-Overage-Logik** (M088-Engine fertig) und die **Guards/Action-Boundary-Bausteine** (M087-Aktions-Grenze). Die Hauptlücken liegen bei: **HiveGrid-spezifische Daten-Modelle** (LlmGatewayProvider/Model, AiSettings, Conversation als HiveGrid-Variante, TenantEmbedding-Tabelle), **Whisper-EU-Transkription** (komplett nicht vorhanden), die **Use-Case-Orchestrierung** (Lead-Zusammenfassung, Sprach→Automation, Stuck-Deal, Email-Klassifizierung) und das **gesamte UI** (Chat, Usage-Dashboard, Settings, Voice-Assistant).
|
|
|
|
---
|
|
|
|
## Übernehmbar aus Boilerplate
|
|
|
|
| Boilerplate-Pfad | Was | Wie nutzbar |
|
|
| --- | --- | --- |
|
|
| `packages/ai/src/index.ts` | Provider-Adapter-Interface + Registry: `AIProviderName = "mistral"\|"scaleway"\|"aleph-alpha"`, `getAIProviderAdapter()`, `getAIProviderAdapterForModel()`, `getPrimaryProvider()`, `getAIProviderDiagnostics()`, Modell-Katalog `aiModels` (mit Preisen pro Mio Tokens), `defaultAIModel = "mistral-large-latest"` | **1:1** — exakt der von Spec Block B geforderte EU-Stack. Deckt M083 Erfolgskriterium (Mistral-Aufruf, Switch via Env-Var, keine US-Endpunkte) |
|
|
| `packages/ai/src/providers/mistral.ts` | Mistral-Provider via `@ai-sdk/mistral`, `resolveMistralModel(env)`, `MISTRAL_API_KEY`/`MISTRAL_MODEL` | **1:1** — Primary-Provider (Spec: Mistral Large Chat / Mistral Small) |
|
|
| `packages/ai/src/providers/scaleway.ts` | Scaleway-Provider (OpenAI-kompatibel), Default `mistral-small-3.2-24b-instruct-2506`, `SCALEWAY_*`-Env | **1:1** — Secondary-Provider (France-EU) |
|
|
| `packages/ai/src/providers/aleph-alpha.ts` | Aleph-Alpha-Provider (OpenAI-kompatibel), Default `pharia-1-llm-7b-control`, `ALEPH_ALPHA_*`-Env | **1:1** — Tertiary-Provider (Germany-EU) |
|
|
| `packages/ai/src/providers/compatible.ts` | `createCompatibleLanguageModel()` (gemeinsame OpenAI-kompatible Basis für Scaleway + Aleph Alpha) | **1:1** |
|
|
| `packages/ai/src/fallback.ts` | `AIProviderHealthTracker` (30-Min-Failure-Window = `fallbackWindowMs`), `getFallbackProviderSelection()`, `fallbackProviderOrder = ["mistral","scaleway","aleph-alpha"]` | **1:1 / anpassen** — deckt M084 (Auto-Fallback + 30-Min-Window) fast vollständig. Spec verlangt zusätzlich 1-Min-Health-Ping + 5-Min-Sperre (Block H / 18.6.3) — der Health-Tracker ist reaktiv (failure-on-call), nicht aktiv-pingend → **kleine Erweiterung nötig** |
|
|
| `packages/ai/src/cost/executeLLMCall.ts` | LLM-Wrapper: wrappt jeden Provider-Call, leitet Token/Kosten ab, emittiert Outbox-Event `ai.cost.event.persist`, Quota-Pre-Check + Soft-Degradation + Concurrency-Slot; Killswitch `AI_COST_TRACKING_ENABLED=false`; Capabilities `chat`/`chat-stream`/`embedding`/`completion`/`rerank`/`tool-call` | **1:1** — zentraler Gateway-Aufruf-Wrapper (Spec Block B Interface + Block F Token-Tracking) |
|
|
| `packages/ai/src/cost/assertCredit.ts` | `assertTenantAICreditAccess()` — Pre-Call-Quota-Assertion (3 Outcomes: allow / allow+degradeTo / throw `AIQuotaExceededError`), Concurrency-Counter, Soft-Degradation (90%-Threshold), per-Capability-Caps, Killswitch `AI_QUOTA_ENFORCEMENT_ENABLED=false` | **1:1 / anpassen** — M088-Kern. **WICHTIG:** Default-Verhalten ist Hard-Deny (HTTP 402) bei Limit. HiveGrid [N13] verlangt **Pay-as-you-go statt Pause** → die Hard-Deny-Pfade durch Overage-Pfad ersetzen (Overage-Logik existiert separat, s.u.) |
|
|
| `packages/entitlements/src/ai-overage.ts` | Pay-as-you-go-Overage: `AI_OVERAGE_DEFAULT_MULTIPLIER = 1.5`, `computeMarkedUpCostCents()`, `roundUpToBlock()`, `resolveTenantAIOverage()`, `standardAIOverageDefaults` pro Plan, `TenantAIOverageOverride` (parse/resolve) | **anpassen** — genau das von M088/[N13] geforderte Aufschlags-Tarif-Modell. Markup-Faktor + Block-Rundung fertig; HiveGrid-Plan-Werte + Notbremse-Threshold (18.8.7) einsetzen |
|
|
| `packages/entitlements/src/ai-quotas.ts` | `aiQuotaCapabilityKeys`, `AIQuotaPlanDefaults` (aiQuotaCentsPerMonth / aiPerCapabilityCaps / aiMaxConcurrentCalls / aiDegradeTo), `standardAIQuotaDefaults` (starter/pro/business), `resolveTenantAIQuota()`, `parseTenantAIQuotaOverride()` | **anpassen** — Inklusiv-Kontingent + per-Capability-Caps pro Plan. HiveGrid-Token/Cent-Werte einsetzen (Spec: „konkrete Mengen mit Pricing-Festlegung", noch offen) |
|
|
| `packages/ai/src/cost/spend-cache.ts` | `createSpendCache()` — Monatsspend-Caching (TTL) als Watermark für 80%-Banner und Forecast | **1:1** — Datenbasis für 80%-Soft-Limit-Banner + Email (18.8.2) und Usage-Dashboard-Forecast (18.8.9) |
|
|
| `packages/ai/src/cost/tokens.ts` | `countTokens`/`countMessageTokens` (gpt-tokenizer + Heuristik-Fallback) | **1:1** — Token-Zählung für Budget pro Use-Case (Spec C: ~2000 in / 800 out etc.) |
|
|
| `packages/ai/src/cost/pricing/v2026-05-16.ts` + `pricing/index.ts` | Versionierte Pricing-Tabelle (`getPricingTable`, `LATEST_PRICING_VERSION`) | **anpassen** — EU-Provider-Preise sind als `aiModels[].costPerM*` bereits hinterlegt; HiveGrid-Aufschlags-Tarife ergänzen |
|
|
| `packages/ai/src/guards/index.ts` | `assertAICostBudget()`, `createFixedWindowAIRateLimiter()` (pro userId), `createAIAuditEvent()`/`createAI{Prompt,ToolCall,Mutation}AuditEvent()`, `redactAIAuditPayload()` (PII-Redaction), `createReviewRequiredResult()`, `AIGuardError` | **1:1 / anpassen** — `createReviewRequiredResult()` + Mutation-Audit-Events sind das Fundament der **Action-Boundary** (M087, Spec Block G/18.5.3: KI generiert nur Vorschläge, User bestätigt). Audit-Redaction deckt AV#6 |
|
|
| `packages/ai/src/embeddings/factory.ts` + `embeddings/types.ts` | `createEmbeddingProvider()`, `registerEmbeddingProviderAdapter()`, `resolveEmbeddingProviderName(env)`, `resolveEmbeddingDimensions(env)`, `EmbeddingProvider`-Interface | **1:1** — RAG-Schreib-/Leseseite-Fundament (M087 / Spec Block D) |
|
|
| `packages/ai/src/embeddings/providers/scaleway.ts` | Scaleway-Embeddings-Adapter, Default `bge-multilingual-gemma2` (1024 dim), Batch 64, max 4096 Tokens | **1:1** — Spec Block D: „Scaleway-Embeddings, 1024-Dim Default" — exakter Match |
|
|
| `packages/ai/src/embeddings/embed-and-upsert.ts` | `embedAndUpsert()` — chunked Embed + Upsert in `VectorUpsertSink`; erzwingt `tenantId` im Payload; deterministische `buildChunkId()`; optionale Kostenverfolgung über `executeLLMCall` | **1:1 / anpassen** — Embedding-Pipeline (Spec D: bei Anlage/Update Embedding). Re-Embed-bei-Text-Änderung via Hash (Spec D) muss als Trigger-Wiring ergänzt werden |
|
|
| `packages/ai/src/embeddings/retrieve.ts` | `retrieveRelevantContext()` — Query embedden, Fan-out über Collections, Rank-Merge, min-Score 0.7, top-K 8; tenant-scoped via `RagRetrievalStore.searchForTenant` | **1:1** — RAG-Leseseite. Spec D Permission-Pre-Filter andocken |
|
|
| `packages/ai/src/embeddings/chunking.ts` | `splitForEmbedding()`, `countTokens()`, `DEFAULT_CHUNK_TOKENS`/`...OVERLAP_TOKENS` | **1:1** |
|
|
| `packages/ai/src/embeddings/outbox-publisher.ts` | `publishRagUpsertEvent`/`publishRagDeleteEvent`, `ragEventType()` → `rag.index.<entity>.<verb>` (BullMQ-Queue `outbox.rag-index`), Idempotenz via `dispatchKey` | **1:1** — async Re-Index bei jedem Domain-Write (Spec D Embedding-Pipeline) |
|
|
| `packages/vector-store/src/factory.ts` + `adapters/pgvector.ts` | `createVectorStore()` (pgvector Default / Qdrant Upgrade), `PgvectorAdapter` mit HNSW-Index (`m`/`efConstruction`), Payload-Filter | **1:1** — Spec D: „pgvector mit HNSW-Index" — exakter Match. Offener Detail-Punkt der Spec (IVFFlat vs. HNSW) ist durch BP bereits auf HNSW entschieden |
|
|
| `packages/vector-store/src/wrappers/tenant-scoped.ts` | `withTenantScope()` → `TenantScopedVectorStore`; `searchForTenant()` erzwingt `tenantId`-must-Filter; bare `searchVectors()` wirft | **1:1** — Spec D: „kein Cross-Tenant!" + M087 Permission-aware. Tenant-Isolation built-in |
|
|
| `prisma/migrations/20260517085146_04_enable_pgvector/migration.sql` | Aktiviert `pgvector`-Extension | **1:1** — Voraussetzung für TenantEmbedding-Tabelle |
|
|
| `packages/ai/src/prompts/index.ts` | `createAIPromptRegistry()` mit Versionierung, `render(selection, variables)`, `{{var}}`-Templates, `AIPromptRegistryError` | **1:1 / als-vorlage** — System-Prompt-Trennung (Spec G/18.5.2) + Use-Case-Prompts. Strikte System/User-Daten/Frage-Trennung als Template-Konvention |
|
|
| `packages/ai/src/tools/index.ts` | `createAIToolRegistry()` (scoped Tools für Vercel AI SDK `ToolSet`), `toToolSet(selection)`, Secret-Redaction | **1:1** — Tool-Calling-Architektur (Spec G: Tools nur per Tool-Call-Output, nicht aus Text geparst). Basis für Sprach→Automation-Tools (M086) |
|
|
| `packages/ai/src/streaming/index.ts` | `createAITextStream()` via `streamText`, Guard-Evaluator, Prompt-/Tool-Registry-Integration, `getAITextStreamDiagnostics()` mit Redaction | **1:1** — Streaming-Chat-UX für Programm-Hilfe-Chat (Use-Case 3). Guard-Evaluator-Seam = Action-Boundary-Andock-Punkt |
|
|
| `packages/ai/src/promptfoo-provider.ts` + `promptfoo.config.yaml` (Repo-Root) + `tests/promptfoo/injection-vectors.yaml` + `.gitea/workflows/promptfoo.yml` | Promptfoo-Eval-Harness mit OWASP-LLM-Vektoren (LLM01/LLM02/LLM06…), Mistral-als-Primary-Label, deterministischer Test-Provider, CI-Workflow | **1:1 / anpassen** — M085 quasi fertig: `description: EU-only OWASP LLM injection-vector eval suite`. Pro neuem HiveGrid-Prompt-Flow eigene Eval-Vektoren ergänzen (Spec G: „pro Prompt-Flow eigene Eval-Suite") |
|
|
| `packages/ai/test/evals/promptfoo-baseline.test.ts` + `prompt-registry-cases.yaml` | Eval-Baseline-Vitest + Prompt-Registry-Testfälle | **als-vorlage** — Muster für HiveGrid-Prompt-Flow-Evals |
|
|
| `prisma/schema/ai.prisma` → `Chat`, `ChatMessage`, `ChatMessagePart` | Chat-Datenmodell (Typ tenant/admin/marketing, Scope, anonym via `sessionId`, Multi-Part-Messages) | **als-vorlage / anpassen** — deckt Spec `Conversation`/`ConversationMessage` strukturell. `Chat.kind`/HiveGrid-`kind`-Enum (programm_help/automation_builder) ergänzen; `lastMessageAt`/`archivedAt` bereits vorhanden |
|
|
| `prisma/schema/ai.prisma` → `GeneratedObject` | Strukturierte AI-Outputs mit Token/Cost-Feldern, `status` pending/success/error, `model`, `chatId` | **1:1 / anpassen** — Spec `GeneratedObject` (JSON-Schema-validierte Outputs). `schema_version`-Feld ergänzen |
|
|
| `prisma/schema/ai.prisma` → `AICostEvent` | Append-only Cost-Log (`requestId @unique`, KEINE Prompt-Bodies, `capability`/`provider`/`model`/Tokens/Cents, `isOverage`, `markedUpCostCents`, `stripeReportedAt`) | **1:1** — Spec `AiTokenUsage` (Verbrauch pro Tenant/User/Use-Case). Overage-Felder + Stripe-Watermark für M088 bereits da |
|
|
| `prisma/schema/ai.prisma` → `TenantAICostSummary` | Vor-aggregierte Cost-Summary pro Periode (`@@unique([tenantId, periodStart])`, `breakdown` JSON) | **1:1** — Spec `AiCredits`-Aggregat + Usage-Dashboard O(1)-Top-Line (18.8.9) |
|
|
| `prisma/schema/accounts.prisma` → `Tenant` AI-Felder | `aiQuotaOverrideJson` (Json, geformt als `TenantAIQuotaOverride`), `aiCostLastAlertedThreshold`, `aiCostLastAlertedPeriod` | **1:1 / anpassen** — Spec `AiSettings.usage_limit_tokens_per_month` + idempotente 80%-Alert-State. HiveGrid-`AiSettings` braucht zusätzlich `enabled_use_cases[]`, `default_models`, `data_residency` (s. Lücken) |
|
|
| `prisma/schema/promptFlows.prisma` → `PromptFlow`, `PromptTemplate`, `PromptFlowExecution`, `PromptFlowOutput*`, `PromptFlowInputVariable` | LLM-Prompt-Pipelines an Entity/Property gekoppelt, `executionType` sequential/parallel, Streaming-Flag, Execution + Result-Log, Output→Row-Property-Mapping | **als-vorlage** — Phase-2-`PromptFlow`/`PromptTemplate` (visueller Prompt-Editor, Spec Block J) bereits strukturell vorhanden. Für Phase 1 optional als Use-Case-Prompt-Definitionen |
|
|
| `packages/queue/src/payloads.ts` → `AiJob` | Typisierte AI-Jobs: `ai.chat-completion` / `ai.embedding` / `ai.browser-task`; Queue `toolctrl.ai-chatbot` (`names.ts`) | **1:1 / anpassen** — async KI-Verarbeitung. **Whisper-Transkriptions-Job-Typ fehlt** → ergänzen (`ai.transcribe`) |
|
|
| `packages/queue/src/*` (producers/priority/connection/runtime) | `enqueueJob()`, Idempotenz (`buildIdempotentJoben`), Plan-basierte Prioritäten (`resolveJobPriorityForTenant`), BullMQ-Runtime-Factory | **1:1** — Whisper-Async-Pipeline (Spec E: Audio-Upload → Job-Queue → Whisper → Resultat) baut hierauf |
|
|
| `packages/storage/src/index.ts` + `signed/index.ts` + `scan/*` | Scaleway-S3-Adapter, Signed-Upload/Download-URLs, ClamAV + magic-bytes Virus-Scan, Quarantäne | **1:1** — Audio-Upload für Whisper-Transkription (Spec E) + DSGVO-EU-Storage |
|
|
| `packages/db/src/outbox.ts` + `prisma/schema/outbox.prisma` | `publishOutboxEvent(tx, args)` transaktional, `OutboxEvent`-Modell | **1:1** — alle KI-Side-Effects (Cost-Persist, RAG-Reindex, Notifications) transaktional |
|
|
| `prisma/schema/notifications.prisma` → `NotificationDelivery`, `UserNotificationPreference` | In-App + Email + Push Notification-Delivery | **1:1** — 80%-Budget-Email an Tenant-Admin (18.8.2), Notbremse-Warnung (18.8.7) — via `notify()` (M011), nicht direkt |
|
|
| `prisma/schema/permissions.prisma` → `Role`, `Permission`, `RolePermission`, `UserRole`, `Group` | RBAC-Fundament | **1:1** — die 6 `ai.*`-Permissions (Spec Block I) als `Permission`-Rows + Bundle-Mapping + Default-Rollen-Zuweisung |
|
|
| `prisma/schema/featureFlags.prisma` → `FeatureFlag` | Feature-Toggles (scope global/tenant/user) | **1:1** — DoD verlangt Feature-Flag-Abschaltbarkeit; `ai-quota-soft-degradation`-Flag wird von `assertCredit.ts` bereits erwartet |
|
|
| `prisma/schema/knowledgeBase.prisma` → `KnowledgeBaseArticle` etc. | Help-Center-Datenmodell | **als-vorlage** — RAG-Quelle für Programm-Hilfe-Chat (Use-Case 3) + `HelpArticleEmbedding` (M38-Kopplung) |
|
|
| `packages/search/src/*` (Meilisearch) + `schemas/kb-articles.ts` | Tenant-scoped Volltext-Index | **1:1** — Spec D Hybrid-Suche (Volltext + Embeddings) + Graceful-Degradation-Fallback bei Provider-Down (Spec D/H: „Standard-Volltext-Suche aktiv") |
|
|
|
|
---
|
|
|
|
## Vorhandene Daten-Modelle (konkret)
|
|
|
|
Alle in `/Users/raffaelsheikh/Documents/GitHub/boilerplate/prisma/schema/`:
|
|
|
|
| Spec-Modell (M18 Block A) | Boilerplate-Entsprechung | Datei | Bewertung |
|
|
| --- | --- | --- | --- |
|
|
| `Conversation` | `Chat` (type tenant/admin/marketing, scope, sessionId, title, `lastMessageAt`, `archivedAt`, metadata) | `ai.prisma` | strukturell vorhanden — `kind`-Werte (programm_help/automation_builder/tenant_assistant) als HiveGrid-Anpassung |
|
|
| `ConversationMessage` | `ChatMessage` + `ChatMessagePart` (role, Multi-Part content, order) | `ai.prisma` | vorhanden — Token-Felder (`tokens_input/output`) pro Message ergänzen (aktuell auf `GeneratedObject`/`AICostEvent`-Ebene) |
|
|
| `GeneratedObject` | `GeneratedObject` (object/type/model, userPrompt/fullPrompt, generatedData JSON, Token+Cost, status, chatId) | `ai.prisma` | nahezu 1:1 — `schema_version` ergänzen |
|
|
| `AiTokenUsage` | `AICostEvent` (capability, provider, model, in/out/total Tokens, costCents, requestId @unique, isOverage, markedUpCostCents, stripeReportedAt) | `ai.prisma` | 1:1 — append-only, KEINE Prompt-Bodies (PII-konform) |
|
|
| `AiCredits` (Aggregat-Teil) | `TenantAICostSummary` (periodStart/End, totalCostCents, total Tokens, breakdown JSON) | `ai.prisma` | 1:1 für vor-aggregierte Sicht |
|
|
| `AiSettings` (Teil) | `Tenant.aiQuotaOverrideJson` + `aiCostLastAlertedThreshold/Period` | `accounts.prisma` | teilweise — Quota-Override + Alert-State da; restliche AiSettings-Felder fehlen |
|
|
| Plan-Defaults / Inklusiv-Kontingent | `standardAIQuotaDefaults` + `AIQuotaPlanDefaults` (Code, kein DB-Modell) | `packages/entitlements/src/ai-quotas.ts` | 1:1 (Code-Registry-Stil) |
|
|
| Overage-/Aufschlags-Tarif | `standardAIOverageDefaults` + `resolveTenantAIOverage` (Code) | `packages/entitlements/src/ai-overage.ts` | 1:1 (Code-Registry-Stil) |
|
|
| `PromptFlow`/`PromptTemplate` (Phase 2) | `PromptFlow`, `PromptTemplate`, `PromptFlowExecution`, `PromptFlowOutput(+Mapping)`, `PromptFlowInputVariable`, `PromptFlowGroup(+Template+Entity)` | `promptFlows.prisma` | 12 Modelle bereits vorhanden (visueller Prompt-Editor Phase 2) |
|
|
|
|
**Provider-Registry als Code, nicht als DB:** Die Spec modelliert `LlmGatewayProvider` / `LlmGatewayModel` als „Plattform-weit, Code-Registry". Die Boilerplate setzt das **genau so** um: `providerMetadata` + `aiModels`-Katalog in `packages/ai/src/index.ts` (mit `costPerMInputTokens`/`costPerMOutputTokens`/`maxOutputTokens` pro Modell). Es gibt **keine** Prisma-Modelle `LlmGatewayProvider`/`LlmGatewayModel` — das ist konform mit der Spec (Code-Registry) und kein Defizit.
|
|
|
|
---
|
|
|
|
## Lücken / komplett neu zu bauen
|
|
|
|
### Daten-Layer (in `prisma/schema/app.prisma` — leerer HiveGrid-Platzhalter)
|
|
1. **`AiSettings` (HiveGrid-spezifisch)** — kein Modell vorhanden. Benötigt: `enabled_use_cases[]`, `default_models` (Use-Case→Modell-Key JSON), `data_residency` (Default `eu`, Hard-Constraint). Teilweise durch `Tenant.aiQuotaOverrideJson` gedeckt; HiveGrid-Settings-Modell neu.
|
|
2. **`TenantEmbedding`-Tabelle** — als Prisma-Modell **nicht vorhanden**. Die Boilerplate legt Vektoren über pgvector in `vec_<namespace>_<collection>`-Tabellen per Raw-SQL an (kein Prisma-Modell). Spec verlangt zusätzlich Metadaten-Tracking (`entity_type`, `entity_id`, `text_source` für Re-Embed-Hash, `embedding_model_id`, `last_embedded_at`) — **Metadaten-Begleittabelle neu bauen** (die Vektoren selbst kommen aus dem vorhandenen pgvector-Adapter).
|
|
3. **`HelpArticleEmbedding`** (M38-Kopplung) — nicht vorhanden; analog zu TenantEmbedding über pgvector + Begleit-Metadaten.
|
|
4. **Conversation-`kind`-Enum** + **per-Message-Token-Felder** — kleine Schema-Erweiterung an `Chat`/`ChatMessage`.
|
|
5. **Whisper-Transkriptions-Modell** (Job-Status, Audio-Ref, Transkript, Sprache, Edit-State) — komplett neu.
|
|
|
|
### Whisper-EU-Transkription (Spec Block E) — KOMPLETT FEHLT
|
|
- **Kein** Transcription-Adapter, **keine** `transcribe()`-Methode in `packages/ai`, **kein** Audio/Whisper-Code (grep über `packages/ai/src` ergab 0 Treffer für transcri/whisper/audio/speech).
|
|
- Queue-Payload `AiJob` kennt nur `ai.chat-completion`/`ai.embedding`/`ai.browser-task` — **`ai.transcribe` fehlt**.
|
|
- Neu zu bauen: Whisper-auf-Scaleway-GPU-Adapter (DSGVO-konform), Async-Pipeline (Storage-Upload → Queue → Whisper → Resultat — Bausteine `storage` + `queue` vorhanden), Auto-Sprache-Erkennung (DE/EN), Mikrofon-Aufnahme-UI, Edit-Funktion, Klartext-Fehler.
|
|
|
|
### Use-Case-Orchestrierung (Spec Block C) — Gateway-Bausteine da, Use-Cases neu
|
|
- **Lead-Zusammenfassung / Pre-Termin-Brief** (Use-Case 2): Activity-Stream + Custom-Felder + Form-Submissions als Kontext sammeln, Cache-Hit-Logik (gleiche Datenbasis), Widget im Kontakt-Detail. Neu.
|
|
- **Programm-Hilfe-Chat** (Use-Case 3): RAG über Help-Articles + Conversation-Historie. Streaming-Chat-Baustein vorhanden, Orchestrierung + UI neu.
|
|
- **Klartext-Diagnostik-Fallback** (Use-Case 4): KI nur Fallback bei unbekannten Fehler-Codes, klar markiert. Neu.
|
|
- **Stuck-Deal-Vorschläge** (Use-Case 5): wöchentlicher Cron-Job, Widget. Neu (Cron via M-Infra).
|
|
- **Email-Klassifizierung** (Use-Case 7): `lead|customer_question|invoice|spam|newsletter|other`, Inbox-Auto-Verknüpfung (M9). Neu.
|
|
- **Sprach-zu-Automation (M086, USP-Hauptstütze)**: Sprach-Befehl → Wenn-Dann-Vorschlag im visuellen Editor, Rückfrage bei Mehrdeutigkeit, Existenz-Probe referenzierter Pipelines/Mitarbeiter/Templates, Risiko-Warnungen, „Vorher/Nachher"-Diff, NIE Auto-Aktivierung. Tool-Registry + Streaming + Prompt-Registry als Fundament; die gesamte Orchestrierung + Editor-Integration (M078) + Voice-Input (Web-Speech-API) neu.
|
|
|
|
### Sicherheits-Layer (Spec Block G) — teilweise
|
|
- **Input-Sanitization (Runtime)**: **FEHLT** als Modul. Die Boilerplate hat Promptfoo-**Test**-Vektoren (`tests/promptfoo/injection-vectors.yaml`, deterministischer Test-Provider), aber **keine produktive Sanitizer-Funktion**, die Marker (`---SYSTEM:`, `[INST]`, `<|im_start|>`) in externen Daten neutralisiert oder Eingabe-Länge cappt (grep ergab 0 Runtime-Treffer). Neu bauen.
|
|
- **System-Prompt-Trennung**: Prompt-Registry (`{{var}}`-Templates) ist da; strikte 3-Block-Trennung (System / User-Daten „nicht als Anweisung" / Frage) als Konvention/Template neu definieren.
|
|
- **Action-Boundary (M087)**: Bausteine vorhanden (`createReviewRequiredResult()`, Mutation-Audit-Events, Streaming-Guard-Evaluator) — die **Bestätigungs-Workflow-Verdrahtung im UI** + Tool-Output-only-Policy neu.
|
|
|
|
### Multi-Provider-Fallback (M084) — fast fertig, 2 Lücken
|
|
- Aktiver **1-Min-Health-Ping** + **5-Min-Sperre** (Spec 18.6.3): vorhandener `AIProviderHealthTracker` ist reaktiv (failure-on-call, 30-Min-Window). Aktives Pingen + 5-Min-Re-Check-Fenster ergänzen.
|
|
- **Deterministischer Response-Cache** (Spec H/18.7: Cache-Hit auch bei KI-Down): **nicht vorhanden** — es gibt `spend-cache` (Kosten), aber keinen Output-Cache für deterministische Prompts. Neu (Hash-basiert).
|
|
|
|
### Pay-as-you-go (M088) — Engine da, Verdrahtung + Notbremse neu
|
|
- Overage-Berechnung (`ai-overage.ts`) + Cost-Felder (`AICostEvent.markedUpCostCents`/`stripeReportedAt`) fertig.
|
|
- **Umstellung Hard-Deny → Overage**: `assertCredit.ts` wirft aktuell bei Limit (HTTP 402). [N13] verlangt **weiterlaufen + Aufschlag**. Pfad umbauen.
|
|
- **Notbremse** (18.8.7): absolute Euro-Obergrenze pro Tenant → Drosselungs-Modus (nur geschäftskritische KI). Neu (Threshold + Capability-Whitelist).
|
|
- **Stripe-Metered-Billing-Reporter** (18.8.6): `stripeReportedAt`-Watermark + nightly Cron vorgesehen; Stripe-Anbindung kommt aus M153/M156. Verdrahtung neu.
|
|
- **Upsell-Logik** (18.8.5): Vergleich Overage-Kosten vs. Plan-Differenz → Soft-Recommendation. Neu.
|
|
|
|
### UI — KOMPLETT NEU (Boilerplate liefert KEIN HiveGrid-UI)
|
|
- Programm-Hilfe-Chat-Oberfläche (Streaming)
|
|
- KI-Sprach-Assistent (M086, Sidebar-Gruppe „AUTOMATION & KI" → laut INTEGRATION-CONTRACTS §1)
|
|
- Usage-Dashboard `/{tenant}/admin/usage/ai` (Pie pro Use-Case, Verbrauch über Zeit, Top-User, Forecast, Tarif, Notbremse-Stand)
|
|
- AI-Settings-Seite (EU-DSGVO-Klartext, Modell-Defaults pro Use-Case, Token-Override) — Sidebar „EINSTELLUNGEN → Mandant"
|
|
- Voice-Aufnahme-Komponente (Mikrofon-Tap/Toggle, Edit, Klartext-Fehler)
|
|
- Lead-Zusammenfassungs-Widget, Stuck-Deal-Widget
|
|
- Action-Boundary-Bestätigungs-Dialog
|
|
- **DoD-Pflicht** (alle Milestones): View-Model-Loader-Trennung, keine Prisma-Imports in `packages/ui-hivegrid/**`, Subframe-Adapter, i18n-Keys, Smoke-Tests, Hot-Swap-Drill gegen `packages/ui-mock`, Visual-Regression — alles HiveGrid-seitig neu.
|
|
|
|
### Querschnitt-Wiring (HiveGrid-seitig)
|
|
- Sidebar-Registrierung in `packages/ui-hivegrid/src/app-shell/sidebar.config.ts` (M086 → Gruppe „AUTOMATION & KI"; Usage/Settings → „EINSTELLUNGEN")
|
|
- Routes unter Tenant-URL-Pattern, Breadcrumbs, Customer-Portal-Sichtbarkeit
|
|
- i18n-Keys für alle Klartext-Fehler (Spec 18.12 — 5 konkrete Beispiele) aus M002-Catalog
|
|
- Activity-Stream (`logActivity`) + Notifications (`notify()`) Anbindung
|
|
- Permission-Seed der 6 `ai.*`-Permissions + 3 Bundles + Default-Rollen-Zuweisung
|
|
- Feature-Flag pro KI-Modul
|
|
|
|
---
|
|
|
|
## Empfohlenes Vorgehen (Reihenfolge)
|
|
|
|
**Phase 0 — Voraussetzung (vor M083):** EU-Sterilisation der Boilerplate prüfen. Der aktive Provider-Pfad ist bereits EU-only (Mistral/Scaleway/Aleph Alpha); **Anthropic/OpenAI existieren nur als Embedding-Stub bzw. `@ai-sdk/openai-compatible`-Bibliothek** (`packages/ai/src/embeddings/providers/{openai,anthropic}.ts`). Sicherstellen, dass diese nicht aktiviert/registriert werden (DSGVO-Hard-Constraint, Spec 18.2.2).
|
|
|
|
**M083 (EU-Provider-Layer) — überwiegend ÜBERNEHMEN:**
|
|
1. `packages/ai` Provider-Registry + Mistral/Scaleway/Aleph-Alpha-Adapter 1:1 nutzen.
|
|
2. `executeLLMCall` als zentralen Gateway-Wrapper verdrahten (Boundary in apps/api injiziert Env-Snapshots + Cost-Publisher + Prisma-Adapter).
|
|
3. EU-DSGVO-Klartext in AiSettings (Spec 18.2.4) als i18n-Key.
|
|
|
|
**M084 (Fallback) — ÜBERNEHMEN + 2 Erweiterungen:**
|
|
1. `fallback.ts` (30-Min-Window, Mistral→Scaleway→Aleph-Alpha) 1:1.
|
|
2. NEU: aktiver 1-Min-Health-Ping + 5-Min-Sperre.
|
|
3. NEU: deterministischer Output-Cache (Hash-basiert, Cache-Hit bei KI-Down).
|
|
4. Graceful-Degradation-Klartexte + Editor-Fallback-Hinweis (UI).
|
|
|
|
**M085 (Promptfoo) — fast fertig ÜBERNEHMEN:**
|
|
1. `promptfoo.config.yaml` + `tests/promptfoo/injection-vectors.yaml` + `.gitea/workflows/promptfoo.yml` 1:1.
|
|
2. NEU: pro HiveGrid-Prompt-Flow eigene Eval-Vektoren ergänzen; CI-Gate verifizieren.
|
|
|
|
**M087 (RAG + Aktions-Grenze) — Bausteine ÜBERNEHMEN, Wiring neu:**
|
|
1. pgvector-Migration aktivieren; `vector-store` tenant-scoped + `embeddings`-Pipeline 1:1.
|
|
2. NEU: `TenantEmbedding`-Metadaten-Modell in `app.prisma` (Re-Embed-Hash, embedding_model_id, last_embedded_at).
|
|
3. NEU: Permission-Pre-Filter vor Vector-Search (Spec 18.3.3).
|
|
4. NEU: Embedding-Trigger bei Entity-Anlage/Update (Outbox `rag.index.*` vorhanden — Domain-Writes andocken).
|
|
5. Action-Boundary: `createReviewRequiredResult()` + Mutation-Audit + UI-Bestätigungs-Dialog.
|
|
6. NEU: Runtime-Input-Sanitizer (Marker-Neutralisierung + Längen-Cap).
|
|
|
|
**M086 (Sprach-zu-Automation, USP) — meiste Eigenleistung:**
|
|
1. Tool-Registry + Streaming + Prompt-Registry als Fundament.
|
|
2. NEU: Sprach→Wenn-Dann-Orchestrierung, Existenz-Probe, Rückfrage-Loop, Risiko-Warnung, Vorher/Nachher-Diff, Voice-Input (Web-Speech-API), Editor-Integration (M078). NIE Auto-Aktivierung.
|
|
3. Abhängig von M087 (Aktions-Grenze) + M075-M077 (Automation-Schema).
|
|
|
|
**M088 (Token-Limits + Pay-as-you-go) — Engine ÜBERNEHMEN, Policy umbauen:**
|
|
1. `ai-quotas.ts` + `ai-overage.ts` + `AICostEvent`/`TenantAICostSummary` 1:1 (HiveGrid-Plan-Werte einsetzen, sobald Pricing fixiert).
|
|
2. UMBAU: `assertCredit.ts` Hard-Deny → Pay-as-you-go-Overage-Pfad ([N13]).
|
|
3. NEU: Notbremse (absolute Euro-Obergrenze → Drosselung statt Pause), Upsell-Logik, 80%-Banner+Email, Usage-Dashboard.
|
|
4. Stripe-Metered-Reporter andocken (M153/M156).
|
|
|
|
**Whisper-EU (Spec Block E) — separater Neubau-Strang (parallel/danach):**
|
|
1. NEU: Whisper-auf-Scaleway-GPU-Adapter + `transcribe()`-Methode in `packages/ai`.
|
|
2. NEU: `ai.transcribe`-Queue-Job + Async-Pipeline (storage + queue vorhanden).
|
|
3. NEU: Voice-Aufnahme-UI + Edit + Klartext-Fehler.
|
|
|
|
**Querschnitt zum Schluss jedes Milestones (DoD):** Sidebar-Wiring, Routes/Breadcrumbs, Permission-Seed (6 `ai.*` + Bundles + Default-Rollen), i18n-Klartexte (18.12), Activity/Notifications, Feature-Flags, View-Model-Loader-Trennung, Smoke- + Hot-Swap- + Visual-Regression-Tests.
|