graphile-llm 0.8.0 → 0.10.0

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

@@ -102,7 +102,7 @@ export function createLlmTextSearchPlugin() {
         after: [
             'LlmModulePlugin',
             'UnifiedSearchPlugin',
-            'VectorCodecPlugin',
+            'VectorCodecPlugin'
         ],
         schema: {
             hooks: {
@@ -113,18 +113,18 @@ export function createLlmTextSearchPlugin() {
                  * The field is optional — clients provide either `text` or `vector`.
                  */
                 GraphQLInputObjectType_fields(fields, build, context) {
-                    const { scope: { inputObjectTypeName }, } = context;
+                    const { scope: { inputObjectTypeName } } = context;
                     if (inputObjectTypeName !== 'VectorNearbyInput') {
                         return fields;
                     }
-                    const { graphql: { GraphQLString }, } = build;
+                    const { graphql: { GraphQLString } } = build;
                     return build.extend(fields, {
                         text: {
                             type: GraphQLString,
                             description: 'Natural language text to embed server-side for similarity search. ' +
                                 'Mutually exclusive with `vector` — provide one or the other. ' +
-                                'Requires the LLM plugin to be configured with an embedding provider.',
-                        },
+                                'Requires the LLM plugin to be configured with an embedding provider.'
+                        }
                     }, 'LlmTextSearchPlugin adding text field to VectorNearbyInput');
                 },
                 /**
@@ -136,7 +136,7 @@ export function createLlmTextSearchPlugin() {
                  * and graphile-bucket-provisioner-plugin.
                  */
                 GraphQLObjectType_fields_field(field, build, context) {
-                    const { scope: { isRootQuery, pgCodec }, } = context;
+                    const { scope: { isRootQuery, pgCodec } } = context;
                     // Only wrap root query fields on tables with vector columns
                     if (!isRootQuery || !pgCodec || !hasVectorColumns(pgCodec)) {
                         return field;
@@ -158,7 +158,7 @@ export function createLlmTextSearchPlugin() {
                                 await embedTextInWhere(args.filter, embedder);
                             }
                             return oldResolve(source, args, graphqlContext, info);
-                        },
+                        }
                     };
                 },
                 finalize(schema, build) {
@@ -168,8 +168,8 @@ export function createLlmTextSearchPlugin() {
                             'will return errors if used. Configure an embedding provider to enable.');
                     }
                     return schema;
-                },
-            },
-        },
+                }
+            }
+        }
     };
 }

package/esm/preset.js

