graphile-llm 0.11.4 → 0.12.0

package/preset.js

@@ -11,8 +11,8 @@
  * - Adds `{column}Text: String` companion fields on mutation inputs for vector columns
  * - Optionally enables billing/metering via the LlmMeteringPlugin
  *
- * 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.
+ * Included in ConstructivePreset when `enableLlm` is true (the default).
+ * Can also be used standalone by adding it directly to your preset's `extends` array.
  *
  * @example
  * ```typescript
@@ -54,6 +54,17 @@
  * })
  * ```
  *
+ * @example With strict quota enforcement (fail if embedding unavailable):
+ * ```typescript
+ * GraphileLlmPreset({
+ *   defaultEmbedder: { provider: 'openai', model: 'text-embedding-3-small' },
+ *   metering: true,
+ *   onQuotaExceeded: 'throw',
+ *   // → if billing quota is exceeded, queries with unifiedSearch throw an error
+ *   // → without this, queries silently fall back to text-only search
+ * })
+ * ```
+ *
  * @example With custom entity_id resolution (bill per-database):
  * ```typescript
  * GraphileLlmPreset({
@@ -78,7 +89,7 @@ const text_search_plugin_1 = require("./plugins/text-search-plugin");
  * @returns A GraphileConfig.Preset to add to your extends array
  */
 function GraphileLlmPreset(options = {}) {
-    const { enableTextSearch = true, enableTextMutations = true, enableRag = false, ragDefaults, metering } = options;
+    const { enableTextSearch = true, enableTextMutations = true, enableRag = false, onQuotaExceeded, ragDefaults, metering } = options;
     const plugins = [
         (0, llm_module_plugin_1.createLlmModulePlugin)(options)
     ];
@@ -89,7 +100,7 @@ function GraphileLlmPreset(options = {}) {
         plugins.push((0, metering_plugin_1.createLlmMeteringPlugin)(meteringConfig));
     }
     if (enableTextSearch) {
-        plugins.push((0, text_search_plugin_1.createLlmTextSearchPlugin)());
+        plugins.push((0, text_search_plugin_1.createLlmTextSearchPlugin)({ onQuotaExceeded }));
     }
     if (enableTextMutations) {
         plugins.push((0, text_mutation_plugin_1.createLlmTextMutationPlugin)());

package/types.d.ts

@@ -216,6 +216,19 @@ export interface GraphileLlmOptions {
      * @default true
      */
     enableTextSearch?: boolean;
+    /**
+     * Controls behavior when the embedder returns null (e.g. billing quota exceeded).
+     *
+     * - `'degrade'` (default): Skip the vector search silently and fall back to
+     *   text-only adapters (tsvector, BM25, trgm). If no text adapters are
+     *   available, throws an error regardless of this setting.
+     * - `'throw'`: Always throw an error when the embedder fails, even if
+     *   text adapters could handle the query. Use this when semantic search
+     *   is critical and keyword-only results are unacceptable.
+     *
+     * @default 'degrade'
+     */
+    onQuotaExceeded?: 'degrade' | 'throw';
     /**
      * Whether to add `*Text` companion fields on mutation inputs for vector columns.
      * @default true