@retrivora-ai/rag-engine 0.1.0

package/src/llm/ILLMProvider.ts

@@ -0,0 +1,60 @@
+/**
+ * Generic LLM Provider interface.
+ * Covers both chat completion and embedding generation so a single
+ * provider can handle both responsibilities when appropriate.
+ */
+
+export interface ChatMessage {
+  role: 'user' | 'assistant' | 'system';
+  content: string;
+}
+
+export interface ChatOptions {
+  /** Override max tokens for this specific call */
+  maxTokens?: number;
+  /** Override temperature for this specific call */
+  temperature?: number;
+  /** Stop sequences */
+  stop?: string[];
+}
+
+export interface EmbedOptions {
+  /** Override model for this specific embed call */
+  model?: string;
+}
+
+export interface ILLMProvider {
+  /**
+   * Send a chat completion request.
+   * @param messages – the full conversation history
+   * @param context  – retrieved RAG context to inject
+   * @param options  – optional per-call overrides
+   * @returns        – the assistant's reply text
+   */
+  chat(
+    messages: ChatMessage[],
+    context: string,
+    options?: ChatOptions
+  ): Promise<string>;
+
+  /**
+   * Generate an embedding vector for the given text.
+   * @param text    – text to embed
+   * @param options – optional overrides
+   * @returns       – float array (the embedding)
+   */
+  embed(text: string, options?: EmbedOptions): Promise<number[]>;
+
+  /**
+   * Generate embedding vectors for multiple texts in a single batch.
+   * @param texts   – array of texts to embed
+   * @param options – optional overrides
+   * @returns       – array of float arrays
+   */
+  batchEmbed(texts: string[], options?: EmbedOptions): Promise<number[][]>;
+
+  /**
+   * Check if the provider endpoint is reachable.
+   */
+  ping(): Promise<boolean>;
+}

package/src/llm/LLMFactory.ts

@@ -0,0 +1,54 @@
+/**
+ * LLMFactory — instantiates the correct ILLMProvider based on llmConfig.provider.
+ *
+ * Also accepts an optional EmbeddingConfig so providers that support embedding
+ * can be initialised with separate embedding credentials.
+ */
+
+import { ILLMProvider } from './ILLMProvider';
+import { LLMConfig, EmbeddingConfig, LLMProvider } from '../config/RagConfig';
+import { OpenAIProvider } from './providers/OpenAIProvider';
+import { AnthropicProvider } from './providers/AnthropicProvider';
+import { OllamaProvider } from './providers/OllamaProvider';
+import { UniversalLLMAdapter } from './providers/UniversalLLMAdapter';
+
+export class LLMFactory {
+  static create(llmConfig: LLMConfig, embeddingConfig?: EmbeddingConfig): ILLMProvider {
+    switch (llmConfig.provider) {
+      case 'openai':
+        return new OpenAIProvider(llmConfig, embeddingConfig);
+      case 'anthropic':
+        return new AnthropicProvider(llmConfig, embeddingConfig);
+      case 'ollama':
+        return new OllamaProvider(llmConfig, embeddingConfig);
+      case 'rest':
+      case 'universal_rest':
+      case 'custom':
+        return new UniversalLLMAdapter(llmConfig);
+      default:
+        // If baseUrl is provided but provider is unknown, fallback to Universal Adapter
+        if (llmConfig.baseUrl || (llmConfig.options as Record<string, unknown>)?.baseUrl) {
+          return new UniversalLLMAdapter(llmConfig);
+        }
+        throw new Error(
+          `[LLMFactory] Unknown provider "${llmConfig.provider}". ` +
+            `Supported: openai | anthropic | ollama | rest | custom`
+        );
+    }
+  }
+
+  /**
+   * Creates a dedicated embedding-only provider.
+   * Useful when the LLM provider (e.g. Anthropic) doesn't support embeddings.
+   */
+  static createEmbeddingProvider(embeddingConfig: EmbeddingConfig): ILLMProvider {
+    const fakeLLMConfig: LLMConfig = {
+      provider: embeddingConfig.provider as LLMProvider,
+      model: embeddingConfig.model,
+      apiKey: embeddingConfig.apiKey,
+      baseUrl: embeddingConfig.baseUrl,
+      options: embeddingConfig.options,
+    };
+    return LLMFactory.create(fakeLLMConfig, embeddingConfig);
+  }
+}

