@opensaas/stack-rag 0.1.6 → 0.1.7

package/dist/storage/types.d.ts

@@ -53,6 +53,11 @@ export type SearchOptions = {
      * This is merged with access control filters
      */
     where?: Record<string, unknown>;
+    /**
+     * OpenSaaS config for access control integration
+     * Required to properly enforce access control in raw SQL queries
+     */
+    config?: import('@opensaas/stack-core').OpenSaasConfig;
 };
 /**
  * Distance functions for vector similarity

package/dist/storage/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/storage/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEtD;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;;;;;;;OAQG;IACH,MAAM,CAAC,CAAC,GAAG,OAAO,EAChB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EAAE,EACrB,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;IAE7B;;;;;;;OAOG;IACH,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAAA;CACnD;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB;;;OAGG;IACH,OAAO,EAAE,OAAO,sBAAsB,EAAE,aAAa,CAAA;IAErD;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAChC,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,IAAI,GAAG,eAAe,CAAA;AAEhE;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAI1D;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAK3D;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAS3D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAajE"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/storage/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEtD;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB;;;;;;;;OAQG;IACH,MAAM,CAAC,CAAC,GAAG,OAAO,EAChB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EAAE,EACrB,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;IAE7B;;;;;;;OAOG;IACH,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAAA;CACnD;AAED;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IAEd;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB;;;OAGG;IACH,OAAO,EAAE,OAAO,sBAAsB,EAAE,aAAa,CAAA;IAErD;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAE/B;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,sBAAsB,EAAE,cAAc,CAAA;CACvD,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,IAAI,GAAG,eAAe,CAAA;AAEhE;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAI1D;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAK3D;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAS3D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAajE"}

package/dist/storage/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/storage/types.ts"],"names":[],"mappings":"AA0EA;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,MAAgB;IAC9C,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,GAAG,GAAG,GAAG,GAAG,EAAE,CAAC,CAAC,CAAC,CAAA;IAC5E,IAAI,SAAS,KAAK,CAAC;QAAE,OAAO,MAAM,CAAA;IAClC,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,GAAG,SAAS,CAAC,CAAA;AAC7C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,CAAW,EAAE,CAAW;IACjD,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC,MAAM,OAAO,CAAC,CAAC,MAAM,EAAE,CAAC,CAAA;IAC1E,CAAC;IACD,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;AACvD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,CAAW,EAAE,CAAW;IACjD,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC,MAAM,OAAO,CAAC,CAAC,MAAM,EAAE,CAAC,CAAA;IAC1E,CAAC;IACD,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE;QAC9C,MAAM,IAAI,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAA;QACvB,OAAO,GAAG,GAAG,IAAI,GAAG,IAAI,CAAA;IAC1B,CAAC,EAAE,CAAC,CAAC,CAAA;IACL,OAAO,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,CAAA;AAClC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,CAAW,EAAE,CAAW;IACvD,MAAM,OAAO,GAAG,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IAChC,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;IAC9C,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;IAE9C,IAAI,UAAU,KAAK,CAAC,IAAI,UAAU,KAAK,CAAC,EAAE,CAAC;QACzC,OAAO,CAAC,CAAA;IACV,CAAC;IAED,wCAAwC;IACxC,sCAAsC;IACtC,MAAM,UAAU,GAAG,OAAO,GAAG,CAAC,UAAU,GAAG,UAAU,CAAC,CAAA;IACtD,OAAO,CAAC,UAAU,GAAG,CAAC,CAAC,GAAG,CAAC,CAAA;AAC7B,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/storage/types.ts"],"names":[],"mappings":"AAgFA;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,MAAgB;IAC9C,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,GAAG,GAAG,GAAG,GAAG,EAAE,CAAC,CAAC,CAAC,CAAA;IAC5E,IAAI,SAAS,KAAK,CAAC;QAAE,OAAO,MAAM,CAAA;IAClC,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,GAAG,SAAS,CAAC,CAAA;AAC7C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,CAAW,EAAE,CAAW;IACjD,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC,MAAM,OAAO,CAAC,CAAC,MAAM,EAAE,CAAC,CAAA;IAC1E,CAAC;IACD,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;AACvD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,CAAW,EAAE,CAAW;IACjD,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC,MAAM,OAAO,CAAC,CAAC,MAAM,EAAE,CAAC,CAAA;IAC1E,CAAC;IACD,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE;QAC9C,MAAM,IAAI,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAA;QACvB,OAAO,GAAG,GAAG,IAAI,GAAG,IAAI,CAAA;IAC1B,CAAC,EAAE,CAAC,CAAC,CAAA;IACL,OAAO,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,CAAA;AAClC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,CAAW,EAAE,CAAW;IACvD,MAAM,OAAO,GAAG,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IAChC,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;IAC9C,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;IAE9C,IAAI,UAAU,KAAK,CAAC,IAAI,UAAU,KAAK,CAAC,EAAE,CAAC;QACzC,OAAO,CAAC,CAAA;IACV,CAAC;IAED,wCAAwC;IACxC,sCAAsC;IACtC,MAAM,UAAU,GAAG,OAAO,GAAG,CAAC,UAAU,GAAG,UAAU,CAAC,CAAA;IACtD,OAAO,CAAC,UAAU,GAAG,CAAC,CAAC,GAAG,CAAC,CAAA;AAC7B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opensaas/stack-rag",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "RAG and AI embeddings integration for OpenSaas Stack",
   "type": "module",
   "main": "./dist/index.js",
@@ -52,7 +52,7 @@
   },
   "peerDependencies": {
     "openai": "^6.8.0",
-    "@opensaas/stack-core": "0.1.6"
+    "@opensaas/stack-core": "0.1.7"
   },
   "peerDependenciesMeta": {
     "openai": {
@@ -69,7 +69,7 @@
     "openai": "^6.0.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.0",
-    "@opensaas/stack-core": "0.1.6"
+    "@opensaas/stack-core": "0.1.7"
   },
   "scripts": {
     "build": "tsc",

package/src/config/plugin.ts

@@ -1,7 +1,8 @@
 import type { Plugin } from '@opensaas/stack-core'
-import type { RAGConfig, NormalizedRAGConfig } from './types.js'
+import type { RAGConfig, NormalizedRAGConfig, SearchableMetadata } from './types.js'
 import { normalizeRAGConfig } from './index.js'
 import { createEmbeddingProvider } from '../providers/index.js'
+import { embedding } from '../fields/embedding.js'
 
 /**
  * RAG plugin for OpenSaas Stack
@@ -45,7 +46,39 @@ export function ragPlugin(config: RAGConfig): Plugin {
     version: '0.1.0',
 
     init: async (context) => {
-      // Find all embedding fields with autoGenerate enabled
+      // First pass: Scan for searchable() wrapped fields and inject embedding fields
+      for (const [listName, listConfig] of Object.entries(context.config.lists)) {
+        const embeddingFieldsToInject: Record<string, ReturnType<typeof embedding>> = {}
+
+        for (const [fieldName, fieldConfig] of Object.entries(listConfig.fields)) {
+          // Check if field has _searchable metadata
+          if ('_searchable' in fieldConfig) {
+            const meta = fieldConfig._searchable as SearchableMetadata
+
+            // Determine embedding field name
+            const embeddingName = meta.embeddingFieldName || `${fieldName}Embedding`
+
+            // Create embedding field
+            embeddingFieldsToInject[embeddingName] = embedding({
+              sourceField: fieldName,
+              provider: meta.provider,
+              dimensions: meta.dimensions,
+              chunking: meta.chunking,
+              autoGenerate: true,
+            })
+          }
+        }
+
+        // Inject all embedding fields at once
+        if (Object.keys(embeddingFieldsToInject).length > 0) {
+          context.extendList(listName, {
+            fields: embeddingFieldsToInject,
+          })
+        }
+      }
+
+      // Second pass: Find all embedding fields with autoGenerate enabled
+      // This includes both manually defined embedding fields AND injected ones from searchable()
       for (const [listName, listConfig] of Object.entries(context.config.lists)) {
         for (const [fieldName, fieldConfig] of Object.entries(listConfig.fields)) {
           if (

package/src/config/types.ts

@@ -281,3 +281,62 @@ export type SearchResult<T = unknown> = {
    */
   distance: number
 }
