graphile-llm 1.21.6 → 1.21.8

package/embed-inputs.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Plan-time text-to-vector embedding.
+ *
+ * Under Grafast a field's `resolve()` runs after its plan has executed, so the
+ * SQL has already been built by the time a resolver wrapper could embed text.
+ * Instead, input fields that carry text to embed are tagged with an
+ * `EmbedRule` where they are declared, and `planTimeEmbedding` (run from a
+ * `finalize` hook) wraps the plan of every object field whose arguments can
+ * reach a tagged input field. The wrapper shadows `fieldArgs.getRaw` so every
+ * consumer of those arguments (connection-filter's `where` applyPlan, the
+ * create/update `args.apply`) reads a step that embeds the text first.
+ */
+import type { GraphQLInputType, GraphQLSchema } from 'graphql';
+import type { LlmConfigOverrides } from './embedder';
+export type QuotaPolicy = 'degrade' | 'throw';
+/** Stored on a GraphQL input field's `extensions[EMBED_EXT]`. */
+export type EmbedRule = 
+/** `VectorNearbyInput.text`: embedded into the sibling `into` field. */
+{
+    kind: 'nearby';
+    into: string;
+    onQuotaExceeded: QuotaPolicy;
+}
+/** `unifiedSearch: String`: becomes `{ __text, __vector }` for graphile-search. */
+ | {
+    kind: 'unified';
+    onQuotaExceeded: QuotaPolicy;
+}
+/** `{col}Text` on a create input or patch. `required` means the column is NOT NULL. */
+ | {
+    kind: 'companion';
+    into: string;
+    required: boolean;
+};
+export declare const EMBED_EXT = "graphileLlmEmbed";
+export type VectorEmbedder = (text: string) => Promise<number[] | null>;
+export declare function embedField<T extends object>(rule: EmbedRule, spec: T): T;
+/**
+ * `build.llmEmbedder` resolves to `{ embedding }` from the providers and to
+ * `number[] | null` once the metering plugin has wrapped it.
+ */
+export declare function toVectorEmbedder(raw: unknown): VectorEmbedder | null;
+export declare function resolveConfigOverrides(graphqlContext: any): Promise<LlmConfigOverrides | null>;
+export declare function createEmbedIndex(graphql: any): {
+    reaches: (type: GraphQLInputType) => boolean;
+    embedValue: (type: any, value: any, embed: VectorEmbedder | null) => Promise<any>;
+};
+/**
+ * Wraps the plan of every object field whose arguments reach a tagged input
+ * field. Runs in `finalize` because args are attached after the
+ * `GraphQLObjectType_fields_field` hook. Idempotent per schema, so every plugin
+ * that tags fields can call it without depending on the others being loaded.
+ */
+export declare function planTimeEmbedding(schema: GraphQLSchema, build: any): GraphQLSchema;

package/embed-inputs.js

