Files
HiveGrid-Wireframes/hivegrid-cloud/docs/improvement-plan/04-search-rag/embedding-pipeline.md
T

23 KiB

Embedding-Pipeline + RAG-Retrieval

Status: completed Task-ID: #50 Phase: 04 Estimated Effort: 1 Woche Owner: unassigned

Problem

Damit semantische Suche und RAG (Chatbot V2 in Phase 07) funktionieren, brauchen wir eine durchgängige Pipeline die:

  1. Text-Inhalte aus dem Domain-Model (KB-Articles, Rows-Engine-Rows, CRM-Notes) automatisch und async embedded.
  2. Eine austauschbare Embedding-Provider-Abstraktion bietet (OpenAI, Scaleway-Managed-Inference, Aleph-Alpha, Anthropic) — die Wahl darf nicht im Code festgenagelt sein.
  3. Chunking sauber löst (Token-Counting, Overlap), weil naive Long-Text-Embeddings entweder Token-Limits sprengen oder Recall verschlechtern.
  4. Tenant-Scope hart durchzieht — Embeddings dürfen niemals cross-tenant retrieved werden.
  5. Einen Retrieval-Helper bereitstellt den Chatbot-V2 ohne weiteren Glue-Code aufrufen kann.
  6. Backfill für bestehende Inhalte ermöglicht (Initial-Setup + Disaster-Recovery).

Aktuell existiert keiner dieser Bausteine. Ohne sie ist RAG nicht baubar.