+
+/**
+ * Options for searchable() field wrapper
+ * Simplified options for common use cases
+ */
+export type SearchableOptions = {
+  /**
+   * Embedding provider to use
+   * References a provider name from RAG config
+   * Falls back to default provider if not specified
+   */
+  provider?: EmbeddingProviderName
+
+  /**
+   * Vector dimensions
+   * Must match the provider's output dimensions
+   * @default 1536 (OpenAI text-embedding-3-small)
+   */
+  dimensions?: number
+
+  /**
+   * Chunking configuration for long texts
+   */
+  chunking?: ChunkingConfig
+
+  /**
+   * Custom name for the generated embedding field
+   * If not provided, defaults to `${fieldName}Embedding`
+   * @example 'contentVector' instead of 'contentEmbedding'
+   */
+  embeddingFieldName?: string
+}
+
+/**
+ * Internal metadata attached to searchable fields
+ * Used by ragPlugin to identify and inject embedding fields
+ * @internal
+ */
+export type SearchableMetadata = {
+  /**
+   * Name for the generated embedding field
+   */
+  embeddingFieldName: string
+
+  /**
+   * Embedding provider to use
+   */
+  provider?: EmbeddingProviderName
+
+  /**
+   * Vector dimensions
+   */
+  dimensions?: number
+
+  /**
+   * Chunking configuration
+   */
+  chunking?: ChunkingConfig
+}

