graphile-llm 0.2.0

package/plugins/text-mutation-plugin.js

@@ -0,0 +1,194 @@
+"use strict";
+/**
+ * LlmTextMutationPlugin
+ *
+ * Adds `{columnName}Text: String` companion fields on create/update mutation
+ * inputs for every vector column. When the client provides a text string in
+ * the companion field, the plugin embeds it server-side and injects the
+ * resulting vector into the actual column.
+ *
+ * Example:
+ *   mutation { createArticle(input: { embeddingText: "Machine learning concepts" }) }
+ *
+ * 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.
+ *
+ * Runtime embedding uses the v4-style resolver wrapping approach (same as
+ * graphile-upload-plugin and graphile-bucket-provisioner-plugin). grafserv v5
+ * supports this through its backwards-compatibility layer.
+ *
+ * The companion fields are only added when the LLM plugin is loaded.
+ * If no embedder is configured, the fields are still registered for schema
+ * stability but return a clear error at execution time.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLlmTextMutationPlugin = createLlmTextMutationPlugin;
+require("graphile-build");
+require("graphile-build-pg");
+/**
+ * Check if a codec is the pgvector `vector` type.
+ */
+function isVectorCodec(codec) {
+    return codec?.name === 'vector';
+}
+/**
+ * Collect the text→vector field mapping for a codec's vector columns.
+ * Returns a map of textFieldName → vectorFieldName.
+ */
+function getTextToVectorMapping(pgCodec, build) {
+    const mapping = {};
+    if (!pgCodec?.attributes)
+        return mapping;
+    for (const [attributeName, attribute] of Object.entries(pgCodec.attributes)) {
+        if (isVectorCodec(attribute.codec)) {
+            const fieldName = build.inflection.attribute({
+                codec: pgCodec,
+                attributeName,
+            });
+            mapping[`${fieldName}Text`] = fieldName;
+        }
+    }
+    return mapping;
+}
+/**
+ * Creates the LlmTextMutationPlugin.
+ *
+ * Hooks into GraphQLInputObjectType_fields for create/update input types
+ * and adds `{columnName}Text: String` for each vector column.
+ *
+ * Also wraps mutation resolvers via GraphQLObjectType_fields_field to
+ * intercept `*Text` companion field values, embed them, and inject the
+ * resulting vectors before the mutation executes.
+ */
+function createLlmTextMutationPlugin() {
+    return {
+        name: 'LlmTextMutationPlugin',
+        version: '0.1.0',
+        description: 'Adds text companion fields on mutation inputs for vector columns — ' +
+            'text is embedded server-side before storing',
+        after: [
+            'LlmModulePlugin',
+            'PgAttributesPlugin',
+            'PgMutationCreatePlugin',
+            'PgMutationUpdateDeletePlugin',
+            'VectorCodecPlugin',
+        ],
+        schema: {
+            hooks: {
+                /**
+                 * Add `{columnName}Text: String` fields to create/update input types
+                 * for tables that have vector columns.
+                 */
+                GraphQLInputObjectType_fields(fields, build, context) {
+                    const { scope: { isPgPatch, isPgBaseInput, isMutationInput, pgCodec, }, } = context;
+                    // Only intercept create/update input types for table rows
+                    if (!pgCodec?.attributes || (!isPgPatch && !isPgBaseInput && !isMutationInput)) {
+                        return fields;
+                    }
+                    const { graphql: { GraphQLString }, } = build;
+                    // Find vector columns on this table
+                    const vectorColumns = [];
+                    for (const [attributeName, attribute] of Object.entries(pgCodec.attributes)) {
+                        if (isVectorCodec(attribute.codec)) {
+                            vectorColumns.push(attributeName);
+                        }
+                    }
+                    if (vectorColumns.length === 0) {
+                        return fields;
+                    }
+                    let newFields = fields;
+                    for (const columnName of vectorColumns) {
+                        // Convert snake_case column name to camelCase field name
+                        const fieldName = build.inflection.attribute({
+                            codec: pgCodec,
+                            attributeName: columnName,
+                        });
+                        const textFieldName = `${fieldName}Text`;
+                        newFields = build.extend(newFields, {
+                            [textFieldName]: {
+                                type: GraphQLString,
+                                description: `Natural language text to embed server-side into the \`${fieldName}\` vector column. ` +
+                                    `Mutually exclusive with \`${fieldName}\` — provide one or the other. ` +
+                                    'Requires the LLM plugin to be configured with an embedding provider.',
+                            },
+                        }, `LlmTextMutationPlugin adding ${textFieldName} companion field for vector column '${columnName}'`);
+                    }
+                    return newFields;
+                },
+                /**
+                 * Wrap create/update mutation resolvers to intercept `*Text` companion
+                 * field values, embed them using the configured embedder, and inject
+                 * the resulting vector into the corresponding vector field.
+                 *
+                 * 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.
+                 */
+                GraphQLObjectType_fields_field(field, build, context) {
+                    const { scope: { isRootMutation, fieldName, pgCodec }, } = context;
+                    // Only wrap root mutation fields on tables with attributes
+                    if (!isRootMutation || !pgCodec || !pgCodec.attributes) {
+                        return field;
+                    }
+                    // Only wrap create/update mutations
+                    const isCreate = fieldName.startsWith('create');
+                    const isUpdate = fieldName.startsWith('update');
+                    if (!isCreate && !isUpdate) {
+                        return field;
+                    }
+                    // Build the text→vector mapping for this codec
+                    const textToVectorMap = getTextToVectorMapping(pgCodec, build);
+                    if (Object.keys(textToVectorMap).length === 0) {
+                        return field;
+                    }
+                    const embedder = build.llmEmbedder;
+                    const defaultResolver = (obj) => obj[fieldName];
+                    const { resolve: oldResolve = defaultResolver, ...rest } = field;
+                    return {
+                        ...rest,
+                        async resolve(source, args, graphqlContext, info) {
+                            // Walk through the input args and embed any *Text companion fields
+                            async function embedTextFields(obj) {
+                                if (!obj || typeof obj !== 'object')
+                                    return;
+                                const pending = [];
+                                for (const key of Object.keys(obj)) {
+                                    const value = obj[key];
+                                    // Check if this key is a *Text companion field
+                                    if (key in textToVectorMap && typeof value === 'string') {
+                                        const vectorFieldName = textToVectorMap[key];
+                                        pending.push((async () => {
+                                            if (!embedder) {
+                                                throw new Error(`EMBED_NOT_CONFIGURED: Cannot embed ${key} — no embedding provider configured. ` +
+                                                    'Set defaultEmbedder in GraphileLlmPreset options or EMBEDDER_PROVIDER env var.');
+                                            }
+                                            const startTime = Date.now();
+                                            const vector = await embedder(value);
+                                            const latencyMs = Date.now() - startTime;
+                                            console.log(`[graphile-llm] Mutation embed: field=${key}, dims=${vector.length}, latency=${latencyMs}ms`);
+                                            // Inject the vector into the corresponding field
+                                            obj[vectorFieldName] = vector;
+                                            // Remove the consumed *Text field
+                                            delete obj[key];
+                                        })());
+                                        continue;
+                                    }
+                                    // Recurse into nested objects (e.g. input.article.embeddingText)
+                                    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+                                        pending.push(embedTextFields(value));
+                                    }
+                                }
+                                if (pending.length > 0) {
+                                    await Promise.all(pending);
+                                }
+                            }
+                            await embedTextFields(args);
+                            return oldResolve(source, args, graphqlContext, info);
+                        },
+                    };
+                },
+            },
+        },
+    };
+}

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

