graphile-llm 0.11.5 → 0.12.0

package/esm/__tests__/unified-search-embedding.test.js

@@ -0,0 +1,174 @@
+/**
+ * Unit tests for LlmTextSearchPlugin's embedTextInWhere function.
+ *
+ * Tests the transformation logic:
+ *   - unifiedSearch: "text" → unifiedSearch: { __text: "text", __vector: [...] }
+ *   - VectorNearbyInput.text → VectorNearbyInput.vector (existing behavior)
+ *
+ * Pure unit tests — no database or Ollama required.
+ */
+import { embedTextInWhere } from '../../src/plugins/text-search-plugin';
+describe('unifiedSearch embedding integration', () => {
+    const mockVector = [0.1, 0.2, 0.3, 0.4, 0.5];
+    const mockEmbedder = jest.fn(async (_text) => mockVector);
+    const nullEmbedder = jest.fn(async (_text) => null);
+    beforeEach(() => {
+        mockEmbedder.mockClear();
+        nullEmbedder.mockClear();
+    });
+    describe('unifiedSearch text → { __text, __vector } transformation', () => {
+        it('transforms unifiedSearch string to object with __text and __vector', async () => {
+            const where = { unifiedSearch: 'HIPAA compliance' };
+            await embedTextInWhere(where, mockEmbedder, true);
+            expect(where.unifiedSearch).toEqual({
+                __text: 'HIPAA compliance',
+                __vector: mockVector,
+            });
+            expect(mockEmbedder).toHaveBeenCalledWith('HIPAA compliance');
+        });
+        it('leaves unifiedSearch as plain string when embedder returns null (graceful degradation)', async () => {
+            const where = { unifiedSearch: 'database normalization' };
+            await embedTextInWhere(where, nullEmbedder, true);
+            // Should remain as string — text adapters handle it
+            expect(where.unifiedSearch).toBe('database normalization');
+            expect(nullEmbedder).toHaveBeenCalledWith('database normalization');
+        });
+        it('throws when embedder returns null and no text adapters available', async () => {
+            const where = { unifiedSearch: 'vector only query' };
+            await expect(embedTextInWhere(where, nullEmbedder, false)).rejects.toThrow('embedding failed');
+        });
+        it('does not embed empty unifiedSearch strings', async () => {
+            const where = { unifiedSearch: '   ' };
+            await embedTextInWhere(where, mockEmbedder, true);
+            expect(where.unifiedSearch).toBe('   ');
+            expect(mockEmbedder).not.toHaveBeenCalled();
+        });
+        it('does not embed null unifiedSearch', async () => {
+            const where = { unifiedSearch: null };
+            await embedTextInWhere(where, mockEmbedder, true);
+            expect(where.unifiedSearch).toBeNull();
+            expect(mockEmbedder).not.toHaveBeenCalled();
+        });
+    });
+    describe('VectorNearbyInput text → vector (existing behavior)', () => {
+        it('transforms VectorNearbyInput text to vector', async () => {
+            const where = { vectorEmbedding: { text: 'semantic query' } };
+            await embedTextInWhere(where, mockEmbedder, true);
+            expect(where.vectorEmbedding).toEqual({ vector: mockVector });
+            expect(mockEmbedder).toHaveBeenCalledWith('semantic query');
+        });
+        it('removes text field when embedder returns null', async () => {
+            const where = { vectorEmbedding: { text: 'failed query' } };
+            await embedTextInWhere(where, nullEmbedder, true);
+            expect(where.vectorEmbedding).toEqual({});
+            expect(nullEmbedder).toHaveBeenCalledWith('failed query');
+        });
+        it('does not modify VectorNearbyInput with existing vector', async () => {
+            const existingVector = [1, 2, 3];
+            const where = { vectorEmbedding: { vector: existingVector, text: 'ignored' } };
+            await embedTextInWhere(where, mockEmbedder, true);
+            // text + vector present → not modified (vector takes precedence)
+            expect(where.vectorEmbedding.vector).toBe(existingVector);
+            expect(mockEmbedder).not.toHaveBeenCalled();
+        });
+    });
+    describe('combined unifiedSearch + VectorNearbyInput', () => {
+        it('embeds both unifiedSearch and VectorNearbyInput.text in parallel', async () => {
+            const where = {
+                unifiedSearch: 'hybrid search query',
+                vectorEmbedding: { text: 'vector part' },
+            };
+            await embedTextInWhere(where, mockEmbedder, true);
+            expect(where.unifiedSearch).toEqual({
+                __text: 'hybrid search query',
+                __vector: mockVector,
+            });
+            expect(where.vectorEmbedding).toEqual({ vector: mockVector });
+            expect(mockEmbedder).toHaveBeenCalledTimes(2);
+        });
+    });
+    describe('nested filter structures (AND, OR)', () => {
+        it('handles unifiedSearch inside nested AND/OR filters', async () => {
+            const where = {
+                AND: [
+                    { unifiedSearch: 'first query' },
+                    { unifiedSearch: 'second query' },
+                ],
+            };
+            await embedTextInWhere(where, mockEmbedder, true);
+            expect(where.AND[0].unifiedSearch).toEqual({
+                __text: 'first query',
+                __vector: mockVector,
+            });
+            expect(where.AND[1].unifiedSearch).toEqual({
+                __text: 'second query',
+                __vector: mockVector,
+            });
+        });
+    });
+    describe('onQuotaExceeded option', () => {
+        it('degrade mode (default): leaves unifiedSearch as string when embedder returns null', async () => {
+            const where = { unifiedSearch: 'some query' };
+            await embedTextInWhere(where, nullEmbedder, true, 'degrade');
+            expect(where.unifiedSearch).toBe('some query');
+        });
+        it('throw mode: throws on unifiedSearch when embedder returns null even with text adapters', async () => {
+            const where = { unifiedSearch: 'some query' };
+            await expect(embedTextInWhere(where, nullEmbedder, true, 'throw')).rejects.toThrow('onQuotaExceeded is set to \'throw\'');
+        });
+        it('throw mode: throws on VectorNearbyInput.text when embedder returns null', async () => {
+            const where = { vectorEmbedding: { text: 'semantic query' } };
+            await expect(embedTextInWhere(where, nullEmbedder, true, 'throw')).rejects.toThrow('VectorNearbyInput: embedding failed');
+        });
+        it('degrade mode: silently removes VectorNearbyInput.text when embedder returns null', async () => {
+            const where = { vectorEmbedding: { text: 'failed query' } };
+            await embedTextInWhere(where, nullEmbedder, true, 'degrade');
+            expect(where.vectorEmbedding).toEqual({});
+        });
+        it('throw mode: still works normally when embedder succeeds', async () => {
+            const where = { unifiedSearch: 'good query' };
+            await embedTextInWhere(where, mockEmbedder, true, 'throw');
+            expect(where.unifiedSearch).toEqual({
+                __text: 'good query',
+                __vector: mockVector,
+            });
+        });
+        it('no text adapters: throws regardless of onQuotaExceeded setting', async () => {
+            const where1 = { unifiedSearch: 'query1' };
+            await expect(embedTextInWhere(where1, nullEmbedder, false, 'degrade')).rejects.toThrow('No text search adapters available');
+            const where2 = { unifiedSearch: 'query2' };
+            await expect(embedTextInWhere(where2, nullEmbedder, false, 'throw')).rejects.toThrow('No text search adapters available');
+        });
+    });
+    describe('apply function object shape handling', () => {
+        it('plugin.ts apply function handles { __text, __vector } correctly', () => {
+            // Simulate what the apply function does with the transformed value
+            const val = { __text: 'HIPAA compliance', __vector: [0.1, 0.2, 0.3] };
+            let text;
+            let vector = null;
+            if (typeof val === 'object' && val.__text) {
+                text = val.__text;
+                vector = val.__vector ?? null;
+            }
+            else {
+                text = typeof val === 'string' ? val : String(val);
+            }
+            expect(text).toBe('HIPAA compliance');
+            expect(vector).toEqual([0.1, 0.2, 0.3]);
+        });
+        it('plugin.ts apply function handles plain string correctly', () => {
+            const val = 'plain text search';
+            let text;
+            let vector = null;
+            if (typeof val === 'object' && val.__text) {
+                text = val.__text;
+                vector = val.__vector ?? null;
+            }
+            else {
+                text = typeof val === 'string' ? val : String(val);
+            }
+            expect(text).toBe('plain text search');
+            expect(vector).toBeNull();
+        });
+    });
+});