package/src/fields/index.ts

@@ -4,3 +4,5 @@
 
 export { embedding } from './embedding.js'
 export type { EmbeddingField } from './embedding.js'
+
+export { searchable } from './searchable.js'

package/src/fields/searchable.test.ts

@@ -0,0 +1,136 @@
+import { describe, it, expect } from 'vitest'
+import { searchable } from './searchable.js'
+import type { BaseFieldConfig } from '@opensaas/stack-core'
+import type { SearchableOptions } from '../config/types.js'
+
+// Mock text field for testing
+function mockTextField(): BaseFieldConfig {
+  return {
+    type: 'text',
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    getZodSchema: () => null as any,
+    getPrismaType: () => ({ type: 'String', modifiers: '' }),
+    getTypeScriptType: () => ({ type: 'string', optional: false }),
+  }
+}
+
+describe('searchable() field wrapper', () => {
+  it('should preserve original field properties', () => {
+    const field = mockTextField()
+    const wrapped = searchable(field)
+
+    expect(wrapped.type).toBe('text')
+    expect(wrapped.getZodSchema).toBe(field.getZodSchema)
+    expect(wrapped.getPrismaType).toBe(field.getPrismaType)
+    expect(wrapped.getTypeScriptType).toBe(field.getTypeScriptType)
+  })
+
+  it('should attach _searchable metadata', () => {
+    const field = mockTextField()
+    const wrapped = searchable(field, { provider: 'openai' })
+
+    expect(wrapped._searchable).toBeDefined()
+    expect(wrapped._searchable.provider).toBe('openai')
+  })
+
+  it('should use default options when not provided', () => {
+    const field = mockTextField()
+    const wrapped = searchable(field)
+
+    expect(wrapped._searchable).toBeDefined()
+    expect(wrapped._searchable.embeddingFieldName).toBe('')
+    expect(wrapped._searchable.provider).toBeUndefined()
+    expect(wrapped._searchable.dimensions).toBeUndefined()
+  })
+
+  it('should accept all searchable options', () => {
+    const field = mockTextField()
+    const options: SearchableOptions = {
+      provider: 'ollama',
+      dimensions: 768,
+      chunking: {
+        strategy: 'sentence',
+        maxTokens: 300,
+        overlap: 25,
+      },
+      embeddingFieldName: 'customEmbedding',
+    }
+
+    const wrapped = searchable(field, options)
+
+    expect(wrapped._searchable.provider).toBe('ollama')
+    expect(wrapped._searchable.dimensions).toBe(768)
+    expect(wrapped._searchable.chunking).toEqual({
+      strategy: 'sentence',
+      maxTokens: 300,
+      overlap: 25,
+    })
+    expect(wrapped._searchable.embeddingFieldName).toBe('customEmbedding')
+  })
+
+  it('should preserve field with validation options', () => {
+    const fieldWithValidation = {
+      ...mockTextField(),
+      validation: {
+        isRequired: true,
+        length: { min: 10, max: 1000 },
+      },
+    }
+
+    const wrapped = searchable(fieldWithValidation, { provider: 'openai' })
+
+    expect(wrapped.validation).toEqual({
+      isRequired: true,
+      length: { min: 10, max: 1000 },
+    })
+    expect(wrapped._searchable).toBeDefined()
+  })
+
+  it('should preserve field with hooks', () => {
+    const resolveInputHook = () => {}
+    const fieldWithHooks = {
+      ...mockTextField(),
+      hooks: {
+        resolveInput: resolveInputHook,
+      },
+    }
+
+    const wrapped = searchable(fieldWithHooks)
+
+    expect(wrapped.hooks).toBeDefined()
+    expect(wrapped.hooks?.resolveInput).toBe(resolveInputHook)
+    expect(wrapped._searchable).toBeDefined()
+  })
+
+  it('should work with different field types', () => {
+    const richTextField = {
+      ...mockTextField(),
+      type: 'richText' as const,
+    }
+
+    const wrapped = searchable(richTextField, { provider: 'openai' })
+
+    expect(wrapped.type).toBe('richText')
+    expect(wrapped._searchable).toBeDefined()
+  })
+
+  it('should handle empty embeddingFieldName option', () => {
+    const field = mockTextField()
+    const wrapped = searchable(field, { embeddingFieldName: '' })
+
+    expect(wrapped._searchable.embeddingFieldName).toBe('')
+  })
+
+  it('should handle partial chunking config', () => {
+    const field = mockTextField()
+    const wrapped = searchable(field, {
+      chunking: {
+        strategy: 'recursive',
+      },
+    })
+
+    expect(wrapped._searchable.chunking).toEqual({
+      strategy: 'recursive',
+    })
+  })
+})