@@ -64,10 +64,10 @@
  * ```
  */
 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';
+import { createLlmRagPlugin } from './plugins/rag-plugin';
+import { createLlmTextMutationPlugin } from './plugins/text-mutation-plugin';
+import { createLlmTextSearchPlugin } from './plugins/text-search-plugin';
 /**
  * Creates a preset that includes all LLM plugins.
  *
@@ -75,9 +75,9 @@ import { createLlmMeteringPlugin } from './plugins/metering-plugin';
  * @returns A GraphileConfig.Preset to add to your extends array
  */
 export function GraphileLlmPreset(options = {}) {
-    const { enableTextSearch = true, enableTextMutations = true, enableRag = false, ragDefaults, metering, } = options;
+    const { enableTextSearch = true, enableTextMutations = true, enableRag = false, ragDefaults, metering } = options;
     const plugins = [
-        createLlmModulePlugin(options),
+        createLlmModulePlugin(options)
     ];
     // Metering is opt-in: only loaded when metering is truthy
     // (true, or a MeteringConfig object)
@@ -95,7 +95,7 @@ export function GraphileLlmPreset(options = {}) {
         plugins.push(createLlmRagPlugin(ragDefaults));
     }
     return {
-        plugins,
+        plugins
     };
 }
 export default GraphileLlmPreset;

package/esm/types.d.ts

@@ -4,9 +4,18 @@
  * Shared type definitions for the LLM plugin.
  */
 /**
- * A function that converts text into a vector embedding.
+ * Result from an embedding call, including real token usage from the provider.
  */
-export type EmbedderFunction = (text: string) => Promise<number[]>;
+export interface EmbeddingResult {
+    /** The vector embedding */
+    embedding: number[];
+    /** Number of prompt tokens consumed (from provider; 0 if unavailable) */
+    promptTokens: number;
+}
+/**
+ * A function that converts text into a vector embedding with token usage.
+ */
+export type EmbedderFunction = (text: string) => Promise<EmbeddingResult>;
 /**
  * Configuration for an embedding provider.
  */
@@ -18,6 +27,24 @@ export interface EmbedderConfig {
     /** Base URL for the provider (e.g. 'http://localhost:11434' for Ollama) */
     baseUrl?: string;
 }
+/**
+ * Token usage metadata returned by LLM providers.
+ * Maps to the billing schema's inference_log columns.
+ */
+export interface LlmUsage {
+    /** Prompt / input tokens consumed */
+    input: number;
+    /** Completion / output tokens generated (includes reasoning for providers that count it) */
+    output: number;
+    /** Reasoning tokens (subset of output — not additive) */
+    reasoning: number;
+    /** Tokens served from prompt cache (zero cost) */
+    cacheRead: number;
+    /** Tokens written to prompt cache */
+    cacheWrite: number;
+    /** input + output + cacheRead + cacheWrite */
+    totalTokens: number;
+}
 /**
  * A single message in a chat conversation.
  */
@@ -35,9 +62,17 @@ export interface ChatOptions {
     temperature?: number;
 }
 /**
- * A function that sends messages to a chat completion provider and returns the response.
+ * Result from a chat completion call, including real token usage.
+ */
+export interface ChatResult {
+    content: string;
+    usage: LlmUsage;
+}
+/**
+ * A function that sends messages to a chat completion provider
+ * and returns the response with token usage metadata.
  */
-export type ChatFunction = (messages: ChatMessage[], options?: ChatOptions) => Promise<string>;
+export type ChatFunction = (messages: ChatMessage[], options?: ChatOptions) => Promise<ChatResult>;
 /**
  * Configuration for a chat completion provider.
  */

package/index.d.ts

@@ -29,20 +29,20 @@
  * };
  * ```
  */
-export { getLlmEnvOptions } from './env';
 export type { LlmEnvOptions, LlmProviderConfig } from './env';
+export { getLlmEnvOptions } 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 { createLlmTextMutationPlugin } from './plugins/text-mutation-plugin';
+export { createLlmTextSearchPlugin } from './plugins/text-search-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 { 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';
+export type { AgentDiscovery, AgentTableInfo } from './plugins/agent-discovery-plugin';
+export { clearAgentDiscoveryCache, getAgentDiscovery } from './plugins/agent-discovery-plugin';
+export { buildEmbedder, buildEmbedderFromEnv, buildEmbedderFromModule } from './embedder';
+export { buildChatCompleter, buildChatCompleterFromEnv, buildChatCompleterFromModule } from './chat';
+export type { InferenceLogEntry, MeteringContext, MeteringOptions, MeterResult, WithPgClient } from './metering';
+export { logInferenceUsage, meteredChat, meteredEmbed, QuotaExceededError } from './metering';
+export type { BillingConfig, InferenceLogConfig, LlmBillingCacheEntry, PgClient } from './config-cache';
+export { getLlmBillingCacheStats, getLlmBillingConfig, invalidateLlmBillingConfig } from './config-cache';
+export type { ChatConfig, ChatFunction, ChatMessage, ChatOptions, ChatResult, ChunkTableInfo, EmbedderConfig, EmbedderFunction, EmbeddingResult, GraphileLlmOptions, LlmModuleData, LlmUsage, MeteringConfig, RagDefaults } from './types';

package/index.js

@@ -31,8 +31,7 @@
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-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)
+exports.invalidateLlmBillingConfig = exports.getLlmBillingConfig = exports.getLlmBillingCacheStats = exports.QuotaExceededError = exports.meteredEmbed = exports.meteredChat = exports.logInferenceUsage = exports.buildChatCompleterFromModule = exports.buildChatCompleterFromEnv = exports.buildChatCompleter = exports.buildEmbedderFromModule = exports.buildEmbedderFromEnv = exports.buildEmbedder = exports.getAgentDiscovery = exports.clearAgentDiscoveryCache = exports.createLlmMeteringPlugin = exports.createLlmTextSearchPlugin = exports.createLlmTextMutationPlugin = exports.createLlmRagPlugin = exports.createLlmModulePlugin = exports.GraphileLlmPreset = exports.getLlmEnvOptions = void 0;
 var env_1 = require("./env");
 Object.defineProperty(exports, "getLlmEnvOptions", { enumerable: true, get: function () { return env_1.getLlmEnvOptions; } });
 // Preset (recommended entry point)