@@ -0,0 +1,292 @@
+"use strict";
+/**
+ * Plan-time text-to-vector embedding.
+ *
+ * Under Grafast a field's `resolve()` runs after its plan has executed, so the
+ * SQL has already been built by the time a resolver wrapper could embed text.
+ * Instead, input fields that carry text to embed are tagged with an
+ * `EmbedRule` where they are declared, and `planTimeEmbedding` (run from a
+ * `finalize` hook) wraps the plan of every object field whose arguments can
+ * reach a tagged input field. The wrapper shadows `fieldArgs.getRaw` so every
+ * consumer of those arguments (connection-filter's `where` applyPlan, the
+ * create/update `args.apply`) reads a step that embeds the text first.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EMBED_EXT = void 0;
+exports.embedField = embedField;
+exports.toVectorEmbedder = toVectorEmbedder;
+exports.resolveConfigOverrides = resolveConfigOverrides;
+exports.createEmbedIndex = createEmbedIndex;
+exports.planTimeEmbedding = planTimeEmbedding;
+const grafast_1 = require("grafast");
+const embedder_1 = require("./embedder");
+exports.EMBED_EXT = 'graphileLlmEmbed';
+function embedField(rule, spec) {
+    return { ...spec, extensions: { ...spec.extensions, [exports.EMBED_EXT]: rule } };
+}
+/**
+ * `build.llmEmbedder` resolves to `{ embedding }` from the providers and to
+ * `number[] | null` once the metering plugin has wrapped it.
+ */
+function toVectorEmbedder(raw) {
+    if (typeof raw !== 'function')
+        return null;
+    return async (text) => {
+        const result = await raw(text);
+        const vector = Array.isArray(result) ? result : result?.embedding;
+        return Array.isArray(vector) && vector.length > 0 ? vector : null;
+    };
+}
+function isNonEmptyVector(value) {
+    return Array.isArray(value) && value.length > 0;
+}
+async function resolveConfigOverrides(graphqlContext) {
+    const ctx = graphqlContext?.constructive;
+    if (!ctx?.useLlm)
+        return null;
+    try {
+        const llm = await ctx.useLlm();
+        if (!llm?.embeddingModel)
+            return null;
+        return {
+            embeddingModel: llm.embeddingModel,
+            embeddingBaseUrl: llm.embeddingBaseUrl,
+            chatModel: llm.chatModel ?? undefined,
+            chatBaseUrl: llm.chatBaseUrl ?? undefined
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Binds the embedder to one request's per-database model overrides, resolved on first use. */
+function forRequest(embedder, graphqlContext) {
+    if (!embedder)
+        return null;
+    let overrides;
+    return async (text) => {
+        overrides ??= resolveConfigOverrides(graphqlContext);
+        const resolved = await overrides;
+        const startTime = Date.now();
+        const vector = await embedder_1.llmConfigStore.run(resolved, () => embedder(text));
+        if (vector) {
+            console.log(`[graphile-llm] embed: dims=${vector.length}, latency=${Date.now() - startTime}ms`);
+        }
+        return vector;
+    };
+}
+function createEmbedIndex(graphql) {
+    const { getNamedType, isInputObjectType, isListType, isNonNullType } = graphql;
+    const reachesMemo = new WeakMap();
+    const inputObjectFields = (type) => Object.values(type.getFields());
+    const namedInputObject = (field) => {
+        const named = getNamedType(field.type);
+        return isInputObjectType(named) ? named : null;
+    };
+    // Filter types are cyclic (AND/OR/NOT, forward and backward relations), so
+    // reachability is a fixed point over everything reachable from `type`; a
+    // depth-first walk that memoizes a provisional answer mid-cycle gets it wrong.
+    function reaches(type) {
+        const start = getNamedType(type);
+        if (!isInputObjectType(start))
+            return false;
+        const known = reachesMemo.get(start);
+        if (known !== undefined)
+            return known;
+        const pending = [];
+        const stack = [start];
+        const seen = new Set();
+        while (stack.length > 0) {
+            const node = stack.pop();
+            if (seen.has(node) || reachesMemo.has(node))
+                continue;
+            seen.add(node);
+            pending.push(node);
+            for (const field of inputObjectFields(node)) {
+                const child = namedInputObject(field);
+                if (child)
+                    stack.push(child);
+            }
+        }
+        const hit = new Set(pending.filter((node) => inputObjectFields(node).some((f) => f.extensions?.[exports.EMBED_EXT])));
+        const isHit = (node) => hit.has(node) || reachesMemo.get(node) === true;
+        let changed = true;
+        while (changed) {
+            changed = false;
+            for (const node of pending) {
+                if (hit.has(node))
+                    continue;
+                if (inputObjectFields(node).some((f) => {
+                    const child = namedInputObject(f);
+                    return child !== null && isHit(child);
+                })) {
+                    hit.add(node);
+                    changed = true;
+                }
+            }
+        }
+        for (const node of pending)
+            reachesMemo.set(node, hit.has(node));
+        return reachesMemo.get(start);
+    }
+    async function applyRule(rule, fieldName, typeName, value, next, embed) {
+        const text = value[fieldName];
+        switch (rule.kind) {
+            case 'nearby': {
+                delete next[fieldName];
+                const hasVector = isNonEmptyVector(value[rule.into]);
+                const hasText = typeof text === 'string';
+                if (hasVector && hasText) {
+                    throw new Error(`${typeName}: provide exactly one of \`${rule.into}\` or \`${fieldName}\`, not both.`);
+                }
+                if (!hasVector && !hasText) {
+                    throw new Error(`${typeName}: provide exactly one of \`${rule.into}\` or \`${fieldName}\`; neither was given.`);
+                }
+                if (hasVector)
+                    return;
+                if (!embed) {
+                    throw new Error(`${typeName}: \`${fieldName}\` needs an embedding provider and none is configured; ` +
+                        `send \`${rule.into}\` instead.`);
+                }
+                const vector = await embed(text);
+                if (vector) {
+                    next[rule.into] = vector;
+                }
+                else if (rule.onQuotaExceeded === 'throw') {
+                    throw new Error(`${typeName}: embedding failed (quota exceeded or provider unavailable). ` +
+                        'Upgrade your plan or adjust onQuotaExceeded to \'degrade\' for graceful fallback.');
+                }
+                return;
+            }
+            case 'unified': {
+                if (typeof text !== 'string' || text.trim().length === 0 || !embed)
+                    return;
+                const vector = await embed(text);
+                if (vector) {
+                    next[fieldName] = { __text: text, __vector: vector };
+                }
+                else if (rule.onQuotaExceeded === 'throw') {
+                    throw new Error(`${fieldName}: embedding failed (quota exceeded or provider unavailable). ` +
+                        'onQuotaExceeded is set to \'throw\'. ' +
+                        'Upgrade your plan or adjust onQuotaExceeded to \'degrade\' for text-only fallback.');
+                }
+                return;
+            }
+            case 'companion': {
+                delete next[fieldName];
+                if (isNonEmptyVector(value[rule.into]))
+                    return;
+                if (typeof text !== 'string') {
+                    if (rule.required) {
+                        throw new Error(`${typeName}: provide either \`${rule.into}\` or \`${fieldName}\`.`);
+                    }
+                    return;
+                }
+                if (!embed) {
+                    throw new Error(`EMBED_NOT_CONFIGURED: Cannot embed ${fieldName} — no embedding provider configured. ` +
+                        'Set defaultEmbedder in GraphileLlmPreset options or EMBEDDER_PROVIDER env var.');
+                }
+                const vector = await embed(text);
+                if (!vector) {
+                    throw new Error(`EMBED_QUOTA_EXCEEDED: Cannot embed ${fieldName} — embedding quota exceeded. ` +
+                        'Upgrade your plan or wait for the next billing period.');
+                }
+                next[rule.into] = vector;
+                return;
+            }
+        }
+    }
+    /** Returns `value` itself when its type cannot reach a tagged field. */
+    async function embedValue(type, value, embed) {
+        if (value == null)
+            return value;
+        const inner = isNonNullType(type) ? type.ofType : type;
+        if (isListType(inner)) {
+            if (!Array.isArray(value) || !reaches(inner.ofType))
+                return value;
+            return Promise.all(value.map((item) => embedValue(inner.ofType, item, embed)));
+        }
+        if (!isInputObjectType(inner) || !reaches(inner))
+            return value;
+        const next = { ...value };
+        const jobs = [];
+        for (const [name, field] of Object.entries(inner.getFields())) {
+            const rule = field.extensions?.[exports.EMBED_EXT];
+            if (rule) {
+                jobs.push(applyRule(rule, name, inner.name, value, next, embed));
+            }
+            else if (value[name] != null && reaches(field.type)) {
+                jobs.push(embedValue(field.type, value[name], embed).then((embedded) => { next[name] = embedded; }));
+            }
+        }
+        await Promise.all(jobs);
+        return next;
+    }
+    return { reaches, embedValue };
+}
+function withEmbeddedArgs(originalPlan, argNames, embeddable, index, embedder) {
+    return function planWithEmbeddedArgs(parent, fieldArgs, info) {
+        const originalGetRaw = fieldArgs.getRaw;
+        const roots = new Map();
+        const rootStep = (argName) => {
+            let $root = roots.get(argName);
+            if ($root)
+                return $root;
+            const $raw = originalGetRaw.call(fieldArgs, argName);
+            const absent = $raw instanceof grafast_1.ConstantStep && $raw.data === undefined;
+            if (absent || !embeddable.has(argName)) {
+                $root = $raw;
+            }
+            else {
+                const type = fieldArgs.typeAt(argName);
+                $root = $raw.withLayerPlan(() => (0, grafast_1.lambda)({ raw: $raw, ctx: (0, grafast_1.context)() }, ({ raw, ctx }) => index.embedValue(type, raw, forRequest(embedder, ctx))));
+            }
+            roots.set(argName, $root);
+            return $root;
+        };
+        // grafast reads `fieldArgs.getRaw` through the object (apply, processAfter,
+        // `$arg` getters, getBaked), so shadowing it here reaches every consumer.
+        fieldArgs.getRaw = function getRawEmbedded(path) {
+            if (path === undefined) {
+                const steps = Object.fromEntries(argNames.map((n) => [n, rootStep(n)]));
+                return steps[argNames[0]].withLayerPlan(() => (0, grafast_1.object)(steps));
+            }
+            const [argName, ...rest] = typeof path === 'string' ? [path] : path;
+            if (!embeddable.has(argName))
+                return originalGetRaw.call(fieldArgs, path);
+            const $root = rootStep(argName);
+            return (rest.length === 0 ? $root : $root.withLayerPlan(() => (0, grafast_1.access)($root, rest)));
+        };
+        return originalPlan(parent, fieldArgs, info);
+    };
+}
+const processedSchemas = new WeakSet();
+/**
+ * Wraps the plan of every object field whose arguments reach a tagged input
+ * field. Runs in `finalize` because args are attached after the
+ * `GraphQLObjectType_fields_field` hook. Idempotent per schema, so every plugin
+ * that tags fields can call it without depending on the others being loaded.
+ */
+function planTimeEmbedding(schema, build) {
+    if (processedSchemas.has(schema))
+        return schema;
+    processedSchemas.add(schema);
+    const { graphql } = build;
+    const index = createEmbedIndex(graphql);
+    const embedder = toVectorEmbedder(build.llmEmbedder);
+    for (const type of Object.values(schema.getTypeMap())) {
+        if (!graphql.isObjectType(type) || type.name.startsWith('__'))
+            continue;
+        for (const field of Object.values(type.getFields())) {
+            const grafastExt = field.extensions?.grafast;
+            if (typeof grafastExt?.plan !== 'function')
+                continue;
+            const embeddable = new Set(field.args.filter((a) => index.reaches(a.type)).map((a) => a.name));
+            if (embeddable.size === 0)
+                continue;
+            const argNames = field.args.map((a) => a.name);
+            grafastExt.plan = withEmbeddedArgs(grafastExt.plan, argNames, embeddable, index, embedder);
+        }
+    }
+    return schema;
+}

package/embedder.d.ts

@@ -5,7 +5,7 @@
  * embeddings. Currently supports Ollama via @agentic-kit/ollama.
  *
  * Per-request model/baseUrl overrides are read from AsyncLocalStorage
- * (`llmConfigStore`). The text-search-plugin sets these overrides from
+ * (`llmConfigStore`). embed-inputs.ts sets these overrides from
  * the database's `llm_module` config via `ctx.useLlm()`. This means
  * the same embedder function — and its metering wrapper — handle every
  * request, regardless of which tenant's model config applies.
@@ -25,7 +25,7 @@ export interface LlmConfigOverrides {
 /**
  * AsyncLocalStorage for per-request LLM config overrides.
  *
- * Set by the text-search-plugin resolver wrapper (from ctx.useLlm()),
+ * Set by the plan-time embedding step in embed-inputs.ts (from ctx.useLlm()),
  * read by the embedder at call time. The metering wrapper sits between
  * them and is completely unaware — it just wraps the same function.
  */

package/embedder.js

@@ -6,7 +6,7 @@
  * embeddings. Currently supports Ollama via @agentic-kit/ollama.
  *
  * Per-request model/baseUrl overrides are read from AsyncLocalStorage
- * (`llmConfigStore`). The text-search-plugin sets these overrides from
+ * (`llmConfigStore`). embed-inputs.ts sets these overrides from
  * the database's `llm_module` config via `ctx.useLlm()`. This means
  * the same embedder function — and its metering wrapper — handle every
  * request, regardless of which tenant's model config applies.
@@ -25,7 +25,7 @@ const env_1 = require("./env");
 /**
  * AsyncLocalStorage for per-request LLM config overrides.
  *
- * Set by the text-search-plugin resolver wrapper (from ctx.useLlm()),
+ * Set by the plan-time embedding step in embed-inputs.ts (from ctx.useLlm()),
  * read by the embedder at call time. The metering wrapper sits between
  * them and is completely unaware — it just wraps the same function.
  */

package/esm/embed-inputs.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Plan-time text-to-vector embedding.
+ *
+ * Under Grafast a field's `resolve()` runs after its plan has executed, so the
+ * SQL has already been built by the time a resolver wrapper could embed text.
+ * Instead, input fields that carry text to embed are tagged with an
+ * `EmbedRule` where they are declared, and `planTimeEmbedding` (run from a
+ * `finalize` hook) wraps the plan of every object field whose arguments can
+ * reach a tagged input field. The wrapper shadows `fieldArgs.getRaw` so every
+ * consumer of those arguments (connection-filter's `where` applyPlan, the
+ * create/update `args.apply`) reads a step that embeds the text first.
+ */
+import type { GraphQLInputType, GraphQLSchema } from 'graphql';
+import type { LlmConfigOverrides } from './embedder';
+export type QuotaPolicy = 'degrade' | 'throw';
+/** Stored on a GraphQL input field's `extensions[EMBED_EXT]`. */
+export type EmbedRule = 
+/** `VectorNearbyInput.text`: embedded into the sibling `into` field. */
+{
+    kind: 'nearby';
+    into: string;
+    onQuotaExceeded: QuotaPolicy;
+}
+/** `unifiedSearch: String`: becomes `{ __text, __vector }` for graphile-search. */
+ | {
+    kind: 'unified';
+    onQuotaExceeded: QuotaPolicy;
+}
+/** `{col}Text` on a create input or patch. `required` means the column is NOT NULL. */
+ | {
+    kind: 'companion';
+    into: string;
+    required: boolean;
+};
+export declare const EMBED_EXT = "graphileLlmEmbed";
+export type VectorEmbedder = (text: string) => Promise<number[] | null>;
+export declare function embedField<T extends object>(rule: EmbedRule, spec: T): T;
+/**
+ * `build.llmEmbedder` resolves to `{ embedding }` from the providers and to
+ * `number[] | null` once the metering plugin has wrapped it.
+ */
+export declare function toVectorEmbedder(raw: unknown): VectorEmbedder | null;
+export declare function resolveConfigOverrides(graphqlContext: any): Promise<LlmConfigOverrides | null>;
+export declare function createEmbedIndex(graphql: any): {
+    reaches: (type: GraphQLInputType) => boolean;
+    embedValue: (type: any, value: any, embed: VectorEmbedder | null) => Promise<any>;
+};
+/**
+ * Wraps the plan of every object field whose arguments reach a tagged input
+ * field. Runs in `finalize` because args are attached after the
+ * `GraphQLObjectType_fields_field` hook. Idempotent per schema, so every plugin
+ * that tags fields can call it without depending on the others being loaded.
+ */
+export declare function planTimeEmbedding(schema: GraphQLSchema, build: any): GraphQLSchema;