package/src/fields/searchable.ts

@@ -0,0 +1,57 @@
+import type { BaseFieldConfig } from '@opensaas/stack-core'
+import type { SearchableOptions, SearchableMetadata } from '../config/types.js'
+
+/**
+ * High-level field wrapper that automatically adds embedding field and hooks
+ *
+ * This wrapper makes it easy to add semantic search to any text field by
+ * automatically creating a companion embedding field that stays in sync.
+ *
+ * @example
+ * ```typescript
+ * import { text } from '@opensaas/stack-core/fields'
+ * import { searchable } from '@opensaas/stack-rag/fields'
+ *
+ * fields: {
+ *   content: searchable(text(), {
+ *     provider: 'openai',
+ *     dimensions: 1536
+ *   })
+ * }
+ * ```
+ *
+ * This is equivalent to the manual pattern:
+ * ```typescript
+ * fields: {
+ *   content: text(),
+ *   contentEmbedding: embedding({
+ *     sourceField: 'content',
+ *     provider: 'openai',
+ *     dimensions: 1536,
+ *     autoGenerate: true
+ *   })
+ * }
+ * ```
+ *
+ * @param field - The field to make searchable (usually text() or richText())
+ * @param options - Embedding configuration options
+ * @returns The same field with searchable metadata attached
+ */
+export function searchable<T extends BaseFieldConfig>(
+  field: T,
+  options: SearchableOptions = {},
+): T & { _searchable: SearchableMetadata } {
+  const { embeddingFieldName, provider, dimensions, chunking } = options
+
+  // Attach metadata to the field for ragPlugin to detect
+  return {
+    ...field,
+    _searchable: {
+      // Use custom name if provided, otherwise will be set by plugin based on field name
+      embeddingFieldName: embeddingFieldName || '',
+      provider,
+      dimensions,
+      chunking,
+    },
+  }
+}

