pgkiln 0.69.0 → 0.70.0

package/docs/guide/12-development.md

@@ -145,6 +145,12 @@ src/
                            scramVerifier (SCRAM-SHA-256, SASLprep) and the password slot (maskSql for review and log, withVerifier to run)
   cron-schedule.ts         (sprint 101, DA-12) pg_cron schedules without a database: parseSchedule (cron fields, $, n seconds, macros),
                            nextRuns in a time zone, describeSchedule in words, the builder's presets and fields
+  vector.ts                (sprint 136, AP-1) pgvector: pgvectorStatus(), vectorSchema() (operators and the type schema-qualified),
+                           DISTANCES (cosine/l2/inner_product: operator, HNSW opclass, similarity), vectorColumnDims(); the embedding
+                           queue (meta.embedding_queue, migration 136): embeddingTick() (groups, FOR UPDATE SKIP LOCKED, batches
+                           within the provider's per-minute limit, written with devDbForApp(), retries with backoff), drainEmbeddings(),
+                           kickEmbeddings(), startEmbeddingRunner() (server.ts; EMBEDDINGS=off, EMBEDDING_INTERVAL_S), vectorTriggers()
+                           (meta.embedding_set / embedding_enqueue triggers and their arguments), backfill(), queueState()
   pgcron.ts                (sprint 101, DA-12) pg_cron for SQL Workshop → Scheduling: cronState (installed, loaded, cron.database_name,
                            access), jobs and runs, jobSql/activeSql/unscheduleSql/purgeSql (reviewed, then applySql), runNow
   secrets.ts               secrets at rest (web credentials): AES-256-GCM with PGKILN_SECRET_KEY (or a key given, for rotate-key);
@@ -176,6 +182,11 @@ src/
                            (121) an agent's effort (Claude output_config.effort, OpenAI reasoning_effort) and output limit).
                            Providers (121): anthropic, openai, gemini (OpenAI-compatible endpoint, GEMINI_BASE_URL), openai_compatible
                            (Ollama, vLLM, Azure OpenAI; base URL required, key optional): service.ts serviceKey(), baseUrlFor(), providerLabel()
+                           (sprint 136, AP-1) embeddings.ts: vector providers (meta.app.vector_providers: ai_service with an embedding
+                           model, or a function), vectorProviderProblems(), embedTexts() (the openai SDK's embeddings API, float
+                           encoding, dimensions checked, daily limits via checkDailyLimit(), meta.ai_usage source "embedding"; a
+                           function provider through meta.embed on the caller's connection), embedQuery() (search texts remembered
+                           10 minutes per process), vectorLiteral()
   debug.ts                 debug messages: DebugLog (levels, timed steps, NOTICEs of meta.debug from appTx), started in
                            loadContext, stored after the response (onResponse hook → meta.debug_save), hourly purge
   icons.ts                 icon helper (sprite in public/icons.svg)
@@ -255,7 +266,8 @@ src/
                            definitionProblems), agentFor(), prepareTools() (authorization schemes, navigate pages the user may
                            open, strict schemas), runAgentTool() (sql: read-only transaction as the app role with a time limit;
                            function: named arguments, committed; rest; javascript: queued for the browser; navigate: URL and
-                           checksum built here), logToolCall() (meta.ai_tool_call, debug level 4, 30-day purge)
+                           checksum built here), logToolCall() (meta.ai_tool_call, debug level 4, 30-day purge); (136) retrieve:
+                           retrieveTool() (QUERY only, search.ts retrieve() in a read-only transaction as the app role)
     ai-filter.ts           "Ask in your own words" on a report ("ai_filter", sprint 112: AI interactive reports): the box, the chips
                            form (Edit/Remove/Undo, undo history in the session), ask and chips routes; an AI service's structured
                            output (planSchema) or the phrase parser, then ir-plan.ts
@@ -270,6 +282,10 @@ src/
                            searchable columns), websearch_to_tsquery / ts_rank_cd / ts_headline between private-use markers
                            (headlined() escapes, only the markers become <mark>), textSearchConfig() (pg_ts_config names only,
                            passed as $1::regconfig; tsConfigFor(language)), trigramSchema() and "did you mean" with pg_trgm
+                           (sprint 136, migration 136) search types vector (vectorRows: the text embedded by the provider, nearest
+                           rows by the schema-qualified distance operator, the vector as $1, min_similarity) and hybrid (full-text
+                           and vector rankings, 50 rows each, reciprocal rank fusion 1/(60+rank) per key_column); retrieve() for
+                           an agent's Retrieve tool
     url-region.ts          URL region (migration 078): literal origins only (urlTarget), &ITEM. URL-encoded, sandbox and height,
                            frameOrigins() for the CSP's frame-src (security.ts)
     ajax.ts                Ajax callbacks (migration 085: POST …/ajax/:name, point "ajax" processes, x01 … x10 binds) and the
@@ -360,6 +376,13 @@ src/
     fulltext.ts            (sprint 135, AP-2) Table Properties › Add full-text search: GET/POST /sql/objects/fulltext?o= (text columns
                            with weights A–D, a configuration from pg_ts_config, fulltextDdl(): a generated tsvector column and a GIN
                            index), Preview / Apply (one transaction, recorded in the Change Log) / Open in the worksheet