@@ -0,0 +1,41 @@
+/**
+ * LlmTextSearchPlugin
+ *
+ * Adds a `text: String` field to `VectorNearbyInput` when the LLM plugin
+ * is enabled. This allows clients to pass natural language text instead of
+ * raw float vectors for similarity search — the plugin converts text to
+ * vectors server-side using the configured embedder.
+ *
+ * This mirrors the graphile-postgis pattern where `WithinDistanceInput`
+ * accepts a compound input (point + distance) and the plugin handles
+ * the conversion to SQL internally.
+ *
+ * The `text` field is mutually exclusive with `vector`: clients provide
+ * one or the other. When `text` is provided, the plugin embeds it and
+ * injects the resulting vector into the normal pgvector pipeline.
+ *
+ * Runtime embedding for query filters uses the v4-style resolver wrapping
+ * approach (same as graphile-upload-plugin). When a connection query's
+ * `where` argument includes a VectorNearbyInput with `text`, the resolver
+ * wrapper embeds the text and replaces it with the resulting vector before
+ * the plan executes.
+ *
+ * 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.
+ */
+import type { GraphileConfig } from 'graphile-config';
+declare global {
+    namespace GraphileConfig {
+        interface Plugins {
+            LlmTextSearchPlugin: true;
+        }
+    }
+}
+/**
+ * Creates the LlmTextSearchPlugin.
+ *
+ * Hooks into VectorNearbyInput to add a `text` field alongside the
+ * existing `vector` field. When a user provides `text`, the plugin's
+ * resolver wrapper embeds it before passing to pgvector.
+ */
+export declare function createLlmTextSearchPlugin(): GraphileConfig.Plugin;

