graphile-llm 0.2.0

package/esm/chat.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Chat Completion — pluggable chat/completion provider for the Graphile LLM plugin
+ *
+ * Provides a provider-based architecture for LLM chat completions.
+ * Currently supports Ollama via @agentic-kit/ollama.
+ *
+ * Used by the RAG plugin to generate answers from retrieved context.
+ *
+ * Resolution order mirrors the embedder:
+ *   1. The `llm_module` api_modules configuration (per-database)
+ *   2. The preset's `defaultChatCompleter` option (fallback for dev/testing)
+ *   3. Environment variables (CHAT_PROVIDER, CHAT_MODEL, CHAT_BASE_URL)
+ */
+import type { ChatConfig, ChatFunction, LlmModuleData } from './types';
+/**
+ * Build a chat completion function from a config object.
+ *
+ * @returns A ChatFunction, or null if the provider is not recognized
+ */
+export declare function buildChatCompleter(config: ChatConfig): ChatFunction | null;
+/**
+ * Build a chat completer from an `llm_module` api_modules row.
+ *
+ * @param data - The llm_module data from services_public.api_modules
+ * @returns A ChatFunction, or null if the chat provider is not configured
+ */
+export declare function buildChatCompleterFromModule(data: LlmModuleData): ChatFunction | null;
+/**
+ * Resolve a chat completer from environment variables.
+ * This is a fallback for development when no llm_module or defaultChatCompleter is configured.
+ *
+ * Environment variables:
+ *   CHAT_PROVIDER - Provider name ('ollama')
+ *   CHAT_MODEL    - Model identifier (e.g. 'llama3')
+ *   CHAT_BASE_URL - Provider base URL
+ */
+export declare function buildChatCompleterFromEnv(): ChatFunction | null;

package/esm/chat.js

@@ -0,0 +1,97 @@
+/**
+ * Chat Completion — pluggable chat/completion provider for the Graphile LLM plugin
+ *
+ * Provides a provider-based architecture for LLM chat completions.
+ * Currently supports Ollama via @agentic-kit/ollama.
+ *
+ * Used by the RAG plugin to generate answers from retrieved context.
+ *
+ * Resolution order mirrors the embedder:
+ *   1. The `llm_module` api_modules configuration (per-database)
+ *   2. The preset's `defaultChatCompleter` option (fallback for dev/testing)
+ *   3. Environment variables (CHAT_PROVIDER, CHAT_MODEL, CHAT_BASE_URL)
+ */
+import OllamaClient from '@agentic-kit/ollama';
+// ─── Built-in Providers ─────────────────────────────────────────────────────
+/**
+ * Create an Ollama-based chat completion function.
+ *
+ * Uses OllamaClient.generate() with a messages array, which internally
+ * routes to the /api/chat endpoint.
+ */
+function createOllamaChatCompleter(baseUrl = 'http://localhost:11434', model = 'llama3') {
+    const client = new OllamaClient(baseUrl);
+    return async (messages, options) => {
+        // Build the input for OllamaClient.generate() in chat mode
+        const input = {
+            model,
+            messages: messages.filter((m) => m.role !== 'system'),
+        };
+        // Extract system message if present
+        const systemMsg = messages.find((m) => m.role === 'system');
+        if (systemMsg) {
+            input.system = systemMsg.content;
+        }
+        if (options?.temperature !== undefined) {
+            input.temperature = options.temperature;
+        }
+        const startTime = Date.now();
+        const response = await client.generate(input);
+        const latencyMs = Date.now() - startTime;
+        // Token count logging (metering deferred to billing system)
+        console.log(`[graphile-llm] Chat completion: model=${model}, latency=${latencyMs}ms, ` +
+            `messages=${messages.length}`);
+        return response;
+    };
+}
+// ─── Chat Completer Construction ────────────────────────────────────────────
+/**
+ * Build a chat completion function from a config object.
+ *
+ * @returns A ChatFunction, or null if the provider is not recognized
+ */
+export function buildChatCompleter(config) {
+    switch (config.provider) {
+        case 'ollama':
+            return createOllamaChatCompleter(config.baseUrl, config.model);
+        // Future: 'openai', 'anthropic', 'custom'
+        default:
+            return null;
+    }
+}
+// ─── Resolution from LLM Module ─────────────────────────────────────────────
+/**
+ * Build a chat completer from an `llm_module` api_modules row.
+ *
+ * @param data - The llm_module data from services_public.api_modules
+ * @returns A ChatFunction, or null if the chat provider is not configured
+ */
+export function buildChatCompleterFromModule(data) {
+    if (!data.chat_provider)
+        return null;
+    return buildChatCompleter({
+        provider: data.chat_provider,
+        model: data.chat_model,
+        baseUrl: data.chat_base_url,
+        apiKey: data.api_key_ref,
+    });
+}
+/**
+ * Resolve a chat completer from environment variables.
+ * This is a fallback for development when no llm_module or defaultChatCompleter is configured.
+ *
+ * Environment variables:
+ *   CHAT_PROVIDER - Provider name ('ollama')
+ *   CHAT_MODEL    - Model identifier (e.g. 'llama3')
+ *   CHAT_BASE_URL - Provider base URL
+ */
+export function buildChatCompleterFromEnv() {
+    const provider = process.env.CHAT_PROVIDER;
+    if (!provider)
+        return null;
+    return buildChatCompleter({
+        provider,
+        model: process.env.CHAT_MODEL,
+        baseUrl: process.env.CHAT_BASE_URL,
+    });
+}

