graphile-llm 0.7.2 → 0.8.0

package/esm/plugins/metering-plugin.js

@@ -0,0 +1,175 @@
+/**
+ * LlmMeteringPlugin
+ *
+ * Opt-in billing integration for graphile-llm. Completely separate from the
+ * pure LLM plugins (text-search, text-mutation, rag).
+ *
+ * **How it works:**
+ * 1. At schema build time, replaces `build.llmEmbedder` with a metered wrapper
+ *    that has the same `(text: string) => Promise<number[]>` signature
+ * 2. At request time, wraps every root query/mutation resolver to set up a
+ *    request-scoped MeteringContext via AsyncLocalStorage
+ * 3. When the embedder is called (by any plugin), the wrapper checks
+ *    AsyncLocalStorage for a metering context and if found, calls
+ *    check_billing_quota before and record_usage after
+ * 4. If quota is exceeded, the wrapper returns null — the calling plugin sees
+ *    null and handles it (search falls back to text-only, mutations throw)
+ *
+ * The pure plugins never import metering, config-cache, or billing types.
+ * They call the embedder and handle null results — that's it.
+ *
+ * **Entity ID resolution:**
+ * The billing `entity_id` is resolved via a configurable callback.
+ * Default: reads `jwt.claims.user_id` from pgSettings. Override via
+ * `metering.resolveEntityId` in GraphileLlmPreset options.
+ *
+ * **Graceful behavior:**
+ * - billing_module not provisioned → embedder passes through unmetered
+ * - entity_id not available → embedder passes through unmetered
+ * - check_billing_quota throws → call is allowed (billing is opt-in)
+ * - record_usage throws → call succeeds, recording silently skipped
+ * - quota exceeded → embedder returns null
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { meteredEmbed } from '../metering';
+import { getLlmBillingConfig } from '../config-cache';
+// ─── Request-scoped context via AsyncLocalStorage ───────────────────────────
+const meteringStore = new AsyncLocalStorage();
+// ─── Helpers ────────────────────────────────────────────────────────────────
+function defaultResolveEntityId(pgSettings) {
+    return pgSettings['jwt.claims.user_id'] ?? null;
+}
+async function buildMeteringContext(graphqlContext, resolveEntityId) {
+    const pgSettings = graphqlContext?.pgSettings ?? {};
+    const entityId = resolveEntityId(pgSettings);
+    const databaseId = pgSettings['jwt.claims.database_id'] ?? null;
+    const requestId = pgSettings['request.id'] ?? null;
+    const actorId = pgSettings['jwt.claims.user_id'] ?? null;
+    if (!entityId || !databaseId)
+        return null;
+    const withPgClient = graphqlContext?.withPgClient;
+    if (!withPgClient)
+        return null;
+    let billingConfig = null;
+    let inferenceLogConfig = null;
+    try {
+        await withPgClient(pgSettings, async (pgClient) => {
+            const entry = await getLlmBillingConfig(pgClient, databaseId);
+            billingConfig = entry.billing;
+            inferenceLogConfig = entry.inferenceLog;
+        });
+    }
+    catch {
+        return null;
+    }
+    if (!billingConfig)
+        return null;
+    return {
+        withPgClient,
+        pgSettings,
+        billing: billingConfig,
+        entityId,
+        requestId,
+        databaseId,
+        actorId,
+        inferenceLog: inferenceLogConfig,
+    };
+}
+/**
+ * Wrap an embedder with metering that reads context from AsyncLocalStorage.
+ * The returned function has the same signature as the original embedder,
+ * so downstream plugins are unaware of billing.
+ *
+ * When no metering context is in scope, the original embedder is called directly.
+ * When quota is exceeded, returns null instead of a vector.
+ */
+function wrapEmbedderWithMetering(embedder, meteringOptions) {
+    return async (text) => {
+        const ctx = meteringStore.getStore();
+        if (!ctx) {
+            // No metering context in scope — call original embedder directly
+            const startTime = Date.now();
+            const result = await embedder(text);
+            const latencyMs = Date.now() - startTime;
+            console.log(`[graphile-llm] Embed (unmetered): dims=${result?.length ?? 0}, latency=${latencyMs}ms`);
+            return result;
+        }
+        const result = await meteredEmbed(embedder, text, ctx, meteringOptions);
+        if (result.quotaExceeded) {
+            return null;
+        }
+        return result.result;
+    };
+}
+// ─── Plugin ─────────────────────────────────────────────────────────────────
+export function createLlmMeteringPlugin(meteringConfig = {}) {
+    const { embeddingMeterSlug: configEmbeddingSlug, chatMeterSlug: configChatSlug, skipMetering, resolveEntityId = defaultResolveEntityId, } = meteringConfig;
+    return {
+        name: 'LlmMeteringPlugin',
+        version: '0.2.0',
+        description: 'Wraps LLM embedder/chat with billing quota checks and usage recording',
+        after: ['LlmModulePlugin'],
+        before: ['LlmTextSearchPlugin', 'LlmTextMutationPlugin', 'LlmRagPlugin'],
+        schema: {
+            hooks: {
+                build(build) {
+                    const originalEmbedder = build.llmEmbedder;
+                    if (!originalEmbedder) {
+                        console.log('[graphile-llm] Metering plugin loaded but no embedder configured — skipping');
+                        return build;
+                    }
+                    // Meter slug = model name by default (three-level waterfall: model → inference → universal)
+                    const embeddingModel = build.llmEmbeddingModel;
+                    const chatModel = build.llmChatModel;
+                    const embeddingSlug = configEmbeddingSlug ?? embeddingModel ?? undefined;
+                    const chatSlug = configChatSlug ?? chatModel ?? undefined;
+                    if (embeddingSlug) {
+                        console.log(`[graphile-llm] Metering enabled — embedding meter: ${embeddingSlug}`);
+                    }
+                    else {
+                        console.log('[graphile-llm] Metering enabled but no embedding model name — usage will not be metered');
+                    }
+                    const meteringOptions = {
+                        embeddingMeterSlug: embeddingSlug,
+                        chatMeterSlug: chatSlug,
+                        skipMetering,
+                        embeddingModel: embeddingModel ?? undefined,
+                        chatModel: chatModel ?? undefined,
+                    };
+                    // Replace the embedder with a metered version.
+                    // Same signature except it can return null (quota exceeded).
+                    const meteredEmbedder = wrapEmbedderWithMetering(originalEmbedder, meteringOptions);
+                    return build.extend(build, {
+                        llmEmbedder: meteredEmbedder,
+                    }, 'LlmMeteringPlugin replacing llmEmbedder with metered version');
+                },
+                /**
+                 * Wrap every root query/mutation resolver to establish the
+                 * request-scoped metering context via AsyncLocalStorage.
+                 */
+                GraphQLObjectType_fields_field(field, build, context) {
+                    const { scope: { isRootQuery, isRootMutation }, } = context;
+                    if (!isRootQuery && !isRootMutation)
+                        return field;
+                    // Only wrap if we actually replaced the embedder
+                    if (!build.llmEmbedder)
+                        return field;
+                    const defaultResolver = (obj) => obj[context.scope.fieldName];
+                    const { resolve: oldResolve = defaultResolver, ...rest } = field;
+                    return {
+                        ...rest,
+                        async resolve(source, args, graphqlContext, info) {
+                            // Build the metering context for this request
+                            const ctx = await buildMeteringContext(graphqlContext, resolveEntityId);
+                            // Run the original resolver within the AsyncLocalStorage scope
+                            // so any embedder calls made by downstream plugins pick up the ctx
+                            return meteringStore.run(ctx, () => {
+                                return oldResolve(source, args, graphqlContext, info);
+                            });
+                        },
+                    };
+                },
+            },
+        },
+    };
+}