package/plugins/text-search-plugin.js

@@ -0,0 +1,166 @@
+"use strict";
+/**
+ * LlmTextSearchPlugin
+ *
+ * Adds a `text: String` field to `VectorNearbyInput` when the LLM plugin
+ * is enabled. This allows clients to pass natural language text instead of
+ * raw float vectors for similarity search — the plugin converts text to
+ * vectors server-side using the configured embedder.
+ *
+ * This mirrors the graphile-postgis pattern where `WithinDistanceInput`
+ * accepts a compound input (point + distance) and the plugin handles
+ * the conversion to SQL internally.
+ *
+ * The `text` field is mutually exclusive with `vector`: clients provide
+ * one or the other. When `text` is provided, the plugin embeds it and
+ * injects the resulting vector into the normal pgvector pipeline.
+ *
+ * Runtime embedding for query filters uses the v4-style resolver wrapping
+ * approach (same as graphile-upload-plugin). When a connection query's
+ * `where` argument includes a VectorNearbyInput with `text`, the resolver
+ * wrapper embeds the text and replaces it with the resulting vector before
+ * the plan executes.
+ *
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLlmTextSearchPlugin = createLlmTextSearchPlugin;
+/**
+ * Check if a codec has any pgvector `vector` columns.
+ */
+function hasVectorColumns(pgCodec) {
+    if (!pgCodec?.attributes)
+        return false;
+    for (const attribute of Object.values(pgCodec.attributes)) {
+        if (attribute.codec?.name === 'vector')
+            return true;
+    }
+    return false;
+}
+/**
+ * Recursively walk a `where` argument object and embed any VectorNearbyInput
+ * values that have `text` instead of `vector`.
+ */
+async function embedTextInWhere(obj, embedder) {
+    if (!obj || typeof obj !== 'object')
+        return;
+    const pending = [];
+    for (const key of Object.keys(obj)) {
+        const value = obj[key];
+        if (!value || typeof value !== 'object')
+            continue;
+        // Detect VectorNearbyInput shape: has `text` and no `vector`
+        if ('text' in value && typeof value.text === 'string' && !value.vector) {
+            pending.push((async () => {
+                const startTime = Date.now();
+                const vector = await embedder(value.text);
+                const latencyMs = Date.now() - startTime;
+                console.log(`[graphile-llm] Search embed: field=${key}, dims=${vector.length}, latency=${latencyMs}ms`);
+                // Replace text with vector
+                value.vector = vector;
+                delete value.text;
+            })());
+            continue;
+        }
+        // Recurse into nested filter objects (AND, OR, etc.)
+        if (!Array.isArray(value)) {
+            pending.push(embedTextInWhere(value, embedder));
+        }
+        else {
+            // Handle arrays (e.g. AND: [...], OR: [...])
+            for (const item of value) {
+                pending.push(embedTextInWhere(item, embedder));
+            }
+        }
+    }
+    if (pending.length > 0) {
+        await Promise.all(pending);
+    }
+}
+/**
+ * Creates the LlmTextSearchPlugin.
+ *
+ * Hooks into VectorNearbyInput to add a `text` field alongside the
+ * existing `vector` field. When a user provides `text`, the plugin's
+ * resolver wrapper embeds it before passing to pgvector.
+ */
+function createLlmTextSearchPlugin() {
+    return {
+        name: 'LlmTextSearchPlugin',
+        version: '0.1.0',
+        description: 'Adds text-to-vector embedding support on VectorNearbyInput filter fields',
+        after: [
+            'LlmModulePlugin',
+            'UnifiedSearchPlugin',
+            'VectorCodecPlugin',
+        ],
+        schema: {
+            hooks: {
+                /**
+                 * Add the `text: String` field to VectorNearbyInput.
+                 *
+                 * We intercept VectorNearbyInput specifically and add a `text` field.
+                 * The field is optional — clients provide either `text` or `vector`.
+                 */
+                GraphQLInputObjectType_fields(fields, build, context) {
+                    const { scope: { inputObjectTypeName }, } = context;
+                    if (inputObjectTypeName !== 'VectorNearbyInput') {
+                        return fields;
+                    }
+                    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.',
+                        },
+                    }, 'LlmTextSearchPlugin adding text field to VectorNearbyInput');
+                },
+                /**
+                 * Wrap connection query resolvers to intercept `where` arguments that
+                 * contain VectorNearbyInput with `text`, embed the text, and replace
+                 * it with the resulting vector before the plan executes.
+                 *
+                 * Uses the same v4-style resolver wrapping pattern as graphile-upload-plugin
+                 * and graphile-bucket-provisioner-plugin.
+                 */
+                GraphQLObjectType_fields_field(field, build, context) {
+                    const { scope: { isRootQuery, pgCodec }, } = context;
+                    // Only wrap root query fields on tables with vector columns
+                    if (!isRootQuery || !pgCodec || !hasVectorColumns(pgCodec)) {
+                        return field;
+                    }
+                    const embedder = build.llmEmbedder;
+                    if (!embedder)
+                        return field;
+                    const defaultResolver = (obj) => obj[context.scope.fieldName];
+                    const { resolve: oldResolve = defaultResolver, ...rest } = field;
+                    return {
+                        ...rest,
+                        async resolve(source, args, graphqlContext, info) {
+                            // If the query has a `where` argument, check for text fields
+                            if (args?.where) {
+                                await embedTextInWhere(args.where, embedder);
+                            }
+                            // Also handle `filter` for relay-style connections
+                            if (args?.filter) {
+                                await embedTextInWhere(args.filter, embedder);
+                            }
+                            return oldResolve(source, args, graphqlContext, info);
+                        },
+                    };
+                },
+                finalize(schema, build) {
+                    const embedder = build.llmEmbedder;
+                    if (!embedder) {
+                        console.log('[graphile-llm] No embedder available — text field on VectorNearbyInput ' +
+                            'will return errors if used. Configure an embedding provider to enable.');
+                    }
+                    return schema;
+                },
+            },
+        },
+    };
+}