package/esm/embedder.d.ts

@@ -4,12 +4,32 @@
  * Provides a provider-based architecture for converting text into vector
  * embeddings. Currently supports Ollama via @agentic-kit/ollama.
  *
- * The embedder is resolved at request time from:
- *   1. The `llm_module` api_modules configuration (per-database)
- *   2. The preset's `defaultEmbedder` option (fallback for dev/testing)
- *   3. Environment variables (EMBEDDER_PROVIDER, EMBEDDER_MODEL, EMBEDDER_BASE_URL)
+ * Per-request model/baseUrl overrides are read from AsyncLocalStorage
+ * (`llmConfigStore`). The text-search-plugin sets these overrides from
+ * the database's `llm_module` config via `ctx.useLlm()`. This means
+ * the same embedder function — and its metering wrapper — handle every
+ * request, regardless of which tenant's model config applies.
  */
+import { AsyncLocalStorage } from 'node:async_hooks';
 import type { EmbedderConfig, EmbedderFunction, LlmModuleData } from './types';
+/**
+ * Per-request LLM config overrides from the database's llm_module.
+ * Only string parameters — the embedder client itself stays the same.
+ */
+export interface LlmConfigOverrides {
+    embeddingModel?: string;
+    embeddingBaseUrl?: string;
+    chatModel?: string;
+    chatBaseUrl?: string;
+}
+/**
+ * AsyncLocalStorage for per-request LLM config overrides.
+ *
+ * Set by the text-search-plugin resolver wrapper (from ctx.useLlm()),
+ * read by the embedder at call time. The metering wrapper sits between
+ * them and is completely unaware — it just wraps the same function.
+ */
+export declare const llmConfigStore: AsyncLocalStorage<LlmConfigOverrides>;
 /**
  * Build an embedder function from a config object.
  *

package/esm/embedder.js

@@ -4,22 +4,50 @@
  * Provides a provider-based architecture for converting text into vector
  * embeddings. Currently supports Ollama via @agentic-kit/ollama.
  *
- * The embedder is resolved at request time from:
- *   1. The `llm_module` api_modules configuration (per-database)
- *   2. The preset's `defaultEmbedder` option (fallback for dev/testing)
- *   3. Environment variables (EMBEDDER_PROVIDER, EMBEDDER_MODEL, EMBEDDER_BASE_URL)
+ * Per-request model/baseUrl overrides are read from AsyncLocalStorage
+ * (`llmConfigStore`). The text-search-plugin sets these overrides from
+ * the database's `llm_module` config via `ctx.useLlm()`. This means
+ * the same embedder function — and its metering wrapper — handle every
+ * request, regardless of which tenant's model config applies.
  */
