graphile-llm 0.2.0

package/plugins/llm-module-plugin.js

@@ -0,0 +1,85 @@
+"use strict";
+/**
+ * LlmModulePlugin
+ *
+ * Detects and loads the `llm_module` configuration from `services_public.api_modules`.
+ * Makes the resolved embedder available to other plugins via the build context.
+ *
+ * This plugin is the foundation that enables per-database LLM configuration.
+ * When an API has an `llm_module` configured, the embedder is resolved and
+ * stored on the build object for other plugins (text search, text mutations)
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLlmModulePlugin = createLlmModulePlugin;
+const embedder_1 = require("../embedder");
+const chat_1 = require("../chat");
+/**
+ * Creates the LlmModulePlugin with the given options.
+ */
+function createLlmModulePlugin(options = {}) {
+    const { defaultEmbedder, defaultChatCompleter } = options;
+    return {
+        name: 'LlmModulePlugin',
+        version: '0.1.0',
+        description: 'Resolves LLM embedder and chat completer configuration and makes them available to other plugins',
+        schema: {
+            hooks: {
+                build(build) {
+                    // Resolve the embedder from available sources:
+                    // 1. Preset default embedder option
+                    // 2. Environment variables
+                    // 3. null (disabled)
+                    //
+                    // Note: Per-database llm_module resolution happens at request time,
+                    // not schema build time. The defaultEmbedder and env vars provide
+                    // the schema-build-time embedder so that text fields are registered
+                    // in the GraphQL schema. At execution time, the actual embedder
+                    // used may differ per-database based on the llm_module config.
+                    let embedder = null;
+                    if (defaultEmbedder) {
+                        embedder = (0, embedder_1.buildEmbedder)(defaultEmbedder);
+                    }
+                    if (!embedder) {
+                        embedder = (0, embedder_1.buildEmbedderFromEnv)();
+                    }
+                    if (embedder) {
+                        console.log('[graphile-llm] Embedder configured — LLM text fields will be enabled');
+                    }
+                    else {
+                        console.log('[graphile-llm] No embedder configured. Set defaultEmbedder in preset options ' +
+                            'or EMBEDDER_PROVIDER env var to enable text-to-vector fields.');
+                    }
+                    // Resolve the chat completer from available sources:
+                    // 1. Preset default chat completer option
+                    // 2. Environment variables
+                    // 3. null (disabled — RAG queries will error)
+                    let chat = null;
+                    if (defaultChatCompleter) {
+                        chat = (0, chat_1.buildChatCompleter)(defaultChatCompleter);
+                    }
+                    if (!chat) {
+                        chat = (0, chat_1.buildChatCompleterFromEnv)();
+                    }
+                    if (chat) {
+                        console.log('[graphile-llm] Chat completer configured — RAG queries will be enabled');
+                    }
+                    else {
+                        console.log('[graphile-llm] No chat completer configured. Set defaultChatCompleter in preset ' +
+                            'options or CHAT_PROVIDER env var to enable RAG queries.');
+                    }
+                    return build.extend(build, {
+                        llmEmbedder: embedder,
+                        llmChatCompleter: chat,
+                    }, 'LlmModulePlugin adding llmEmbedder and llmChatCompleter to build');
+                },
+            },
+        },
+    };
+}

package/plugins/rag-plugin.d.ts