package/src/llm/providers/AnthropicProvider.ts

@@ -0,0 +1,87 @@
+/**
+ * Anthropic (Claude) LLM Provider
+ *
+ * Handles chat completion via Anthropic's Messages API.
+ * Note: Anthropic does NOT provide embedding models — use OpenAIProvider
+ * or OllamaProvider for embedding when pairing with this provider.
+ *
+ * Required LLMConfig fields:
+ *   - apiKey: string  – Anthropic API key
+ *   - model:  string  – e.g. "claude-3-5-sonnet-20241022"
+ */
+
+import Anthropic from '@anthropic-ai/sdk';
+import { ILLMProvider, ChatMessage, ChatOptions, EmbedOptions } from '../ILLMProvider';
+import { LLMConfig, EmbeddingConfig } from '../../config/RagConfig';
+
+export class AnthropicProvider implements ILLMProvider {
+  private readonly client: Anthropic;
+  private readonly llmConfig: LLMConfig;
+  private readonly embeddingConfig?: EmbeddingConfig;
+
+  constructor(llmConfig: LLMConfig, embeddingConfig?: EmbeddingConfig) {
+    if (!llmConfig.apiKey) throw new Error('[AnthropicProvider] llmConfig.apiKey is required');
+    this.client = new Anthropic({ apiKey: llmConfig.apiKey });
+    this.llmConfig = llmConfig;
+    this.embeddingConfig = embeddingConfig;
+  }
+
+  async chat(messages: ChatMessage[], context: string, options?: ChatOptions): Promise<string> {
+    const systemPrompt =
+      this.llmConfig.systemPrompt ??
+      `You are a helpful assistant. Use the context below to answer the user's question accurately.\n\nContext:\n${context}`;
+
+    const system = systemPrompt.includes('{{context}}')
+      ? systemPrompt.replace('{{context}}', context)
+      : `${systemPrompt}\n\nContext:\n${context}`;
+
+    // Anthropic requires alternating user/assistant messages
+    const anthropicMessages: Anthropic.MessageParam[] = messages.map((m) => ({
+      role: m.role === 'assistant' ? 'assistant' : 'user',
+      content: m.content,
+    }));
+
+    const response = await this.client.messages.create({
+      model: this.llmConfig.model,
+      max_tokens: options?.maxTokens ?? this.llmConfig.maxTokens ?? 1024,
+      system,
+      messages: anthropicMessages,
+    });
+
+    const block = response.content[0];
+    return block.type === 'text' ? block.text : '';
+  }
+
+  /**
+   * Anthropic does not offer an embedding API.
+   * This method throws with a clear error so developers know to configure
+   * a separate embedding provider (OpenAI or Ollama).
+   */
+  async embed(text: string, options?: EmbedOptions): Promise<number[]> {
+    void text;
+    void options;
+    throw new Error(
+      '[AnthropicProvider] Anthropic does not provide an embedding API. ' +
+        'Set embedding.provider to "openai" or "ollama" in your RagConfig.'
+    );
+  }
+
+  async batchEmbed(texts: string[], options?: EmbedOptions): Promise<number[][]> {
+    void texts;
+    void options;
+    throw new Error(
+      '[AnthropicProvider] Anthropic does not provide an embedding API.'
+    );
+  }
+
+  async ping(): Promise<boolean> {
+    try {
+      // Lightweight model list call to verify connectivity
+      await this.client.models.list();
+      return true;
+    } catch (err) {
+      console.error('[AnthropicProvider] Ping failed:', err);
+      return false;
+    }
+  }
+}

package/src/llm/providers/OllamaProvider.ts

