graphile-llm 0.11.5 → 0.12.1

package/metering.js

@@ -23,85 +23,43 @@ exports.QuotaExceededError = void 0;
 exports.logInferenceUsage = logInferenceUsage;
 exports.meteredEmbed = meteredEmbed;
 exports.meteredChat = meteredChat;
-// ─── Billing SQL Helpers ────────────────────────────────────────────────────
+const express_context_1 = require("@constructive-io/express-context");
+// ─── Billing Client Adapter ─────────────────────────────────────────────────
 /**
- * Check if the entity has sufficient quota for the requested amount.
- * Returns true if the call is allowed, false if quota is exceeded.
- *
- * Gracefully returns true if the billing function doesn't exist or errors —
- * metering is opt-in, so missing infrastructure means "allow".
- */
-async function checkQuota(pgClient, billing, entityId, meterSlug, amount) {
-    try {
-        const sql = `SELECT "${billing.privateSchema}"."${billing.checkBillingQuotaFunction}"($1, $2::uuid, $3) AS allowed`;
-        const result = await pgClient.query(sql, [meterSlug, entityId, amount]);
-        return result.rows[0]?.allowed !== false;
-    }
-    catch (e) {
-        const message = e instanceof Error ? e.message : String(e);
-        console.warn(`[graphile-llm] check_billing_quota failed (allowing): ${message}`);
-        return true;
-    }
-}
-/**
- * Record usage after a successful call.
- * Gracefully skips if the billing function doesn't exist or errors.
+ * Create a BillingClient from a MeteringContext by adapting Graphile's 2-arg
+ * withPgClient(pgSettings, fn) to the express-context 1-arg withPgClient(fn).
  */