+import { AsyncLocalStorage } from 'node:async_hooks';
 import OllamaClient from '@agentic-kit/ollama';
 import { getLlmEnvOptions } from './env';
+/**
+ * AsyncLocalStorage for per-request LLM config overrides.
+ *
+ * Set by the text-search-plugin resolver wrapper (from ctx.useLlm()),
+ * read by the embedder at call time. The metering wrapper sits between
+ * them and is completely unaware — it just wraps the same function.
+ */
+export const llmConfigStore = new AsyncLocalStorage();
+// ─── Client cache ───────────────────────────────────────────────────────────
+/** Cache OllamaClient instances by baseUrl to avoid re-creation per request */
+const ollamaClientCache = new Map();
+function getOllamaClient(baseUrl) {
+    let client = ollamaClientCache.get(baseUrl);
+    if (!client) {
+        client = new OllamaClient(baseUrl);
+        ollamaClientCache.set(baseUrl, client);
+    }
+    return client;
+}
 // ─── Built-in Providers ─────────────────────────────────────────────────────
 /**
  * Create an Ollama-based embedder function.
  *
- * Uses the /api/embed endpoint which returns prompt_eval_count (real token count).
+ * At call time, checks `llmConfigStore` for per-request model/baseUrl
+ * overrides. Falls back to the defaults passed at creation time.
+ * Client instances are cached by baseUrl — no new objects per request.
  */
