@retrivora-ai/rag-engine 1.0.4 → 1.0.6

package/src/config/ConfigBuilder.ts

@@ -8,7 +8,7 @@
  * - Fluent API for easy configuration
  * - Type-safe provider selection
  * - Automatic environment variable resolution
- * - Built-in validation
+ * - Built-in validation at build() time
  * - Support for presets
  *
  * @example
@@ -22,23 +22,31 @@
  * const plugin = new VectorPlugin(config);
  */
 
-import { RagConfig, VectorDBConfig, LLMConfig, EmbeddingConfig, VectorDBProvider, LLMProvider, EmbeddingProvider } from './RagConfig';
+import {
+  RagConfig,
+  VectorDBConfig,
+  LLMConfig,
+  EmbeddingConfig,
+  UIConfig,
+  RAGConfig,
+  VectorDBProvider,
+  LLMProvider,
+  EmbeddingProvider,
+} from './RagConfig';
 
 export class ConfigBuilder {
-  private config: Partial<RagConfig> = {
-    projectId: 'default-project',
-    rag: {
-      chunkSize: 1000,
-      chunkOverlap: 200,
-      topK: 5,
-    },
-  };
+  private _projectId?: string;
+  private _vectorDb?: VectorDBConfig;
+  private _llm?: LLMConfig;
+  private _embedding?: EmbeddingConfig;
+  private _ui?: UIConfig;
+  private _rag?: RAGConfig;
 
   /**
    * Set the project/application ID for namespacing
    */
   projectId(id: string): this {
-    this.config.projectId = id;
+    this._projectId = id;
     return this;
   }
 
@@ -50,15 +58,12 @@ export class ConfigBuilder {
     options?: Record<string, unknown>
   ): this {
     if (provider === 'auto') {
-      // Auto-detect from environment
-      this.config.vectorDb = this.autoDetectVectorDb();
+      this._vectorDb = this._autoDetectVectorDb();
     } else {
-      this.config.vectorDb = {
+      this._vectorDb = {
         provider: provider as VectorDBProvider,
         indexName: (options?.indexName as string) ?? 'default',
-        options: {
-          ...options,
-        },
+        options: { ...options },
       };
     }
     return this;
@@ -74,9 +79,9 @@ export class ConfigBuilder {
     options?: Record<string, unknown>
   ): this {
     if (provider === 'auto') {
-      this.config.llm = this.autoDetectLLM();
+      this._llm = this._autoDetectLLM();
     } else {
-      this.config.llm = {
+      this._llm = {
         provider: provider as LLMProvider,
         model: model ?? 'default-model',
         apiKey,
@@ -100,9 +105,9 @@ export class ConfigBuilder {
     options?: Record<string, unknown>
   ): this {
     if (provider === 'auto') {
-      this.config.embedding = this.autoDetectEmbedding();
+      this._embedding = this._autoDetectEmbedding();
     } else {
-      this.config.embedding = {
+      this._embedding = {
         provider: provider as EmbeddingProvider,
         model: model ?? 'default-embedding',
         apiKey,
@@ -114,40 +119,48 @@ export class ConfigBuilder {
   }
 
   /**
-   * Set RAG-specific parameters
+   * Set RAG-specific pipeline parameters
    */
-  rag(options: {
-    chunkSize?: number;
-    chunkOverlap?: number;
-    topK?: number;
-  }): this {
-    this.config.rag = {
-      ...(this.config.rag ?? {}),
-      ...options,
-    };
+  rag(options: RAGConfig): this {
+    this._rag = { ...(this._rag ?? {}), ...options };
     return this;
   }
 
   /**
-   * Set UI/UX parameters
+   * Set UI branding and appearance options.
+   * Accepts the full UIConfig interface.
    */
-  ui(options: {
-    branding?: string;
-    primaryColor?: string;
-    darkMode?: boolean;
-  }): this {
-    this.config.ui = options;
+  ui(options: UIConfig): this {
+    this._ui = options;
     return this;
   }
 
-
-
   /**
-   * Build and return the configuration
+   * Build and return the final RagConfig.
+   * Throws if required fields (projectId, vectorDb, llm, embedding) are not set.
    */
   build(): RagConfig {
-    const finalConfig = this.config as RagConfig;
-    return finalConfig;
+    const missing: string[] = [];
+    if (!this._projectId) missing.push('projectId (call .projectId("my-app"))');
+    if (!this._vectorDb)  missing.push('vectorDb (call .vectorDb("pinecone", { ... }))');
+    if (!this._llm)       missing.push('llm (call .llm("openai", "gpt-4o", apiKey))');
+    if (!this._embedding) missing.push('embedding (call .embedding("openai", "text-embedding-3-small"))');
+
+    if (missing.length > 0) {
+      throw new Error(
+        `[ConfigBuilder] Cannot build — required fields are missing:\n  ${missing.join('\n  ')}`
+      );
+    }
+
+    return {
+      projectId:  this._projectId!,
+      vectorDb:   this._vectorDb!,
+      llm:        this._llm!,
+      embedding:  this._embedding!,
+      ui:         this._rag ? this._ui : undefined,
+      rag:        this._rag ?? { chunkSize: 1000, chunkOverlap: 200, topK: 5 },
+      ...(this._ui ? { ui: this._ui } : {}),
+    };
   }
 
   /**
@@ -161,133 +174,43 @@ export class ConfigBuilder {
   // Private helper methods for auto-detection
   // ============================================================================
 
-  private autoDetectVectorDb(): VectorDBConfig {
-    // Check for Pinecone
+  private _autoDetectVectorDb(): VectorDBConfig {
     if (process.env.PINECONE_API_KEY && process.env.PINECONE_INDEX) {
-      return {
-        provider: 'pinecone',
-        indexName: process.env.PINECONE_INDEX,
-        options: { apiKey: process.env.PINECONE_API_KEY },
-      };
+      return { provider: 'pinecone', indexName: process.env.PINECONE_INDEX, options: { apiKey: process.env.PINECONE_API_KEY } };
     }
-
-    // Check for Qdrant
     if (process.env.QDRANT_URL) {
-      return {
-        provider: 'qdrant',
-        indexName: process.env.QDRANT_COLLECTION || 'documents',
-        options: {
-          url: process.env.QDRANT_URL,
-          apiKey: process.env.QDRANT_API_KEY,
-        },
-      };
+      return { provider: 'qdrant', indexName: process.env.QDRANT_COLLECTION || 'documents', options: { url: process.env.QDRANT_URL, apiKey: process.env.QDRANT_API_KEY } };
     }
-
-    // Check for PostgreSQL/pgvector
     if (process.env.DATABASE_URL) {
-      return {
-        provider: 'postgresql',
-        indexName: process.env.PG_TABLE || 'documents',
-        options: {
-          connectionString: process.env.DATABASE_URL,
-        },
-      };
+      return { provider: 'postgresql', indexName: process.env.PG_TABLE || 'documents', options: { connectionString: process.env.DATABASE_URL } };
     }
-
-    // Check for MongoDB
     if (process.env.MONGODB_URI) {
-      return {
-        provider: 'mongodb',
-        indexName: process.env.MONGODB_COLLECTION || 'documents',
-        options: {
-          uri: process.env.MONGODB_URI,
-          database: process.env.MONGODB_DB || 'ai_db',
-          collection: process.env.MONGODB_COLLECTION || 'documents',
-        },
-      };
+      return { provider: 'mongodb', indexName: process.env.MONGODB_COLLECTION || 'documents', options: { uri: process.env.MONGODB_URI, database: process.env.MONGODB_DB || 'ai_db', collection: process.env.MONGODB_COLLECTION || 'documents' } };
     }
-
-    // Check for Redis
     if (process.env.REDIS_URL) {
-      return {
-        provider: 'redis',
-        indexName: process.env.REDIS_INDEX || 'documents',
-        options: {
-          url: process.env.REDIS_URL,
-        },
-      };
+      return { provider: 'redis', indexName: process.env.REDIS_INDEX || 'documents', options: { url: process.env.REDIS_URL } };
     }
-
-    // Default to Qdrant localhost
-    return {
-      provider: 'qdrant',
-      indexName: 'documents',
-      options: {
-        url: process.env.QDRANT_URL || 'http://localhost:6333',
-      },
-    };
+    return { provider: 'qdrant', indexName: 'documents', options: { url: process.env.QDRANT_URL || 'http://localhost:6333' } };
   }
 
-  private autoDetectLLM(): LLMConfig {
-    // Check for OpenAI
+  private _autoDetectLLM(): LLMConfig {
     if (process.env.OPENAI_API_KEY) {
-      return {
-        provider: 'openai',
-        model: process.env.OPENAI_MODEL || 'gpt-4o-mini',
-        apiKey: process.env.OPENAI_API_KEY,
-        maxTokens: parseInt(process.env.OPENAI_MAX_TOKENS || '1024'),
-        temperature: parseFloat(process.env.OPENAI_TEMPERATURE || '0.7'),
-      };
+      return { provider: 'openai', model: process.env.OPENAI_MODEL || 'gpt-4o-mini', apiKey: process.env.OPENAI_API_KEY, maxTokens: parseInt(process.env.OPENAI_MAX_TOKENS || '1024'), temperature: parseFloat(process.env.OPENAI_TEMPERATURE || '0.7') };
     }
-
-    // Check for Anthropic
     if (process.env.ANTHROPIC_API_KEY) {
-      return {
-        provider: 'anthropic',
-        model: process.env.ANTHROPIC_MODEL || 'claude-3-haiku-20240307',
-        apiKey: process.env.ANTHROPIC_API_KEY,
-        maxTokens: parseInt(process.env.ANTHROPIC_MAX_TOKENS || '1024'),
-        temperature: parseFloat(process.env.ANTHROPIC_TEMPERATURE || '0.7'),
-      };
+      return { provider: 'anthropic', model: process.env.ANTHROPIC_MODEL || 'claude-3-haiku-20240307', apiKey: process.env.ANTHROPIC_API_KEY, maxTokens: parseInt(process.env.ANTHROPIC_MAX_TOKENS || '1024'), temperature: parseFloat(process.env.ANTHROPIC_TEMPERATURE || '0.7') };
     }
-
-    // Check for Ollama
     if (process.env.OLLAMA_BASE_URL) {
-      return {
-        provider: 'ollama',
-        model: process.env.OLLAMA_MODEL || 'mistral',
-        baseUrl: process.env.OLLAMA_BASE_URL,
-        maxTokens: parseInt(process.env.OLLAMA_MAX_TOKENS || '1024'),
-        temperature: parseFloat(process.env.OLLAMA_TEMPERATURE || '0.7'),
-      };
+      return { provider: 'ollama', model: process.env.OLLAMA_MODEL || 'mistral', baseUrl: process.env.OLLAMA_BASE_URL, maxTokens: parseInt(process.env.OLLAMA_MAX_TOKENS || '1024'), temperature: parseFloat(process.env.OLLAMA_TEMPERATURE || '0.7') };
     }
-
-    // Default to OpenAI (requires API key at runtime)
-    return {
-      provider: 'openai',
-      model: 'gpt-4o-mini',
-      apiKey: process.env.OPENAI_API_KEY,
-    };
+    return { provider: 'openai', model: 'gpt-4o-mini', apiKey: process.env.OPENAI_API_KEY };
   }
 
-  private autoDetectEmbedding(): EmbeddingConfig {
-    // Check for dedicated embedding provider
+  private _autoDetectEmbedding(): EmbeddingConfig {
     if (process.env.EMBEDDING_PROVIDER) {
-      const provider = process.env.EMBEDDING_PROVIDER as EmbeddingProvider;
-      return {
-        provider,
-        model: process.env.EMBEDDING_MODEL || 'default',
-        apiKey: process.env.EMBEDDING_API_KEY,
-        baseUrl: process.env.EMBEDDING_BASE_URL,
-      };
+      return { provider: process.env.EMBEDDING_PROVIDER as EmbeddingProvider, model: process.env.EMBEDDING_MODEL || 'default', apiKey: process.env.EMBEDDING_API_KEY, baseUrl: process.env.EMBEDDING_BASE_URL };
     }
-
-    // Default to OpenAI embeddings
-    return {
-      provider: 'openai',
-      model: 'text-embedding-3-small',
-      apiKey: process.env.OPENAI_API_KEY,
-    };
+    return { provider: 'openai', model: 'text-embedding-3-small', apiKey: process.env.OPENAI_API_KEY };
   }
 }
 
@@ -295,74 +218,26 @@ export class ConfigBuilder {
  * Preset configurations for common provider combinations
  */
 export const PRESETS = {
-  /**
-   * OpenAI + Pinecone: Production-ready cloud setup
-   */
-  'openai-pinecone': {
-    vectorDb: 'pinecone' as const,
-    llm: 'openai' as const,
-    embedding: 'openai' as const,
-  },
-
-  /**
-   * Claude + Qdrant: Open-source vector DB + proprietary LLM
-   */
-  'claude-qdrant': {
-    vectorDb: 'qdrant' as const,
-    llm: 'anthropic' as const,
-    embedding: 'openai' as const,
-  },
-
-  /**
-   * Local development: Ollama + local Qdrant
-   */
-  'local-dev': {
-    vectorDb: 'qdrant' as const,
-    llm: 'ollama' as const,
-    embedding: 'ollama' as const,
-  },
-
-  /**
-   * Fully open-source: Ollama LLM + Qdrant vector DB + Ollama embeddings
-   */
-  'fully-open-source': {
-    vectorDb: 'qdrant' as const,
-    llm: 'ollama' as const,
-    embedding: 'ollama' as const,
-  },
-
-  /**
-   * PostgreSQL stack: pgvector + OpenAI
-   */
-  'postgres-openai': {
-    vectorDb: 'postgresql' as const,
-    llm: 'openai' as const,
-    embedding: 'openai' as const,
-  },
-
-  /**
-   * Enterprise MongoDB: MongoDB Atlas with OpenAI
-   */
-  'mongodb-openai': {
-    vectorDb: 'mongodb' as const,
-    llm: 'openai' as const,
-    embedding: 'openai' as const,
-  },
-
-  /**
-   * Redis stack for caching + search
-   */
-  'redis-openai': {
-    vectorDb: 'redis' as const,
-    llm: 'openai' as const,
-    embedding: 'openai' as const,
-  },
+  /** OpenAI + Pinecone: Production-ready cloud setup */
+  'openai-pinecone':     { vectorDb: 'pinecone'    as const, llm: 'openai'    as const, embedding: 'openai'    as const },
+  /** Claude + Qdrant: Open-source vector DB + proprietary LLM */
+  'claude-qdrant':       { vectorDb: 'qdrant'      as const, llm: 'anthropic' as const, embedding: 'openai'    as const },
+  /** Local development: Ollama + local Qdrant */
+  'local-dev':           { vectorDb: 'qdrant'      as const, llm: 'ollama'    as const, embedding: 'ollama'    as const },
+  /** Fully open-source: Ollama LLM + Qdrant + Ollama embeddings */
+  'fully-open-source':   { vectorDb: 'qdrant'      as const, llm: 'ollama'    as const, embedding: 'ollama'    as const },
+  /** PostgreSQL stack: pgvector + OpenAI */
+  'postgres-openai':     { vectorDb: 'postgresql'  as const, llm: 'openai'    as const, embedding: 'openai'    as const },
+  /** Enterprise MongoDB: MongoDB Atlas with OpenAI */
+  'mongodb-openai':      { vectorDb: 'mongodb'     as const, llm: 'openai'    as const, embedding: 'openai'    as const },
+  /** Redis stack for caching + search */
+  'redis-openai':        { vectorDb: 'redis'       as const, llm: 'openai'    as const, embedding: 'openai'    as const },
 } as const;
 
 export type PresetName = keyof typeof PRESETS;
 
 /**
- * Helper to create config from preset
+ * Helper to create a ConfigBuilder pre-seeded with a named preset.
  */
 export function createFromPreset(presetName: PresetName): ConfigBuilder {
   const preset = PRESETS[presetName];

package/src/config/RagConfig.ts

@@ -174,6 +174,10 @@ export interface RAGConfig {
   useGraphRetrieval?: boolean;
   /** Whether to perform reranking on retrieved results */
   useReranking?: boolean;
+  /** List of metadata fields that are valid for filtering. 
+   * Used to dynamically extract hints from natural language queries. 
+   */
+  filterableFields?: string[];
 }
 
 // ---------------------------------------------------------------------------

package/src/config/uiConstants.ts

@@ -0,0 +1,23 @@
+/**
+ * uiConstants.ts — UI-specific constants for the package's React components.
+ *
+ * Kept inside the package src so they resolve correctly when the package
+ * is consumed via npm without Next.js path-alias configuration.
+ */
+
+/** Maps the `borderRadius` config value to a Tailwind class. */
+export const BORDER_RADIUS_MAP: Record<string, string> = {
+  none: 'rounded-none',
+  sm: 'rounded-sm',
+  md: 'rounded-md',
+  lg: 'rounded-lg',
+  xl: 'rounded-xl',
+  full: 'rounded-3xl',
+};
+
+/** Default suggested prompts shown on the chat welcome screen. */
+export const CHAT_SUGGESTIONS: string[] = [
+  'What can you help me with?',
+  'Summarise the key topics',
+  'Show me an example',
+];

package/src/core/ConfigResolver.ts

@@ -1,52 +1,80 @@
+/**
+ * ConfigResolver — validates and normalizes host configuration.
+ * It merges host-provided config with environment defaults.
+ *
+ * The `getRagConfig()` result is memoized at module level so that
+ * environment variables are only parsed once per process, avoiding
+ * repeated work in serverless cold starts and per-request handler calls.
+ */
 import { RagConfig } from '../config/RagConfig';
 import { mergeDefined } from '../utils/templateUtils';
 import { getRagConfig as getEnvConfig } from '../config/serverConfig';
 
+/** Module-level cache: populated on first use, shared across all VectorPlugin instances. */
+let _cachedEnvConfig: RagConfig | null = null;
+
+function getCachedEnvConfig(): RagConfig {
+  if (!_cachedEnvConfig) {
+    _cachedEnvConfig = getEnvConfig();
+  }
+  return _cachedEnvConfig;
+}
+
 /**
- * ConfigResolver — validates and normalizes host configuration.
- * It merges host-provided config with environment defaults.
+ * Reset the cached env config. Useful in tests where environment variables
+ * change between test cases.
  */
+export function resetConfigCache(): void {
+  _cachedEnvConfig = null;
+}
+
 export class ConfigResolver {
   /**
-   * Resolves the final configuration by merging host-provided config with defaults.
+   * Resolves the final configuration by merging host-provided config with environment defaults.
    * @param hostConfig - Partial configuration passed from the host application.
    */
   static resolve(hostConfig?: Partial<RagConfig>): RagConfig {
-    const envConfig = getEnvConfig();
+    const envConfig = getCachedEnvConfig();
 
     if (!hostConfig) {
       return envConfig;
     }
 
-    // Deep merge or specific merging logic
+    // Deep merge: host config wins over env config at every level
     return {
       ...envConfig,
       ...hostConfig,
       projectId: hostConfig.projectId || envConfig.projectId,
-      vectorDb: hostConfig.vectorDb ? {
-        ...envConfig.vectorDb,
-        ...hostConfig.vectorDb,
-        options: {
-          ...envConfig.vectorDb.options,
-          ...(hostConfig.vectorDb.options || {})
-        }
-      } : envConfig.vectorDb,
-      llm: hostConfig.llm ? {
-        ...envConfig.llm,
-        ...hostConfig.llm,
-        options: {
-          ...(envConfig.llm.options || {}),
-          ...(hostConfig.llm.options || {})
-        }
-      } : envConfig.llm,
-      embedding: hostConfig.embedding ? {
-        ...envConfig.embedding,
-        ...hostConfig.embedding,
-        options: {
-          ...(envConfig.embedding.options || {}),
-          ...(hostConfig.embedding.options || {})
-        }
-      } : envConfig.embedding,
+      vectorDb: hostConfig.vectorDb
+        ? {
+            ...envConfig.vectorDb,
+            ...hostConfig.vectorDb,
+            options: {
+              ...envConfig.vectorDb.options,
+              ...(hostConfig.vectorDb.options || {}),
+            },
+          }
+        : envConfig.vectorDb,
+      llm: hostConfig.llm
+        ? {
+            ...envConfig.llm,
+            ...hostConfig.llm,
+            options: {
+              ...(envConfig.llm.options || {}),
+              ...(hostConfig.llm.options || {}),
+            },
+          }
+        : envConfig.llm,
+      embedding: hostConfig.embedding
+        ? {
+            ...envConfig.embedding,
+            ...hostConfig.embedding,
+            options: {
+              ...(envConfig.embedding.options || {}),
+              ...(hostConfig.embedding.options || {}),
+            },
+          }
+        : envConfig.embedding,
       ui: hostConfig.ui ? mergeDefined(envConfig.ui, hostConfig.ui) : envConfig.ui,
       rag: hostConfig.rag ? { ...envConfig.rag, ...hostConfig.rag } : envConfig.rag,
     };