-async function recordUsage(pgClient, billing, entityId, meterSlug, amount, metadata) {
-    try {
-        const sql = `SELECT "${billing.privateSchema}"."${billing.recordUsageFunction}"($1, $2::uuid, $3, $4::jsonb)`;
-        await pgClient.query(sql, [meterSlug, entityId, amount, JSON.stringify(metadata)]);
-    }
-    catch (e) {
-        const message = e instanceof Error ? e.message : String(e);
-        console.warn(`[graphile-llm] record_usage failed (non-fatal): ${message}`);
-    }
+function billingClientFromCtx(ctx) {
+    const adaptedWithPgClient = (fn) => ctx.withPgClient(ctx.pgSettings, fn);
+    return (0, express_context_1.createBillingClient)(adaptedWithPgClient, ctx.entityId, ctx.billing, ctx.inferenceLog);
 }
 /**
  * Write a row to the usage_log_inference table.
- * Gracefully skips if the inference_log_module is not provisioned.
- *
- * TODO: Also write to child (generated) database when dual-write is needed.
+ * Delegates to the shared BillingClient from express-context.
  */
 async function logInferenceUsage(ctx, entry) {
-    if (!ctx.inferenceLog)
-        return;
-    const { schema, tableName } = ctx.inferenceLog;
-    const sql = `INSERT INTO "${schema}"."${tableName}" (
-    database_id, entity_id, actor_id,
-    model, provider, service, operation,
-    input_tokens, output_tokens, total_tokens,
-    cache_read_tokens, cache_write_tokens,
-    latency_ms, rag_enabled, chunks_retrieved,
-    embedding_model, embedding_latency_ms,
-    status, error_type, raw_usage
-  ) VALUES (
-    $1, $2, $3,
-    $4, $5, $6, $7,
-    $8, $9, $10,
-    $11, $12,
-    $13, $14, $15,
-    $16, $17,
-    $18, $19, $20
-  )`;
-    try {
-        await ctx.withPgClient(ctx.pgSettings, async (pgClient) => {
-            await pgClient.query(sql, [
-                entry.databaseId, entry.entityId, entry.actorId,
-                entry.model, entry.provider, entry.service, entry.operation,
-                entry.inputTokens, entry.outputTokens, entry.totalTokens,
-                entry.cacheReadTokens, entry.cacheWriteTokens,
-                entry.latencyMs, entry.ragEnabled, entry.chunksRetrieved,
-                entry.embeddingModel, entry.embeddingLatencyMs,
-                entry.status, entry.errorType,
-                entry.rawUsage ? JSON.stringify(entry.rawUsage) : null
-            ]);
-        });
-    }
-    catch (e) {
-        const message = e instanceof Error ? e.message : String(e);
-        console.warn(`[graphile-llm] inference log INSERT failed (non-fatal): ${message}`);
-    }
+    const client = billingClientFromCtx(ctx);
+    return client.logInference({
+        entityId: entry.entityId,
+        actorId: entry.actorId,
+        model: entry.model,
+        provider: entry.provider,
+        service: entry.service,
+        operation: entry.operation,
+        inputTokens: entry.inputTokens,
+        outputTokens: entry.outputTokens,
+        totalTokens: entry.totalTokens,
+        latencyMs: entry.latencyMs,
+        status: entry.status,
+        cacheReadTokens: entry.cacheReadTokens,
+        cacheWriteTokens: entry.cacheWriteTokens,
+        ragEnabled: entry.ragEnabled,
+        chunksRetrieved: entry.chunksRetrieved,
+        embeddingModel: entry.embeddingModel,
+        embeddingLatencyMs: entry.embeddingLatencyMs,
+        errorType: entry.errorType,
+        rawUsage: entry.rawUsage
+    });
 }
 // ─── Metered Embedder ───────────────────────────────────────────────────────
 /**
@@ -142,15 +100,8 @@ async function meteredEmbed(embedder, text, ctx, options = {}) {
         };
     }
     // Pre-check: can this entity afford this call?
-    let allowed = true;
-    try {
-        await ctx.withPgClient(ctx.pgSettings, async (pgClient) => {
-            allowed = await checkQuota(pgClient, ctx.billing, ctx.entityId, meterSlug, 1);
-        });
-    }
-    catch {
-        allowed = true;
-    }
+    const billingClient = billingClientFromCtx(ctx);
+    const allowed = await billingClient.checkQuota(meterSlug);
     if (!allowed) {
         logInferenceUsage(ctx, {
             databaseId: ctx.databaseId,
@@ -184,14 +135,12 @@ async function meteredEmbed(embedder, text, ctx, options = {}) {
     // Execute embedding — real token count from provider via EmbeddingResult
     const { embedding, promptTokens } = await embedder(text);
     const latencyMs = Date.now() - startTime;
-    ctx.withPgClient(ctx.pgSettings, async (pgClient) => {
-        await recordUsage(pgClient, ctx.billing, ctx.entityId, meterSlug, promptTokens, {
-            request_id: ctx.requestId,
-            input_chars: text.length,
-            prompt_tokens: promptTokens,
-            dims: embedding.length,
-            latency_ms: latencyMs
-        });
+    billingClient.recordUsage(meterSlug, promptTokens, {
+        request_id: ctx.requestId,
+        input_chars: text.length,
+        prompt_tokens: promptTokens,
+        dims: embedding.length,
+        latency_ms: latencyMs
     }).catch(() => { });
     // Log to inference usage table
     logInferenceUsage(ctx, {
@@ -258,15 +207,8 @@ async function meteredChat(chat, messages, ctx, chatOptions, meteringOptions = {
         };
     }
     // Pre-check: can this entity afford this call?
-    let allowed = true;
-    try {
-        await ctx.withPgClient(ctx.pgSettings, async (pgClient) => {
-            allowed = await checkQuota(pgClient, ctx.billing, ctx.entityId, meterSlug, 1);
-        });
-    }
-    catch {
-        allowed = true;
-    }
+    const billingClient = billingClientFromCtx(ctx);
+    const allowed = await billingClient.checkQuota(meterSlug);
     if (!allowed) {
         const estimatedInputTokens = Math.ceil(messages.reduce((sum, m) => sum + m.content.length, 0) / 4);
         logInferenceUsage(ctx, {
@@ -302,16 +244,14 @@ async function meteredChat(chat, messages, ctx, chatOptions, meteringOptions = {
     const chatResult = await chat(messages, chatOptions);
     const latencyMs = Date.now() - startTime;
     const usage = chatResult.usage;
-    ctx.withPgClient(ctx.pgSettings, async (pgClient) => {
-        await recordUsage(pgClient, ctx.billing, ctx.entityId, meterSlug, usage.totalTokens, {
-            request_id: ctx.requestId,
-            input_tokens: usage.input,
-            output_tokens: usage.output,
-            cache_read_tokens: usage.cacheRead,
-            cache_write_tokens: usage.cacheWrite,
-            messages_count: messages.length,
-            latency_ms: latencyMs
-        });
+    billingClient.recordUsage(meterSlug, usage.totalTokens, {
+        request_id: ctx.requestId,
+        input_tokens: usage.input,
+        output_tokens: usage.output,
+        cache_read_tokens: usage.cacheRead,
+        cache_write_tokens: usage.cacheWrite,
+        messages_count: messages.length,
+        latency_ms: latencyMs
     }).catch(() => { });
     // Log to inference usage table with real provider token counts
     logInferenceUsage(ctx, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphile-llm",
-  "version": "0.11.5",
+  "version": "0.12.1",
   "description": "LLM integration plugin for PostGraphile v5 — server-side text-to-vector embedding and text companion fields for pgvector columns",
   "author": "Constructive <developers@constructive.io>",
   "homepage": "https://github.com/constructive-io/constructive",
@@ -29,8 +29,10 @@
     "url": "https://github.com/constructive-io/constructive/issues"
   },
   "dependencies": {
-    "@agentic-kit/ollama": "^2.0.0",
-    "graphile-cache": "^3.13.0"
+    "@agentic-kit/ollama": "2.1.0",
+    "@constructive-io/express-context": "^0.6.0",
+    "@constructive-io/llm-env": "^0.1.1",
+    "graphile-cache": "^3.13.1"
   },
   "peerDependencies": {
     "@dataplan/pg": "1.0.3",
@@ -55,7 +57,7 @@
   "devDependencies": {
     "@types/node": "^22.19.11",
     "graphile-connection-filter": "^1.12.4",
-    "graphile-search": "^1.16.0",
+    "graphile-search": "^1.17.0",
     "graphile-test": "^4.17.4",
     "makage": "^0.3.0",
     "pgsql-test": "^4.16.4"
@@ -73,5 +75,5 @@
     "ollama",
     "openai"
   ],
-  "gitHead": "2558a0cdb58c815933af8bfe6769cd59014c77cf"
+  "gitHead": "fc6f9780ea1cab2c9344c2e392649ae644e84849"
 }

package/plugins/llm-module-plugin.d.ts

@@ -11,10 +11,15 @@
  * to consume.
  *
  * Resolution order for the embedder:
- *   1. `llm_module` from api_modules (per-database, loaded at schema build time)
- *   2. `defaultEmbedder` from preset options (dev/testing fallback)
- *   3. Environment variables (EMBEDDER_PROVIDER, EMBEDDER_MODEL, EMBEDDER_BASE_URL)
- *   4. null — LLM features are disabled
+ *   1. `defaultEmbedder` from preset options (build-time)
+ *   2. Environment variables (EMBEDDER_PROVIDER, EMBEDDER_MODEL, EMBEDDER_BASE_URL)
+ *   3. null — LLM features are disabled
+ *
+ * Per-database model/baseUrl overrides (from `llm_module` via `ctx.useLlm()`)
+ * are applied at request time via `llmConfigStore` (AsyncLocalStorage) in
+ * the text-search-plugin resolver wrapper. The same embedder function — and
+ * its metering wrapper — handles every request; only the model name and
+ * base URL parameters change per-tenant.
  *
  * This plugin is intentionally pure — no billing or metering logic.
  * The optional LlmMeteringPlugin wraps the embedder with billing integration

package/plugins/llm-module-plugin.js

@@ -12,10 +12,15 @@
  * to consume.
  *
  * Resolution order for the embedder:
- *   1. `llm_module` from api_modules (per-database, loaded at schema build time)
- *   2. `defaultEmbedder` from preset options (dev/testing fallback)
- *   3. Environment variables (EMBEDDER_PROVIDER, EMBEDDER_MODEL, EMBEDDER_BASE_URL)
- *   4. null — LLM features are disabled
+ *   1. `defaultEmbedder` from preset options (build-time)
+ *   2. Environment variables (EMBEDDER_PROVIDER, EMBEDDER_MODEL, EMBEDDER_BASE_URL)
+ *   3. null — LLM features are disabled
+ *
+ * Per-database model/baseUrl overrides (from `llm_module` via `ctx.useLlm()`)
+ * are applied at request time via `llmConfigStore` (AsyncLocalStorage) in
+ * the text-search-plugin resolver wrapper. The same embedder function — and
+ * its metering wrapper — handles every request; only the model name and
+ * base URL parameters change per-tenant.
  *
  * This plugin is intentionally pure — no billing or metering logic.
  * The optional LlmMeteringPlugin wraps the embedder with billing integration

package/plugins/rag-plugin.js

@@ -73,18 +73,18 @@ function parseHasChunksTag(raw, codec) {
  */
 function discoverChunkTables(build) {
     const chunkTables = [];
-    const pgRegistry = build.pgRegistry;
+    const pgRegistry = build.input?.pgRegistry ?? build.pgRegistry;
     if (!pgRegistry)
         return chunkTables;
     // Scan all codecs for @hasChunks smart tag
-    for (const source of Object.values(pgRegistry.pgResources || {})) {
-        const codec = source?.codec;
-        if (!codec?.attributes)
+    for (const codec of Object.values(pgRegistry.pgCodecs || {})) {
+        const c = codec;
+        if (!c?.attributes)
             continue;
-        const tags = codec.extensions?.tags;
+        const tags = c.extensions?.tags;
         if (!tags?.hasChunks)
             continue;
-        const info = parseHasChunksTag(tags.hasChunks, codec);
+        const info = parseHasChunksTag(tags.hasChunks, c);
         if (info) {
             chunkTables.push(info);
         }
@@ -138,18 +138,6 @@ function createLlmRagPlugin(ragDefaults = {}) {
     let embedder = null;
     let chatCompleter = null;
     const schemaExtension = (0, graphile_utils_1.extendSchema)((build) => {
-        // Discover chunk-aware tables from pgRegistry
-        chunkTables = discoverChunkTables(build);
-        embedder = build.llmEmbedder || null;
-        chatCompleter = build.llmChatCompleter || null;
-        if (chunkTables.length > 0) {
-            console.log(`[graphile-llm] RAG plugin discovered ${chunkTables.length} chunk-aware table(s): ` +
-                chunkTables.map((t) => t.parentCodecName).join(', '));
-        }
-        else {
-            console.log('[graphile-llm] RAG plugin found no @hasChunks tables. ' +
-                'ragQuery will still work if chunks tables are queried directly.');
-        }
         return {
             typeDefs: (0, graphile_utils_1.gql) `
         """A source chunk retrieved during RAG context assembly."""
@@ -328,8 +316,8 @@ function createLlmRagPlugin(ragDefaults = {}) {
                 }
             }
         };
-    });
-    return {
+    }, 'LlmRagPlugin');
+    const plugin = {
         ...schemaExtension,
         name: 'LlmRagPlugin',
         version: '0.1.0',
@@ -341,4 +329,26 @@ function createLlmRagPlugin(ragDefaults = {}) {
             'VectorCodecPlugin'
         ]
     };
+    // Wrap the build hook to also discover chunk tables.
+    // The build hook runs after all init hooks (including smart tag injection),
+    // so @hasChunks tags are guaranteed to be visible.
+    const existingBuildHook = plugin.schema.hooks.build;
+    plugin.schema.hooks.build = (build) => {
+        // Run extendSchema's build hook first (sets up graphql ref)
+        build = existingBuildHook(build) || build;
+        // Discover chunk tables — runs during build phase when all smart tags are applied
+        chunkTables = discoverChunkTables(build);
+        embedder = build.llmEmbedder || null;
+        chatCompleter = build.llmChatCompleter || null;
+        if (chunkTables.length > 0) {
+            console.log(`[graphile-llm] RAG plugin discovered ${chunkTables.length} chunk-aware table(s): ` +
+                chunkTables.map((t) => t.parentCodecName).join(', '));
+        }
+        else {
+            console.log('[graphile-llm] RAG plugin found no @hasChunks tables. ' +
+                'ragQuery will still work if chunks tables are queried directly.');
+        }
+        return build;
+    };
+    return plugin;
 }

package/plugins/text-mutation-plugin.js

@@ -86,8 +86,21 @@ function createLlmTextMutationPlugin() {
                  */
                 GraphQLInputObjectType_fields(fields, build, context) {
                     const { scope: { isPgPatch, isPgBaseInput, isMutationInput, pgCodec } } = context;
-                    // Only intercept create/update input types for table rows
-                    if (!pgCodec?.attributes || (!isPgPatch && !isPgBaseInput && !isMutationInput)) {
+                    // Only intercept mutation-related input types for table rows.
+                    // PostGraphile v5 sets isPgPatch on update types, isPgBaseInput on
+                    // create base types. For tables with `serial PRIMARY KEY`, the create
+                    // input type (e.g. ArticleInput) has pgCodec set but none of the
+                    // explicit mutation scope flags — detect via type name convention.
+                    if (!pgCodec?.attributes)
+                        return fields;
+                    const typeName = context.Self.name;
+                    const hasExplicitMutationScope = isPgPatch || isPgBaseInput || isMutationInput;
+                    const looksLikeMutationInput = typeName.endsWith('Input') || typeName.endsWith('Patch');
+                    const isFilterOrCondition = typeName.endsWith('FilterInput')
+                        || typeName.endsWith('Filter')
+                        || typeName.endsWith('Condition')
+                        || typeName === 'VectorNearbyInput';
+                    if (!hasExplicitMutationScope && (!looksLikeMutationInput || isFilterOrCondition)) {
                         return fields;
                     }
                     const { graphql: { GraphQLString } } = build;

package/plugins/text-search-plugin.d.ts

@@ -24,8 +24,10 @@
  * (so the schema is stable) but will return a clear error at execution time.
  *
  * If the embedder returns null (e.g. quota exceeded when the metering
- * plugin is loaded), the text field is silently removed — the query
- * continues with text-only search as a graceful fallback.
+ * plugin is loaded), behavior depends on `onQuotaExceeded`:
+ * - `'degrade'` (default): silently removes the text field and continues
+ *   with text-only search as a graceful fallback.
+ * - `'throw'`: always throws an error, even if text adapters could handle it.
  */
 import type { GraphileConfig } from 'graphile-config';
 declare global {
@@ -35,6 +37,14 @@ declare global {
         }
     }
 }
+/**
+ * Recursively walk a `where` argument object and embed any VectorNearbyInput
+ * values that have `text` instead of `vector`.
+ *
+ * If the embedder returns null (e.g. quota exceeded), the text field is
+ * removed so the pgvector filter is skipped — graceful text-only fallback.
+ */
+export declare function embedTextInWhere(obj: any, embedder: (text: string) => Promise<number[] | null>, hasTextAdapters: boolean, onQuotaExceeded?: 'degrade' | 'throw'): Promise<void>;
 /**
  * Creates the LlmTextSearchPlugin.
  *
@@ -42,4 +52,6 @@ declare global {
  * existing `vector` field. When a user provides `text`, the plugin's
  * resolver wrapper embeds it before passing to pgvector.
  */
-export declare function createLlmTextSearchPlugin(): GraphileConfig.Plugin;
+export declare function createLlmTextSearchPlugin(options?: {
+    onQuotaExceeded?: 'degrade' | 'throw';
+}): GraphileConfig.Plugin;

package/plugins/text-search-plugin.js

@@ -25,11 +25,15 @@
  * (so the schema is stable) but will return a clear error at execution time.
  *
  * If the embedder returns null (e.g. quota exceeded when the metering
- * plugin is loaded), the text field is silently removed — the query
- * continues with text-only search as a graceful fallback.
+ * plugin is loaded), behavior depends on `onQuotaExceeded`:
+ * - `'degrade'` (default): silently removes the text field and continues
+ *   with text-only search as a graceful fallback.
+ * - `'throw'`: always throws an error, even if text adapters could handle it.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.embedTextInWhere = embedTextInWhere;
 exports.createLlmTextSearchPlugin = createLlmTextSearchPlugin;
+const embedder_1 = require("../embedder");
 /**
  * Check if a codec has any pgvector `vector` columns.
  */
@@ -49,12 +53,34 @@ function hasVectorColumns(pgCodec) {
  * If the embedder returns null (e.g. quota exceeded), the text field is
  * removed so the pgvector filter is skipped — graceful text-only fallback.
  */
-async function embedTextInWhere(obj, embedder) {
+async function embedTextInWhere(obj, embedder, hasTextAdapters, onQuotaExceeded = 'degrade') {
     if (!obj || typeof obj !== 'object')
         return;
     const pending = [];
     for (const key of Object.keys(obj)) {
         const value = obj[key];
+        // Handle unifiedSearch: embed text and transform to { __text, __vector }
+        if (key === 'unifiedSearch' && typeof value === 'string' && value.trim().length > 0) {
+            pending.push((async () => {
+                const startTime = Date.now();
+                const vector = await embedder(value);
+                const latencyMs = Date.now() - startTime;
+                if (vector === null) {
+                    if (onQuotaExceeded === 'throw' || !hasTextAdapters) {
+                        throw new Error('unifiedSearch: embedding failed (quota exceeded or provider unavailable). ' +
+                            (!hasTextAdapters
+                                ? 'No text search adapters available for fallback. '
+                                : 'onQuotaExceeded is set to \'throw\'. ') +
+                            'Upgrade your plan or adjust onQuotaExceeded to \'degrade\' for text-only fallback.');
+                    }
+                    return;
+                }
+                console.log(`[graphile-llm] unifiedSearch embed: dims=${vector.length}, latency=${latencyMs}ms`);
+                // Transform to object shape that graphile-search understands
+                obj[key] = { __text: value, __vector: vector };
+            })());
+            continue;
+        }
         if (!value || typeof value !== 'object')
             continue;
         // Detect VectorNearbyInput shape: has `text` and no `vector`
@@ -64,7 +90,10 @@ async function embedTextInWhere(obj, embedder) {
                 const vector = await embedder(value.text);
                 const latencyMs = Date.now() - startTime;
                 if (vector === null) {
-                    // Embedder returned null (e.g. quota exceeded) — skip vector search
+                    if (onQuotaExceeded === 'throw') {
+                        throw new Error('VectorNearbyInput: embedding failed (quota exceeded or provider unavailable). ' +
+                            'Upgrade your plan or adjust onQuotaExceeded to \'degrade\' for graceful fallback.');
+                    }
                     delete value.text;
                     return;
                 }
@@ -77,12 +106,12 @@ async function embedTextInWhere(obj, embedder) {
         }
         // Recurse into nested filter objects (AND, OR, etc.)
         if (!Array.isArray(value)) {
-            pending.push(embedTextInWhere(value, embedder));
+            pending.push(embedTextInWhere(value, embedder, hasTextAdapters, onQuotaExceeded));
         }
         else {
             // Handle arrays (e.g. AND: [...], OR: [...])
             for (const item of value) {
-                pending.push(embedTextInWhere(item, embedder));
+                pending.push(embedTextInWhere(item, embedder, hasTextAdapters, onQuotaExceeded));
             }
         }
     }
@@ -90,6 +119,32 @@ async function embedTextInWhere(obj, embedder) {
         await Promise.all(pending);
     }
 }
+/**
+ * Resolve per-DB LLM config overrides from express-context.
+ * Returns an LlmConfigOverrides object if per-DB config is available,
+ * or null to use defaults. These overrides are string parameters only
+ * (model name, base URL) — the embedder function and its metering
+ * wrapper stay the same.
+ */
+async function resolveConfigOverrides(graphqlContext) {
+    const ctx = graphqlContext?.constructive;
+    if (!ctx?.useLlm)
+        return null;
+    try {
+        const llm = await ctx.useLlm();
+        if (!llm?.embeddingModel)
+            return null;
+        return {
+            embeddingModel: llm.embeddingModel,
+            embeddingBaseUrl: llm.embeddingBaseUrl,
+            chatModel: llm.chatModel ?? undefined,
+            chatBaseUrl: llm.chatBaseUrl ?? undefined,
+        };
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Creates the LlmTextSearchPlugin.
  *
@@ -97,7 +152,8 @@ async function embedTextInWhere(obj, embedder) {
  * existing `vector` field. When a user provides `text`, the plugin's
  * resolver wrapper embeds it before passing to pgvector.
  */
-function createLlmTextSearchPlugin() {
+function createLlmTextSearchPlugin(options = {}) {
+    const { onQuotaExceeded = 'degrade' } = options;
     return {
         name: 'LlmTextSearchPlugin',
         version: '0.2.0',
@@ -116,8 +172,8 @@ function createLlmTextSearchPlugin() {
                  * The field is optional — clients provide either `text` or `vector`.
                  */
                 GraphQLInputObjectType_fields(fields, build, context) {
-                    const { scope: { inputObjectTypeName } } = context;
-                    if (inputObjectTypeName !== 'VectorNearbyInput') {
+                    const typeName = context.Self.name;
+                    if (typeName !== 'VectorNearbyInput') {
                         return fields;
                     }
                     const { graphql: { GraphQLString } } = build;
@@ -132,35 +188,51 @@ function createLlmTextSearchPlugin() {
                 },
                 /**
                  * Wrap connection query resolvers to intercept `where` arguments that
-                 * contain VectorNearbyInput with `text`, embed the text, and replace
-                 * it with the resulting vector before the plan executes.
+                 * contain VectorNearbyInput with `text` or `unifiedSearch` with text,
+                 * embed the text, and inject the resulting vector before the plan executes.
+                 *
+                 * For tables with vector columns: embeds VectorNearbyInput.text → vector
+                 * For ALL tables with unifiedSearch: embeds unifiedSearch text → { __text, __vector }
                  *
                  * Uses the same v4-style resolver wrapping pattern as graphile-upload-plugin
                  * and graphile-bucket-provisioner-plugin.
                  */
                 GraphQLObjectType_fields_field(field, build, context) {
                     const { scope: { isRootQuery, pgCodec } } = context;
-                    // Only wrap root query fields on tables with vector columns
-                    if (!isRootQuery || !pgCodec || !hasVectorColumns(pgCodec)) {
+                    if (!isRootQuery || !pgCodec)
+                        return field;
+                    // Wrap if the table has vector columns OR has any searchable columns
+                    // (for unifiedSearch embedding support)
+                    const hasVector = hasVectorColumns(pgCodec);
+                    const hasSearchableColumns = pgCodec.attributes && Object.values(pgCodec.attributes).some((attr) => attr.codec?.name === 'tsvector' || attr.codec?.name === 'vector');
+                    if (!hasVector && !hasSearchableColumns)
                         return field;
-                    }
                     const embedder = build.llmEmbedder;
                     if (!embedder)
                         return field;
+                    // Determine if this table has text-based search adapters for fallback logic
+                    const hasTextAdapters = pgCodec.attributes && Object.values(pgCodec.attributes).some((attr) => attr.codec?.name === 'tsvector');
                     const defaultResolver = (obj) => obj[context.scope.fieldName];
                     const { resolve: oldResolve = defaultResolver, ...rest } = field;
                     return {
                         ...rest,
                         async resolve(source, args, graphqlContext, info) {
-                            // If the query has a `where` argument, check for text fields
-                            if (args?.where) {
-                                await embedTextInWhere(args.where, embedder);
-                            }
-                            // Also handle `filter` for relay-style connections
-                            if (args?.filter) {
-                                await embedTextInWhere(args.filter, embedder);
-                            }
-                            return oldResolve(source, args, graphqlContext, info);
+                            // Resolve per-DB model/baseUrl overrides from express-context.
+                            // These are just string parameters — the embedder function
+                            // (and its metering wrapper) stays the same.
+                            const overrides = await resolveConfigOverrides(graphqlContext);
+                            // Run within llmConfigStore so the embedder picks up per-DB
+                            // model/baseUrl at call time. Metering wraps the same function
+                            // and is unaffected.
+                            return embedder_1.llmConfigStore.run(overrides, async () => {
+                                if (args?.where) {
+                                    await embedTextInWhere(args.where, embedder, !!hasTextAdapters, onQuotaExceeded);
+                                }
+                                if (args?.filter) {
+                                    await embedTextInWhere(args.filter, embedder, !!hasTextAdapters, onQuotaExceeded);
+                                }
+                                return oldResolve(source, args, graphqlContext, info);
+                            });
                         }
                     };
                 },

package/preset.d.ts

@@ -10,8 +10,8 @@
  * - Adds `{column}Text: String` companion fields on mutation inputs for vector columns
  * - Optionally enables billing/metering via the LlmMeteringPlugin
  *
- * This preset is standalone — it is NOT included in ConstructivePreset by default.
- * Projects that want LLM features opt in by adding it to their preset.
+ * Included in ConstructivePreset when `enableLlm` is true (the default).
+ * Can also be used standalone by adding it directly to your preset's `extends` array.
  *
  * @example
  * ```typescript
@@ -53,6 +53,17 @@
  * })
  * ```
  *
+ * @example With strict quota enforcement (fail if embedding unavailable):
+ * ```typescript
+ * GraphileLlmPreset({
+ *   defaultEmbedder: { provider: 'openai', model: 'text-embedding-3-small' },
+ *   metering: true,
+ *   onQuotaExceeded: 'throw',
+ *   // → if billing quota is exceeded, queries with unifiedSearch throw an error
+ *   // → without this, queries silently fall back to text-only search
+ * })
+ * ```
+ *
  * @example With custom entity_id resolution (bill per-database):
  * ```typescript
  * GraphileLlmPreset({