package/preset.d.ts

@@ -0,0 +1,55 @@
+/**
+ * GraphileLlmPreset
+ *
+ * A preset that bundles all LLM plugins for PostGraphile v5.
+ * This is the recommended entry point — add it to your preset's `extends` array.
+ *
+ * When enabled, this preset:
+ * - 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)
+ *
+ * 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.
+ *
+ * @example
+ * ```typescript
+ * import { GraphileLlmPreset } from 'graphile-llm';
+ *
+ * const preset = {
+ *   extends: [
+ *     ConstructivePreset,
+ *     GraphileLlmPreset(),
+ *   ],
+ * };
+ * ```
+ *
+ * @example With explicit embedder configuration:
+ * ```typescript
+ * import { GraphileLlmPreset } from 'graphile-llm';
+ *
+ * const preset = {
+ *   extends: [
+ *     ConstructivePreset,
+ *     GraphileLlmPreset({
+ *       defaultEmbedder: {
+ *         provider: 'ollama',
+ *         model: 'nomic-embed-text',
+ *         baseUrl: 'http://localhost:11434',
+ *       },
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+import type { GraphileConfig } from 'graphile-config';
+import type { GraphileLlmOptions } from './types';
+/**
+ * Creates a preset that includes all LLM plugins.
+ *
+ * @param options - Configuration options for the LLM plugin
+ * @returns A GraphileConfig.Preset to add to your extends array
+ */
+export declare function GraphileLlmPreset(options?: GraphileLlmOptions): GraphileConfig.Preset;
+export default GraphileLlmPreset;

