@retrivora-ai/rag-engine 0.1.7 → 0.1.9

package/src/app/types.ts

@@ -0,0 +1,30 @@
+import React from 'react';
+
+export interface ArchitectureCardProps {
+  icon: React.ReactNode;
+  title: string;
+  description: string;
+  badge: string;
+  badgeColor: string;
+}
+
+export interface Snippet {
+  id: string;
+  title: string;
+  description: string;
+  code: string;
+  language: string;
+}
+
+export interface PipelineStep {
+  step: string;
+  Icon: React.ElementType;
+  title: string;
+  desc: string;
+  colors: { from: string; to: string };
+}
+
+export interface ProviderPill {
+  Icon: React.ElementType;
+  label: string;
+}

package/src/components/ChatWindow.tsx

@@ -12,6 +12,7 @@ import {
 import { MessageBubble } from './MessageBubble';
 import { useConfig } from './ConfigProvider';
 import { useRagChat } from '@/hooks/useRagChat';
+import { BORDER_RADIUS_MAP, CHAT_SUGGESTIONS } from '@/app/constants';
 
 interface ChatWindowProps {
   /** Additional className for the wrapper div */
@@ -67,16 +68,7 @@ export function ChatWindow({ className = '', style, onClose, showClose = false }
 
   const isEmpty = messages.length === 0;
 
-  const borderRadiusMap = {
-    none: 'rounded-none',
-    sm: 'rounded-sm',
-    md: 'rounded-md',
-    lg: 'rounded-lg',
-    xl: 'rounded-xl',
-    full: 'rounded-3xl',
-  };
-
-  const currentRadius = borderRadiusMap[ui.borderRadius || 'xl'];
+    const currentRadius = BORDER_RADIUS_MAP[ui.borderRadius || 'xl'];
   const isGlass = ui.visualStyle !== 'solid';
 
   return (
@@ -161,7 +153,7 @@ export function ChatWindow({ className = '', style, onClose, showClose = false }
 
             {/* Suggested prompts */}
             <div className="flex flex-wrap gap-2 justify-center mt-2">
-              {['What can you help me with?', 'Summarise the key topics', 'Show me an example'].map(
+              {CHAT_SUGGESTIONS.map(
                 (suggestion) => (
                   <button
                     key={suggestion}

package/src/config/ConfigBuilder.ts

@@ -0,0 +1,373 @@
+/**
+ * ConfigBuilder — Fluent, type-safe configuration builder for RagConfig
+ *
+ * Simplifies host application setup with a builder pattern while maintaining
+ * type safety and validation.
+ *
+ * Features:
+ * - Fluent API for easy configuration
+ * - Type-safe provider selection
+ * - Automatic environment variable resolution
+ * - Built-in validation
+ * - Support for presets
+ *
+ * @example
+ * const config = new ConfigBuilder()
+ *   .vectorDb('pinecone', { apiKey: process.env.PINECONE_API_KEY })
+ *   .llm('openai', 'gpt-4o', process.env.OPENAI_API_KEY)
+ *   .embedding('openai', 'text-embedding-3-small')
+ *   .projectId('my-app')
+ *   .build();
+ *
+ * const plugin = new VectorPlugin(config);
+ */
+
+import { RagConfig, VectorDBConfig, LLMConfig, EmbeddingConfig, VectorDBProvider, LLMProvider, EmbeddingProvider } from './RagConfig';
+
+export class ConfigBuilder {
+  private config: Partial<RagConfig> = {
+    projectId: 'default-project',
+    rag: {
+      chunkSize: 1000,
+      chunkOverlap: 200,
+      topK: 5,
+    },
+  };
+
+  /**
+   * Set the project/application ID for namespacing
+   */
+  projectId(id: string): this {
+    this.config.projectId = id;
+    return this;
+  }
+
+  /**
+   * Configure the vector database provider
+   */
+  vectorDb(
+    provider: VectorDBProvider | 'universal-rest' | 'auto',
+    options?: Record<string, unknown>
+  ): this {
+    if (provider === 'auto') {
+      // Auto-detect from environment
+      this.config.vectorDb = this.autoDetectVectorDb();
+    } else {
+      this.config.vectorDb = {
+        provider: provider as VectorDBProvider,
+        indexName: (options?.indexName as string) ?? 'default',
+        options: {
+          ...options,
+        },
+      };
+    }
+    return this;
+  }
+
+  /**
+   * Configure the LLM provider for chat
+   */
+  llm(
+    provider: LLMProvider | 'auto',
+    model?: string,
+    apiKey?: string,
+    options?: Record<string, unknown>
+  ): this {
+    if (provider === 'auto') {
+      this.config.llm = this.autoDetectLLM();
+    } else {
+      this.config.llm = {
+        provider: provider as LLMProvider,
+        model: model ?? 'default-model',
+        apiKey,
+        systemPrompt: options?.systemPrompt as string | undefined,
+        maxTokens: (options?.maxTokens as number) ?? 1024,
+        temperature: (options?.temperature as number) ?? 0.7,
+        baseUrl: options?.baseUrl as string | undefined,
+        options,
+      };
+    }
+    return this;
+  }
+
+  /**
+   * Configure the embedding provider
+   */
+  embedding(
+    provider: EmbeddingProvider | 'auto',
+    model?: string,
+    apiKey?: string,
+    options?: Record<string, unknown>
+  ): this {
+    if (provider === 'auto') {
+      this.config.embedding = this.autoDetectEmbedding();
+    } else {
+      this.config.embedding = {
+        provider: provider as EmbeddingProvider,
+        model: model ?? 'default-embedding',
+        apiKey,
+        baseUrl: options?.baseUrl as string | undefined,
+        options,
+      };
+    }
+    return this;
+  }
+
+  /**
+   * Set RAG-specific parameters
+   */
+  rag(options: {
+    chunkSize?: number;
+    chunkOverlap?: number;
+    topK?: number;
+  }): this {
+    this.config.rag = {
+      ...(this.config.rag ?? {}),
+      ...options,
+    };
+    return this;
+  }
+
+  /**
+   * Set UI/UX parameters
+   */
+  ui(options: {
+    branding?: string;
+    primaryColor?: string;
+    darkMode?: boolean;
+  }): this {
+    this.config.ui = options;
+    return this;
+  }
+
+
+
+  /**
+   * Build and return the configuration
+   */
+  build(): RagConfig {
+    const finalConfig = this.config as RagConfig;
+    return finalConfig;
+  }
+
+  /**
+   * Build and return as JSON for serialization
+   */
+  toJSON(): string {
+    return JSON.stringify(this.build());
+  }
+
+  // ============================================================================
+  // Private helper methods for auto-detection
+  // ============================================================================
+
+  private autoDetectVectorDb(): VectorDBConfig {
+    // Check for Pinecone
+    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 },
+      };
+    }
+
+    // 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,
+        },
+      };
+    }
+
+    // Check for PostgreSQL/pgvector
+    if (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',
+        },
+      };
+    }
+
+    // Check for Redis
+    if (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',
+      },
+    };
+  }
+
+  private autoDetectLLM(): LLMConfig {
+    // Check for OpenAI
+    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'),
+      };
+    }
+
+    // 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'),
+      };
+    }
+
+    // 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'),
+      };
+    }
+
+    // Default to OpenAI (requires API key at runtime)
+    return {
+      provider: 'openai',
+      model: 'gpt-4o-mini',
+      apiKey: process.env.OPENAI_API_KEY,
+    };
+  }
+
+  private autoDetectEmbedding(): EmbeddingConfig {
+    // Check for dedicated embedding provider
+    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,
+      };
+    }
+
+    // Default to OpenAI embeddings
+    return {
+      provider: 'openai',
+      model: 'text-embedding-3-small',
+      apiKey: process.env.OPENAI_API_KEY,
+    };
+  }
+}
+
+/**
+ * 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,
+  },
+} as const;
+
+export type PresetName = keyof typeof PRESETS;
+
+/**
+ * Helper to create config from preset
+ */
+export function createFromPreset(presetName: PresetName): ConfigBuilder {
+  const preset = PRESETS[presetName];
+  return new ConfigBuilder()
+    .vectorDb(preset.vectorDb, { apiKey: process.env[`${preset.vectorDb.toUpperCase()}_API_KEY`] })
+    .llm(preset.llm, undefined, process.env[`${preset.llm.toUpperCase()}_API_KEY`])
+    .embedding(preset.embedding, undefined, process.env[`${preset.embedding.toUpperCase()}_API_KEY`]);
+}

