feat: add graphile-llm plugin — server-side text-to-vector embedding for PostGraphile

Foundation bundle of the graphile-llm plugin:
- Embedder abstraction with provider resolution (@agentic-kit/ollama)
- LlmModulePlugin: resolves embedder from llm_module api_modules config, env vars, or preset options
- LlmTextSearchPlugin: adds text field to VectorNearbyInput for text-based vector search
- LlmTextMutationPlugin: adds *Text companion fields on mutation inputs for vector columns
- GraphileLlmPreset: bundles all plugins with configurable options
- Debug logging for token counts (metering deferred to billing system)

Refs: constructive-io/constructive-planning#743

Author: pyramation

graphile/graphile-llm/README.md

@@ -0,0 +1,29 @@
+# graphile-llm
+
+LLM integration plugin for PostGraphile v5. Provides server-side text-to-vector embedding for pgvector columns.
+
+## Features
+
+- **Text-based vector search**: Adds `text: String` field to `VectorNearbyInput` — clients pass natural language instead of raw float vectors
+- **Text mutation fields**: Adds `{column}Text: String` companion fields on create/update inputs for vector columns
+- **Pluggable embedders**: Provider-based architecture (Ollama via `@agentic-kit/ollama`, with room for OpenAI, etc.)
+- **Per-database configuration**: Reads `llm_module` from `services_public.api_modules` for per-API embedder config
+- **Plugin-conditional**: Fields only appear in the schema when the plugin is loaded
+
+## Usage
+
+```typescript
+import { GraphileLlmPreset } from 'graphile-llm';
+
+const preset = {
+  extends: [
+    GraphileLlmPreset({
+      defaultEmbedder: {
+        provider: 'ollama',
+        model: 'nomic-embed-text',
+        baseUrl: 'http://localhost:11434',
+      },
+    }),
+  ],
+};
+```

graphile/graphile-llm/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "graphile-llm",
+  "version": "0.1.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",
+  "license": "MIT",
+  "main": "index.js",
+  "module": "esm/index.js",
+  "types": "index.d.ts",
+  "scripts": {
+    "clean": "makage clean",
+    "prepack": "npm run build",
+    "build": "makage build",
+    "build:dev": "makage build --dev",
+    "lint": "eslint . --fix",
+    "test": "jest --forceExit",
+    "test:watch": "jest --watch"
+  },
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/constructive-io/constructive"
+  },
+  "bugs": {
+    "url": "https://github.com/constructive-io/constructive/issues"
+  },
+  "dependencies": {
+    "@agentic-kit/ollama": "^1.0.3"
+  },
+  "peerDependencies": {
+    "@dataplan/pg": "1.0.0",
+    "grafast": "1.0.0",
+    "graphile-build": "5.0.0",
+    "graphile-build-pg": "5.0.0",
+    "graphile-config": "1.0.0",
+    "graphile-search": "workspace:^",
+    "graphql": "16.13.0",
+    "pg-sql2": "5.0.0",
+    "postgraphile": "5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "graphile-search": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.11",
+    "makage": "^0.3.0"
+  },
+  "keywords": [
+    "postgraphile",
+    "graphile",
+    "constructive",
+    "plugin",
+    "llm",
+    "embedding",
+    "pgvector",
+    "rag",
+    "agentic-kit",
+    "ollama",
+    "openai"
+  ]
+}

graphile/graphile-llm/src/embedder.ts

@@ -0,0 +1,83 @@
+/**
+ * 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';
+import type { EmbedderConfig, EmbedderFunction, LlmModuleData } from './types';
+
+// ─── Built-in Providers ─────────────────────────────────────────────────────
+
+/**
+ * Create an Ollama-based embedder function.
+ */
+function createOllamaEmbedder(
+  baseUrl: string = 'http://localhost:11434',
+  model: string = 'nomic-embed-text',
+): EmbedderFunction {
+  const client = new OllamaClient(baseUrl);
+  return async (text: string): Promise<number[]> => {
+    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: EmbedderConfig): EmbedderFunction | null {
+  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: LlmModuleData): EmbedderFunction | null {
+  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(): EmbedderFunction | null {
+  const provider = process.env.EMBEDDER_PROVIDER;
+  if (!provider) return null;
+
+  return buildEmbedder({
+    provider,
+    model: process.env.EMBEDDER_MODEL,
+    baseUrl: process.env.EMBEDDER_BASE_URL,
+  });
+}

graphile/graphile-llm/src/index.ts

@@ -0,0 +1,47 @@
+/**
+ * graphile-llm — LLM Integration Plugin for PostGraphile v5
+ *
+ * Server-side text-to-vector embedding and text companion fields for
+ * pgvector columns. 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',
+ *       },
+ *     }),
+ *   ],
+ * };
+ * ```
+ */
+
+// 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';
+
+// Embedder utilities
+export {
+  buildEmbedder,
+  buildEmbedderFromModule,
+  buildEmbedderFromEnv,
+} from './embedder';
+
+// Types
+export type {
+  EmbedderFunction,
+  EmbedderConfig,
+  LlmModuleData,
+  GraphileLlmOptions,
+} from './types';

graphile/graphile-llm/src/plugins/llm-module-plugin.ts

@@ -0,0 +1,92 @@
+/**
+ * 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 { buildEmbedder, buildEmbedderFromEnv } from '../embedder';
+import type { EmbedderConfig, EmbedderFunction, GraphileLlmOptions } from '../types';
+
+// ─── TypeScript Augmentation ────────────────────────────────────────────────
+
+declare global {
+  namespace GraphileBuild {
+    interface Build {
+      /** The resolved embedder function, or null if LLM is not configured */
+      llmEmbedder: EmbedderFunction | null;
+    }
+  }
+  namespace GraphileConfig {
+    interface Plugins {
+      LlmModulePlugin: true;
+    }
+  }
+}
+
+/**
+ * Creates the LlmModulePlugin with the given options.
+ */
+export function createLlmModulePlugin(
+  options: GraphileLlmOptions = {}
+): GraphileConfig.Plugin {
+  const { defaultEmbedder } = options;
+
+  return {
+    name: 'LlmModulePlugin',
+    version: '0.1.0',
+    description:
+      'Resolves LLM embedder configuration and makes it 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: EmbedderFunction | null = 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.'
+            );
+          }
+
+          return build.extend(build, {
+            llmEmbedder: embedder,
+          }, 'LlmModulePlugin adding llmEmbedder to build');
+        },
+      },
+    },
+  };
+}