-function createOllamaEmbedder(baseUrl = 'http://localhost:11434', model = 'nomic-embed-text') {
-    const client = new OllamaClient(baseUrl);
+function createOllamaEmbedder(defaultBaseUrl = 'http://localhost:11434', defaultModel = 'nomic-embed-text') {
+    // Pre-cache the default client
+    const defaultClient = getOllamaClient(defaultBaseUrl);
     return async (text) => {
+        const overrides = llmConfigStore.getStore();
+        const model = overrides?.embeddingModel ?? defaultModel;
+        const baseUrl = overrides?.embeddingBaseUrl ?? defaultBaseUrl;
+        const client = baseUrl === defaultBaseUrl ? defaultClient : getOllamaClient(baseUrl);
         return client.generateEmbedding(text, model);
     };
 }

package/esm/env.d.ts

@@ -1,31 +1,9 @@
 /**
- * LLM Environment Configuration
+ * Re-export LLM env configuration from @constructive-io/llm-env.
  *
- * Single source of truth for all LLM-related environment variables and defaults.
- * Every other module in graphile-llm imports from here — no direct process.env
- * reads or scattered null coalescing elsewhere.
- *
- * Environment variables:
- *   EMBEDDER_PROVIDER  - Embedding provider name ('ollama')
- *   EMBEDDER_MODEL     - Embedding model (default: 'nomic-embed-text')
- *   EMBEDDER_BASE_URL  - Embedding provider URL (default: 'http://localhost:11434')
- *   CHAT_PROVIDER      - Chat provider name ('ollama')
- *   CHAT_MODEL         - Chat model (default: 'llama3')
- *   CHAT_BASE_URL      - Chat provider URL (default: 'http://localhost:11434')
- */
-export interface LlmProviderConfig {
-    provider: string;
-    model: string;
-    baseUrl: string;
-}
-export interface LlmEnvOptions {
-    embedding: LlmProviderConfig;
-    chat: LlmProviderConfig;
-}
-/**
- * Resolve LLM configuration from environment variables with sensible defaults.
- *
- * Call this once and pass the result around — never read process.env directly
- * in plugin code.
+ * This file exists for backward compatibility — all internal graphile-llm
+ * modules import from './env'. The actual implementation lives in the
+ * shared @constructive-io/llm-env package.
  */
-export declare function getLlmEnvOptions(): LlmEnvOptions;
+export { getEnvVars, getEnvOptions, getLlmEnvOptions, llmDefaults, } from '@constructive-io/llm-env';
+export type { LlmEnvOptions, LlmProviderConfig, ResolvedLlmEnvOptions, } from '@constructive-io/llm-env';

package/esm/env.js

@@ -1,49 +1,8 @@
 /**
- * LLM Environment Configuration
+ * Re-export LLM env configuration from @constructive-io/llm-env.
  *
- * Single source of truth for all LLM-related environment variables and defaults.
- * Every other module in graphile-llm imports from here — no direct process.env
- * reads or scattered null coalescing elsewhere.
- *
- * Environment variables:
- *   EMBEDDER_PROVIDER  - Embedding provider name ('ollama')
- *   EMBEDDER_MODEL     - Embedding model (default: 'nomic-embed-text')
- *   EMBEDDER_BASE_URL  - Embedding provider URL (default: 'http://localhost:11434')
- *   CHAT_PROVIDER      - Chat provider name ('ollama')
- *   CHAT_MODEL         - Chat model (default: 'llama3')
- *   CHAT_BASE_URL      - Chat provider URL (default: 'http://localhost:11434')
- */
-// ─── Defaults ───────────────────────────────────────────────────────────────
-const LLM_DEFAULTS = {
-    embedding: {
-        provider: 'ollama',
-        model: 'nomic-embed-text',
-        baseUrl: 'http://localhost:11434'
-    },
-    chat: {
-        provider: 'ollama',
-        model: 'llama3',
-        baseUrl: 'http://localhost:11434'
-    }
-};
-// ─── Resolution ─────────────────────────────────────────────────────────────
-/**
- * Resolve LLM configuration from environment variables with sensible defaults.
- *
- * Call this once and pass the result around — never read process.env directly
- * in plugin code.
+ * This file exists for backward compatibility — all internal graphile-llm
+ * modules import from './env'. The actual implementation lives in the
+ * shared @constructive-io/llm-env package.
  */
-export function getLlmEnvOptions() {
-    return {
-        embedding: {
-            provider: process.env.EMBEDDER_PROVIDER ?? LLM_DEFAULTS.embedding.provider,
-            model: process.env.EMBEDDER_MODEL ?? LLM_DEFAULTS.embedding.model,
-            baseUrl: process.env.EMBEDDER_BASE_URL ?? LLM_DEFAULTS.embedding.baseUrl
-        },
-        chat: {
-            provider: process.env.CHAT_PROVIDER ?? LLM_DEFAULTS.chat.provider,
-            model: process.env.CHAT_MODEL ?? LLM_DEFAULTS.chat.model,
-            baseUrl: process.env.CHAT_BASE_URL ?? LLM_DEFAULTS.chat.baseUrl
-        }
-    };
-}
+export { getEnvVars, getEnvOptions, getLlmEnvOptions, llmDefaults, } from '@constructive-io/llm-env';

package/esm/index.d.ts

@@ -29,17 +29,18 @@
  * };
  * ```
  */
-export type { LlmEnvOptions, LlmProviderConfig } from './env';
-export { getLlmEnvOptions } from './env';
+export type { LlmEnvOptions, LlmProviderConfig, ResolvedLlmEnvOptions } from './env';
+export { getEnvVars, getEnvOptions, getLlmEnvOptions, llmDefaults } from './env';
 export { GraphileLlmPreset } from './preset';
 export { createLlmModulePlugin } from './plugins/llm-module-plugin';
 export { createLlmRagPlugin } from './plugins/rag-plugin';
 export { createLlmTextMutationPlugin } from './plugins/text-mutation-plugin';
-export { createLlmTextSearchPlugin } from './plugins/text-search-plugin';
+export { createLlmTextSearchPlugin, embedTextInWhere } from './plugins/text-search-plugin';
 export { createLlmMeteringPlugin } from './plugins/metering-plugin';
 export type { AgentDiscovery, AgentTableInfo } from './plugins/agent-discovery-plugin';
 export { clearAgentDiscoveryCache, getAgentDiscovery } from './plugins/agent-discovery-plugin';
-export { buildEmbedder, buildEmbedderFromEnv, buildEmbedderFromModule } from './embedder';
+export type { LlmConfigOverrides } from './embedder';
+export { buildEmbedder, buildEmbedderFromEnv, buildEmbedderFromModule, llmConfigStore } from './embedder';
 export { buildChatCompleter, buildChatCompleterFromEnv, buildChatCompleterFromModule } from './chat';
 export type { InferenceLogEntry, MeteringContext, MeteringOptions, MeterResult, WithPgClient } from './metering';
 export { logInferenceUsage, meteredChat, meteredEmbed, QuotaExceededError } from './metering';

package/esm/index.js

@@ -29,19 +29,18 @@
  * };
  * ```
  */