@@ -0,0 +1,36 @@
+/**
+ * LlmRagPlugin
+ *
+ * Adds RAG (Retrieval-Augmented Generation) query support to PostGraphile v5.
+ *
+ * When enabled, this plugin:
+ * 1. Discovers tables with @hasChunks smart tag during schema build
+ * 2. Adds a `ragQuery` root query field that orchestrates:
+ *    embed prompt → pgvector search chunks → assemble context → call chat LLM → return answer
+ * 3. Adds an `embedText` root query field for standalone text-to-vector conversion
+ *
+ * Uses the extendSchema + grafast lambda pattern (same as bucket-provisioner
+ * and presigned-url plugins) for async operations at execution time.
+ *
+ * RAG is a consumer of graphile-search's pgvector adapter — it uses the existing
+ * chunk-aware tables but orchestrates the full LLM synthesis pipeline.
+ *
+ * Resolution order for embedder and chat completer:
+ *   1. build.llmEmbedder / build.llmChatCompleter (from LlmModulePlugin)
+ *   2. Falls back to error if not configured
+ */
+import type { GraphileConfig } from 'graphile-config';
+import type { RagDefaults } from '../types';
+declare global {
+    namespace GraphileConfig {
+        interface Plugins {
+            LlmRagPlugin: true;
+        }
+    }
+}
+/**
+ * Creates the LlmRagPlugin.
+ *
+ * @param ragDefaults - Default configuration for RAG queries
+ */
+export declare function createLlmRagPlugin(ragDefaults?: RagDefaults): GraphileConfig.Plugin;

package/plugins/rag-plugin.js