@@ -41,37 +40,34 @@ Object.defineProperty(exports, "GraphileLlmPreset", { enumerable: true, get: fun
 // 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");
-Object.defineProperty(exports, "createLlmTextSearchPlugin", { enumerable: true, get: function () { return text_search_plugin_1.createLlmTextSearchPlugin; } });
-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; } });
+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 text_search_plugin_1 = require("./plugins/text-search-plugin");
+Object.defineProperty(exports, "createLlmTextSearchPlugin", { enumerable: true, get: function () { return text_search_plugin_1.createLlmTextSearchPlugin; } });
 // 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; } });
+Object.defineProperty(exports, "getAgentDiscovery", { enumerable: true, get: function () { return agent_discovery_plugin_1.getAgentDiscovery; } });
 // Embedder utilities
 var embedder_1 = require("./embedder");
 Object.defineProperty(exports, "buildEmbedder", { enumerable: true, get: function () { return embedder_1.buildEmbedder; } });
-Object.defineProperty(exports, "buildEmbedderFromModule", { enumerable: true, get: function () { return embedder_1.buildEmbedderFromModule; } });
 Object.defineProperty(exports, "buildEmbedderFromEnv", { enumerable: true, get: function () { return embedder_1.buildEmbedderFromEnv; } });
+Object.defineProperty(exports, "buildEmbedderFromModule", { enumerable: true, get: function () { return embedder_1.buildEmbedderFromModule; } });
 // Chat completion utilities
 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)
+Object.defineProperty(exports, "buildChatCompleterFromModule", { enumerable: true, get: function () { return chat_1.buildChatCompleterFromModule; } });
 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, "meteredChat", { enumerable: true, get: function () { return metering_1.meteredChat; } });
+Object.defineProperty(exports, "meteredEmbed", { enumerable: true, get: function () { return metering_1.meteredEmbed; } });
 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, "getLlmBillingCacheStats", { enumerable: true, get: function () { return config_cache_1.getLlmBillingCacheStats; } });
 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

@@ -9,16 +9,16 @@
  * 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.
+ * Token counts:
+ *   - Chat: real provider counts via ChatResult.usage (from OllamaAdapter.stream())
+ *   - Embedding: real provider counts via EmbeddingResult.promptTokens (from /api/embed)
  *
  * 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';