@@ -0,0 +1,102 @@
+/**
+ * Ollama LLM Provider (local / self-hosted)
+ *
+ * Communicates with an Ollama server via its REST API.
+ * Supports both chat completion and embedding (requires a model with embed support,
+ * e.g. "nomic-embed-text", "mxbai-embed-large").
+ *
+ * Required LLMConfig fields:
+ *   - model:    string  – e.g. "llama3", "mistral", "gemma2"
+ *   - baseUrl?: string  – Ollama server URL (default "http://localhost:11434")
+ */
+
+import axios, { AxiosInstance } from 'axios';
+import { ILLMProvider, ChatMessage, ChatOptions, EmbedOptions } from '../ILLMProvider';
+import { LLMConfig, EmbeddingConfig } from '../../config/RagConfig';
+
+interface OllamaChatResponse {
+  message: { content: string };
+}
+
+interface OllamaEmbedResponse {
+  embedding: number[];
+}
+
+export class OllamaProvider implements ILLMProvider {
+  private readonly http: AxiosInstance;
+  private readonly llmConfig: LLMConfig;
+  private readonly embeddingConfig?: EmbeddingConfig;
+
+  constructor(llmConfig: LLMConfig, embeddingConfig?: EmbeddingConfig) {
+    const baseURL = llmConfig.baseUrl ?? 'http://localhost:11434';
+    this.http = axios.create({ baseURL, timeout: 120_000 });
+    this.llmConfig = llmConfig;
+    this.embeddingConfig = embeddingConfig;
+  }
+
+  async chat(messages: ChatMessage[], context: string, options?: ChatOptions): Promise<string> {
+    const systemPrompt =
+      this.llmConfig.systemPrompt ??
+      `You are a helpful assistant. Use the provided context to answer the user's question.\n\nContext:\n${context}`;
+
+    const system = systemPrompt.includes('{{context}}')
+      ? systemPrompt.replace('{{context}}', context)
+      : `${systemPrompt}\n\nContext:\n${context}`;
+
+    const { data } = await this.http.post<OllamaChatResponse>('/api/chat', {
+      model: this.llmConfig.model,
+      stream: false,
+      options: {
+        temperature: options?.temperature ?? this.llmConfig.temperature ?? 0.7,
+        num_predict: options?.maxTokens ?? this.llmConfig.maxTokens ?? 1024,
+      },
+      messages: [
+        { role: 'system', content: system },
+        ...messages.map((m) => ({ role: m.role, content: m.content })),
+      ],
+    });
+
+    return data.message.content;
+  }
+
+  async embed(text: string, options?: EmbedOptions): Promise<number[]> {
+    const model =
+      options?.model ??
+      this.embeddingConfig?.model ??
+      'nomic-embed-text';
+
+    const baseURL =
+      this.embeddingConfig?.baseUrl ?? this.llmConfig.baseUrl ?? 'http://localhost:11434';
+
+    const client =
+      baseURL !== (this.llmConfig.baseUrl ?? 'http://localhost:11434')
+        ? axios.create({ baseURL, timeout: 60_000 })
+        : this.http;
+
+    const { data } = await client.post<OllamaEmbedResponse>('/api/embeddings', {
+      model,
+      prompt: text,
+    });
+
+    return data.embedding;
+  }
+
+  async batchEmbed(texts: string[], options?: EmbedOptions): Promise<number[][]> {
+    const vectors: number[][] = [];
+    // Sequential fallback for Ollama (batch support varies by version)
+    for (const text of texts) {
+      vectors.push(await this.embed(text, options));
+    }
+    return vectors;
+  }
+
+  async ping(): Promise<boolean> {
+    try {
+      await this.http.get('/api/tags');
+      return true;
+    } catch (err) {
+      console.error('[OllamaProvider] Ping failed:', err);
+      return false;
+    }
+  }
+}

package/src/llm/providers/OpenAIProvider.ts