package/preset.js

@@ -0,0 +1,77 @@
+"use strict";
+/**
+ * GraphileLlmPreset
+ *
+ * A preset that bundles all LLM plugins for PostGraphile v5.
+ * This is the recommended entry point — add it to your preset's `extends` array.
+ *
+ * When enabled, this preset:
+ * - 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)
+ *
+ * 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.
+ *
+ * @example
+ * ```typescript
+ * import { GraphileLlmPreset } from 'graphile-llm';
+ *
+ * const preset = {
+ *   extends: [
+ *     ConstructivePreset,
+ *     GraphileLlmPreset(),
+ *   ],
+ * };
+ * ```
+ *
+ * @example With explicit embedder configuration:
+ * ```typescript
+ * import { GraphileLlmPreset } from 'graphile-llm';
+ *
+ * const preset = {
+ *   extends: [
+ *     ConstructivePreset,
+ *     GraphileLlmPreset({
+ *       defaultEmbedder: {
+ *         provider: 'ollama',
+ *         model: 'nomic-embed-text',
+ *         baseUrl: 'http://localhost:11434',
+ *       },
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GraphileLlmPreset = GraphileLlmPreset;
+const llm_module_plugin_1 = require("./plugins/llm-module-plugin");
+const text_search_plugin_1 = require("./plugins/text-search-plugin");
+const text_mutation_plugin_1 = require("./plugins/text-mutation-plugin");
+const rag_plugin_1 = require("./plugins/rag-plugin");
+/**
+ * Creates a preset that includes all LLM plugins.
+ *
+ * @param options - Configuration options for the LLM plugin
+ * @returns A GraphileConfig.Preset to add to your extends array
+ */
+function GraphileLlmPreset(options = {}) {
+    const { enableTextSearch = true, enableTextMutations = true, enableRag = false, ragDefaults, } = options;
+    const plugins = [
+        (0, llm_module_plugin_1.createLlmModulePlugin)(options),
+    ];
+    if (enableTextSearch) {
+        plugins.push((0, text_search_plugin_1.createLlmTextSearchPlugin)());
+    }
+    if (enableTextMutations) {
+        plugins.push((0, text_mutation_plugin_1.createLlmTextMutationPlugin)());
+    }
+    if (enableRag) {
+        plugins.push((0, rag_plugin_1.createLlmRagPlugin)(ragDefaults));
+    }
+    return {
+        plugins,
+    };
+}
+exports.default = GraphileLlmPreset;