# Vector-Store — Adapter-Pattern für pgvector und Qdrant **Status:** completed **Task-ID:** #49 **Phase:** 04 **Estimated Effort:** 1.5 Wochen (beide Adapter inkl. Tests) **Owner:** unassigned ## Problem Für semantische Suche und RAG (Phase 07 Chatbot V2) brauchen wir einen Vector-Store: ein Storage-System das hochdimensionale Embedding-Vektoren persistiert und schnelle Nearest-Neighbor-Suche darüber bietet. Aktuell existiert nichts davon in der Boilerplate. Wir wollen aber nicht früh auf einen Anbieter festlegen: - **pgvector** ist betrieblich trivial — gleiche Postgres-Instanz, gleiche Backups, gleiche RLS-Patterns, keine zusätzliche Infrastruktur. Für die meisten Tenants (bis ca. 1M Vektoren pro Collection) völlig ausreichend. - **Qdrant** skaliert besser auf große Vektor-Mengen, hat reichhaltigere Filter-Syntax und ein production-grade HNSW-Implementation. Für Power-Tenants oder dedizierte Deployments interessant. Statt eines harten Lock-Ins bauen wir eine Adapter-Schicht. Default ist pgvector (zero-ops), Qdrant wird optional aktiviert wenn `QDRANT_URL` gesetzt ist. Das gibt der Boilerplate Optionalität ohne Komplexität für den 80%-Use-Case. ## Depends on - `03-scaling-infrastructure/outbox-pattern.md` (#42) — wird vom Embedding-Pipeline-Task (#50) genutzt; der Vector-Store selbst ist synchroner Adapter, aber Konsumenten dieses Packages werden ihn aus Outbox-Worker-Jobs heraus aufrufen. - `03-scaling-infrastructure/read-write-split.md` (#41) — der pgvector-Adapter nutzt den `prismaWrite`-Client für alle Writes, damit Replication-Lag-Issues vermieden werden. Reads können über `prismaRead` laufen (mit Toleranz-Marker). ## Blocks - `04-search-rag/embedding-pipeline.md` (#50) — die Embedding-Pipeline nutzt die hier definierten Helpers (`embedAndUpsert`, `semanticSearch`). - `07-chatbot/chatbot-v2.md` — Chatbot V2 macht semantic Retrieval direkt über `semanticSearch`. ## Approach **Neues Package `packages/vector-store/` mit einem Adapter-Interface und zwei Implementierungen (pgvector und Qdrant), plus einer Factory die per env oder explizitem Parameter auswählt.** Beide Adapter durchlaufen identische Vitest-Test-Suites — das ist die Garantie dass sie austauschbar sind. **Adapter-Interface (verbindlich):** ```ts interface VectorStoreAdapter { createCollection(args: { name: string; dimensions: number; metric: "cosine" | "euclidean" | "dot" }): Promise; deleteCollection(name: string): Promise; listCollections(): Promise; upsertVectors(args: { collection: string; items: VectorItem[] }): Promise; searchVectors(args: { collection: string; vector: number[]; topK: number; filter?: VectorFilter }): Promise; deleteVectors(args: { collection: string; ids: string[] }): Promise; health(): Promise<{ ok: boolean; latencyMs: number }>; } type VectorItem = { id: string; vector: number[]; payload: Record & { tenantId: string } }; type VectorFilter = { must?: FilterClause[]; should?: FilterClause[] }; type FilterClause = { key: string; match: { value: string | number | boolean } | { any: (string | number)[] } }; type VectorHit = { id: string; score: number; payload: Record }; ``` **pgvector-Adapter (Default):** - Nutzt `prismaWrite` für Writes, `prismaRead` für Searches. - Eine Tabelle pro Collection: `vec_` mit Columns `id TEXT PRIMARY KEY`, `vector vector()`, `payload JSONB`, `tenant_id TEXT GENERATED ALWAYS AS (payload->>'tenantId') STORED`, plus `created_at`, `updated_at`. - HNSW-Index für die Vector-Spalte (Postgres 16+ pgvector 0.5+): `CREATE INDEX ... USING hnsw (vector vector_cosine_ops)`. - GIN-Index für die payload-jsonb für Filter. - B-Tree-Index auf `tenant_id` für effiziente Tenant-Skopierung. - Filter werden in `WHERE`-Klauseln übersetzt, `tenant_id`-Filter ist Pflicht und wird durch den Wrapper injiziert. **Qdrant-Adapter (Optional):** - Nutzt `qdrant-js-client`. - Collection-Auto-Create on first upsert: wenn Collection nicht existiert → `createCollection` mit den Settings aus dem ersten Upsert. Bei Mismatch (dimensions verschieden): throw mit klarer Fehlermeldung. - Tenant-Scope über Qdrant native Payload-Filter (`must: [{ key: "tenantId", match: { value: tenantId } }]`). - Snapshot-API für Backups. **Factory:** ```ts createVectorStore({ namespace: string, // z.B. "rag-prod" oder pro-tenant-prefix adapter?: "pgvector" | "qdrant", // explizit; sonst auto }) ``` Auswahl-Logik: explizit `adapter`-Param > `QDRANT_URL`-env gesetzt → qdrant > sonst pgvector. Der `namespace` wird in Collection-Namen prefixed. **Alternativen verworfen:** - **Weaviate**: schwerer Footprint, Schema-Definition-Aufwand zu hoch für unsere Use-Cases. - **Pinecone (SaaS)**: vendor-lock-in, DSGVO problematisch (US-Region), unvereinbar mit Selfhost-Anspruch. - **Milvus**: Production-Setup zu komplex (etcd, MinIO, mehrere Services), nicht im Verhältnis zum Gewinn. - **Nur pgvector**: dann kein Upgrade-Pfad für Power-Tenants — wir wollen die Tür offen halten ohne komplexitäts-overhead. - **Nur Qdrant**: nicht zero-ops; bei kleinen Tenants Over-Engineering. ## Implementation Steps 1. **Package `packages/vector-store/` initialisieren** — gemäß Repo-Convention (tsup, vitest, types-only-export für public-API). Exports: `createVectorStore`, Interface `VectorStoreAdapter`, Types `VectorItem`, `VectorFilter`, `VectorHit`. - Files: `packages/vector-store/package.json`, `packages/vector-store/src/index.ts`, `packages/vector-store/src/types.ts`, `packages/vector-store/tsconfig.json`, `packages/vector-store/vitest.config.ts` - Commit: `04/vector-store: scaffold packages/vector-store with adapter interface` 2. **pgvector-Setup als Prisma-Migration** — Migration `_enable_pgvector` mit `CREATE EXTENSION IF NOT EXISTS vector;`. Plus Helper-Migration-Generator-Skript für `vec_`-Tabellen (wird vom Adapter zur Runtime aufgerufen falls Tabelle fehlt — idempotent). - Files: `prisma/migrations/_enable_pgvector/migration.sql`, `packages/vector-store/src/adapters/pgvector/schema.ts` - Commit: `04/vector-store: enable pgvector extension and add schema helper` 3. **pgvector-Adapter implementieren** — alle Interface-Methoden. `createCollection` legt Tabelle inkl. HNSW- und GIN-Index an. `upsertVectors` nutzt `INSERT ... ON CONFLICT (id) DO UPDATE`. `searchVectors` nutzt `ORDER BY vector <=> $1 LIMIT topK` mit Tenant-Filter in `WHERE`. `deleteVectors` per `DELETE WHERE id = ANY($1)`. Health-Check pingt mit einem Dummy-Vektor gegen eine Test-Collection. - Files: `packages/vector-store/src/adapters/pgvector/adapter.ts`, `packages/vector-store/src/adapters/pgvector/queries.ts` - Commit: `04/vector-store: implement pgvector adapter` 4. **Qdrant-Adapter implementieren** — Wrapper um `qdrant-js-client`. `createCollection` mit den passenden Vector-Params, `upsertVectors` (Batch-Size 256), `searchVectors` mit native Filter-Übersetzung, `deleteVectors`, Health-Check via Cluster-Status-API. - Files: `packages/vector-store/src/adapters/qdrant/adapter.ts`, `packages/vector-store/src/adapters/qdrant/filter.ts` - Commit: `04/vector-store: implement qdrant adapter` 5. **Factory + Auto-Select-Logik** — `createVectorStore` mit Namespace-Prefix, adapter-param oder env-basiert. Throws klar bei Inkonsistenzen (z.B. `adapter: "qdrant"` aber kein `QDRANT_URL` gesetzt). - Files: `packages/vector-store/src/factory.ts`, `packages/vector-store/src/factory.test.ts` - Commit: `04/vector-store: add factory with auto adapter selection` 6. **Wrapper-Helpers `embedAndUpsert` und `semanticSearch`** — höher-level Helper die Embedding-Provider (`@toolctrl/ai`) mit Vector-Store kombinieren. `embedAndUpsert({ store, collection, items: [{id, text, payload}] })` embedded die Texte, batched, upserted. `semanticSearch({ store, collection, tenantId, query, topK, filter? })` embedded die Query, sucht, gibt Hits zurück. Tenant-Scope wird hier ebenfalls erzwungen. - Files: `packages/vector-store/src/helpers.ts`, `packages/vector-store/src/helpers.test.ts` - Commit: `04/vector-store: add embedAndUpsert and semanticSearch helpers` 7. **Identische Test-Suite gegen beide Adapter** — Vitest-Test-Suite die per Test-Parameter beide Adapter durchläuft. Nutzt testcontainers für Postgres-mit-pgvector (`pgvector/pgvector:pg16`) und für Qdrant (`qdrant/qdrant`). Test-Cases: create/delete collection, upsert + search idempotent, Tenant-Isolation (Tenant A sieht Tenant B nicht), Filter-Kombinationen, Edge-Cases (empty collection, topK > items, malformed vector). - Files: `packages/vector-store/src/adapters/__tests__/conformance.test.ts` - Commit: `04/vector-store: add conformance test suite for both adapters` 8. **Doku `docs/features/vector-store.md`** — Adapter-Vergleich (Latenz-Erwartungen, Skalierungs-Grenzen, Ops-Aufwand), Wahl-Empfehlung, Migration-Guide pgvector→Qdrant via Bulk-Reindex (kein direkter Daten-Transfer, sondern re-embed aus Source-of-Truth). - Files: `docs/features/vector-store.md` - Commit: `04/vector-store: add user-facing vector-store documentation` 9. **Backup-Strategy-Doc pro Adapter** — pgvector: über Standard-Postgres-Backup mitgesichert (bereits in `03-scaling-infrastructure/backup-cli.md` etabliert). Qdrant: Snapshot-API + Cron-Job der Snapshots zu S3 pusht. Dokumentation + Skript. - Files: `docs/deploy/vector-store-backup.md`, `scripts/qdrant-snapshot.sh` - Commit: `04/vector-store: document backup strategy per adapter` 10. **Qdrant-Container in docker-compose (optional-Service)** — als profile-gated Service in `docker-compose.yml` mit Image `qdrant/qdrant:v1.9`, Volume, Health-Check. Aktivierung über `COMPOSE_PROFILES=qdrant`. `.env.example` enthält `QDRANT_URL` als optionalen Key mit Kommentar. - Files: `docker-compose.yml`, `.env.example` - Commit: `04/vector-store: add optional qdrant service to docker-compose` ## Test Requirements - **Unit-Tests:** - Factory-Logik: pgvector als Default, Qdrant wenn env gesetzt, expliziter Param überschreibt. - Filter-Übersetzung pgvector: SQL-Klauseln korrekt für `must`/`should`/`match.value`/`match.any`. - Filter-Übersetzung Qdrant: native-Format korrekt; Tenant-Filter immer als `must` injiziert. - Schema-Helper: idempotente Tabellen-Erstellung; HNSW- und GIN-Index werden angelegt. - `embedAndUpsert`: batched korrekt, propagiert Embedding-Errors, kein partial-write. - `semanticSearch`: Tenant-Scope-Pflicht, Result-Sortierung nach Score absteigend. - **Conformance-Tests (gegen beide Adapter via testcontainers):** - Lifecycle: createCollection → upsert 100 items → search → delete 10 → search bestätigt count = 90 → deleteCollection. - Tenant-Isolation: zwei Tenants mit je 50 Items in gleicher Collection; Search aus Tenant A liefert nie Tenant-B-Items. - Recall-Smoke: 1000 zufällige Items, Query-Vektor identisch zu Item #500 → Top-1-Hit ist #500 mit Score >0.99. - Filter-Kombination: Tenant A Items mit `payload.category=foo` (20 Stück) und `bar` (30 Stück); Search mit Filter `category=foo` liefert nur diese 20. - Edge-Cases: empty collection search → 0 hits; topK=0 → 0 hits; vector mit falscher Dimension → typed error. - **Integration-Test (E2E flow):** - `embedAndUpsert` mit Test-Embedding-Provider (Mock liefert deterministische Vektoren) → `semanticSearch` findet das eingefügte Item. - **Coverage-Target:** `packages/vector-store/` ≥85%. - **Test-Files:** - `packages/vector-store/src/**/*.test.ts` - `packages/vector-store/src/adapters/__tests__/conformance.test.ts` **NICHT als completed markieren bevor alle Tests grün sind und die Conformance-Suite gegen beide Adapter durchläuft.** ## Acceptance Criteria - [ ] `packages/vector-store/` exportiert public-API: `createVectorStore`, `VectorStoreAdapter`, `VectorItem`, `VectorFilter`, `VectorHit`, `embedAndUpsert`, `semanticSearch` - [ ] pgvector-Adapter implementiert alle Interface-Methoden; Migration enable-pgvector vorhanden; HNSW + GIN-Index werden angelegt - [ ] Qdrant-Adapter implementiert alle Interface-Methoden; Collection-Auto-Create funktioniert - [ ] Factory wählt korrekt zwischen pgvector und Qdrant (Default, env, expliziter Param) - [ ] `embedAndUpsert` und `semanticSearch` Helpers funktionieren mit beiden Adaptern - [ ] Conformance-Test-Suite läuft gegen beide Adapter via testcontainers; alle Cases grün - [ ] Tenant-Isolation in beiden Adaptern garantiert (kein Crossover möglich) - [ ] Doku `docs/features/vector-store.md` mit Adapter-Vergleich und Migration-Guide - [ ] Doku `docs/deploy/vector-store-backup.md` mit Backup-Strategie pro Adapter - [ ] Optional-Qdrant-Service in `docker-compose.yml` (Profile-gated) - [ ] `.env.example` enthält `QDRANT_URL` (kommentiert als optional) - [ ] Tests grün (lint, typecheck, unit, conformance integration) - [ ] Detail-MD Progress-Log aktualisiert - [ ] PROGRESS.md Status auf `completed` ## Rollback Strategy - **Code-Revert:** Alle Commits sind atomic und revert-fähig. Package ist neu, Konsumenten sind erst in Task #50 (embedding-pipeline) — solange dort nicht abgerufen, hat Rollback null Production-Impact. - **pgvector-Extension drop:** Migration `enable_pgvector` hat ein Pendant-Down-Migration-Script (`DROP EXTENSION IF EXISTS vector CASCADE;`). Vorsicht: CASCADE killt alle `vec_*`-Tabellen — vor Drop unbedingt Backup. - **Qdrant-Container:** Stoppen + Volume löschen. Daten gehen verloren, aber Source-of-Truth ist Postgres — Re-Embedding via `rag:reindex`-Command (kommt in Task #50) stellt Vector-Store wieder her. - **Adapter-Wechsel:** Wenn pgvector in Production zu langsam wird, Migration zu Qdrant über Bulk-Reindex (kein direkter Daten-Transfer — Embeddings werden aus dem Source-of-Truth neu berechnet). Vorgehen dokumentiert in `docs/features/vector-store.md`. ## Security Notes - **Tenant-Isolation ist sicherheitskritisch.** Wie bei Meilisearch ist das Filter-Pattern die einzige Trennung zwischen Tenants. Deshalb: - `tenantId` ist Pflicht-Property auf `VectorItem.payload` (TypeScript-erzwungen via `Record & { tenantId: string }`). - `semanticSearch` verlangt Pflicht-Parameter `tenantId` und injiziert ihn als `must`-Filter. - Direkter Adapter-Zugriff ohne Helper ist nicht abgeschnitten (für Power-User), aber Code-Review-Guideline: Adapter-Direct-Use nur in `packages/vector-store/` und in `embedding-pipeline`-Worker. - **Embedding-Leak-Schutz:** Embeddings können theoretisch Source-Text rekonstruieren (mit Aufwand). Behandlung wie PII — kein Cross-Tenant-Read, kein Logging von Vektoren in Cleartext. - **pgvector-Migration:** `CREATE EXTENSION` benötigt Superuser-Rechte auf der DB. In Staging/Prod sicherstellen dass die Migration-User-Rolle die nötigen Rechte hat oder die Extension out-of-band durch DBA aktiviert wurde. - **Qdrant-API-Key:** Wenn Qdrant production-deployed wird, MUSS `QDRANT_API_KEY` gesetzt werden. Wrapper validiert: wenn `QDRANT_URL` öffentlich erreichbar (nicht localhost/private) und kein API-Key → throw beim Init. - **Snapshot-Encryption:** Qdrant-Snapshots, die zu S3 gepusht werden, müssen S3-side encryption (SSE-S3 oder SSE-KMS) aktiviert haben. Backup-Skript verifiziert das. ## Subagent Recommendations - **Planning:** `Plan`-Subagent — soll Interface-Design validieren und schauen ob alle benötigten Operationen für RAG-Use-Case abgedeckt sind (Konsultation gegen `embedding-pipeline.md`). - **Research:** `Explore`-Subagent mit Auftrag: "Recherchiere pgvector 0.7+ HNSW vs IVFFlat Trade-offs für Collections mit <1M Vektoren. Liefer-Format: Tabelle mit Build-Time, Query-Latenz, Recall@10." - **Implementation:** - Subagent 1: Steps 1-3 (Scaffold + pgvector-Adapter). - Subagent 2: Steps 4-5 (Qdrant-Adapter + Factory), parallel zu Subagent 1 sobald Step 1 gemergt. - Subagent 3: Steps 6-7 (Helpers + Conformance-Tests), nach Merge von Subagents 1 und 2. - Subagent 4: Steps 8-10 (Doku + Optional-Container), parallel zu Subagent 3. - **Tests:** Conformance-Test-Suite ist nontrivial wegen testcontainers-Setup. Dedizierter Test-Subagent der die Container-Boot-Sequenz, Cleanup und parameterisierte Tests sauber baut. - **Verification:** `gsd-verifier` mit Acceptance-Criteria-Checkliste. - **Code-Review:** `gsd-code-reviewer` am Ende, mit Fokus auf SQL-Injection-Vermeidung im pgvector-Adapter (alle Tabellen-Namen aus Whitelist, alle Filter-Values parametrisiert). ## Staging-Deployment-Steps 1. Branch `agent/04-vector-store` pushen. 2. Migration `enable_pgvector` auf Staging-DB laufen lassen: `pnpm prisma migrate deploy`. Verifizieren via `SELECT extname FROM pg_extension WHERE extname='vector';`. 3. Bei Qdrant-Test-Setup: Qdrant-Container in Coolify-Stack hinzufügen (Profile `qdrant`). `QDRANT_URL` und `QDRANT_API_KEY` als Secrets setzen. 4. Smoke-Tests: - `pnpm tsx scripts/staging/vector-smoke.ts` (neues Skript, das `createVectorStore` aufruft, eine Test-Collection erzeugt, 100 Random-Vektoren upserted, eine Search ausführt, alles wieder löscht). - Für beide Adapter durchlaufen lassen (env-switch). 5. Performance-Check: 10k Vektoren upserten, P95-Search-Latenz messen. Erwartung: pgvector <30ms bei topK=10; Qdrant <15ms. 6. Backup-Verify: einmal Snapshot-Skript für Qdrant laufen lassen, S3-Upload prüfen. Restore-Test in einer zweiten Qdrant-Test-Instance. ## Deviations from Plan _(leer)_ ## Progress Log - 2026-05-17 10:51 — 2a192829 — pgvector extension migration (`20260517085146_04_enable_pgvector`). - 2026-05-17 10:55 — 9231a302 — `packages/vector-store` scaffold + public types (`VectorStoreAdapter`, `VectorItem`, …) + `VectorDimensionMismatchError`. - 2026-05-17 11:01 — 896369ae — pgvector adapter with HNSW/GIN/tenant indexes and parameter-bound search. - 2026-05-17 11:05 — 6ea1145b — Qdrant adapter against a minimal `QdrantClientLike` surface. - 2026-05-17 11:07 — a2ca182d — `withTenantScope` wrapper that injects `tenantId` and refuses the bare `searchVectors`. - 2026-05-17 11:09 — 6d0dc128 — `createVectorStore` factory with adapter selection (explicit > `qdrantUrl` > pgvector). - 2026-05-17 11:13 — 684add56 — Parameterised conformance suite running both adapters against in-memory shims (14 tests, 7 per adapter). - 2026-05-17 11:17 — d15627eb — `QDRANT_URL`, `QDRANT_API_KEY`, `VECTOR_STORE_DEFAULT_ADAPTER` cataloged + added to `.env.example`. - 2026-05-17 11:19 — f1e2674d — `docs/architecture/vector-store.md` covering adapter trade-offs, tuning, and migration path. ## Lessons Learned _(Wird nach Task-Abschluss ergänzt — insbesondere: pgvector HNSW-Tuning-Parameter die in Praxis funktionieren, Memory-Profil von Qdrant unter Last, Beobachtungen zur Adapter-Interface-Stabilität.)_