@@ -0,0 +1,92 @@
+/**
+ * OpenAI LLM Provider
+ *
+ * Handles both chat completion (GPT-4o, GPT-4-turbo, etc.) and
+ * embedding (text-embedding-ada-002, text-embedding-3-small/large).
+ *
+ * Required LLMConfig fields:
+ *   - apiKey: string  – OpenAI API key
+ *   - model:  string  – e.g. "gpt-4o"
+ *
+ * Required EmbeddingConfig fields (when used for embedding):
+ *   - apiKey: string  – same or separate key
+ *   - model:  string  – e.g. "text-embedding-3-small"
+ */
+
+import OpenAI from 'openai';
+import { ILLMProvider, ChatMessage, ChatOptions, EmbedOptions } from '../ILLMProvider';
+import { LLMConfig, EmbeddingConfig } from '../../config/RagConfig';
+
+export class OpenAIProvider implements ILLMProvider {
+  private readonly client: OpenAI;
+  private readonly llmConfig: LLMConfig;
+  private readonly embeddingConfig?: EmbeddingConfig;
+
+  constructor(llmConfig: LLMConfig, embeddingConfig?: EmbeddingConfig) {
+    if (!llmConfig.apiKey) throw new Error('[OpenAIProvider] llmConfig.apiKey is required');
+    this.client = new OpenAI({ apiKey: llmConfig.apiKey });
+    this.llmConfig = llmConfig;
+    this.embeddingConfig = embeddingConfig;
+  }
+
+  async chat(messages: ChatMessage[], context: string, options?: ChatOptions): Promise<string> {
+    const systemContent =
+      this.llmConfig.systemPrompt ??
+      `You are a helpful assistant. Answer questions based on the provided context.\n\nContext:\n${context}`;
+
+    const systemMessage: OpenAI.Chat.ChatCompletionSystemMessageParam = {
+      role: 'system',
+      content: systemContent.includes('{{context}}')
+        ? systemContent.replace('{{context}}', context)
+        : `${systemContent}\n\nContext:\n${context}`,
+    };
+
+    const formattedMessages: OpenAI.Chat.ChatCompletionMessageParam[] = [
+      systemMessage,
+      ...messages.map((m) => ({
+        role: m.role as 'user' | 'assistant',
+        content: m.content,
+      })),
+    ];
+
+    const completion = await this.client.chat.completions.create({
+      model: this.llmConfig.model,
+      messages: formattedMessages,
+      max_tokens: options?.maxTokens ?? this.llmConfig.maxTokens ?? 1024,
+      temperature: options?.temperature ?? this.llmConfig.temperature ?? 0.7,
+      stop: options?.stop,
+    });
+
+    return completion.choices[0]?.message?.content ?? '';
+  }
+
+  async embed(text: string, options?: EmbedOptions): Promise<number[]> {
+    const results = await this.batchEmbed([text], options);
+    return results[0];
+  }
+
+  async batchEmbed(texts: string[], options?: EmbedOptions): Promise<number[][]> {
+    const model =
+      options?.model ??
+      this.embeddingConfig?.model ??
+      'text-embedding-3-small';
+
+    const apiKey = this.embeddingConfig?.apiKey ?? this.llmConfig.apiKey;
+    const client = apiKey !== this.llmConfig.apiKey
+      ? new OpenAI({ apiKey })
+      : this.client;
+
+    const response = await client.embeddings.create({ model, input: texts });
+    return response.data.map((d) => d.embedding);
+  }
+
+  async ping(): Promise<boolean> {
+    try {
+      await this.client.models.list();
+      return true;
+    } catch (err) {
+      console.error('[OpenAIProvider] Ping failed:', err);
+      return false;
+    }
+  }
+}

package/src/llm/providers/UniversalLLMAdapter.ts