-export { getLlmEnvOptions } from './env';
+export { getEnvVars, getEnvOptions, getLlmEnvOptions, llmDefaults } from './env';
 // Preset (recommended entry point)
 export { GraphileLlmPreset } from './preset';
 // Individual plugins (pure — no billing dependency)
 export { createLlmModulePlugin } from './plugins/llm-module-plugin';
 export { createLlmRagPlugin } from './plugins/rag-plugin';
 export { createLlmTextMutationPlugin } from './plugins/text-mutation-plugin';
-export { createLlmTextSearchPlugin } from './plugins/text-search-plugin';
+export { createLlmTextSearchPlugin, embedTextInWhere } from './plugins/text-search-plugin';
 // Metering plugin (opt-in billing integration)
 export { createLlmMeteringPlugin } from './plugins/metering-plugin';
 export { clearAgentDiscoveryCache, getAgentDiscovery } from './plugins/agent-discovery-plugin';
-// Embedder utilities
-export { buildEmbedder, buildEmbedderFromEnv, buildEmbedderFromModule } from './embedder';
+export { buildEmbedder, buildEmbedderFromEnv, buildEmbedderFromModule, llmConfigStore } from './embedder';
 // Chat completion utilities
 export { buildChatCompleter, buildChatCompleterFromEnv, buildChatCompleterFromModule } from './chat';
 export { logInferenceUsage, meteredChat, meteredEmbed, QuotaExceededError } from './metering';

package/esm/metering.d.ts

@@ -90,9 +90,7 @@ export interface InferenceLogEntry {
 }
 /**
  * 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.
  */
 export declare function logInferenceUsage(ctx: MeteringContext, entry: InferenceLogEntry): Promise<void>;
 /**

package/esm/metering.js

@@ -17,85 +17,43 @@
  * Graphile `withPgClient` callback. Function locations (schema, names) are
  * resolved from `billing_module` metaschema and cached by `config-cache.ts`.
  */
-// ─── Billing SQL Helpers ────────────────────────────────────────────────────
+import { createBillingClient } from '@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 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.
  */
 export 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 ───────────────────────────────────────────────────────
 /**
@@ -136,15 +94,8 @@ export 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,
@@ -178,14 +129,12 @@ export 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, {
@@ -252,15 +201,8 @@ export async function meteredChat(chat, messages, ctx, chatOptions, meteringOpti
         };
     }
     // 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, {
@@ -296,16 +238,14 @@ export async function meteredChat(chat, messages, ctx, chatOptions, meteringOpti
     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/esm/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