package/esm/embedder.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Embedder — pluggable text-to-vector embedding for the Graphile LLM plugin
+ *
+ * Provides a provider-based architecture for converting text into vector
+ * embeddings. Currently supports Ollama via @agentic-kit/ollama.
+ *
+ * The embedder is resolved at request time from:
+ *   1. The `llm_module` api_modules configuration (per-database)
+ *   2. The preset's `defaultEmbedder` option (fallback for dev/testing)
+ *   3. Environment variables (EMBEDDER_PROVIDER, EMBEDDER_MODEL, EMBEDDER_BASE_URL)
+ */
+import type { EmbedderConfig, EmbedderFunction, LlmModuleData } from './types';
+/**
+ * Build an embedder function from a config object.
+ *
+ * @returns An EmbedderFunction, or null if the provider is not recognized
+ */
+export declare function buildEmbedder(config: EmbedderConfig): EmbedderFunction | null;
+/**
+ * Build an embedder from an `llm_module` api_modules row.
+ *
+ * @param data - The llm_module data from services_public.api_modules
+ * @returns An EmbedderFunction, or null if the provider is not supported
+ */
+export declare function buildEmbedderFromModule(data: LlmModuleData): EmbedderFunction | null;
+/**
+ * Resolve an embedder from environment variables.
+ * This is a fallback for development when no llm_module or defaultEmbedder is configured.
+ *
+ * Environment variables:
+ *   EMBEDDER_PROVIDER - Provider name ('ollama')
+ *   EMBEDDER_MODEL    - Model identifier
+ *   EMBEDDER_BASE_URL - Provider base URL
+ */
+export declare function buildEmbedderFromEnv(): EmbedderFunction | null;

package/esm/embedder.js

@@ -0,0 +1,71 @@
+/**
+ * Embedder — pluggable text-to-vector embedding for the Graphile LLM plugin
+ *
+ * Provides a provider-based architecture for converting text into vector
+ * embeddings. Currently supports Ollama via @agentic-kit/ollama.
+ *
+ * The embedder is resolved at request time from:
+ *   1. The `llm_module` api_modules configuration (per-database)
+ *   2. The preset's `defaultEmbedder` option (fallback for dev/testing)
+ *   3. Environment variables (EMBEDDER_PROVIDER, EMBEDDER_MODEL, EMBEDDER_BASE_URL)
+ */
+import OllamaClient from '@agentic-kit/ollama';
+// ─── Built-in Providers ─────────────────────────────────────────────────────
+/**
+ * Create an Ollama-based embedder function.
+ */
+function createOllamaEmbedder(baseUrl = 'http://localhost:11434', model = 'nomic-embed-text') {
+    const client = new OllamaClient(baseUrl);
+    return async (text) => {
+        return client.generateEmbedding(text, model);
+    };
+}
+// ─── Embedder Construction ──────────────────────────────────────────────────
+/**
+ * Build an embedder function from a config object.
+ *
+ * @returns An EmbedderFunction, or null if the provider is not recognized
+ */
+export function buildEmbedder(config) {
+    switch (config.provider) {
+        case 'ollama':
+            return createOllamaEmbedder(config.baseUrl, config.model);
+        // Future: 'openai', 'anthropic', 'custom'
+        default:
+            return null;
+    }
+}
+// ─── Resolution from LLM Module ─────────────────────────────────────────────
+/**
+ * Build an embedder from an `llm_module` api_modules row.
+ *
+ * @param data - The llm_module data from services_public.api_modules
+ * @returns An EmbedderFunction, or null if the provider is not supported
+ */
+export function buildEmbedderFromModule(data) {
+    return buildEmbedder({
+        provider: data.embedding_provider,
+        model: data.embedding_model,
+        baseUrl: data.embedding_base_url,
+        apiKey: data.api_key_ref,
+    });
+}
+/**
+ * Resolve an embedder from environment variables.
+ * This is a fallback for development when no llm_module or defaultEmbedder is configured.
+ *
+ * Environment variables:
+ *   EMBEDDER_PROVIDER - Provider name ('ollama')
+ *   EMBEDDER_MODEL    - Model identifier
+ *   EMBEDDER_BASE_URL - Provider base URL
+ */
+export function buildEmbedderFromEnv() {
+    const provider = process.env.EMBEDDER_PROVIDER;
+    if (!provider)
+        return null;
+    return buildEmbedder({
+        provider,
+        model: process.env.EMBEDDER_MODEL,
+        baseUrl: process.env.EMBEDDER_BASE_URL,
+    });
+}