@@ -0,0 +1,154 @@
+import axios, { AxiosInstance } from 'axios';
+import { ILLMProvider, ChatMessage } from '../ILLMProvider';
+import { LLMConfig, EmbeddingConfig } from '../../config/RagConfig';
+import { resolvePath, buildPayload } from '../../utils/templateUtils';
+import { LLM_PROFILES } from '../../config/UniversalProfiles';
+
+interface UniversalLLMOptions {
+  baseUrl?: string;
+  headers?: Record<string, string>;
+  chatPath?: string;
+  embedPath?: string;
+  pingPath?: string;
+  chatPayloadTemplate?: string;
+  embedPayloadTemplate?: string;
+  responseExtractPath?: string;
+  embedExtractPath?: string;
+  timeout?: number;
+}
+
+export class UniversalLLMAdapter implements ILLMProvider {
+  private readonly http: AxiosInstance;
+  private readonly model: string;
+  private readonly opts: UniversalLLMOptions;
+  private readonly systemPrompt: string;
+  private readonly maxTokens: number;
+  private readonly temperature: number;
+
+  constructor(config: LLMConfig | EmbeddingConfig) {
+    this.model = config.model;
+    
+    // Type narrow to extract LLM-specific fields safely
+    const llmConfig = config as LLMConfig;
+    
+    // Merge profile defaults if specified in options
+    const options = (llmConfig.options as Record<string, unknown>) ?? {};
+    let profile: Record<string, unknown> = {};
+    
+    if (typeof options.profile === 'string') {
+      profile = (LLM_PROFILES as Record<string, Record<string, unknown>>)[options.profile] || {};
+    } else if (typeof options.profile === 'object' && options.profile !== null) {
+      profile = options.profile as Record<string, unknown>;
+    }
+    
+    this.opts = { ...profile, ...(llmConfig.options ?? {}) } as UniversalLLMOptions;
+    this.systemPrompt = llmConfig.systemPrompt ?? 'You are a helpful AI assistant. Use the provided context to answer the user.';
+    this.maxTokens = llmConfig.maxTokens ?? 1024;
+    this.temperature = llmConfig.temperature ?? 0;
+
+    const baseUrl = llmConfig.baseUrl ?? this.opts.baseUrl;
+    if (!baseUrl) {
+      throw new Error('[UniversalLLMAdapter] baseUrl is required in config or config.options');
+    }
+
+    this.http = axios.create({
+      baseURL: baseUrl,
+      headers: {
+        'Content-Type': 'application/json',
+        ...(config.apiKey ? { Authorization: `Bearer ${config.apiKey}` } : {}),
+        ...(this.opts.headers || {}),
+      },
+      timeout: this.opts.timeout ?? 60_000,
+    });
+  }
+
+  async chat(messages: ChatMessage[], context?: string): Promise<string> {
+    const path = this.opts.chatPath ?? '/chat/completions';
+    
+    const formattedMessages = [
+      { role: 'system', content: `${this.systemPrompt}\n\nContext:\n${context ?? 'None'}` },
+      ...messages,
+    ];
+
+    let payload: unknown;
+    if (this.opts.chatPayloadTemplate) {
+      // The user wants to map messages and parameters to their unique JSON shape
+      payload = buildPayload(this.opts.chatPayloadTemplate, {
+        model: this.model,
+        messages: formattedMessages,
+        maxTokens: this.maxTokens,
+        temperature: this.temperature,
+      });
+    } else {
+      // Fallback to OpenAI standard which covers 90% of open-source models (vLLM, LMStudio, Ollama, etc.)
+      payload = {
+        model: this.model,
+        messages: formattedMessages,
+        max_tokens: this.maxTokens,
+        temperature: this.temperature,
+      };
+    }
+
+    const { data } = await this.http.post(path, payload);
+
+    const extractPath = this.opts.responseExtractPath ?? 'choices[0].message.content';
+    const result = resolvePath(data, extractPath);
+
+    if (result === undefined) {
+      throw new Error(`[UniversalLLMAdapter] Could not extract text from path '${extractPath}' in response.`);
+    }
+
+    return String(result);
+  }
+
+  async embed(text: string): Promise<number[]> {
+    const path = this.opts.embedPath ?? '/embeddings';
+
+    let payload: unknown;
+    if (this.opts.embedPayloadTemplate) {
+      payload = buildPayload(this.opts.embedPayloadTemplate, {
+        model: this.model,
+        input: text,
+      });
+    } else {
+      // OpenAI standard fallback
+      payload = {
+        model: this.model,
+        input: text,
+      };
+    }
+
+    const { data } = await this.http.post(path, payload);
+
+    const extractPath = this.opts.embedExtractPath ?? 'data[0].embedding';
+    const vector = resolvePath(data, extractPath);
+
+    if (!Array.isArray(vector)) {
+      throw new Error(`[UniversalLLMAdapter] Expected a number array at '${extractPath}' for embeddings.`);
+    }
+
+    return vector;
+  }
+
+  async batchEmbed(texts: string[]): Promise<number[][]> {
+    const vectors: number[][] = [];
+    // Sequential fallback if the provider doesn't have a specific batch template
+    // In production, we should add a batchEmbedPayloadTemplate to UniversalLLMOptions
+    for (const text of texts) {
+      vectors.push(await this.embed(text));
+    }
+    return vectors;
+  }
+
+  async ping(): Promise<boolean> {
+    try {
+      if (this.opts.pingPath) {
+        await this.http.get(this.opts.pingPath);
+      }
+      return true;
+    } catch (err) {
+      console.error('[UniversalLLMAdapter] Ping failed:', err);
+      return false;
+    }
+  }
+}