package/esm/plugins/text-mutation-plugin.d.ts

@@ -9,6 +9,10 @@
  * Example:
  *   mutation { createArticle(input: { embeddingText: "Machine learning concepts" }) }
  *
+ * If the embedder returns null (e.g. quota exceeded when the metering plugin
+ * is loaded), the mutation throws an error — unlike search, mutations cannot
+ * silently skip writing a vector the user asked for.
+ *
  * This is the mutation counterpart to LlmTextSearchPlugin (which handles
  * filter/query-side text-to-vector). Together they let clients work entirely
  * with text/prompts instead of raw float vectors.

package/esm/plugins/text-mutation-plugin.js

@@ -9,6 +9,10 @@
  * Example:
  *   mutation { createArticle(input: { embeddingText: "Machine learning concepts" }) }
  *
+ * If the embedder returns null (e.g. quota exceeded when the metering plugin
+ * is loaded), the mutation throws an error — unlike search, mutations cannot
+ * silently skip writing a vector the user asked for.
+ *
  * This is the mutation counterpart to LlmTextSearchPlugin (which handles
  * filter/query-side text-to-vector). Together they let clients work entirely
  * with text/prompts instead of raw float vectors.
@@ -61,7 +65,7 @@ function getTextToVectorMapping(pgCodec, build) {
 export function createLlmTextMutationPlugin() {
     return {
         name: 'LlmTextMutationPlugin',
-        version: '0.1.0',
+        version: '0.2.0',
         description: 'Adds text companion fields on mutation inputs for vector columns — ' +
             'text is embedded server-side before storing',
         after: [
@@ -121,6 +125,8 @@ export function createLlmTextMutationPlugin() {
                  * Uses the same v4-style resolver wrapping pattern as graphile-upload-plugin
                  * and graphile-bucket-provisioner-plugin. grafserv v5 supports this through
                  * its backwards-compatibility layer.
+                 *
+                 * If the embedder returns null (e.g. quota exceeded), throws an error.
                  */
                 GraphQLObjectType_fields_field(field, build, context) {
                     const { scope: { isRootMutation, fieldName, pgCodec }, } = context;
@@ -163,6 +169,10 @@ export function createLlmTextMutationPlugin() {
                                             const startTime = Date.now();
                                             const vector = await embedder(value);
                                             const latencyMs = Date.now() - startTime;
+                                            if (vector === null) {
+                                                throw new Error(`EMBED_QUOTA_EXCEEDED: Cannot embed ${key} — embedding quota exceeded. ` +
+                                                    'Upgrade your plan or wait for the next billing period.');
+                                            }
                                             console.log(`[graphile-llm] Mutation embed: field=${key}, dims=${vector.length}, latency=${latencyMs}ms`);
                                             // Inject the vector into the corresponding field
                                             obj[vectorFieldName] = vector;

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

@@ -22,6 +22,10 @@
  *
  * If the embedder is not configured, the `text` field is still registered
  * (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.
  */
 import type { GraphileConfig } from 'graphile-config';
 declare global {

package/esm/plugins/text-search-plugin.js

@@ -22,6 +22,10 @@
  *
  * If the embedder is not configured, the `text` field is still registered
  * (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.
  */
 /**
  * Check if a codec has any pgvector `vector` columns.
@@ -38,6 +42,9 @@ function hasVectorColumns(pgCodec) {
 /**
  * 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.
  */
 async function embedTextInWhere(obj, embedder) {
     if (!obj || typeof obj !== 'object')
@@ -53,6 +60,11 @@ async function embedTextInWhere(obj, embedder) {
                 const startTime = Date.now();
                 const vector = await embedder(value.text);
                 const latencyMs = Date.now() - startTime;
+                if (vector === null) {
+                    // Embedder returned null (e.g. quota exceeded) — skip vector search
+                    delete value.text;
+                    return;
+                }
                 console.log(`[graphile-llm] Search embed: field=${key}, dims=${vector.length}, latency=${latencyMs}ms`);
                 // Replace text with vector
                 value.vector = vector;
@@ -85,7 +97,7 @@ async function embedTextInWhere(obj, embedder) {
 export function createLlmTextSearchPlugin() {
     return {
         name: 'LlmTextSearchPlugin',
-        version: '0.1.0',
+        version: '0.2.0',
         description: 'Adds text-to-vector embedding support on VectorNearbyInput filter fields',
         after: [
             'LlmModulePlugin',

package/esm/preset.d.ts

@@ -8,7 +8,7 @@
  * - Resolves an embedder from configuration (llm_module, env vars, or preset options)
  * - Adds a `text: String` field to `VectorNearbyInput` for text-based vector search
  * - Adds `{column}Text: String` companion fields on mutation inputs for vector columns
- * - Logs token usage to console (metering integration deferred to billing system)
+ * - 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.
@@ -42,6 +42,26 @@
  *   ],
  * };
  * ```
+ *
+ * @example With billing metering (opt-in, meter slug = model name by default):
+ * ```typescript
+ * GraphileLlmPreset({
+ *   defaultEmbedder: { provider: 'openai', model: 'text-embedding-3-small' },
+ *   metering: true,
+ *   // → embedding calls metered under 'text-embedding-3-small' meter slug
+ *   // → three-level waterfall: text-embedding-3-small → inference pool → universal
+ * })
+ * ```
+ *
+ * @example With custom entity_id resolution (bill per-database):
+ * ```typescript
+ * GraphileLlmPreset({
+ *   defaultEmbedder: { provider: 'openai', model: 'text-embedding-3-small' },
+ *   metering: {
+ *     resolveEntityId: (pgSettings) => pgSettings['jwt.claims.database_id'],
+ *   },
+ * })
+ * ```
  */
 import type { GraphileConfig } from 'graphile-config';
 import type { GraphileLlmOptions } from './types';

package/esm/preset.js

@@ -8,7 +8,7 @@
  * - Resolves an embedder from configuration (llm_module, env vars, or preset options)
  * - Adds a `text: String` field to `VectorNearbyInput` for text-based vector search
  * - Adds `{column}Text: String` companion fields on mutation inputs for vector columns
- * - Logs token usage to console (metering integration deferred to billing system)
+ * - 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.
@@ -42,11 +42,32 @@
  *   ],
  * };
  * ```
+ *
+ * @example With billing metering (opt-in, meter slug = model name by default):
+ * ```typescript
+ * GraphileLlmPreset({
+ *   defaultEmbedder: { provider: 'openai', model: 'text-embedding-3-small' },
+ *   metering: true,
+ *   // → embedding calls metered under 'text-embedding-3-small' meter slug
+ *   // → three-level waterfall: text-embedding-3-small → inference pool → universal
+ * })
+ * ```
+ *
+ * @example With custom entity_id resolution (bill per-database):
+ * ```typescript
+ * GraphileLlmPreset({
+ *   defaultEmbedder: { provider: 'openai', model: 'text-embedding-3-small' },
+ *   metering: {
+ *     resolveEntityId: (pgSettings) => pgSettings['jwt.claims.database_id'],
+ *   },
+ * })
+ * ```
  */
 import { createLlmModulePlugin } from './plugins/llm-module-plugin';
 import { createLlmTextSearchPlugin } from './plugins/text-search-plugin';
 import { createLlmTextMutationPlugin } from './plugins/text-mutation-plugin';
 import { createLlmRagPlugin } from './plugins/rag-plugin';
+import { createLlmMeteringPlugin } from './plugins/metering-plugin';
 /**
  * Creates a preset that includes all LLM plugins.
  *
@@ -54,10 +75,16 @@ import { createLlmRagPlugin } from './plugins/rag-plugin';
  * @returns A GraphileConfig.Preset to add to your extends array
  */
 export function GraphileLlmPreset(options = {}) {
-    const { enableTextSearch = true, enableTextMutations = true, enableRag = false, ragDefaults, } = options;
+    const { enableTextSearch = true, enableTextMutations = true, enableRag = false, ragDefaults, metering, } = options;
     const plugins = [
         createLlmModulePlugin(options),
     ];
+    // Metering is opt-in: only loaded when metering is truthy
+    // (true, or a MeteringConfig object)
+    if (metering) {
+        const meteringConfig = metering === true ? {} : metering;
+        plugins.push(createLlmMeteringPlugin(meteringConfig));
+    }
     if (enableTextSearch) {
         plugins.push(createLlmTextSearchPlugin());
     }

package/esm/types.d.ts

@@ -17,8 +17,6 @@ export interface EmbedderConfig {
     model?: string;
     /** Base URL for the provider (e.g. 'http://localhost:11434' for Ollama) */
     baseUrl?: string;
-    /** API key for providers that require authentication (e.g. OpenAI) */
-    apiKey?: string;
 }
 /**
  * A single message in a chat conversation.
@@ -50,8 +48,6 @@ export interface ChatConfig {
     model?: string;
     /** Base URL for the provider */
     baseUrl?: string;
-    /** API key for providers that require authentication */
-    apiKey?: string;
 }
 /**
  * The shape of the `llm_module` data stored in `services_public.api_modules`.
@@ -74,8 +70,6 @@ export interface LlmModuleData {
     chat_model?: string;
     /** Base URL for the chat provider */
     chat_base_url?: string;
-    /** API key reference (e.g. 'vault://openai-key' or env var name) */
-    api_key_ref?: string;
     /** Rate limit: requests per minute */
     rate_limit_rpm?: number;
     /** Maximum tokens per request */
@@ -131,6 +125,41 @@ export interface ChunkTableInfo {
     /** Text content column on chunks table (the actual chunk text) */
     contentField: string;
 }
+/**
+ * Configuration for billing/metering integration.
+ * When provided, embedding and chat calls are wrapped with quota checks
+ * and usage recording via the billing_module functions.
+ */
+export interface MeteringConfig {
+    /**
+     * Meter slug for embedding operations.
+     * Must match a slug in the billing_module meters table.
+     *
+     * @default the embedding model name (e.g. 'text-embedding-3-small')
+     * — meter slug = model name, so each model has its own meter
+     * in the three-level waterfall (per-model → inference pool → universal).
+     */
+    embeddingMeterSlug?: string;
+    /**
+     * Meter slug for chat completion operations.
+     *
+     * @default the chat model name (e.g. 'gpt-4o-mini')
+     */
+    chatMeterSlug?: string;
+    /**
+     * Disable metering entirely (e.g. for local dev).
+     * When true, billing functions are never called.
+     * @default false
+     */
+    skipMetering?: boolean;
+    /**
+     * Resolve the billing entity_id from pgSettings.
+     * The entity_id identifies who gets billed (user, org, etc.).
+     *
+     * @default reads jwt.claims.user_id
+     */
+    resolveEntityId?: (pgSettings: Record<string, string>) => string | null;
+}
 /**
  * Options for the GraphileLlmPreset.
  */
@@ -170,4 +199,16 @@ export interface GraphileLlmOptions {
      * Individual queries can override these values.
      */
     ragDefaults?: RagDefaults;
+    /**
+     * Billing/metering configuration (opt-in).
+     * When truthy, loads the LlmMeteringPlugin which wraps the embedder
+     * with billing quota checks + usage recording.
+     *
+     * Set to `true` to enable metering with defaults (entity_id from jwt.claims.user_id).
+     * Provide a MeteringConfig object for fine-grained control (custom entity_id, meter slugs).
+     * Set to `false` or omit to disable metering entirely.
+     *
+     * @default undefined (metering disabled)
+     */
+    metering?: boolean | MeteringConfig;
 }

package/index.d.ts

@@ -29,11 +29,20 @@
  * };
  * ```
  */
+export { getLlmEnvOptions } from './env';
+export type { LlmEnvOptions, LlmProviderConfig } from './env';
 export { GraphileLlmPreset } from './preset';
 export { createLlmModulePlugin } from './plugins/llm-module-plugin';
 export { createLlmTextSearchPlugin } from './plugins/text-search-plugin';
 export { createLlmTextMutationPlugin } from './plugins/text-mutation-plugin';
 export { createLlmRagPlugin } from './plugins/rag-plugin';
+export { createLlmMeteringPlugin } from './plugins/metering-plugin';
+export { getAgentDiscovery, clearAgentDiscoveryCache } from './plugins/agent-discovery-plugin';
+export type { AgentTableInfo, AgentDiscovery } from './plugins/agent-discovery-plugin';
 export { buildEmbedder, buildEmbedderFromModule, buildEmbedderFromEnv, } from './embedder';
 export { buildChatCompleter, buildChatCompleterFromModule, buildChatCompleterFromEnv, } from './chat';
-export type { EmbedderFunction, EmbedderConfig, ChatFunction, ChatConfig, ChatMessage, ChatOptions, LlmModuleData, GraphileLlmOptions, RagDefaults, ChunkTableInfo, } from './types';
+export { meteredEmbed, meteredChat, logInferenceUsage, QuotaExceededError } from './metering';
+export type { MeteringContext, MeteringOptions, MeterResult, WithPgClient, InferenceLogEntry } from './metering';
+export { getLlmBillingConfig, invalidateLlmBillingConfig, getLlmBillingCacheStats, } from './config-cache';
+export type { BillingConfig, LlmBillingCacheEntry, InferenceLogConfig, PgClient } from './config-cache';
+export type { EmbedderFunction, EmbedderConfig, ChatFunction, ChatConfig, ChatMessage, ChatOptions, LlmModuleData, GraphileLlmOptions, MeteringConfig, RagDefaults, ChunkTableInfo, } from './types';

package/index.js

@@ -31,11 +31,14 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildChatCompleterFromEnv = exports.buildChatCompleterFromModule = exports.buildChatCompleter = exports.buildEmbedderFromEnv = exports.buildEmbedderFromModule = exports.buildEmbedder = exports.createLlmRagPlugin = exports.createLlmTextMutationPlugin = exports.createLlmTextSearchPlugin = exports.createLlmModulePlugin = exports.GraphileLlmPreset = void 0;
+exports.getLlmBillingCacheStats = exports.invalidateLlmBillingConfig = exports.getLlmBillingConfig = exports.QuotaExceededError = exports.logInferenceUsage = exports.meteredChat = exports.meteredEmbed = exports.buildChatCompleterFromEnv = exports.buildChatCompleterFromModule = exports.buildChatCompleter = exports.buildEmbedderFromEnv = exports.buildEmbedderFromModule = exports.buildEmbedder = exports.clearAgentDiscoveryCache = exports.getAgentDiscovery = exports.createLlmMeteringPlugin = exports.createLlmRagPlugin = exports.createLlmTextMutationPlugin = exports.createLlmTextSearchPlugin = exports.createLlmModulePlugin = exports.GraphileLlmPreset = exports.getLlmEnvOptions = void 0;
+// Environment configuration (single source of truth for LLM defaults)
+var env_1 = require("./env");
+Object.defineProperty(exports, "getLlmEnvOptions", { enumerable: true, get: function () { return env_1.getLlmEnvOptions; } });
 // Preset (recommended entry point)
 var preset_1 = require("./preset");
 Object.defineProperty(exports, "GraphileLlmPreset", { enumerable: true, get: function () { return preset_1.GraphileLlmPreset; } });
-// Individual plugins
+// Individual plugins (pure — no billing dependency)
 var llm_module_plugin_1 = require("./plugins/llm-module-plugin");
 Object.defineProperty(exports, "createLlmModulePlugin", { enumerable: true, get: function () { return llm_module_plugin_1.createLlmModulePlugin; } });
 var text_search_plugin_1 = require("./plugins/text-search-plugin");
@@ -44,6 +47,13 @@ var text_mutation_plugin_1 = require("./plugins/text-mutation-plugin");
 Object.defineProperty(exports, "createLlmTextMutationPlugin", { enumerable: true, get: function () { return text_mutation_plugin_1.createLlmTextMutationPlugin; } });
 var rag_plugin_1 = require("./plugins/rag-plugin");
 Object.defineProperty(exports, "createLlmRagPlugin", { enumerable: true, get: function () { return rag_plugin_1.createLlmRagPlugin; } });
+// Metering plugin (opt-in billing integration)
+var metering_plugin_1 = require("./plugins/metering-plugin");
+Object.defineProperty(exports, "createLlmMeteringPlugin", { enumerable: true, get: function () { return metering_plugin_1.createLlmMeteringPlugin; } });
+// Agent discovery (queries agent_chat_module config table at runtime)
+var agent_discovery_plugin_1 = require("./plugins/agent-discovery-plugin");
+Object.defineProperty(exports, "getAgentDiscovery", { enumerable: true, get: function () { return agent_discovery_plugin_1.getAgentDiscovery; } });
+Object.defineProperty(exports, "clearAgentDiscoveryCache", { enumerable: true, get: function () { return agent_discovery_plugin_1.clearAgentDiscoveryCache; } });
 // Embedder utilities
 var embedder_1 = require("./embedder");
 Object.defineProperty(exports, "buildEmbedder", { enumerable: true, get: function () { return embedder_1.buildEmbedder; } });
@@ -54,3 +64,14 @@ var chat_1 = require("./chat");
 Object.defineProperty(exports, "buildChatCompleter", { enumerable: true, get: function () { return chat_1.buildChatCompleter; } });
 Object.defineProperty(exports, "buildChatCompleterFromModule", { enumerable: true, get: function () { return chat_1.buildChatCompleterFromModule; } });
 Object.defineProperty(exports, "buildChatCompleterFromEnv", { enumerable: true, get: function () { return chat_1.buildChatCompleterFromEnv; } });
+// Metering utilities (for custom integration)
+var metering_1 = require("./metering");
+Object.defineProperty(exports, "meteredEmbed", { enumerable: true, get: function () { return metering_1.meteredEmbed; } });
+Object.defineProperty(exports, "meteredChat", { enumerable: true, get: function () { return metering_1.meteredChat; } });
+Object.defineProperty(exports, "logInferenceUsage", { enumerable: true, get: function () { return metering_1.logInferenceUsage; } });
+Object.defineProperty(exports, "QuotaExceededError", { enumerable: true, get: function () { return metering_1.QuotaExceededError; } });
+// Config cache (for custom integration)
+var config_cache_1 = require("./config-cache");
+Object.defineProperty(exports, "getLlmBillingConfig", { enumerable: true, get: function () { return config_cache_1.getLlmBillingConfig; } });
+Object.defineProperty(exports, "invalidateLlmBillingConfig", { enumerable: true, get: function () { return config_cache_1.invalidateLlmBillingConfig; } });
+Object.defineProperty(exports, "getLlmBillingCacheStats", { enumerable: true, get: function () { return config_cache_1.getLlmBillingCacheStats; } });

package/metering.d.ts

@@ -0,0 +1,114 @@
+/**
+ * metering — Billing-aware wrappers for embedder and chat functions
+ *
+ * Wraps EmbedderFunction and ChatFunction with:
+ *   1. Pre-check: `check_billing_quota(meter_slug, entity_id, estimated_amount)`
+ *   2. Execute the underlying function
+ *   3. Post-record: `record_usage(meter_slug, entity_id, actual_amount)`
+ *
+ * When the quota check fails, the wrapper returns null (graceful degradation)
+ * instead of throwing, so the search pipeline can fall back to text-only.
+ *
+ * Token counts are estimated from text length (~4 chars per token). No
+ * tokenizer needed — the billing system uses tokens as abstract units
+ * and the credit_cost on each model's meter normalizes the relative expense.
+ *
+ * The billing functions live in the tenant database and are called via the
+ * Graphile `withPgClient` callback. Function locations (schema, names) are
+ * resolved from `billing_module` metaschema and cached by `config-cache.ts`.
+ */
+import type { PgClient, BillingConfig, InferenceLogConfig } from './config-cache';
+import type { EmbedderFunction, ChatFunction, ChatMessage, ChatOptions } from './types';
+/**
+ * Callback matching Graphile's withPgClient signature.
+ * Acquires a pg client, calls the callback, then releases the client.
+ */
+export type WithPgClient = (pgSettings: Record<string, string>, callback: (pgClient: PgClient) => Promise<void>) => Promise<void>;
+export interface MeteringContext {
+    /** Callback to acquire a tenant database client */
+    withPgClient: WithPgClient;
+    /** pgSettings from the GraphQL context (for role/claims) */
+    pgSettings: Record<string, string>;
+    /** Billing function references from the billing_module */
+    billing: BillingConfig;
+    /** Entity ID to meter against (from JWT claims) */
+    entityId: string;
+    /** Per-request correlation ID (from request.id pgSetting) */
+    requestId: string | null;
+    /** Database UUID from JWT claims */
+    databaseId: string;
+    /** Actor (user) ID from JWT claims */
+    actorId: string | null;
+    /** Inference log table config (null if inference_log_module not provisioned) */
+    inferenceLog: InferenceLogConfig | null;
+}
+export interface MeteringOptions {
+    /** Meter slug for embedding operations (default: model name from build config) */
+    embeddingMeterSlug?: string;
+    /** Meter slug for chat completion operations (default: model name from build config) */
+    chatMeterSlug?: string;
+    /** Whether to skip metering entirely (e.g. for local dev). Default: false */
+    skipMetering?: boolean;
+    /** Embedding model name (for inference log) */
+    embeddingModel?: string;
+    /** Chat model name (for inference log) */
+    chatModel?: string;
+    /** Provider name (for inference log) */
+    provider?: string;
+}
+export interface MeterResult<T> {
+    /** The result from the underlying function, or null if quota exceeded */
+    result: T | null;
+    /** Whether the call was metered */
+    metered: boolean;
+    /** Whether the call was skipped due to quota limits */
+    quotaExceeded: boolean;
+    /** Latency of the underlying function call in ms */
+    latencyMs: number;
+}
+export interface InferenceLogEntry {
+    databaseId: string;
+    entityId: string;
+    actorId: string | null;
+    model: string;
+    provider: string | null;
+    service: 'llm' | 'embedding' | 'tts' | 'stt' | 'ocr' | 'image_gen' | 'search' | 'compute';
+    operation: string;
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    cacheReadTokens: number | null;
+    cacheWriteTokens: number | null;
+    latencyMs: number;
+    ragEnabled: boolean;
+    chunksRetrieved: number | null;
+    embeddingModel: string | null;
+    embeddingLatencyMs: number | null;
+    status: 'success' | 'quota_exceeded' | 'provider_error' | 'timeout';
+    errorType: string | null;
+    rawUsage: Record<string, unknown> | null;
+}
+/**
+ * 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.
+ */
+export declare function logInferenceUsage(ctx: MeteringContext, entry: InferenceLogEntry): Promise<void>;
+/**
+ * Wrap an embedder with billing quota check + usage recording.
+ *
+ * The returned MeterResult contains `quotaExceeded: true` when the pre-check
+ * fails, enabling the caller to fall back to text-only search.
+ */
+export declare function meteredEmbed(embedder: EmbedderFunction, text: string, ctx: MeteringContext | null, options?: MeteringOptions): Promise<MeterResult<number[]>>;
+/**
+ * Wrap a chat completion call with billing quota check + usage recording.
+ */
+export declare function meteredChat(chat: ChatFunction, messages: ChatMessage[], ctx: MeteringContext | null, chatOptions?: ChatOptions, meteringOptions?: MeteringOptions): Promise<MeterResult<string>>;
+export declare class QuotaExceededError extends Error {
+    readonly code = "QUOTA_EXCEEDED";
+    readonly meterSlug: string;
+    readonly entityId: string;
+    constructor(meterSlug: string, entityId: string);
+}