+    vector-column.ts       (sprint 136, AP-1) Table Properties › Add vector column: GET/POST /sql/objects/vector?o= (a provider of the
+                           workspace's applications, source columns, distance; vectorDdl(): vector(n), HNSW index, the
+                           meta.embedding_set / embedding_enqueue trigger), Preview / Apply (Change Log; the rows queued) / worksheet;
+                           the table's vector columns with progress and Backfill (mode=backfill, all=on)
+    vector-providers.ts    (sprint 136, AP-1) Shared Components → Vector providers (/apps/:id/vector-providers: list, provider form,
+                           test, delete) and Workspace utilities → Vector providers (/vector-providers: pgvector status, Create
+                           extension for administrators, the workspace's providers and vector columns); pgvectorNote()
     data-security.ts       (sprint 119) a table's Security: GET/POST /sql/objects/security?o= (policies, roles × columns, masks), Preview / Apply
     object-actions.ts      (sprint 94) an object's ⋯ menu (objectMenu) in the worksheet and the Object Browser: Quick DDL (objectDdl), Drop with
                            dependents, Add index / trigger / policy as drafts; GET /sql/objects/action, /sql/objects/panel (Open in a panel)
@@ -505,6 +528,10 @@ test/
   fulltext-search.test.ts  (sprint 135) full-text search configurations: stemming, rank order, highlights, websearch syntax, the
                            configuration fallback, did you mean (pg_trgm when it can be installed), the report search on a tsvector
                            column, the Advisor's GIN check, Add full-text search (preview, apply, change log), export/import
+  vector-search.test.ts    (sprint 136) vector providers and their checks, meta.embed, Add vector column (preview, apply, the queue
+                           with the mock's embeddings, a change queued again, Backfill, a failing batch), vector and hybrid search
+                           ("time off for a family move" → Relocation leave; RLS), the Advisor, Retrieve tools on page 49, the
+                           builder pages, export; skips what needs pgvector when it isn't installed
   object-actions.test.ts   (sprint 94) object menus: Quick DDL, Drop with dependents, Add index / trigger / policy, the panel, not-found
   data-modeler.test.ts     (sprint 98) Data Modeler: "hr core" with its FK lines, saved positions, SVG, objects, DDL, dictionary, geometry
   worksheet.test.ts        (sprint 91) the SQL Worksheet: statement at the cursor, Run Script log, plans, notices, history, navigator, Run as
@@ -566,7 +593,9 @@ test/
   find-workspace.test.ts   developers' addresses, builder mail, the workspaces mail, the same answer, limits
   ai-builder.test.ts       App Builder AI: the builder's service, SQL from a question, explain, describe tables, pages with AI
   ai-script-mock.ts        a scripted mock of Claude (SSE, tool_use with a thinking block) and OpenAI (tool calls), reply by reply
-  ai-mock.ts               a local mock of the Claude Messages API (SSE stream) and OpenAI Chat Completions
+  ai-mock.ts               a local mock of the Claude Messages API (SSE stream) and OpenAI Chat Completions; (136) OpenAI's
+                           embeddings (/embeddings, also in ai-script-mock.ts): conceptEmbedding(), eight "topics", the same
+                           as the HR example's hr.policy_embedding
   helpers.ts               a cookie-keeping test browser
   e2e/responsive.test.ts   browser tests at phone/tablet/desktop widths (Playwright)
   e2e/builder-i18n.test.ts (sprint 121) Deutsch on the sign-in page, the status bar's language menu, German screens at 390 px, CSP

package/docs/guide/15-extensions.md

@@ -63,7 +63,7 @@ that includes them.
 | **[pg_cron](https://github.com/citusdata/pg_cron)** | Run SQL on a schedule inside the database (`select cron.schedule('nightly', '0 2 * * *', 'call hr.close_month()')`) | **Automations**, `DBMS_SCHEDULER` |
 | **[pgaudit](https://github.com/pgaudit/pgaudit)** | Statement-level audit logging (reads, writes, DDL, role changes) to the server log, for compliance | Oracle Unified Auditing |
 | **PostGIS** | Geometry and geography types, spatial indexes and functions: the foundation for a map region | **Map region**, Oracle Spatial |
-| **pgvector** | Vector similarity search (embeddings) for semantic search and retrieval-augmented generation | APEX AI (RAG sources), Oracle AI Vector Search |
+| **pgvector** | Vector similarity search (embeddings) for semantic search and retrieval-augmented generation; pgkiln's vector providers, vector and hybrid search configurations and Retrieve tools use it (sprint 136, [chapter 4](04-pages-and-regions.md#vector-search)) | APEX AI (RAG sources), Oracle AI Vector Search |
 | **[plpgsql_check](https://github.com/okbob/plpgsql_check)** | Static analysis of PL/pgSQL: wrong columns, unused variables, missing `RETURN`, hidden casts. Run it on your app's functions in CI | **Advisor** (for code) |
 
 Scheduling example with pg_cron. pg_cron must be in `shared_preload_libraries` (a server setting;

package/examples/hr/README.md

@@ -43,6 +43,7 @@ Then open http://127.0.0.1:3100/a/hr and sign in as `king`, `blake`, `jones`, `a
 | `hr_64_ai_agent.sql` | *HR agent* (page 46): the AI agent `HR_AGENT` (Shared Components → AI Agents) with four tools: `top_earners` (SQL, read-only as `hr_app`), `open_employee` (navigate: a link to the employee form with its checksum, only for users who may open page 3), `give_raise` (the PL/pgSQL function `hr.give_raise`, managers only) and `note` (a JavaScript tool: the custom event `hr_agent_note`). Ask *Who in Sales earns most?* Needs an AI service named `HR_ASSISTANT` (see part 41) |
 | `hr_68_component_details.sql` | *Component details* (page 47): a popup LOV over 6,000 rows that loads more as the dialog scrolls, a wait popup around a two-second process (*Recalculate*) and around an Ajax call (*Check in the background*), and an *Actions* menu whose entries run dynamic actions (event `menu_entry`) |
 | `hr_71_fulltext_search.sql` | Full-text search: `hr.policy` gets a generated `search_vector` column (title weight A, body B, english) with a GIN index, and the search configuration `POLICIES` (search type *fulltext*, *Did you mean* when `pg_trgm` is installed) joins page 42 *Search*: "works home" finds *Working from home*, the matched words highlighted |
+| `hr_72_vector_search.sql` | Search by meaning: `hr.policy` gets *Relocation leave* and a managers-only *Salary bands* with row level security (`audience`); with pgvector, the vector provider `POLICY_EMBEDDINGS` (a stand-in function, `hr.policy_embedding`, eight topics), `hr.policy.embedding vector(8)` with an HNSW index and a trigger, the hybrid search configuration `POLICIES_MEANING` on page 42 (*time off for a family move* finds *Relocation leave*), and *Policy questions* (page 49): the agent `POLICY_AGENT` with the Retrieve tool `policy_search`. Needs an AI service named `HR_ASSISTANT` for page 49 |
 
 The files run in order, each once (recorded in `public.pgkiln_seed`), so new ones can be added
 later. pgkiln's own tests use this application as their fixture (`npm test` installs it first).

package/examples/hr/hr_72_vector_search.sql

@@ -0,0 +1,158 @@
+-- =====================================================================
+-- HR example, part 72: search by meaning (sprint 136, AP-1; migration
+-- 136; docs/guide/04-pages-and-regions.md "Vector search", 03-builder.md
+-- "Vector providers", 20-ai-agents.md)
+--
+-- hr.policy (parts 42 and 71) gets two more policies and an audience:
+-- "Salary bands" is for managers only, and row level security now shows
+-- hr_app only the policies the user may read. Every search below runs as
+-- hr_app, so an employee never finds the managers' policy.
+--
+-- With pgvector installed (the extension is created here when the server
+-- has it and this connection may; otherwise this part only adds the
+-- policies and says so):
+--
+--   - the vector provider POLICY_EMBEDDINGS (Shared Components → Vector
+--     providers) of type function: hr.policy_embedding(text), a tiny
+--     stand-in for an embedding model that maps words to eight topics
+--     (moving house, time off, home working, sickness, pay, requests,
+--     public holidays, anything else). It keeps the example working without
+--     an AI service; for real use, make the provider an AI service with an
+--     embedding model (e.g. OpenAI text-embedding-3-small, 1536 dimensions,
+--     or Ollama's nomic-embed-text, 768) and add the column again with
+--     Table Properties › Add vector column;
+--   - what Table Properties › Add vector column writes: hr.policy.embedding
+--     vector(8), an HNSW index (vector_cosine_ops) and a trigger
+--     (meta.embedding_set) that embeds a policy when its title or body
+--     changes;
+--   - the search configuration POLICIES_MEANING (search type hybrid:
+--     full-text on search_vector and the embedding, merged by reciprocal
+--     rank fusion) joins page 42 "Search": "time off for a family move"
+--     finds "Relocation leave", which uses none of those words;
+--   - page 49 "Policy questions": an AI assistant region with the agent
+--     POLICY_AGENT, whose Retrieve tool policy_search hands the model the
+--     policies that match a question (as hr_app). Like parts 41, 42 and 64
+--     it needs an AI service named HR_ASSISTANT.
+-- =====================================================================
+
+alter table hr.policy add column audience text not null default 'all' check (audience in ('all', 'managers'));
+
+insert into hr.policy (title, body, audience) values
+  ('Relocation leave', 'Employees who relocate to another city for the company get three paid days to settle into the new house, and help with the removal costs.', 'all'),
+  ('Salary bands', 'Managers review the salary bands every spring; a raise above the band needs the director''s approval.', 'managers');
+
+alter table hr.policy enable row level security;
+create policy policy_visible on hr.policy for select
+  using (audience = 'all' or meta.has_role('manager') or meta.has_role('admin'));
+
+-- a stand-in for an embedding model: each word counts for one of eight topics (unknown words a little for the
+-- last), and the vector is normalised, so the cosine of two texts says how much they share topics
+create function hr.policy_embedding(p_text text) returns real[]
+language sql immutable parallel safe set search_path = pg_catalog as $$
+  with w as (select lower(m[1]) as w from regexp_matches(coalesce(p_text, ''), '([[:alpha:]]+)', 'g') m),
+  d as (select case
+                 when w ~ '^(relocat|move|moving|removal|house|settl|city|family)' then 1
+                 when w ~ '^(leave|time|off|holiday|vacation|days|absence)$' then 2
+                 when w ~ '^(home|remote|working|work)$' then 3
+                 when w ~ '^(sick|ill|doctor)' then 4
+                 when w ~ '^(salar|pay|band|raise|wage|scale)' then 5
+                 when w ~ '^(request|approv|manager)' then 6
+                 when w ~ '^(public|closed|office)' then 7
+                 else 8 end as dim,
+               case when w ~ '^(relocat|move|moving|removal|house|settl|city|family|leave|time|off|holiday|vacation|days|absence|home|remote|working|work|sick|ill|doctor|salar|pay|band|raise|wage|scale|request|approv|manager|public|closed|office)'
+                    then 1.0 else 0.05 end as weight
+          from w),
+  v as (select i, coalesce((select sum(weight) from d where d.dim = i), 0) as x from generate_series(1, 8) i),
+  n as (select sqrt(sum(x * x)) as n from v)
+  select array_agg((case when n.n = 0 then (case when i = 8 then 1 else 0 end) else x / n.n end)::real order by i) from v, n
+$$;
+grant execute on function hr.policy_embedding(text) to hr_app;
+
+update meta.app set
+  vector_providers = vector_providers || $j$[
+    {"name": "POLICY_EMBEDDINGS", "type": "function", "function": "hr.policy_embedding", "dimensions": 8,
+     "description": "A stand-in for an embedding model (eight topics); use an AI service for real texts"}
+  ]$j$::jsonb,
+  ai_tools = ai_tools || $j$[
+    {"name": "policy_search", "type": "retrieve", "search_config": "POLICIES_MEANING", "max_rows": 3,
+     "description": "The HR policies that match a question, best first (title and text). Use it for every question about rules, leave, pay or working arrangements."}
+  ]$j$::jsonb,
+  ai_agents = ai_agents || $j$[
+    {"name": "POLICY_AGENT", "description": "Answers questions about the HR policies the user may read",
+     "service": "HR_ASSISTANT", "effort": "low", "tools": ["policy_search"], "max_steps": 3, "max_tokens": 1500,
+     "system": "You answer questions of &APP_USER. about the company's HR policies. Look the policies up with policy_search and answer only from what it returns; say so when no policy covers the question. Name the policy you used. Be brief."}
+  ]$j$::jsonb
+ where alias = 'hr';
+
+-- page 49: questions about the policies, answered through the Retrieve tool
+insert into meta.page (app_id, page_no, name, title, parent_page)
+select id, 49, 'Policy questions', 'Policy questions', 1 from meta.app where alias = 'hr';
+
+insert into meta.region (page_id, seq, title, type, columns, template, source, condition, config)
+select p.id, r.seq, r.title, r.type, r.cols, 'standard', r.source, r.cond, r.config::jsonb
+  from meta.page p join meta.app a on a.id = p.app_id, (values
+  (10, 'Not set up yet', 'static', 12,
+   '<p class="alert alert-info">Policy questions need the pgvector extension in the database and an AI service named <b>HR_ASSISTANT</b> (App Builder → Workspace utilities → AI services, allowed for the HR application).</p>',
+   'not (meta.ai_available(''HR_ASSISTANT'') and exists (select from pg_catalog.pg_extension where extname = ''vector''))', '{}'),
+  (20, 'Ask about the policies', 'ai_assistant', 8, null,
+   'meta.ai_available(''HR_ASSISTANT'') and exists (select from pg_catalog.pg_extension where extname = ''vector'')',
+   $j${"agent": "POLICY_AGENT",
+       "welcome": "Hello! Ask me about the HR policies, e.g. how much time off you get when you move for the company.",
+       "placeholder": "e.g. Do I get time off for a family move?",
+       "max_turns": 20,
+       "error_message": "The policy assistant could not answer just now. Please try again later."}$j$)
+  ) as r (seq, title, type, cols, source, cond, config)
+ where a.alias = 'hr' and p.page_no = 49;
+
+insert into meta.nav_entry (app_id, seq, label, icon, target_page)
+select id, 30, 'Policy questions', 'book', 49 from meta.app where alias = 'hr';
+
+-- with pgvector: the extension (when this connection may create it), the vector column, the search configuration
+-- and the search page
+do $$
+declare
+  v_schema text;
+begin
+  if not exists (select from pg_extension where extname = 'vector') then
+    if exists (select from pg_available_extensions where name = 'vector') and (select rolsuper from pg_roles where rolname = current_user) then
+      create extension vector;
+    else
+      raise notice 'HR part 72: pgvector is not installed: hr.policy gets no vector column (install pgvector, then add one with Table Properties › Add vector column).';
+      return;
+    end if;
+  end if;
+  select n.nspname into v_schema from pg_extension e join pg_namespace n on n.oid = e.extnamespace where e.extname = 'vector';
+  execute format('alter table hr.policy add column embedding %I.vector(8)', v_schema);
+  execute format('create index policy_embedding_idx on hr.policy using hnsw (embedding %I.vector_cosine_ops)', v_schema);
+  execute format($t$create trigger embedding_embed before insert or update of title, body on hr.policy
+                    for each row execute function meta.embedding_set(%L, 'POLICY_EMBEDDINGS', 'embedding', 'id', 'title', 'body')$t$,
+                 (select id from meta.app where alias = 'hr'));
+  -- the policies there are: embedded now (the trigger does it for new and changed ones)
+  execute format($u$update hr.policy set embedding = translate(meta.embed(meta.embedding_text(to_jsonb(policy), '{title,body}'), 'POLICY_EMBEDDINGS', %s)::text, '{}', '[]')::text::%I.vector$u$,
+                 (select id from meta.app where alias = 'hr'), v_schema);
+  insert into meta.search_config (app_id, name, label, seq, source_type, source, search_type, fts_vector, fts_config,
+                                  vector_provider, vector_column, key_column, distance, min_similarity,
+                                  title_column, description_column, icon, max_results)
+  select id, 'POLICIES_MEANING', 'Policies by meaning', 26, 'table', 'hr.policy', 'hybrid', 'search_vector', 'english',
+         'POLICY_EMBEDDINGS', 'embedding', 'id', 'cosine', 0.6,
+         'title', 'body', 'book', 3
+    from meta.app where alias = 'hr';
+  update meta.region r
+     set config = jsonb_set(r.config, '{configs}', (r.config->'configs') || '["POLICIES_MEANING"]'::jsonb)
+    from meta.page p join meta.app a on a.id = p.app_id
+   where r.page_id = p.id and a.alias = 'hr' and p.page_no = 42 and r.type = 'search';
+end $$;
+
+insert into meta.translation (app_id, language, source, target)
+select a.id, 'nl', t.source, t.target
+  from meta.app a, (values
+  ('Policies by meaning', 'Regelingen op betekenis'),
+  ('Policy questions', 'Vragen over regelingen'),
+  ('Ask about the policies', 'Vraag naar de regelingen'),
+  ('Not set up yet', 'Nog niet ingesteld'),
+  ('Hello! Ask me about the HR policies, e.g. how much time off you get when you move for the company.',
+   'Hallo! Vraag me naar de HR-regelingen, bijv. hoeveel vrij je krijgt als je voor het bedrijf verhuist.'),
+  ('e.g. Do I get time off for a family move?', 'bijv. Krijg ik vrij voor een verhuizing met het gezin?')
+  ) as t (source, target)
+ where a.alias = 'hr'
+on conflict do nothing;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgkiln",
-  "version": "0.69.0",
+  "version": "0.70.0",
   "description": "Open source low-code, SQL-driven application builder for PostgreSQL, inspired by Oracle APEX",
   "keywords": [
     "postgresql",

package/public/builder.css

@@ -1597,3 +1597,6 @@ pre.wrap-pre { white-space: pre-wrap; overflow-wrap: anywhere; }
   --font: "Inter", "Segoe UI Variable Text", "Segoe UI", system-ui, -apple-system, "Apple SD Gothic Neo", "Malgun Gothic", "Noto Sans KR", "Noto Sans CJK KR", "Source Han Sans KR", sans-serif; }
 :is(.ide-lang-form, .signin-langs) [lang] { font-family: var(--font); }
 :is(.ide, .ide-login):lang(ko) { word-break: keep-all; overflow-wrap: break-word; }
+
+/* (sprint 136) a button inside an alert (e.g. Add vector column without pgvector) wraps on a phone instead of overflowing */
+.alert .btn { white-space: normal; overflow-wrap: anywhere; max-width: 100%; }

package/src/ai/embeddings.ts

@@ -0,0 +1,197 @@
+import OpenAI from 'openai';
+import { owner } from '../db.ts';
+import { openAiError } from './openai.ts';
+import { baseUrlFor, checkDailyLimit, logUsage, serviceForApp, serviceKey, type CallInfo } from './service.ts';
+import { AiError } from './types.ts';
+
+// (sprint 136, AP-1; APEX: Vector Providers, APEX_AI.GET_VECTOR_EMBEDDINGS) Vector providers turn text into an
+// embedding. They are a JSON list in meta.app (vector_providers, migration 136), exported with the application:
+//
+//  - ai_service: an AI service of the installation (OpenAI, Gemini, or any OpenAI-compatible endpoint such as
+//    Ollama) and an embedding model (text-embedding-3-small, gemini-embedding-001, nomic-embed-text …), called with
+//    the official openai SDK's embeddings API. The key stays in meta.ai_service (encrypted, write-only, never
+//    exported); the application must be allowed to use the service and its daily limits apply; every call is
+//    logged in meta.ai_usage (source "embedding": tokens, model, duration, never the text).
+//  - function: a SQL or PL/pgSQL function (text → vector, real[] or float8[]), called by meta.embed() as the
+//    role that runs the query (security invoker), so its grants apply.
+//
+// The dimensions are part of the definition: every embedding is checked against them, and the builder checks
+// them against the vector column (vector(n)) a search configuration or a vector column helper uses.
+
+export type VectorProviderType = 'ai_service' | 'function';
+export const VECTOR_PROVIDER_TYPES: VectorProviderType[] = ['ai_service', 'function'];
+
+export interface VectorProvider {
+  name: string;
+  description?: string;
+  type: VectorProviderType;
+  /** ai_service: the AI service's name */
+  service?: string;
+  /** ai_service: the embedding model, exactly as the provider names it */
+  model?: string;
+  dimensions: number;
+  /** function: schema.name */
+  function?: string;
+  /** ai_service: texts per request (background embedding; default 64) */
+  batch_size?: number;
+  /** ai_service: requests per minute (background embedding; default 60) */
+  per_minute?: number;
+}
+
+export const PROVIDER_NAME = /^[A-Z][A-Z0-9_]{0,59}$/;
+const SERVICE_NAME = /^[A-Za-z][A-Za-z0-9_]{0,59}$/;
+const MODEL = /^[A-Za-z0-9][A-Za-z0-9._:/@-]{0,199}$/;
+export const FUNCTION_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,62}\.[A-Za-z_][A-Za-z0-9_]{0,62}$/;
+/** pgvector's vector type takes up to 16,000 dimensions (an HNSW index up to 2,000). */
+export const MAX_DIMENSIONS = 16_000;
+export const HNSW_MAX_DIMENSIONS = 2_000;
+export const DEFAULT_BATCH = 64;
+export const DEFAULT_PER_MINUTE = 60;
+/** Characters of one text sent to a provider (longer texts are cut). */
+export const MAX_TEXT_CHARS = 20_000;
+
+const isObj = (v: unknown): v is Record<string, any> => !!v && typeof v === 'object' && !Array.isArray(v);
+const intIn = (v: unknown, min: number, max: number) => Number.isInteger(v) && (v as number) >= min && (v as number) <= max;
+
+/** Problems with one vector provider (builder and runtime). */
+export function vectorProviderProblems(p: unknown): string[] {
+  if (!isObj(p)) return ['A vector provider is an object.'];
+  const what = `Vector provider ${typeof p.name === 'string' ? p.name : '?'}`;
+  const out: string[] = [];
+  if (typeof p.name !== 'string' || !PROVIDER_NAME.test(p.name)) out.push(`${what}: the name (static ID) is upper case letters, digits and _ (e.g. DOC_EMBEDDINGS).`);
+  if (!VECTOR_PROVIDER_TYPES.includes(p.type)) out.push(`${what}: the type is ai_service or function.`);
+  if (p.description !== undefined && p.description !== null && (typeof p.description !== 'string' || p.description.length > 500)) out.push(`${what}: the description is text (at most 500 characters).`);
+  if (!intIn(p.dimensions, 1, MAX_DIMENSIONS)) out.push(`${what}: the dimensions are a whole number from 1 to ${MAX_DIMENSIONS}.`);
+  if (p.type === 'ai_service') {
+    if (typeof p.service !== 'string' || !SERVICE_NAME.test(p.service)) out.push(`${what}: choose an AI service.`);
+    if (typeof p.model !== 'string' || !MODEL.test(p.model)) out.push(`${what}: the embedding model is its name, e.g. text-embedding-3-small or nomic-embed-text.`);
+    if (p.function !== undefined) out.push(`${what}: an AI service provider has no function.`);
+  }
+  if (p.type === 'function') {
+    if (typeof p.function !== 'string' || !FUNCTION_NAME.test(p.function)) out.push(`${what}: the function is schema.name, e.g. sales.embed.`);
+    if (p.service !== undefined || p.model !== undefined) out.push(`${what}: a function provider has no AI service or model.`);
+  }
+  if (p.batch_size !== undefined && !intIn(p.batch_size, 1, 2048)) out.push(`${what}: texts per request 1 to 2048.`);
+  if (p.per_minute !== undefined && !intIn(p.per_minute, 1, 10_000)) out.push(`${what}: requests per minute 1 to 10000.`);
+  return out;
+}
+
+/** Problems with an application's list: each entry, and names used twice. */
+export function vectorProvidersProblems(list: unknown): string[] {
+  if (!Array.isArray(list)) return ['Vector providers are a list.'];
+  const out: string[] = [];
+  const names = new Set<string>();
+  for (const p of list) {
+    out.push(...vectorProviderProblems(p));
+    if (isObj(p) && typeof p.name === 'string') {
+      if (names.has(p.name)) out.push(`Vector provider ${p.name} is defined twice.`);
+      names.add(p.name);
+    }
+  }
+  return out;
+}
+
+/** The application's vector providers (the owner reads them: the builder may have changed them a moment ago). */
+export async function loadVectorProviders(appId: number): Promise<VectorProvider[]> {
+  const r = await owner.one<{ vector_providers: unknown }>('select vector_providers from meta.app where id = $1', [appId]);
+  return Array.isArray(r?.vector_providers) ? (r!.vector_providers as VectorProvider[]) : [];
+}
+
+/** One valid provider of an application by its static ID, or an AiError. */
+export async function vectorProviderFor(appId: number, name: string): Promise<VectorProvider> {
+  const p = (await loadVectorProviders(appId)).find((x) => x.name === String(name ?? '').toUpperCase());
+  if (!p) throw new AiError('config', `There is no vector provider ${String(name ?? '').toUpperCase()} (Shared Components → Vector providers).`);
+  const problems = vectorProviderProblems(p);
+  if (problems.length) throw new AiError('config', problems.join(' '));
+  return p;
+}
+
+/** A vector as pgvector's text input: [0.1,0.2,…] (numbers only). */
+export function vectorLiteral(v: number[]): string {
+  if (!Array.isArray(v) || !v.length || v.some((x) => typeof x !== 'number' || !Number.isFinite(x))) throw new AiError('output', 'The embedding is not a list of numbers.');
+  return `[${v.join(',')}]`;
+}
+
+/** A client, a pool or pgkiln's Db: something that runs a query with parameters. */
+type Queryable = { query: (sql: string, params?: unknown[]) => Promise<{ rows: any[] }> };
+
+export interface EmbedInfo extends Pick<CallInfo, 'appId' | 'pageNo' | 'user' | 'debug'> {
+  appId: number;
+}
+
+/**
+ * Embed texts with a provider: one vector per text, each with the provider's dimensions. A function provider
+ * runs through meta.embed() on `client` (the caller's role and transaction); an AI service is called here.
+ */
+export async function embedTexts(p: VectorProvider, texts: string[], info: EmbedInfo, client?: Queryable): Promise<number[][]> {
+  if (!texts.length) return [];
+  const input = texts.map((t) => String(t ?? '').slice(0, MAX_TEXT_CHARS));
+  if (p.type === 'function') {
+    if (!client) throw new AiError('config', `Vector provider ${p.name}: a function provider needs a database connection.`);
+    const rows = (await client.query('select meta.embed(t, $2, $3) as v from unnest($1::text[]) with ordinality u(t, n) order by n', [input, p.name, info.appId])).rows;
+    return rows.map((r: { v: number[] | null }) => {
+      if (!Array.isArray(r.v)) throw new AiError('output', `Vector provider ${p.name}: the function returned no embedding.`);
+      return r.v.map(Number);
+    });
+  }
+  const { service: s, limits } = await serviceForApp(p.service!, info.appId);
+  if (s.provider === 'anthropic') throw new AiError('config', `AI service ${s.name} is a Claude service: Claude has no embeddings API (use an OpenAI, Gemini or OpenAI-compatible service).`);
+  const call: CallInfo = { ...info, source: 'embedding' };
+  await checkDailyLimit(s, limits, call, p.model!);
+  const client2 = new OpenAI({ apiKey: serviceKey(s), baseURL: baseUrlFor(s) || undefined, timeout: s.timeout_s * 1000, maxRetries: 1 });
+  const t0 = performance.now();
+  info.debug?.(6, `vector provider ${p.name}: ${input.length} text(s) to AI service ${s.name} (${s.provider}, ${p.model})`);
+  let tokens = 0;
+  try {
+    let res: OpenAI.CreateEmbeddingResponse;
+    try {
+      res = await client2.embeddings.create({
+        model: p.model!,
+        input,
+        encoding_format: 'float',
+        // OpenAI's text-embedding-3 models shorten their vectors to the dimensions asked for
+        ...(s.provider === 'openai' && /^text-embedding-3/.test(p.model!) ? { dimensions: p.dimensions } : {}),
+      });
+    } catch (e) {
+      throw openAiError(e);
+    }
+    tokens = res.usage?.prompt_tokens ?? 0;
+    const data = [...(res.data ?? [])].sort((a, b) => a.index - b.index);
+    if (data.length !== input.length) throw new AiError('output', `The AI service sent ${data.length} embeddings for ${input.length} texts.`);
+    const out = data.map((d) => (Array.isArray(d.embedding) ? d.embedding.map(Number) : []));
+    for (const v of out) {
+      if (v.length !== p.dimensions)
+        throw new AiError('output', `Vector provider ${p.name}: the model returned ${v.length} dimensions, the provider says ${p.dimensions} (change the provider's dimensions).`);
+      if (v.some((x) => !Number.isFinite(x))) throw new AiError('output', 'The embedding is not a list of numbers.');
+    }
+    await logUsage(call, { service: s, model: res.model || p.model!, inputTokens: tokens, outputTokens: 0, ms: performance.now() - t0, status: 'ok', message: null });
+    return out;
+  } catch (e) {
+    const err = e instanceof AiError ? e : new AiError('server', 'The embedding request failed.');
+    await logUsage(call, { service: s, model: p.model!, inputTokens: tokens, outputTokens: 0, ms: performance.now() - t0, status: 'error', message: err.kind + (err.status ? ` ${err.status}` : '') });
+    info.debug?.(1, `vector provider ${p.name}: ${err.kind}: ${err.message}`);
+    throw err;
+  }
+}
+
+// ---------------------------------------------------------------- the search text's embedding
+
+/** Search texts embedded recently (per server process, AI service providers only): a search as you type asks again. */
+const recent = new Map<string, { at: number; v: number[] }>();
+const RECENT_MAX = 500;
+const RECENT_MS = 10 * 60_000;
+
+/** The embedding of one search text (AI service providers: kept a few minutes in this process's memory). */
+export async function embedQuery(p: VectorProvider, text: string, info: EmbedInfo, client?: Queryable): Promise<number[]> {
+  if (p.type === 'function') return (await embedTexts(p, [text], info, client))[0];
+  const key = JSON.stringify([info.appId, p.name, p.service, p.model, p.dimensions, text]);
+  const hit = recent.get(key);
+  if (hit && Date.now() - hit.at < RECENT_MS) return hit.v;
+  const [v] = await embedTexts(p, [text], info, client);
+  if (recent.size >= RECENT_MAX) recent.delete(recent.keys().next().value!);
+  recent.set(key, { at: Date.now(), v });
+  return v;
+}
+
+/** Forget the remembered search texts (tests; a provider that changed). */
+export const forgetQueries = () => recent.clear();

package/src/ai/service.ts

@@ -99,7 +99,7 @@ export interface CallInfo {
   appId: number | null;
   pageNo?: number | null;
   user?: string | null;
-  source: 'process' | 'dynamic_action' | 'sql' | 'builder' | 'assistant' | 'nl2ir';
+  source: 'process' | 'dynamic_action' | 'sql' | 'builder' | 'assistant' | 'nl2ir' | 'embedding';
   /** debug messages of the request (level, text) */
   debug?: (level: number, text: string) => void;
 }
@@ -147,6 +147,17 @@ export async function serviceForApp(name: string, appId: number | null) {
   return { service: s, limits };
 }
 
+/** The application's daily request and token limits on a service (logged and refused when reached). */
+export async function checkDailyLimit(s: AiService, limits: { max_requests: number | null; max_tokens: string | null } | null, info: CallInfo, model = s.model) {
+  if (!limits || info.appId === null || (limits.max_requests === null && limits.max_tokens === null)) return;
+  const today = await usageToday(info.appId, s.id);
+  const over = (limits.max_requests !== null && today.requests >= limits.max_requests) || (limits.max_tokens !== null && today.tokens >= Number(limits.max_tokens));
+  if (over) {
+    await logUsage(info, { service: s, model, inputTokens: 0, outputTokens: 0, ms: 0, status: 'limited', message: 'daily limit' });
+    throw new AiError('limit', `This application has reached its daily limit for AI service ${s.name}: try again tomorrow.`);
+  }
+}
+
 /**
  * One AI request through a service: checks, daily limits, the call, the
  * usage log. A structured request returns the parsed JSON in `json`.
@@ -157,14 +168,7 @@ export async function generate(name: string, req: GenerateRequest, info: CallInf
   if (req.prompt.length > MAX_PROMPT_CHARS || (req.system?.length ?? 0) > MAX_SYSTEM_CHARS)
     throw new AiError('config', `The prompt is too long (at most ${MAX_PROMPT_CHARS} characters, the system prompt ${MAX_SYSTEM_CHARS}).`);
   if (!req.prompt.trim()) throw new AiError('config', 'The prompt is empty.');
-  if (limits && info.appId !== null && (limits.max_requests !== null || limits.max_tokens !== null)) {
-    const today = await usageToday(info.appId, s.id);
-    const over = (limits.max_requests !== null && today.requests >= limits.max_requests) || (limits.max_tokens !== null && today.tokens >= Number(limits.max_tokens));
-    if (over) {
-      await logUsage(info, { service: s, model: s.model, inputTokens: 0, outputTokens: 0, ms: 0, status: 'limited', message: 'daily limit' });
-      throw new AiError('limit', `This application has reached its daily limit for AI service ${s.name}: try again tomorrow.`);
-    }
-  }
+  await checkDailyLimit(s, limits, info);
   const provider = providerFor(s);
   const t0 = performance.now();
   info.debug?.(6, `AI service ${s.name} (${s.provider}, ${s.model})${req.schema ? ', structured output' : ''}`);

package/src/app.ts

@@ -26,6 +26,7 @@ import { diagnosticsRoutes } from './builder/diagnostics.ts';
 import { ldapRoutes } from './builder/ldap.ts';
 import { aiRoutes } from './builder/ai.ts';
 import { aiAgentRoutes } from './builder/ai-agents.ts';
+import { vectorProviderRoutes } from './builder/vector-providers.ts';
 import { mailRoutes } from './builder/mail.ts';
 import { backupRoutes } from './builder/backups.ts';
 import { availabilityRoutes } from './builder/availability.ts';
@@ -236,6 +237,8 @@ export async function buildApp(opts: { logger?: boolean } = {}) {
   await app.register(ldapRoutes);
   await app.register(aiRoutes);
   await app.register(aiAgentRoutes);
+  // (sprint 136, AP-1) vector providers: Shared Components and Workspace utilities
+  await app.register(vectorProviderRoutes);
   await app.register(mailRoutes);
   await app.register(backupRoutes);
   await app.register(availabilityRoutes);

package/src/builder/advisor.ts

@@ -13,6 +13,7 @@ import { processProblems } from '../runtime/processes.ts';
 import { urlConfigProblem, urlTarget } from '../runtime/url-region.ts';
 import { configColumns, searchConfigProblems, textSearchConfig, tsvectorSql } from '../runtime/search.ts';
 import { COMPONENTS } from './components.ts';
+import { DISTANCES, PGVECTOR_MISSING, vectorColumnDims, vectorSchema, type Distance } from '../vector.ts';
 import { appEntries, type Entry } from './search.ts';
 import { appHeader, BASE, developer, region, send, shell, type Req } from './ui.ts';
 
@@ -242,7 +243,10 @@ export async function advise(appId: number, tx?: pg.ClientBase, opts: { db?: Db
       }
       let cols = configColumns(row).map((x) => `t.${pg.escapeIdentifier(x)}`).join(', ') || '*';
       // (135) a full-text configuration: its tsvector matched with its text search configuration
-      const fulltext = row.search_type === 'fulltext';
+      const fulltext = row.search_type === 'fulltext' || row.search_type === 'hybrid';
+      // (136) a vector or hybrid configuration also reads its vector (and key) column
+      const vectorType = row.search_type === 'vector' || row.search_type === 'hybrid';
+      if (vectorType) cols = [cols === '*' ? 't.*' : cols, ...[row.vector_column, row.key_column].filter(Boolean).map((x: string) => `t.${pg.escapeIdentifier(x)}`)].join(', ');
       if (fulltext) {
         const cfg = await textSearchConfig(c, row.fts_config, app.language);
         if (row.fts_config && cfg !== row.fts_config)
@@ -281,6 +285,42 @@ export async function advise(appId: number, tx?: pg.ClientBase, opts: { db?: Db
           });
       }
     }
+    // (136) vector and hybrid configurations: pgvector, the provider, the column's dimensions and its index
+    for (const { kind, row } of all.filter((x) => x.kind === 'search_config' && (x.row.search_type === 'vector' || x.row.search_type === 'hybrid') && !searchConfigProblems(x.row).length)) {
+      const entry = byKey.get(`${kind}-${row.id}`) ?? null;
+      const schema = await vectorSchema(c);
+      if (!schema) {
+        findings.push({ severity: 'error', entry, field: 'Search type', message: PGVECTOR_MISSING });
+        continue;
+      }
+      const provider = (Array.isArray(app.vector_providers) ? app.vector_providers : []).find((p: { name: string }) => p.name === row.vector_provider);
+      if (!provider) findings.push({ severity: 'error', entry, field: 'Vector provider', message: `There is no vector provider ${row.vector_provider} (Shared Components → Vector providers).` });
+      if (row.source_type !== 'table') continue;
+      await c.query('savepoint advisor_vec');
+      const info = await (async () => {
+        const dims = await vectorColumnDims(c, row.source.trim(), row.vector_column);
+        const ix = (await c.query<{ ok: boolean; ops: string | null }>(
+          `select exists (select from pg_catalog.pg_index i join pg_catalog.pg_class ic on ic.oid = i.indexrelid join pg_catalog.pg_am am on am.oid = ic.relam
+                           where i.indrelid = $1::regclass and am.amname in ('hnsw', 'ivfflat')
+                             and (select a.attnum from pg_catalog.pg_attribute a where a.attrelid = $1::regclass and a.attname = $2) = any (i.indkey::int2[])) as ok,
+                  (select string_agg(o.opcname, ',') from pg_catalog.pg_index i join pg_catalog.pg_opclass o on o.oid = any (i.indclass::oid[])
+                    where i.indrelid = $1::regclass and (select a.attnum from pg_catalog.pg_attribute a where a.attrelid = $1::regclass and a.attname = $2) = any (i.indkey::int2[])) as ops`,
+          [row.source.trim(), row.vector_column])).rows[0];
+        return { dims, ix };
+      })().catch(async () => {
+        await c.query('rollback to savepoint advisor_vec');
+        return null;
+      });
+      if (!info) continue;
+      if (info.dims === undefined) findings.push({ severity: 'error', entry, field: 'Vector column', message: `${row.source.trim()} has no column ${row.vector_column}.` });
+      else if (info.dims === null) findings.push({ severity: 'error', entry, field: 'Vector column', message: `${row.source.trim()}.${row.vector_column} is not a vector(n) column.` });
+      else if (provider && info.dims !== provider.dimensions)
+        findings.push({ severity: 'error', entry, field: 'Vector column', message: `${row.source.trim()}.${row.vector_column} is vector(${info.dims}), vector provider ${provider.name} gives ${provider.dimensions} dimensions.` });
+      if (info.dims && !info.ix?.ok)
+        findings.push({ severity: 'warning', entry, field: 'Vector column', message: `${row.source.trim()}.${row.vector_column} has no HNSW index: every search reads the whole table (SQL Workshop › Table Properties › Add vector column adds one).` });
+      else if (info.dims && info.ix?.ops && !info.ix.ops.split(',').includes(DISTANCES[(row.distance ?? 'cosine') as Distance].opclass))
+        findings.push({ severity: 'warning', entry, field: 'Distance', message: `The index on ${row.vector_column} is for ${info.ix.ops}, not ${DISTANCES[(row.distance ?? 'cosine') as Distance].opclass}: the ${row.distance ?? 'cosine'} search can't use it.` });
+    }
     // the search regions name existing configurations
     for (const { kind, row } of all.filter((x) => x.kind === 'region' && x.row.type === 'search')) {
       const names: unknown[] = Array.isArray(row.config?.configs) ? row.config.configs : [];