package/src/rag/DocumentChunker.ts

@@ -0,0 +1,105 @@
+/**
+ * DocumentChunker — splits long text into overlapping chunks
+ * suitable for vector embedding and retrieval.
+ *
+ * Strategy: sentence-aware sliding window
+ *   1. Split on sentence boundaries
+ *   2. Accumulate sentences into chunks up to `chunkSize` characters
+ *   3. Carry over `chunkOverlap` characters from the previous chunk
+ */
+
+export interface Chunk {
+  id: string;
+  content: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface ChunkOptions {
+  /** Target chunk size in characters (default 1000) */
+  chunkSize?: number;
+  /** Overlap between consecutive chunks in characters (default 200) */
+  chunkOverlap?: number;
+  /** Source document identifier used as ID prefix */
+  docId?: string;
+  /** Extra metadata to attach to every chunk */
+  metadata?: Record<string, unknown>;
+}
+
+export class DocumentChunker {
+  private readonly chunkSize: number;
+  private readonly chunkOverlap: number;
+
+  constructor(chunkSize = 1000, chunkOverlap = 200) {
+    this.chunkSize = chunkSize;
+    this.chunkOverlap = chunkOverlap;
+  }
+
+  /**
+   * Split a single text string into overlapping chunks.
+   */
+  chunk(text: string, options: ChunkOptions = {}): Chunk[] {
+    const {
+      chunkSize = this.chunkSize,
+      chunkOverlap = this.chunkOverlap,
+      docId = `doc_${Date.now()}`,
+      metadata = {},
+    } = options;
+
+    // Normalise whitespace
+    const cleaned = text.replace(/\r\n/g, '\n').trim();
+    if (!cleaned) return [];
+
+    // Split into sentences (handles . ! ? followed by space/newline)
+    const sentences = cleaned
+      .split(/(?<=[.!?])\s+|\n{2,}/)
+      .map((s) => s.trim())
+      .filter(Boolean);
+
+    const chunks: Chunk[] = [];
+    let current = '';
+    let chunkIndex = 0;
+
+    for (const sentence of sentences) {
+      if ((current + ' ' + sentence).trim().length <= chunkSize) {
+        current = current ? `${current} ${sentence}` : sentence;
+      } else {
+        if (current) {
+          chunks.push({
+            id: `${docId}_chunk_${chunkIndex++}`,
+            content: current.trim(),
+            metadata: { ...metadata, docId, chunkIndex: chunkIndex - 1 },
+          });
+        }
+
+        // Start new chunk with overlap from the previous one
+        if (chunkOverlap > 0 && current.length > chunkOverlap) {
+          current = current.slice(-chunkOverlap) + ' ' + sentence;
+        } else {
+          current = sentence;
+        }
+      }
+    }
+
+    // Push the last remaining chunk
+    if (current.trim()) {
+      chunks.push({
+        id: `${docId}_chunk_${chunkIndex}`,
+        content: current.trim(),
+        metadata: { ...metadata, docId, chunkIndex },
+      });
+    }
+
+    return chunks;
+  }
+
+  /**
+   * Chunk multiple documents at once.
+   */
+  chunkMany(
+    documents: Array<{ content: string; docId?: string; metadata?: Record<string, unknown> }>
+  ): Chunk[] {
+    return documents.flatMap((doc) =>
+      this.chunk(doc.content, { docId: doc.docId, metadata: doc.metadata })
+    );
+  }
+}