package/src/providers/openai.ts

@@ -10,6 +10,21 @@ const MODEL_DIMENSIONS: Record<OpenAIEmbeddingModel, number> = {
   'text-embedding-ada-002': 1536,
 }
 
+/**
+ * Lazily load OpenAI to avoid requiring it at import time
+ */
+async function getOpenAI() {
+  try {
+    const module = await import('openai')
+    return module.default
+  } catch (error) {
+    throw new Error(
+      'OpenAI package not found. Install it with: npm install openai\n' +
+        'Make sure to run: pnpm install openai',
+    )
+  }
+}
+
 /**
  * Type for OpenAI client (avoids direct dependency)
  */
@@ -34,35 +49,33 @@ export class OpenAIEmbeddingProvider implements EmbeddingProvider {
   readonly model: string
   readonly dimensions: number
 
-  private client: OpenAIClient
+  private client: OpenAIClient | null = null
   private config: OpenAIEmbeddingConfig
+  private clientPromise: Promise<OpenAIClient> | null = null
 
   constructor(config: OpenAIEmbeddingConfig) {
     this.config = config
     this.model = config.model || 'text-embedding-3-small'
     this.dimensions = MODEL_DIMENSIONS[this.model as OpenAIEmbeddingModel] || 1536
+  }
 
-    // Initialize OpenAI client
-    this.client = this.initializeClient()
+  private async ensureClient(): Promise<OpenAIClient> {
+    if (this.client) return this.client
+    if (this.clientPromise) return this.clientPromise
+
+    this.clientPromise = this.initializeClient()
+    this.client = await this.clientPromise
+    return this.client
   }
 
-  private initializeClient(): OpenAIClient {
-    try {
-      // eslint-disable-next-line @typescript-eslint/no-require-imports
-      const { OpenAI } = require('openai')
-
-      return new OpenAI({
-        apiKey: this.config.apiKey,
-        organization: this.config.organization,
-        baseURL: this.config.baseURL,
-      }) as OpenAIClient
-    } catch (error) {
-      throw new Error(
-        'OpenAI package not found. Install it with: npm install openai\n' +
-          'Error: ' +
-          (error as Error).message,
-      )
-    }
+  private async initializeClient(): Promise<OpenAIClient> {
+    const OpenAI = await getOpenAI()
+
+    return new OpenAI({
+      apiKey: this.config.apiKey,
+      organization: this.config.organization,
+      baseURL: this.config.baseURL,
+    }) as OpenAIClient
   }
 
   /**
@@ -74,7 +87,8 @@ export class OpenAIEmbeddingProvider implements EmbeddingProvider {
     }
 
     try {
-      const response = await this.client.embeddings.create({
+      const client = await this.ensureClient()
+      const response = await client.embeddings.create({
         model: this.model,
         input: text,
         encoding_format: 'float',
@@ -111,7 +125,8 @@ export class OpenAIEmbeddingProvider implements EmbeddingProvider {
 
     try {
       // OpenAI supports batch embedding
-      const response = await this.client.embeddings.create({
+      const client = await this.ensureClient()
+      const response = await client.embeddings.create({
         model: this.model,
         input: validTexts,
         encoding_format: 'float',

package/src/runtime/batch.test.ts

@@ -267,7 +267,7 @@ describe('ProcessingQueue', () => {
     // With concurrency 3, should be faster than sequential
     // 5 items with 10ms each sequentially = 50ms
     // With concurrency 3: ceil(5/3) * 10ms = 20ms
-    expect(duration).toBeLessThan(40)
+    expect(duration).toBeLessThan(50)
   })
 
   it('should track queue size', async () => {