Semantic (vector) search for issues — pgvector embeddings + hybrid retrieval for the triage bot

Follow-up to PAR-227 (conversational ANSWER). The bot's retrieval is purely lexical today — PostgresTaskSystem.searchTasks (V12 search_tsv tsvector + ts_rank, OR-prefix, ILIKE fallback). It misses conceptually-related issues that don't share words ("can't pay rent" vs "rent payment fails"). Add semantic search via embeddings so search_tasks (and thus FIND + the ANSWER action) retrieves by meaning, and fuse it with the existing full-text for the best of both.

Where it plugs in

• Retrieval entrypoint: PostgresTaskSystem.searchTasks(query, limit) (src/main/java/io/paradaux/tesks/tasks/store/PostgresTaskSystem.java). The agentic loop's search_tasks tool (TriageService.runReadTool) and applyFind/applyAnswer all funnel through it — improving it lifts every path with no caller changes.
• Embeddings provider: reuse the OpenAI Java SDK already on the classpath (com.openai:openai-java:4.37.0) — client.embeddings(). Mirror the LlmClient/OpenAiLlmClient port pattern: add an EmbeddingClient port + OpenAI adapter, configured under tesks.llm (api-key/base-url reused) with tesks.llm.embedding-model (default text-embedding-3-small, 1536 dims). Meter tokens through the existing LlmUsageSink.

Infra prerequisite (do first / confirm)

• The deployed DB is stock postgres:16 (gitops/apps/postgres/base/resources.yaml) — no pgvector. Switch that image to pgvector/pgvector:pg16 (or install the extension) and CREATE EXTENSION IF NOT EXISTS vector in the tesks database. This is a shared instance (also hosts paradaux-api's apps db), so validate the image swap doesn't disrupt other databases. Gitops change + Argo sync.

Implementation

1. Migration V28__issue_embeddings.sql (latest is V27): create extension if not exists vector; add issue.embedding vector(1536) (nullable — NULL = not yet embedded), plus an HNSW index using hnsw (embedding vector_cosine_ops). Keep search_tsv — this is additive.
2. EmbeddingClient port + OpenAiEmbeddingClient adapter (io.paradaux.tesks.llm): float[] embed(String text) / batch variant; disabled-safe when no api-key (like OpenAiLlmClient).
3. Write path: embed title + "\n" + description on create and on title/description update (createTask/updateTask in PostgresTaskSystem). Do it best-effort/async so a failed/slow embedding never blocks the task write (NULL embedding just means it's not yet semantically searchable; full-text still covers it).
4. Backfill: a one-off runner (CommandLineRunner behind a flag, or an admin endpoint) that embeds all existing issues with NULL embedding, batched + rate-limit-aware, resumable.
5. Hybrid query: add a semantic ranking to searchTasks — embed the query, ANN by cosine distance, and fuse with the existing ts_rank lexical results (Reciprocal Rank Fusion is simplest/robust). Tenant-scope the ANN (where tenant_id = ? and archived_at is null and embedding is not null). Fall back to pure full-text when embeddings are disabled or the query embed fails. Keep the Task projection unchanged.
6. (Optional) expose a semantic_search tool to the agent in addition to keyword search_tasks, or just make search_tasks hybrid (preferred — fewer tools, the model already uses it well).

Considerations

• Cost/latency: text-embedding-3-small is cheap; one embed per query + one per issue write. Cache the query embedding within an agentic loop if the same query repeats.
• Multi-tenant: every ANN query MUST carry the tenant_id predicate (IIDOR parity with the rest of PostgresTaskSystem).
• Dimension lock-in: 1536 is fixed by the model; note it in the migration. Switching embedding models later means a re-embed/backfill.
• No mirror impact: this is the tesks-owned issue table in the tesks DB, not the tesks-ui Postgres mirror.

Acceptance

• A query semantically related but lexically distinct from an issue's text retrieves it (regression test with a seeded issue + paraphrased query, using a stubbed EmbeddingClient so the test is deterministic — no live API).
• Lexical results still rank well (hybrid doesn't regress exact-term matches); pure full-text path still works with embeddings disabled.
• New issues become semantically searchable after create; backfill covers historical issues.
• Tenant isolation holds on the ANN path. Full backend suite green; embedding calls metered.
• pgvector enabled in dev (and prod when it exists) via gitops.

State reconciliation — 2026-10-13

Reconciled 2026-10-13: the 2026-06-18 comment records an uncommitted working-tree implementation, not a shipped feature. Current merged main has no EmbeddingClient, EmbeddingMaintainer, vector migration, or hybrid-search implementation. Its migrations have since advanced through V31, so the proposed V28/V29 numbering and old package paths must be revised. Status remains In Progress pending recovery/verification of that earlier work; no claim of deployment or completion is made.

State reconciliation — 2026-10-19

Supersedes the 2026-10-13 assessment: PR #12 merged on 2026-10-14. It implements hybrid lexical/vector retrieval, asynchronous embedding maintenance and resumable backfill, tenant isolation, fallback, metering, and V32. The PR records 244 passing backend tests and pgvector verified in both dev and production after GitOps #54. Current main retains RankedSearchIssues, EmbeddingMaintainer and the embedding persistence implementation. Marked Done for completed implementation. Embedding calls are opt-in; this reconciliation does not assert that production enablement or historical backfill has been executed.