package/esm/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * graphile-llm — LLM Integration Plugin for PostGraphile v5
+ *
+ * Server-side text-to-vector embedding, text companion fields for pgvector
+ * columns, and RAG (Retrieval-Augmented Generation) query support.
+ *
+ * Moves the embedding logic from the client (CLI --auto-embed) into the
+ * Graphile server layer so clients work with text/prompts instead of raw
+ * float vectors.
+ *
+ * @example
+ * ```typescript
+ * import { GraphileLlmPreset } from 'graphile-llm';
+ *
+ * const preset = {
+ *   extends: [
+ *     GraphileLlmPreset({
+ *       defaultEmbedder: {
+ *         provider: 'ollama',
+ *         model: 'nomic-embed-text',
+ *       },
+ *       defaultChatCompleter: {
+ *         provider: 'ollama',
+ *         model: 'llama3',
+ *       },
+ *       enableRag: true,
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+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 { 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';

package/esm/index.js

@@ -0,0 +1,42 @@
+/**
+ * graphile-llm — LLM Integration Plugin for PostGraphile v5
+ *
+ * Server-side text-to-vector embedding, text companion fields for pgvector
+ * columns, and RAG (Retrieval-Augmented Generation) query support.
+ *
+ * Moves the embedding logic from the client (CLI --auto-embed) into the
+ * Graphile server layer so clients work with text/prompts instead of raw
+ * float vectors.
+ *
+ * @example
+ * ```typescript
+ * import { GraphileLlmPreset } from 'graphile-llm';
+ *
+ * const preset = {
+ *   extends: [
+ *     GraphileLlmPreset({
+ *       defaultEmbedder: {
+ *         provider: 'ollama',
+ *         model: 'nomic-embed-text',
+ *       },
+ *       defaultChatCompleter: {
+ *         provider: 'ollama',
+ *         model: 'llama3',
+ *       },
+ *       enableRag: true,
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+// Preset (recommended entry point)
+export { GraphileLlmPreset } from './preset';
+// Individual plugins
+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';
+// Embedder utilities
+export { buildEmbedder, buildEmbedderFromModule, buildEmbedderFromEnv, } from './embedder';
+// Chat completion utilities
+export { buildChatCompleter, buildChatCompleterFromModule, buildChatCompleterFromEnv, } from './chat';

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

@@ -0,0 +1,38 @@
+/**
+ * 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
+ */
+import type { GraphileConfig } from 'graphile-config';
+import type { EmbedderFunction, ChatFunction, GraphileLlmOptions } from '../types';
+declare global {
+    namespace GraphileBuild {
+        interface Build {
+            /** The resolved embedder function, or null if LLM is not configured */
+            llmEmbedder: EmbedderFunction | null;
+            /** The resolved chat completion function, or null if not configured */
+            llmChatCompleter: ChatFunction | null;
+        }
+    }
+    namespace GraphileConfig {
+        interface Plugins {
+            LlmModulePlugin: true;
+        }
+    }
+}
+/**
+ * Creates the LlmModulePlugin with the given options.
+ */
+export declare function createLlmModulePlugin(options?: GraphileLlmOptions): GraphileConfig.Plugin;

package/esm/plugins/llm-module-plugin.js

@@ -0,0 +1,82 @@
+/**
+ * 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
+ */
+import { buildEmbedder, buildEmbedderFromEnv } from '../embedder';
+import { buildChatCompleter, buildChatCompleterFromEnv } from '../chat';
+/**
+ * Creates the LlmModulePlugin with the given options.
+ */
+export 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 = buildEmbedder(defaultEmbedder);
+                    }
+                    if (!embedder) {
+                        embedder = 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 = buildChatCompleter(defaultChatCompleter);
+                    }
+                    if (!chat) {
+                        chat = 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/esm/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;