package/src/config/EmbeddingStrategy.ts

@@ -0,0 +1,147 @@
+/**
+ * EmbeddingStrategy — Unified strategy for handling different embedding scenarios
+ *
+ * Automatically determines whether to:
+ * 1. Use the LLM provider's built-in embedding (integrated)
+ * 2. Use a separate embedding provider (fallback)
+ * 3. Use an external embedding service
+ *
+ * This removes special-case handling from Pipeline and consolidates embedding logic.
+ */
+
+import { ILLMProvider } from '../llm/ILLMProvider';
+import { LLMFactory } from '../llm/LLMFactory';
+import { LLMConfig, EmbeddingConfig, LLMProvider, EmbeddingProvider } from './RagConfig';
+
+export enum EmbeddingStrategy {
+  /**
+   * LLM provider handles both chat and embeddings
+   * Example: OpenAI for both GPT and embeddings
+   */
+  INTEGRATED = 'integrated',
+
+  /**
+   * Use separate embedding provider different from LLM
+   * Example: Anthropic (chat) + OpenAI (embeddings)
+   */
+  SEPARATE = 'separate',
+
+  /**
+   * Use standalone embedding service
+   * Example: Dedicated embedding API
+   */
+  EXTERNAL = 'external',
+}
+
+export interface EmbeddingStrategyResult {
+  strategy: EmbeddingStrategy;
+  embeddingProvider: ILLMProvider;
+  llmProvider: ILLMProvider;
+}
+
+/**
+ * Determines the optimal embedding strategy and initializes providers
+ */
+export class EmbeddingStrategyResolver {
+  /**
+   * Determine strategy based on LLM and embedding configs
+   */
+  static determineStrategy(
+    llmConfig: LLMConfig,
+    embeddingConfig?: EmbeddingConfig
+  ): EmbeddingStrategy {
+    // If embedding config not provided, use integrated strategy
+    if (!embeddingConfig) {
+      return this.supportsEmbedding(llmConfig.provider)
+        ? EmbeddingStrategy.INTEGRATED
+        : EmbeddingStrategy.SEPARATE;
+    }
+
+    // If embedding config differs from LLM provider, use separate
+    if (embeddingConfig.provider !== (llmConfig.provider as EmbeddingProvider)) {
+      return EmbeddingStrategy.SEPARATE;
+    }
+
+    // If same provider but different models/configs, use external
+    if (embeddingConfig.model !== llmConfig.model) {
+      return EmbeddingStrategy.EXTERNAL;
+    }
+
+    // Default to integrated
+    return EmbeddingStrategy.INTEGRATED;
+  }
+
+  /**
+   * Resolve and initialize providers according to the strategy
+   */
+  static async resolve(
+    llmConfig: LLMConfig,
+    embeddingConfig?: EmbeddingConfig
+  ): Promise<EmbeddingStrategyResult> {
+    const strategy = this.determineStrategy(llmConfig, embeddingConfig);
+
+    const llmProvider = LLMFactory.create(llmConfig, embeddingConfig);
+
+    let embeddingProvider: ILLMProvider;
+
+    switch (strategy) {
+      case EmbeddingStrategy.INTEGRATED:
+        // Use the same provider for embeddings
+        embeddingProvider = llmProvider;
+        break;
+
+      case EmbeddingStrategy.SEPARATE:
+        // Create a separate embedding provider
+        if (!embeddingConfig) {
+          throw new Error(
+            '[EmbeddingStrategyResolver] SEPARATE strategy requires embeddingConfig'
+          );
+        }
+        embeddingProvider = LLMFactory.createEmbeddingProvider(embeddingConfig);
+        break;
+
+      case EmbeddingStrategy.EXTERNAL:
+        // Use the embedding config as a separate provider
+        if (!embeddingConfig) {
+          throw new Error(
+            '[EmbeddingStrategyResolver] EXTERNAL strategy requires embeddingConfig'
+          );
+        }
+        embeddingProvider = LLMFactory.createEmbeddingProvider(embeddingConfig);
+        break;
+
+      default:
+        throw new Error(`[EmbeddingStrategyResolver] Unknown strategy: ${strategy}`);
+    }
+
+    return {
+      strategy,
+      embeddingProvider,
+      llmProvider,
+    };
+  }
+
+  /**
+   * Check if an LLM provider natively supports embeddings
+   */
+  private static supportsEmbedding(provider: LLMProvider | string): boolean {
+    const providersWithEmbedding = ['openai', 'ollama', 'rest', 'universal_rest'];
+    return providersWithEmbedding.includes(provider);
+  }
+
+  /**
+   * Get a human-readable description of the strategy
+   */
+  static getDescription(strategy: EmbeddingStrategy): string {
+    switch (strategy) {
+      case EmbeddingStrategy.INTEGRATED:
+        return 'Using LLM provider for both chat and embeddings';
+      case EmbeddingStrategy.SEPARATE:
+        return 'Using separate embedding provider';
+      case EmbeddingStrategy.EXTERNAL:
+        return 'Using external embedding service';
+      default:
+        return 'Unknown strategy';
+    }
+  }
+}