Depends on

  • 03-scaling-infrastructure/outbox-pattern.md (#42) — Indexer-Worker konsumiert rag.index-Outbox-Events. Synchrone Embedding-Pfade wären inakzeptabel langsam und würden Request-Threads blockieren.
  • 03-scaling-infrastructure/worker-queues.md (#43) — Worker läuft als BullMQ-Job im worker-general.
  • 04-search-rag/vector-store.md (#49) — die Pipeline schreibt direkt in den Vector-Store, nutzt embedAndUpsert und semanticSearch.
  • 04-search-rag/meilisearch.md (#48) — das Pattern der Outbox-Indexer-Worker (Job-Handler-Registrierung, Idempotenz, Retry-Strategy) ist hier etabliert und wird übernommen.
  • Existierendes packages/ai/ — wird um embeddings/-Modul erweitert.

Blocks

  • 07-chatbot/chatbot-v2.md — die RAG-Variante des Chatbots nutzt retrieveRelevantContext direkt. Ohne Embedding-Pipeline keine RAG-Antworten.
  • diverse Phase-05-Features die "ähnliche Items vorschlagen" wollen (z.B. Knowledge-Base "verwandte Artikel"-Widget) können nach Abschluss dieser Pipeline implementiert werden.

Approach

Embedding-Provider-Abstraktion in packages/ai/src/embeddings/ mit dem gleichen Adapter-Pattern wie der Vector-Store: ein Interface, mehrere Adapter, eine Factory die per env auswählt.

Indexer-Worker konsumiert generische rag.index-Events mit Payload { tenantId, collection, sourceType, sourceId, text, metadata }. Der Worker chunked, embedded und upserted in einem Schritt. Bei rag.delete-Events: deleteVectors mit id-Pattern <sourceType>:<sourceId>:*.

Auto-Indexing-Hooks in den Domain-Services: bei Create/Update/Delete eines indexierbaren Items wird ein Outbox-Event geschrieben. Welche Items indexierbar sind, wird durch Konvention (KB-Articles) oder durch eine isEmbeddable-Property (Rows-Engine, opt-in pro Entity-Definition) entschieden.

RAG-Retrieval-Helper retrieveRelevantContext kapselt: query-embed → vector-search (multi-collection-fan-out) → rank-merge → Source-Refs zurückgeben.

Backfill-CLI schreibt rag.index-Events in die Outbox für alle bestehenden Items — kein direkter Embedding-Pfad aus dem CLI-Prozess heraus, damit Quota-Konsistenz und Worker-Throughput-Limits respektiert werden.

Alternativen verworfen:

  • Synchrones Embedding bei Save: blockiert Save-Latenz um 200-2000ms je nach Provider; bei Provider-Outage ist Save kaputt.
  • Direkter Worker-Trigger ohne Outbox: würde Dual-Write zwischen Postgres-Save und Worker-Trigger einführen → Inkonsistenzen bei Crash zwischen den beiden Writes.
  • LangChain als Framework: viel zu groß, zu meinungsstark, zu fragile bei Version-Bumps. Wir nutzen die zwei nützlichen Bausteine (Splitter-Algorithmus, Token-Counter) eigenständig.

Implementation Steps

  1. Embedding-Provider-Interface in packages/ai/src/embeddings/ — Interface EmbeddingProvider mit Methoden:
    interface EmbeddingProvider {
      readonly name: string;
      readonly model: string;
      readonly dimensions: number;
      readonly maxBatchSize: number;
      readonly maxTokensPerInput: number;
      embed(texts: string[]): Promise<number[][]>;  // batch, gleich lang wie input
      embedSingle(text: string): Promise<number[]>;
    }
    
    Types-Exports und Factory createEmbeddingProvider(env?: ProviderEnv).
    • Files: packages/ai/src/embeddings/types.ts, packages/ai/src/embeddings/factory.ts, packages/ai/src/embeddings/index.ts
    • Commit: 04/embedding-pipeline: add embedding provider interface and factory
  2. OpenAI-Adapter — Wrapper um OpenAI-SDK, Modelle text-embedding-3-small (1536d) und text-embedding-3-large (3072d), automatisches Batching auf 96 Inputs/Request, Retry mit exponential Backoff bei 429/5xx.
    • Files: packages/ai/src/embeddings/providers/openai.ts, packages/ai/src/embeddings/providers/openai.test.ts
    • Commit: 04/embedding-pipeline: add openai embedding adapter
  3. Scaleway-Managed-Inference-Adapter — REST-Wrapper für Scaleway-Embedding-Endpoint (OpenAI-kompatibel), env SCALEWAY_INFERENCE_URL, SCALEWAY_INFERENCE_TOKEN.
    • Files: packages/ai/src/embeddings/providers/scaleway.ts, packages/ai/src/embeddings/providers/scaleway.test.ts
    • Commit: 04/embedding-pipeline: add scaleway embedding adapter
  4. Aleph-Alpha-Adapter — Wrapper um Aleph-Alpha-Embedding-API (semantic_embedding), Token-Limits beachten, Batching.
    • Files: packages/ai/src/embeddings/providers/aleph-alpha.ts, packages/ai/src/embeddings/providers/aleph-alpha.test.ts
    • Commit: 04/embedding-pipeline: add aleph-alpha embedding adapter
  5. Anthropic-Adapter (Stub mit clear-error-throw) — Anthropic hat noch kein offizielles Embedding-Endpoint. Adapter existiert als Platzhalter, der bei Aufruf einen klaren Fehler wirft mit Hinweis darauf, welche Provider stattdessen zu nutzen sind. Sobald Anthropic launched, wird der Stub durch eine echte Implementation ersetzt.
    • Files: packages/ai/src/embeddings/providers/anthropic.ts
    • Commit: 04/embedding-pipeline: add anthropic embedding adapter placeholder
  6. Provider-Factory mit env-Auswahl — AI_EMBEDDING_PROVIDER (openai|scaleway|aleph-alpha|anthropic), AI_EMBEDDING_MODEL (provider-spezifisch), AI_EMBEDDING_DIMENSIONS (für Vector-Store-Collection-Setup). Factory validiert env-Konsistenz beim Start.
    • Files: packages/ai/src/embeddings/factory.ts (erweitert), packages/ai/src/embeddings/factory.test.ts
    • Commit: 04/embedding-pipeline: implement env-based provider selection
  7. Chunking-Helper splitForEmbedding — Signatur:
    splitForEmbedding(text: string, opts?: { maxTokens?: number; overlap?: number; encoding?: string }): Chunk[]
    type Chunk = { index: number; text: string; tokenCount: number; charStart: number; charEnd: number }
    
    Token-Counting via tiktoken (für OpenAI-kompatible Modelle) oder model-spezifisch. Splits an Satzgrenzen wenn möglich (Recursive-Character-Splitter), fallback auf hard-cut. Overlap default 50 Tokens.
    • Files: packages/ai/src/embeddings/chunking.ts, packages/ai/src/embeddings/chunking.test.ts
    • Commit: 04/embedding-pipeline: add token-aware chunking helper
  8. Indexer-Worker im worker-general — neuer BullMQ-Job-Handler rag.index und rag.delete. Konsumiert Outbox-Events:
    • rag.index payload: { tenantId, collection, sourceType: "kb-article" | "row" | "crm-note", sourceId, text, metadata }. Worker: splitForEmbedding(text) → für jeden Chunk eine deterministische ID <sourceType>:<sourceId>:<chunkIndex>, payload mergt metadata + { tenantId, sourceType, sourceId, chunkIndex } → embedAndUpsert in Vector-Store.
    • rag.delete payload: { tenantId, collection, sourceType, sourceId }. Worker: Vektoren mit id-Pattern <sourceType>:<sourceId>:* aus Collection entfernen (Adapter unterstützt prefix-delete oder list+delete).
    • Idempotenz: re-processing eines Events liefert gleichen Endzustand. Bei Provider-Error: BullMQ-Retry mit exponential Backoff.
    • Files: apps/worker-general/src/jobs/rag-indexer.ts, apps/worker-general/src/jobs/rag-indexer.test.ts, apps/worker-general/src/index.ts
    • Commit: 04/embedding-pipeline: add rag-indexer worker job
  9. Auto-Indexing-Hooks in Domain-Services — Outbox-Events produzieren bei:
    • KB-Article Create/Update/Delete → rag.index mit sourceType: "kb-article", text = title + "\n\n" + content.
    • CRM-Notes Create/Update/Delete → rag.index mit sourceType: "crm-note", text = note-body, metadata enthält contactId + userId.
    • Rows-Engine: opt-in pro Entity-Definition via neue Property isEmbeddable: boolean und embeddableFields: string[]. Wenn gesetzt: bei Row-Create/Update/Delete → rag.index mit text = concat der embeddableFields-Werte.
    • Files: jeweilige Domain-Service-Files, Entity-Definition-Schema-Erweiterung
    • Commits: pro Source-Type ein Commit, z.B. 04/embedding-pipeline: emit rag.index events from kb-articles
  10. RAG-Retrieval-Helper retrieveRelevantContext — Public-API in packages/ai/src/embeddings/retrieval.ts:
    retrieveRelevantContext({
      tenantId: string,
      query: string,
      topK?: number,           // default 8
      collections?: string[],  // default: alle aktiven RAG-Collections des Tenants
      minScore?: number,       // default 0.7
    }): Promise<RetrievedContext[]>
    type RetrievedContext = {
      sourceType: string;
      sourceId: string;
      chunkIndex: number;
      text: string;
      score: number;
      metadata: Record<string, unknown>;
    }
    
    Embedded die Query mit dem konfigurierten Provider, sucht parallel in allen relevanten Collections, merged + ranked nach Score, filtert minScore, gibt top-K zurück. Tenant-Scope wird durchgehalten.
    • Files: packages/ai/src/embeddings/retrieval.ts, packages/ai/src/embeddings/retrieval.test.ts
    • Commit: 04/embedding-pipeline: add retrieveRelevantContext helper for rag
  11. Backfill-CLI-Command — pnpm cli rag:reindex --tenant=<id|all> --collection=<name|all>. Iteriert per Cursor über die Source-Tabellen (KB-Articles, CRM-Notes, embeddable Rows) und schreibt rag.index-Events in die Outbox. Worker-Throughput limitiert die Rate automatisch (kein DOS gegen Embedding-Provider).
    • Files: packages/cli/src/commands/rag-reindex.ts, packages/cli/src/commands/rag-reindex.test.ts
    • Commit: 04/embedding-pipeline: add cli command for rag backfill
  12. Doku docs/features/rag.md — Architektur-Diagramm (Domain-Event → Outbox → Worker → Embedding-Provider → Vector-Store; Query-Pfad: Chatbot → retrieveRelevantContext → Vector-Store → ranked Snippets), Chunking-Tipps (richtige maxTokens pro Use-Case), Provider-Vergleich (Cost pro 1M Tokens, EU-Region-Verfügbarkeit, DSGVO-Status), Onboarding-Anleitung für eigene isEmbeddable-Entities.
    • Files: docs/features/rag.md
    • Commit: 04/embedding-pipeline: add user-facing rag documentation

Test Requirements

  • Unit-Tests:
    • Provider-Adapter (jeweils mit gemockten HTTP-Calls): korrektes Batching, Retry-Verhalten bei 429/5xx, korrekte Dimension-Validierung, Token-Limit-Errors werden propagiert.
    • Factory: env-basierte Auswahl, klare Errors bei inkonsistenter Config (z.B. Provider gesetzt aber kein API-Key).
    • splitForEmbedding: Chunks <= maxTokens, Overlap stimmt, Satzgrenzen werden präferiert, Edge-Cases (empty string, single-word, ein einziger riesiger Satz).
    • retrieveRelevantContext: Tenant-Scope-Pflicht, mehrere Collections werden parallel abgefragt, minScore-Filter greift, topK-Cap eingehalten.
  • Worker-Tests:
    • rag-indexer für rag.index: chunked → embedded → upserted; idempotent bei Re-Play; bei Provider-Error wird Job retried (verifiziert via BullMQ-Mock).
    • rag-indexer für rag.delete: entfernt alle Chunks zu einem sourceId; idempotent bei wiederholtem Event.
    • Outbox-Producer-Hooks: KB-Article Create → produziert genau ein rag.index-Event mit korrektem Payload.
  • Integration-Tests (mit testcontainers):
    • Spinne Postgres-mit-pgvector + Redis (für BullMQ).
    • End-to-End: KB-Article einfügen (über Domain-Service) → Outbox-Event wird produziert → Worker konsumiert → Vector-Store enthält Chunks → retrieveRelevantContext mit ähnlicher Query findet die Chunks.
    • Tenant-Isolation: Tenant A indexed KB-Artikel, Tenant B macht semantische Suche → 0 Treffer.
    • Backfill: 100 bestehende KB-Articles in DB ohne Embeddings, rag:reindex ausführen → alle 100 landen im Vector-Store.
  • Provider-Smoke-Test (separates Test-Suite, gated by env):
    • Wenn OPENAI_API_KEY gesetzt: ein echter embed-Call gegen text-embedding-3-small, verifiziert Dimension und Score-Plausibilität.
    • Analog für Scaleway, Aleph-Alpha.
    • Tests sind via vitest --grep=@live-provider nur in dediziertem Lauf aktiv.
  • Coverage-Target: packages/ai/src/embeddings/ ≥85%, apps/worker-general/src/jobs/rag-indexer.ts ≥80%.
  • Test-Files:
    • packages/ai/src/embeddings/**/*.test.ts
    • apps/worker-general/src/jobs/rag-indexer.test.ts
    • packages/cli/src/commands/rag-reindex.test.ts
    • tests/integration/rag-pipeline.test.ts (E2E mit testcontainers)

NICHT als completed markieren bevor alle Tests grün sind. Provider-Smoke-Tests gegen mindestens einen echten Provider müssen einmal manuell durchgeführt und im Progress-Log dokumentiert sein.

Acceptance Criteria

  • packages/ai/src/embeddings/ exportiert: EmbeddingProvider-Interface, createEmbeddingProvider, splitForEmbedding, retrieveRelevantContext
  • OpenAI-, Scaleway-, Aleph-Alpha-Adapter implementiert und getestet; Anthropic als Platzhalter mit klarem Throw
  • env-basierte Provider-Selektion via AI_EMBEDDING_PROVIDER, AI_EMBEDDING_MODEL, AI_EMBEDDING_DIMENSIONS
  • splitForEmbedding mit Token-Counter (tiktoken oder model-spezifisch), default 512/50 (maxTokens/overlap)
  • rag-indexer-Worker im worker-general registriert; konsumiert rag.index und rag.delete
  • Outbox-Producer-Hooks aktiv für: KB-Articles, CRM-Notes, Rows mit isEmbeddable=true
  • isEmbeddable + embeddableFields als opt-in-Property in Entity-Definitionen einsetzbar
  • retrieveRelevantContext mit Multi-Collection-Fan-Out, Tenant-Scope-Pflicht, topK + minScore-Filter
  • CLI-Command rag:reindex --tenant --collection produziert Backfill-Events
  • Doku docs/features/rag.md mit Architektur + Chunking + Provider-Vergleich + Onboarding-Guide
  • .env.example enthält AI_EMBEDDING_PROVIDER, AI_EMBEDDING_MODEL, AI_EMBEDDING_DIMENSIONS
  • Tests grün (lint, typecheck, unit, worker, integration via testcontainers)
  • Mindestens ein Provider-Smoke-Test einmal gegen echtes Endpoint gefahren und dokumentiert
  • Detail-MD Progress-Log aktualisiert
  • PROGRESS.md Status auf completed

Rollback Strategy

  • Worker-Disable: Feature-Flag RAG_INDEXER_ENABLED=false stoppt die Job-Handler-Registrierung. Outbox-Events sammeln sich an, werden später beim Re-Enable abgearbeitet (Outbox-Retention beachten — ggf. erhöhen vor Disable).
  • Provider-Wechsel: Bei Provider-Outage AI_EMBEDDING_PROVIDER-env umstellen und Worker neu deployen. Bestehende Embeddings im Vector-Store bleiben benutzbar wenn Dimension passt; sonst rag:reindex --tenant=all nach dem Wechsel.
  • Code-Revert: Commits sind atomic. Revert der Worker- und Hook-Commits stoppt die Pipeline. Vector-Store-Daten bleiben erhalten (kein Schema-Schaden) — können später wieder befüllt werden.
  • Dimension-Mismatch-Recovery: Wenn aus Versehen ein anderes Embedding-Modell mit anderer Dimension aktiviert wurde, schlägt der Vector-Store-Upsert mit klarem Error fehl. Recovery: alte Collection löschen (vector-store deleteCollection), neue mit korrekter Dimension anlegen (auto via createCollection beim ersten Upsert), rag:reindex triggern.

Security Notes

  • Tenant-Isolation ist sicherheitskritisch. tenantId ist Pflicht in Event-Payload, Chunk-Metadata, Vector-Store-Payload und Retrieval-Aufruf. retrieveRelevantContext verlangt tenantId als Pflicht-Parameter — TypeScript erzwingt es.
  • Provider-Datenabfluss: Jeder Embed-Call schickt Text an einen externen Provider. Implikationen:
    • DSGVO: nur EU-Region-Provider (Scaleway, Aleph-Alpha) für Tenants mit EU-Daten-Anforderung. Doku in docs/features/rag.md.
    • Per-Tenant-Provider-Override (Phase-11-Backlog): Tenants sollen pro-Tenant einen Provider wählen können (Premium-Feature). Aktuell global-env-basiert.
    • Logging: niemals den Input-Text in Logs (nur Hashes für Debug); Embedding-Vektoren selber auch nicht (siehe Vector-Store-Security-Notes).
  • PII in Source-Texten: KB-Articles und CRM-Notes können PII enthalten. Kein Cross-Tenant-Leak möglich solange Tenant-Filter strikt; aber: wenn ein Tenant seinen Provider auf OpenAI setzt, akzeptiert er implizit dass die Texte an OpenAI gehen. UI-Hinweis und Opt-In-Toggle für CRM-Notes-Indexing (default off, vom Tenant explizit zu aktivieren).
  • API-Key-Handling: Provider-API-Keys (OpenAI/Scaleway/Aleph-Alpha) gehören in den Secret-Store, nie in .env.example. Worker holt sie beim Start.
  • Rate-Limiting: Backfill kann teuer werden. CLI-Command rag:reindex produziert nur Outbox-Events; Worker-Concurrency-Limit (BullMQ-concurrency) kontrolliert die effektive Provider-Last. Default-Concurrency: 2 für Embedding-Jobs (konservativ, kann pro Tenant erhöht werden).
  • Cost-Guard (vorläufig): Bis AI-Cost-Tracking (Phase 05 Task #54-#56) live ist, Worker hartcoded auf max 10k Embed-Calls pro Tenant pro Stunde, sonst Job-Stop mit Alert. Wird abgelöst sobald Quota-Enforcement aus Phase 05 verfügbar ist.

Subagent Recommendations

  • Planning: Plan-Subagent — validiert Reihenfolge der 12 Steps, prüft ob Interface-Designs mit Vector-Store-Helpers konsistent sind.
  • Research: Explore-Subagent mit Auftrag: "Recherchiere aktuelle Embedding-Provider-Konditionen: Modelle, Dimensions, Cost pro 1M Tokens, EU-Region-Verfügbarkeit für OpenAI, Scaleway-Inference, Aleph-Alpha. Liefer-Format: Markdown-Tabelle. Bestätige außerdem ob Anthropic in 2026 ein Embedding-Endpoint anbietet — wenn ja, Doku-Link."
  • Implementation:
    • Subagent 1: Steps 1-6 (Interface + alle Provider-Adapter + Factory). Parallel arbeitbar nach internen Sub-Splits.
    • Subagent 2: Step 7 (Chunking). Unabhängig, kann parallel zu Subagent 1 laufen.
    • Subagent 3: Steps 8-9 (Worker + Outbox-Hooks). Hängt von Subagents 1+2 ab.
    • Subagent 4: Steps 10-11 (Retrieval-Helper + CLI). Hängt von Subagent 3 ab für vollständige E2E-Tests, kann aber parallel implementiert werden.
    • Subagent 5: Step 12 (Doku). Parallel zu Subagent 4.
  • Tests:
    • Dedizierter Test-Subagent für die Conformance-Tests der Provider-Adapter (mit gemockten HTTP-Calls).
    • Dedizierter Test-Subagent für den E2E-Integration-Test mit testcontainers (Postgres-pgvector + Redis).
  • Verification: gsd-verifier mit Acceptance-Criteria-Checkliste.
  • Code-Review: gsd-code-reviewer am Ende mit besonderem Fokus auf: Tenant-Filter-Coverage, Secret-Handling, korrekte Dimension-Validierung.

Staging-Deployment-Steps

  1. Branch agent/04-embedding-pipeline pushen.
  2. Voraussetzungen auf Staging verifizieren: pgvector aktiviert (aus Task #49), Outbox läuft (Task #42), Worker-General deployed (Task #43).
  3. Embedding-Provider-Secret in Coolify setzen: OPENAI_API_KEY oder SCALEWAY_INFERENCE_TOKEN (je nach Wahl). AI_EMBEDDING_PROVIDER, AI_EMBEDDING_MODEL, AI_EMBEDDING_DIMENSIONS als Env-Vars.
  4. Worker-Deploy triggern; Logs prüfen: rag-indexer registered, embedding-provider: <name> (<model>, <dim>d).
  5. Smoke-Tests:
    • In Staging-UI einen KB-Artikel mit ~500 Wörtern anlegen → innerhalb 30s Worker-Log rag.index processed sourceId=<id> chunks=<n> → Vector-Store-Eintrag prüfen via pnpm tsx scripts/staging/vector-inspect.ts <tenantId> <sourceId>.
    • pnpm cli rag:reindex --tenant=<staging-tenant> für KB-Articles → Worker arbeitet alle Events ab → BullMQ-Dashboard zeigt 0 pending.
    • pnpm tsx scripts/staging/rag-query.ts <tenantId> "<test-query>" → liefert ranked Chunks; manuelle Plausibilitätsprüfung.
  6. Tenant-Isolation auf Staging: zwei Tenants mit unterschiedlichen KB-Inhalten anlegen, gegenseitige Queries müssen 0 Treffer liefern.
  7. Cost-Beobachtung: nach Smoke-Tests Provider-Dashboard prüfen (OpenAI-Usage, Scaleway-Usage). Sicherstellen dass das Cost-Guard greift falls Backfill überdimensioniert war.

Deviations from Plan

(leer)

Progress Log

  • 2026-05-17 12:00 — 26ef2e2c — embedding provider interface + factory + types (packages/ai/src/embeddings/{types,factory,index}.ts) with registry-based adapter pattern; 15 factory tests green.
  • 2026-05-17 12:05 — 7f167a43 — OpenAI adapter (text-embedding-3-small default, batch 96, retry-with-jitter on 429/5xx, dimension validation, optional dims override on v3 models); 10 tests.
  • 2026-05-17 12:10 — 31b1fe1d — Scaleway adapter (OpenAI-compatible, EU residency by default, bge-multilingual-gemma2 1024d); 6 tests.
  • 2026-05-17 12:15 — fd26a9f0 — Aleph-Alpha adapter (semantic_embed endpoint, parallel single-input calls, luminous-base 5120d); 5 tests.
  • 2026-05-17 12:18 — c7c2e4e9 — Anthropic placeholder adapter (throws EMBEDDING_PROVIDER_NOT_SUPPORTED with provider-pick hint); 3 tests.
  • 2026-05-17 12:25 — ef800f6c — chunking helper splitForEmbedding backed by gpt-tokenizer (cl100k), default 500/50 tokens, sentence-boundary + hard-cut fallback; 10 tests.
  • 2026-05-17 12:35 — d5764a79 — embedAndUpsert helper enforcing tenant scope at the seam (extraPayload can't override tenantId); 7 tests.
  • 2026-05-17 12:45 — a8e69306 — rag-indexer worker job + bootstrap on outbox.rag-index, event-router rule, BullMQ wiring in apps/worker; 13 worker tests + router test.
  • 2026-05-17 13:00 — ce34c873 — outbox publishers publishRagUpsertEvent/publishRagDeleteEvent + KB-Article wire helper apps/web/.../kbArticleRag.server.ts; CRUD-call-site migration deferred per spec.
  • 2026-05-17 13:10 — 6eee711a — retrieveRelevantContext with multi-collection fan-out, rank-merge by score, minScore filter, topK cap; 6 tests.
  • 2026-05-17 13:20 — ad01e707 — toolctrl-cli rag reindex --tenant --source backfill with KB-Article source adapter; 8 tests.
  • 2026-05-17 13:25 — 9ddfa0b1 — env catalog + .env.example entries for every embedding/RAG env (AI_EMBEDDING_, provider keys, RAG_).
  • 2026-05-17 13:30 — 3d004d69 — docs/features/rag.md documenting architecture, provider matrix, tenant isolation, chunking, cost, disaster-recovery, onboarding.

Open follow-ups (not blocking acceptance):

  • migrate every KB CRUD call site to invoke emitKbArticleRagUpsert / emitKbArticleRagDelete (the helper is shipped; routes/admin currently delete via the legacy db helpers).
  • wire CRM-notes + embeddable rows-engine entities (source adapters + service hooks) per the documented pattern.
  • replace the hard-coded 2-concurrency cap with the per-tenant cost-guard once Phase 05 task #54-#56 lands.
  • run the manual provider-smoke-test against the deployed Scaleway endpoint (staging-step #5) and append the run notes here.

Lessons Learned

(Wird nach Task-Abschluss ergänzt — insbesondere: Chunking-Größen die in Praxis funktionieren, Provider-Latenz-Vergleich, Cost-pro-Tenant-Profil, Retrieval-Quality-Beobachtungen.)