@@ -0,0 +1,344 @@
+"use strict";
+/**
+ * LlmRagPlugin
+ *
+ * Adds RAG (Retrieval-Augmented Generation) query support to PostGraphile v5.
+ *
+ * When enabled, this plugin:
+ * 1. Discovers tables with @hasChunks smart tag during schema build
+ * 2. Adds a `ragQuery` root query field that orchestrates:
+ *    embed prompt → pgvector search chunks → assemble context → call chat LLM → return answer
+ * 3. Adds an `embedText` root query field for standalone text-to-vector conversion
+ *
+ * Uses the extendSchema + grafast lambda pattern (same as bucket-provisioner
+ * and presigned-url plugins) for async operations at execution time.
+ *
+ * RAG is a consumer of graphile-search's pgvector adapter — it uses the existing
+ * chunk-aware tables but orchestrates the full LLM synthesis pipeline.
+ *
+ * Resolution order for embedder and chat completer:
+ *   1. build.llmEmbedder / build.llmChatCompleter (from LlmModulePlugin)
+ *   2. Falls back to error if not configured
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createLlmRagPlugin = createLlmRagPlugin;
+const grafast_1 = require("grafast");
+const graphile_utils_1 = require("graphile-utils");
+// ─── Constants ──────────────────────────────────────────────────────────────
+const DEFAULT_CONTEXT_LIMIT = 5;
+const DEFAULT_MAX_TOKENS = 4000;
+const DEFAULT_MIN_SIMILARITY = 0;
+const DEFAULT_SYSTEM_PROMPT = 'You are a helpful assistant. Answer the user\'s question based ONLY on the ' +
+    'following context. If the context does not contain enough information to ' +
+    'answer, say so. Do not make up information.\n\n' +
+    '--- CONTEXT ---\n';
+// ─── Helpers ────────────────────────────────────────────────────────────────
+/**
+ * Parse @hasChunks smart tag from a codec's extensions into ChunkTableInfo.
+ * Mirrors the parsing logic in graphile-search's pgvector adapter.
+ */
+function parseHasChunksTag(raw, codec) {
+    let parsed;
+    if (typeof raw === 'string') {
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    else if (typeof raw === 'object' && raw !== null) {
+        parsed = raw;
+    }
+    else {
+        return null;
+    }
+    if (!parsed.chunksTable)
+        return null;
+    const chunksSchema = parsed.chunksSchema
+        || codec?.extensions?.pg?.schemaName
+        || null;
+    return {
+        parentCodecName: codec.name || 'unknown',
+        chunksSchema,
+        chunksTableName: parsed.chunksTable,
+        parentFkField: parsed.parentFk || 'parent_id',
+        parentPkField: parsed.parentPk || 'id',
+        embeddingField: parsed.embeddingField || 'embedding',
+        contentField: parsed.contentField || 'content',
+    };
+}
+/**
+ * Discover all chunk-aware tables from the pgRegistry.
+ */
+function discoverChunkTables(build) {
+    const chunkTables = [];
+    const pgRegistry = build.pgRegistry;
+    if (!pgRegistry)
+        return chunkTables;
+    // Scan all codecs for @hasChunks smart tag
+    for (const source of Object.values(pgRegistry.pgResources || {})) {
+        const codec = source?.codec;
+        if (!codec?.attributes)
+            continue;
+        const tags = codec.extensions?.tags;
+        if (!tags?.hasChunks)
+            continue;
+        const info = parseHasChunksTag(tags.hasChunks, codec);
+        if (info) {
+            chunkTables.push(info);
+        }
+    }
+    return chunkTables;
+}
+/**
+ * Build a SQL query string to search a chunks table for similar embeddings.
+ */
+function buildChunkSearchSql(table, vectorString, limit, maxDistance) {
+    const schema = table.chunksSchema;
+    const qualifiedTable = schema
+        ? `"${schema}"."${table.chunksTableName}"`
+        : `"${table.chunksTableName}"`;
+    const embeddingCol = `"${table.embeddingField}"`;
+    const contentCol = `"${table.contentField}"`;
+    const parentFkCol = `"${table.parentFkField}"`;
+    let text = `
+    SELECT
+      ${contentCol} AS content,
+      ${parentFkCol}::text AS parent_id,
+      (${embeddingCol} <=> $1::vector) AS distance
+    FROM ${qualifiedTable}
+  `;
+    const values = [vectorString];
+    if (maxDistance !== null) {
+        text += ` WHERE (${embeddingCol} <=> $1::vector) <= $2`;
+        values.push(maxDistance);
+    }
+    text += ` ORDER BY ${embeddingCol} <=> $1::vector LIMIT $${values.length + 1}`;
+    values.push(limit);
+    return { text, values };
+}
+/**
+ * Assemble retrieved chunks into a context string for the LLM prompt.
+ */
+function assembleContext(chunks) {
+    return chunks
+        .map((chunk, i) => `[Source ${i + 1}] (similarity: ${(1 - chunk.distance).toFixed(3)})\n${chunk.content}`)
+        .join('\n\n---\n\n');
+}
+// ─── Plugin Factory ─────────────────────────────────────────────────────────
+/**
+ * Creates the LlmRagPlugin.
+ *
+ * @param ragDefaults - Default configuration for RAG queries
+ */
+function createLlmRagPlugin(ragDefaults = {}) {
+    // Chunk tables discovered during schema build, used by the plan at execution time
+    let chunkTables = [];
+    let embedder = null;
+    let chatCompleter = null;
+    const schemaExtension = (0, graphile_utils_1.extendSchema)((build) => {
+        // Discover chunk-aware tables from pgRegistry
+        chunkTables = discoverChunkTables(build);
+        embedder = build.llmEmbedder || null;
+        chatCompleter = build.llmChatCompleter || null;
+        if (chunkTables.length > 0) {
+            console.log(`[graphile-llm] RAG plugin discovered ${chunkTables.length} chunk-aware table(s): ` +
+                chunkTables.map((t) => t.parentCodecName).join(', '));
+        }
+        else {
+            console.log('[graphile-llm] RAG plugin found no @hasChunks tables. ' +
+                'ragQuery will still work if chunks tables are queried directly.');
+        }
+        return {
+            typeDefs: (0, graphile_utils_1.gql) `
+        """A source chunk retrieved during RAG context assembly."""
+        type RagSource {
+          """The text content of the retrieved chunk."""
+          content: String!
+          """Cosine similarity score (0..1, higher = more similar)."""
+          similarity: Float!
+          """The parent table this chunk belongs to."""
+          tableName: String
+          """The parent row ID this chunk belongs to."""
+          parentId: String
+        }
+
+        """Response from a RAG (Retrieval-Augmented Generation) query."""
+        type RagResponse {
+          """The LLM-generated answer based on retrieved context."""
+          answer: String!
+          """The source chunks used as context for the answer."""
+          sources: [RagSource!]!
+          """Approximate token count for the request (logging only, not metered)."""
+          tokensUsed: Int
+        }
+
+        """Response from an embedText query."""
+        type EmbedTextResponse {
+          """The resulting vector embedding."""
+          vector: [Float!]!
+          """Number of dimensions in the vector."""
+          dimensions: Int!
+        }
+
+        extend type Query {
+          """
+          RAG (Retrieval-Augmented Generation) query.
+          Embeds the prompt, searches chunk-aware tables for similar content,
+          assembles context, and calls the chat LLM to generate an answer.
+          Requires both an embedding provider and a chat provider to be configured.
+          """
+          ragQuery(
+            """The natural language question or prompt."""
+            prompt: String!
+            """Maximum number of context chunks to include (default: 5)."""
+            contextLimit: Int
+            """Minimum similarity threshold (0..1). Chunks below this are excluded."""
+            minSimilarity: Float
+            """Custom system prompt. Overrides the default RAG system prompt."""
+            systemPrompt: String
+          ): RagResponse
+
+          """
+          Convert text to a vector embedding using the configured embedding provider.
+          Useful for client-side vector operations when you need the raw vector.
+          """
+          embedText(
+            """The text to embed."""
+            text: String!
+          ): EmbedTextResponse
+        }
+      `,
+            plans: {
+                Query: {
+                    ragQuery(_$root, fieldArgs) {
+                        const $prompt = fieldArgs.getRaw('prompt');
+                        const $contextLimit = fieldArgs.getRaw('contextLimit');
+                        const $minSimilarity = fieldArgs.getRaw('minSimilarity');
+                        const $systemPrompt = fieldArgs.getRaw('systemPrompt');
+                        const $withPgClient = (0, grafast_1.context)().get('withPgClient');
+                        const $pgSettings = (0, grafast_1.context)().get('pgSettings');
+                        const $combined = (0, grafast_1.object)({
+                            prompt: $prompt,
+                            contextLimit: $contextLimit,
+                            minSimilarity: $minSimilarity,
+                            systemPrompt: $systemPrompt,
+                            withPgClient: $withPgClient,
+                            pgSettings: $pgSettings,
+                        });
+                        return (0, grafast_1.lambda)($combined, async (input) => {
+                            const { prompt, contextLimit: queryContextLimit, minSimilarity: queryMinSimilarity, systemPrompt: querySystemPrompt, withPgClient, pgSettings, } = input;
+                            if (!prompt || typeof prompt !== 'string') {
+                                throw new Error('RAG_INVALID_PROMPT: prompt is required');
+                            }
+                            if (!embedder) {
+                                throw new Error('RAG_EMBEDDER_NOT_CONFIGURED: An embedding provider must be configured ' +
+                                    'to use ragQuery. Set defaultEmbedder in GraphileLlmPreset options.');
+                            }
+                            if (!chatCompleter) {
+                                throw new Error('RAG_CHAT_NOT_CONFIGURED: A chat completion provider must be configured ' +
+                                    'to use ragQuery. Set defaultChatCompleter in GraphileLlmPreset options.');
+                            }
+                            // Resolve parameters with defaults
+                            const limit = queryContextLimit ?? ragDefaults.contextLimit ?? DEFAULT_CONTEXT_LIMIT;
+                            const minSim = queryMinSimilarity ?? ragDefaults.minSimilarity ?? DEFAULT_MIN_SIMILARITY;
+                            const maxDistance = minSim > 0 ? (1 - minSim) : null;
+                            const systemPromptTemplate = querySystemPrompt ?? ragDefaults.systemPrompt ?? DEFAULT_SYSTEM_PROMPT;
+                            // Step 1: Embed the prompt
+                            const startEmbed = Date.now();
+                            const vector = await embedder(prompt);
+                            const embedLatency = Date.now() - startEmbed;
+                            const vectorString = `[${vector.join(',')}]`;
+                            console.log(`[graphile-llm] RAG embed: dims=${vector.length}, latency=${embedLatency}ms`);
+                            // Step 2: Search chunks tables for similar content
+                            const allChunks = [];
+                            if (chunkTables.length > 0) {
+                                await withPgClient(pgSettings, async (pgClient) => {
+                                    for (const table of chunkTables) {
+                                        const query = buildChunkSearchSql(table, vectorString, limit, maxDistance);
+                                        const result = await pgClient.query(query);
+                                        for (const row of result.rows) {
+                                            allChunks.push({
+                                                content: row.content,
+                                                parent_id: row.parent_id,
+                                                distance: parseFloat(row.distance),
+                                                table_name: table.parentCodecName,
+                                            });
+                                        }
+                                    }
+                                });
+                            }
+                            // Sort by distance (ascending) and take top N
+                            allChunks.sort((a, b) => a.distance - b.distance);
+                            const topChunks = allChunks.slice(0, limit);
+                            if (topChunks.length === 0) {
+                                return {
+                                    answer: 'No relevant context found for your query. ' +
+                                        'Try broadening your search or lowering the minimum similarity threshold.',
+                                    sources: [],
+                                    tokensUsed: null,
+                                };
+                            }
+                            // Step 3: Assemble context
+                            const contextText = assembleContext(topChunks);
+                            // Step 4: Call chat completion
+                            const startChat = Date.now();
+                            const answer = await chatCompleter([
+                                { role: 'system', content: systemPromptTemplate + contextText },
+                                { role: 'user', content: prompt },
+                            ], {
+                                maxTokens: ragDefaults.maxTokens ?? DEFAULT_MAX_TOKENS,
+                            });
+                            const chatLatency = Date.now() - startChat;
+                            console.log(`[graphile-llm] RAG chat: sources=${topChunks.length}, latency=${chatLatency}ms`);
+                            // Step 5: Return response
+                            return {
+                                answer,
+                                sources: topChunks.map((chunk) => ({
+                                    content: chunk.content,
+                                    similarity: 1 - chunk.distance,
+                                    tableName: chunk.table_name,
+                                    parentId: chunk.parent_id,
+                                })),
+                                tokensUsed: null, // Deferred to metering system
+                            };
+                        });
+                    },
+                    embedText(_$root, fieldArgs) {
+                        const $text = fieldArgs.getRaw('text');
+                        return (0, grafast_1.lambda)($text, async (text) => {
+                            if (!text || typeof text !== 'string') {
+                                throw new Error('EMBED_INVALID_TEXT: text is required');
+                            }
+                            if (!embedder) {
+                                throw new Error('EMBED_NOT_CONFIGURED: An embedding provider must be configured ' +
+                                    'to use embedText. Set defaultEmbedder in GraphileLlmPreset options.');
+                            }
+                            const startTime = Date.now();
+                            const vector = await embedder(text);
+                            const latencyMs = Date.now() - startTime;
+                            console.log(`[graphile-llm] embedText: dims=${vector.length}, latency=${latencyMs}ms`);
+                            return {
+                                vector,
+                                dimensions: vector.length,
+                            };
+                        });
+                    },
+                },
+            },
+        };
+    });
+    return {
+        ...schemaExtension,
+        name: 'LlmRagPlugin',
+        version: '0.1.0',
+        description: 'RAG (Retrieval-Augmented Generation) query support — ' +
+            'detects @hasChunks tables and adds ragQuery/embedText fields',
+        after: [
+            'LlmModulePlugin',
+            'UnifiedSearchPlugin',
+            'VectorCodecPlugin',
+        ],
+    };
+}

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

@@ -0,0 +1,44 @@
+/**
+ * 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.
+ */
+import 'graphile-build';
+import 'graphile-build-pg';
+import type { GraphileConfig } from 'graphile-config';
+declare global {
+    namespace GraphileConfig {
+        interface Plugins {
+            LlmTextMutationPlugin: true;
+        }
+    }
+}
+/**
+ * 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.
+ */
+export declare function createLlmTextMutationPlugin(): GraphileConfig.Plugin;