+import type { BillingConfig, InferenceLogConfig, PgClient } from './config-cache';
+import type { ChatFunction, ChatMessage, ChatOptions, EmbedderFunction } from './types';
 /**
  * Callback matching Graphile's withPgClient signature.
  * Acquires a pg client, calls the callback, then releases the client.

package/metering.js

@@ -10,9 +10,9 @@
  * 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.
+ * Token counts:
+ *   - Chat: real provider counts via ChatResult.usage (from OllamaAdapter.stream())
+ *   - Embedding: real provider counts via EmbeddingResult.promptTokens (from /api/embed)
  *
  * The billing functions live in the tenant database and are called via the
  * Graphile `withPgClient` callback. Function locations (schema, names) are
@@ -94,7 +94,7 @@ async function logInferenceUsage(ctx, entry) {
                 entry.latencyMs, entry.ragEnabled, entry.chunksRetrieved,
                 entry.embeddingModel, entry.embeddingLatencyMs,
                 entry.status, entry.errorType,
-                entry.rawUsage ? JSON.stringify(entry.rawUsage) : null,
+                entry.rawUsage ? JSON.stringify(entry.rawUsage) : null
             ]);
         });
     }
@@ -114,31 +114,31 @@ async function meteredEmbed(embedder, text, ctx, options = {}) {
     const startTime = Date.now();
     // No billing context → just embed without metering
     if (!ctx) {
-        const result = await embedder(text);
+        const { embedding } = await embedder(text);
         return {
-            result,
+            result: embedding,
             metered: false,
             quotaExceeded: false,
-            latencyMs: Date.now() - startTime,
+            latencyMs: Date.now() - startTime
         };
     }
     const meterSlug = options.embeddingMeterSlug;
     if (!meterSlug) {
-        const result = await embedder(text);
+        const { embedding } = await embedder(text);
         return {
-            result,
+            result: embedding,
             metered: false,
             quotaExceeded: false,
-            latencyMs: Date.now() - startTime,
+            latencyMs: Date.now() - startTime
         };
     }
     if (options.skipMetering) {
-        const result = await embedder(text);
+        const { embedding } = await embedder(text);
         return {
-            result,
+            result: embedding,
             metered: false,
             quotaExceeded: false,
-            latencyMs: Date.now() - startTime,
+            latencyMs: Date.now() - startTime
         };
     }
     // Pre-check: can this entity afford this call?
@@ -152,8 +152,6 @@ async function meteredEmbed(embedder, text, ctx, options = {}) {
         allowed = true;
     }
     if (!allowed) {
-        // Placeholder: replace with actual provider token counts once generateWithUsage() is approved
-        const placeholderAmountTokens = Math.ceil(text.length / 4);
         logInferenceUsage(ctx, {
             databaseId: ctx.databaseId,
             entityId: ctx.entityId,
@@ -162,9 +160,9 @@ async function meteredEmbed(embedder, text, ctx, options = {}) {
             provider: options.provider ?? null,
             service: 'embedding',
             operation: 'create',
-            inputTokens: placeholderAmountTokens,
+            inputTokens: 0,
             outputTokens: 0,
-            totalTokens: placeholderAmountTokens,
+            totalTokens: 0,
             cacheReadTokens: null,
             cacheWriteTokens: null,
             latencyMs: Date.now() - startTime,
@@ -174,26 +172,25 @@ async function meteredEmbed(embedder, text, ctx, options = {}) {
             embeddingLatencyMs: null,
             status: 'quota_exceeded',
             errorType: null,
-            rawUsage: null,
+            rawUsage: null
         }).catch(() => { });
         return {
             result: null,
             metered: true,
             quotaExceeded: true,
-            latencyMs: Date.now() - startTime,
+            latencyMs: Date.now() - startTime
         };
     }
-    // Execute embedding
-    const result = await embedder(text);
+    // Execute embedding — real token count from provider via EmbeddingResult
+    const { embedding, promptTokens } = await embedder(text);
     const latencyMs = Date.now() - startTime;
-    // Placeholder: replace with actual provider token counts once generateWithUsage() is approved
-    const placeholderAmountTokens = Math.ceil(text.length / 4);
     ctx.withPgClient(ctx.pgSettings, async (pgClient) => {
-        await recordUsage(pgClient, ctx.billing, ctx.entityId, meterSlug, text.length, {
+        await recordUsage(pgClient, ctx.billing, ctx.entityId, meterSlug, promptTokens, {
             request_id: ctx.requestId,
             input_chars: text.length,
-            dims: result.length,
-            latency_ms: latencyMs,
+            prompt_tokens: promptTokens,
+            dims: embedding.length,
+            latency_ms: latencyMs
         });
     }).catch(() => { });
     // Log to inference usage table
@@ -205,9 +202,9 @@ async function meteredEmbed(embedder, text, ctx, options = {}) {
         provider: options.provider ?? null,
         service: 'embedding',
         operation: 'create',
-        inputTokens: placeholderAmountTokens,
+        inputTokens: promptTokens,
         outputTokens: 0,
-        totalTokens: placeholderAmountTokens,
+        totalTokens: promptTokens,
         cacheReadTokens: null,
         cacheWriteTokens: null,
         latencyMs,
@@ -217,13 +214,13 @@ async function meteredEmbed(embedder, text, ctx, options = {}) {
         embeddingLatencyMs: latencyMs,
         status: 'success',
         errorType: null,
-        rawUsage: null,
+        rawUsage: { prompt_tokens: promptTokens }
     }).catch(() => { });
     return {
-        result,
+        result: embedding,
         metered: true,
         quotaExceeded: false,
-        latencyMs,
+        latencyMs
     };
 }
 // ─── Metered Chat ───────────────────────────────────────────────────────────
@@ -233,31 +230,31 @@ async function meteredEmbed(embedder, text, ctx, options = {}) {
 async function meteredChat(chat, messages, ctx, chatOptions, meteringOptions = {}) {
     const startTime = Date.now();
     if (!ctx) {
-        const result = await chat(messages, chatOptions);
+        const chatResult = await chat(messages, chatOptions);
         return {
-            result,
+            result: chatResult.content,
             metered: false,
             quotaExceeded: false,
-            latencyMs: Date.now() - startTime,
+            latencyMs: Date.now() - startTime
         };
     }
     const meterSlug = meteringOptions.chatMeterSlug;
     if (!meterSlug) {
-        const result = await chat(messages, chatOptions);
+        const chatResult = await chat(messages, chatOptions);
         return {
-            result,
+            result: chatResult.content,
             metered: false,
             quotaExceeded: false,
-            latencyMs: Date.now() - startTime,
+            latencyMs: Date.now() - startTime
         };
     }
     if (meteringOptions.skipMetering) {
-        const result = await chat(messages, chatOptions);
+        const chatResult = await chat(messages, chatOptions);
         return {
-            result,
+            result: chatResult.content,
             metered: false,
             quotaExceeded: false,
-            latencyMs: Date.now() - startTime,
+            latencyMs: Date.now() - startTime
         };
     }
     // Pre-check: can this entity afford this call?
@@ -271,8 +268,7 @@ async function meteredChat(chat, messages, ctx, chatOptions, meteringOptions = {
         allowed = true;
     }
     if (!allowed) {
-        // Placeholder: replace with actual provider token counts once generateWithUsage() is approved
-        const placeholderInputTokens = Math.ceil(messages.reduce((sum, m) => sum + m.content.length, 0) / 4);
+        const estimatedInputTokens = Math.ceil(messages.reduce((sum, m) => sum + m.content.length, 0) / 4);
         logInferenceUsage(ctx, {
             databaseId: ctx.databaseId,
             entityId: ctx.entityId,
@@ -281,9 +277,9 @@ async function meteredChat(chat, messages, ctx, chatOptions, meteringOptions = {
             provider: meteringOptions.provider ?? null,
             service: 'llm',
             operation: 'chat',
-            inputTokens: placeholderInputTokens,
+            inputTokens: estimatedInputTokens,
             outputTokens: 0,
-            totalTokens: placeholderInputTokens,
+            totalTokens: estimatedInputTokens,
             cacheReadTokens: null,
             cacheWriteTokens: null,
             latencyMs: Date.now() - startTime,
@@ -293,33 +289,31 @@ async function meteredChat(chat, messages, ctx, chatOptions, meteringOptions = {
             embeddingLatencyMs: null,
             status: 'quota_exceeded',
             errorType: null,
-            rawUsage: null,
+            rawUsage: null
         }).catch(() => { });
         return {
             result: null,
             metered: true,
             quotaExceeded: true,
-            latencyMs: Date.now() - startTime,
+            latencyMs: Date.now() - startTime
         };
     }
-    // Execute chat completion
-    const result = await chat(messages, chatOptions);
+    // Execute chat completion — returns real token usage from provider
+    const chatResult = await chat(messages, chatOptions);
     const latencyMs = Date.now() - startTime;
-    // Placeholder: replace with actual provider token counts once generateWithUsage() is approved
-    const inputChars = messages.reduce((sum, m) => sum + m.content.length, 0);
-    const placeholderInputTokens = Math.ceil(inputChars / 4);
-    const placeholderOutputTokens = Math.ceil(result.length / 4);
-    const placeholderTotalTokens = placeholderInputTokens + placeholderOutputTokens;
+    const usage = chatResult.usage;
     ctx.withPgClient(ctx.pgSettings, async (pgClient) => {
-        await recordUsage(pgClient, ctx.billing, ctx.entityId, meterSlug, inputChars + result.length, {
+        await recordUsage(pgClient, ctx.billing, ctx.entityId, meterSlug, usage.totalTokens, {
             request_id: ctx.requestId,
-            input_chars: inputChars,
-            output_chars: result.length,
+            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,
+            latency_ms: latencyMs
         });
     }).catch(() => { });
-    // Log to inference usage table
+    // Log to inference usage table with real provider token counts
     logInferenceUsage(ctx, {
         databaseId: ctx.databaseId,
         entityId: ctx.entityId,
@@ -328,11 +322,11 @@ async function meteredChat(chat, messages, ctx, chatOptions, meteringOptions = {
         provider: meteringOptions.provider ?? null,
         service: 'llm',
         operation: 'chat',
-        inputTokens: placeholderInputTokens,
-        outputTokens: placeholderOutputTokens,
-        totalTokens: placeholderTotalTokens,
-        cacheReadTokens: null,
-        cacheWriteTokens: null,
+        inputTokens: usage.input,
+        outputTokens: usage.output,
+        totalTokens: usage.totalTokens,
+        cacheReadTokens: usage.cacheRead || null,
+        cacheWriteTokens: usage.cacheWrite || null,
         latencyMs,
         ragEnabled: false,
         chunksRetrieved: null,
@@ -340,13 +334,13 @@ async function meteredChat(chat, messages, ctx, chatOptions, meteringOptions = {
         embeddingLatencyMs: null,
         status: 'success',
         errorType: null,
-        rawUsage: null,
+        rawUsage: { reasoning: usage.reasoning }
     }).catch(() => { });
     return {
-        result,
+        result: chatResult.content,
         metered: true,
         quotaExceeded: false,
-        latencyMs,
+        latencyMs
     };
 }
 // ─── Error Types ────────────────────────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphile-llm",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "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,8 @@
     "url": "https://github.com/constructive-io/constructive/issues"
   },
   "dependencies": {
-    "@agentic-kit/ollama": "^1.2.1",
-    "graphile-cache": "^3.11.2"
+    "@agentic-kit/ollama": "^2.0.0",
+    "graphile-cache": "^3.12.0"
   },
   "peerDependencies": {
     "@dataplan/pg": "1.0.3",
@@ -54,11 +54,11 @@
   },
   "devDependencies": {
     "@types/node": "^22.19.11",
-    "graphile-connection-filter": "^1.10.3",
-    "graphile-search": "^1.13.2",
-    "graphile-test": "^4.15.3",
+    "graphile-connection-filter": "^1.11.0",
+    "graphile-search": "^1.14.0",
+    "graphile-test": "^4.16.0",
     "makage": "^0.3.0",
-    "pgsql-test": "^4.14.3"
+    "pgsql-test": "^4.15.0"
   },
   "keywords": [
     "postgraphile",
@@ -73,5 +73,5 @@
     "ollama",
     "openai"
   ],
-  "gitHead": "030e1144acbd4e288ee74eff2ac0021ca0382ef7"
+  "gitHead": "c0d04574f7719d92e67becb58d60791ae978c5f5"
 }

package/plugins/agent-discovery-plugin.js

@@ -16,7 +16,7 @@ const graphile_cache_1 = require("graphile-cache");
 // ─── Cache ──────────────────────────────────────────────────────────────────
 const agentDiscoveryCache = new graphile_cache_1.ModuleConfigCache({
     name: 'agent-discovery',
-    ttlMs: 60_000,
+    ttlMs: 60_000
 });
 /** Clear all cached discovery results (for testing) */
 function clearAgentDiscoveryCache() {
@@ -57,7 +57,7 @@ async function getAgentDiscovery(pool, dbname) {
                     : null,
                 task: row.task_table_name
                     ? { schemaName, tableName: row.task_table_name }
-                    : null,
+                    : null
             };
         }
     }

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

@@ -21,7 +21,7 @@
  * if loaded (it runs after this plugin and before the consumer plugins).
  */
 import type { GraphileConfig } from 'graphile-config';
-import type { EmbedderFunction, ChatFunction, GraphileLlmOptions } from '../types';
+import type { ChatFunction, EmbedderFunction, GraphileLlmOptions } from '../types';
 declare global {
     namespace GraphileBuild {
         interface Build {