@retrivora-ai/rag-engine 1.8.0 → 1.8.2

package/dist/DocumentChunker-Dh9TvmGG.d.mts

@@ -0,0 +1,45 @@
+/**
+ * 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
+ */
+interface Chunk {
+    id: string;
+    content: string;
+    metadata?: Record<string, unknown>;
+}
+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 | number;
+    /** Extra metadata to attach to every chunk */
+    metadata?: Record<string, unknown>;
+    /** Characters used to split text, in order of priority */
+    separators?: string[];
+}
+declare class DocumentChunker {
+    private readonly chunkSize;
+    private readonly chunkOverlap;
+    private readonly separators;
+    constructor(chunkSize?: number, chunkOverlap?: number, separators?: string[]);
+    /**
+     * Split a single text string into overlapping chunks using a recursive strategy.
+     * Preserves structural boundaries (Markdown headers) where possible.
+     */
+    chunk(text: string, options?: ChunkOptions): Chunk[];
+    private recursiveSplit;
+    chunkMany(documents: Array<{
+        content: string;
+        docId?: string | number;
+        metadata?: Record<string, unknown>;
+    }>): Chunk[];
+}
+
+export { type Chunk as C, DocumentChunker as D, type ChunkOptions as a };

package/dist/DocumentChunker-Dh9TvmGG.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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
+ */
+interface Chunk {
+    id: string;
+    content: string;
+    metadata?: Record<string, unknown>;
+}
+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 | number;
+    /** Extra metadata to attach to every chunk */
+    metadata?: Record<string, unknown>;
+    /** Characters used to split text, in order of priority */
+    separators?: string[];
+}
+declare class DocumentChunker {
+    private readonly chunkSize;
+    private readonly chunkOverlap;
+    private readonly separators;
+    constructor(chunkSize?: number, chunkOverlap?: number, separators?: string[]);
+    /**
+     * Split a single text string into overlapping chunks using a recursive strategy.
+     * Preserves structural boundaries (Markdown headers) where possible.
+     */
+    chunk(text: string, options?: ChunkOptions): Chunk[];
+    private recursiveSplit;
+    chunkMany(documents: Array<{
+        content: string;
+        docId?: string | number;
+        metadata?: Record<string, unknown>;
+    }>): Chunk[];
+}
+
+export { type Chunk as C, DocumentChunker as D, type ChunkOptions as a };

package/dist/{index-DPsQodME.d.mts → ILLMProvider-BOJFz3Na.d.mts}

@@ -7,6 +7,8 @@ interface RagMessage extends ChatMessage {
     id: string;
     sources?: VectorMatch[];
     uiTransformation?: unknown;
+    /** Full observability trace emitted by the backend. Only present on assistant messages. */
+    trace?: ObservabilityTrace;
     createdAt: string;
 }
 interface ChatOptions {
@@ -16,6 +18,12 @@ interface ChatOptions {
     temperature?: number;
     /** Stop sequences */
     stop?: string[];
+    /**
+     * Per-call system prompt override. When provided, providers should use this
+     * instead of (or in addition to) their configured llmConfig.systemPrompt.
+     * Useful for one-off analytical calls (e.g. UITransformer.analyzeAndDecide).
+     */
+    systemPrompt?: string;
 }
 interface UseRagChatOptions {
     /** Override the chat API endpoint (default: /api/chat) */
@@ -201,6 +209,11 @@ interface RAGConfig {
      * Used to dynamically extract hints from natural language queries.
      */
     filterableFields?: string[];
+    /** Optional mapping from database metadata fields to standard UI properties.
+     * Useful for databases with custom schemas.
+     * e.g., { "name": "ProductName", "price": "SalesPrice", "image": "ThumbnailUrl" }
+     */
+    uiMapping?: Record<string, string>;
 }
 interface RagConfig {
     /**
@@ -222,6 +235,48 @@ interface RagConfig {
     graphDb?: GraphDBConfig;
 }
 
+/** Per-stage latency breakdown for a single RAG request. */
+interface LatencyBreakdown {
+    embedMs: number;
+    retrieveMs: number;
+    rerankMs?: number;
+    generateMs: number;
+    totalMs: number;
+}
+/** Token usage reported by the LLM (or estimated when the provider doesn't expose it). */
+interface TokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    /** Rough cost in USD — estimated from token counts and model pricing. */
+    estimatedCostUsd?: number;
+}
+/** A single retrieved chunk annotated with its retrieval context. */
+interface RetrievedChunk {
+    id: string | number;
+    score: number;
+    content: string;
+    metadata: Record<string, unknown>;
+    namespace: string;
+}
+/**
+ * Full observability trace for one RAG request.
+ * Emitted by the backend as an SSE frame and stored on each RagMessage.
+ */
+interface ObservabilityTrace {
+    requestId: string;
+    query: string;
+    rewrittenQuery?: string;
+    systemPrompt: string;
+    userPrompt: string;
+    chunks: RetrievedChunk[];
+    latency: LatencyBreakdown;
+    tokens?: TokenUsage;
+    /** 0 = fully grounded, 1 = likely hallucinated. */
+    hallucinationScore?: number;
+    hallucinationReason?: string;
+    timestamp: string;
+}
 interface VectorMatch {
     id: string | number;
     score: number;
@@ -244,6 +299,8 @@ interface ChatResponse {
     sources: VectorMatch[];
     graphData?: GraphSearchResult;
     ui_transformation?: unknown;
+    /** Observability trace — populated by the instrumented Pipeline. */
+    trace?: ObservabilityTrace;
 }
 interface GraphNode {
     id: string;
@@ -274,4 +331,50 @@ interface Product {
     description?: string;
 }
 
-export type { ChatMessage as C, EmbeddingConfig as E, GraphDBConfig as G, IngestDocument as I, LLMConfig as L, Product as P, RagMessage as R, UIConfig as U, VectorMatch as V, UseRagChatOptions as a, UseRagChatReturn as b, ChatOptions as c, ChatResponse as d, EmbeddingProvider as e, LLMProvider as f, RAGConfig as g, RagConfig as h, UpsertDocument as i, VectorDBConfig as j, VectorDBProvider as k, RetrievalResult as l, GraphNode as m, Edge as n, GraphSearchResult as o };
+/**
+ * Generic LLM Provider interface.
+ * Covers both chat completion and embedding generation so a single
+ * provider can handle both responsibilities when appropriate.
+ */
+
+interface EmbedOptions {
+    /** Override model for this specific embed call */
+    model?: string;
+    /** Specify the task type for models that require prefixes (e.g. nomic-embed-text) */
+    taskType?: 'query' | 'document';
+}
+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>;
+    /**
+     * Send a streaming chat completion request.
+     * @returns – an async iterable of text chunks
+     */
+    chatStream?(messages: ChatMessage[], context: string, options?: ChatOptions): AsyncIterable<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>;
+}
+
+export type { ChatMessage as C, EmbedOptions as E, GraphDBConfig as G, ILLMProvider as I, LLMConfig as L, ObservabilityTrace as O, Product as P, RagMessage as R, TokenUsage as T, UIConfig as U, VectorMatch as V, UseRagChatOptions as a, UseRagChatReturn as b, ChatOptions as c, ChatResponse as d, EmbeddingConfig as e, EmbeddingProvider as f, IngestDocument as g, LLMProvider as h, LatencyBreakdown as i, RAGConfig as j, RagConfig as k, RetrievedChunk as l, UpsertDocument as m, VectorDBConfig as n, VectorDBProvider as o, RetrievalResult as p, GraphNode as q, Edge as r, GraphSearchResult as s };

package/dist/{index-DPsQodME.d.ts → ILLMProvider-BOJFz3Na.d.ts}

@@ -7,6 +7,8 @@ interface RagMessage extends ChatMessage {
     id: string;
     sources?: VectorMatch[];
     uiTransformation?: unknown;
+    /** Full observability trace emitted by the backend. Only present on assistant messages. */
+    trace?: ObservabilityTrace;
     createdAt: string;
 }
 interface ChatOptions {
@@ -16,6 +18,12 @@ interface ChatOptions {
     temperature?: number;
     /** Stop sequences */
     stop?: string[];
+    /**
+     * Per-call system prompt override. When provided, providers should use this
+     * instead of (or in addition to) their configured llmConfig.systemPrompt.
+     * Useful for one-off analytical calls (e.g. UITransformer.analyzeAndDecide).
+     */
+    systemPrompt?: string;
 }
 interface UseRagChatOptions {
     /** Override the chat API endpoint (default: /api/chat) */
@@ -201,6 +209,11 @@ interface RAGConfig {
      * Used to dynamically extract hints from natural language queries.
      */
     filterableFields?: string[];
+    /** Optional mapping from database metadata fields to standard UI properties.
+     * Useful for databases with custom schemas.
+     * e.g., { "name": "ProductName", "price": "SalesPrice", "image": "ThumbnailUrl" }
+     */
+    uiMapping?: Record<string, string>;
 }
 interface RagConfig {
     /**
@@ -222,6 +235,48 @@ interface RagConfig {
     graphDb?: GraphDBConfig;
 }
 
+/** Per-stage latency breakdown for a single RAG request. */
+interface LatencyBreakdown {
+    embedMs: number;
+    retrieveMs: number;
+    rerankMs?: number;
+    generateMs: number;
+    totalMs: number;
+}
+/** Token usage reported by the LLM (or estimated when the provider doesn't expose it). */
+interface TokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    /** Rough cost in USD — estimated from token counts and model pricing. */
+    estimatedCostUsd?: number;
+}
+/** A single retrieved chunk annotated with its retrieval context. */
+interface RetrievedChunk {
+    id: string | number;
+    score: number;
+    content: string;
+    metadata: Record<string, unknown>;
+    namespace: string;
+}
+/**
+ * Full observability trace for one RAG request.
+ * Emitted by the backend as an SSE frame and stored on each RagMessage.
+ */
+interface ObservabilityTrace {
+    requestId: string;
+    query: string;
+    rewrittenQuery?: string;
+    systemPrompt: string;
+    userPrompt: string;
+    chunks: RetrievedChunk[];
+    latency: LatencyBreakdown;
+    tokens?: TokenUsage;
+    /** 0 = fully grounded, 1 = likely hallucinated. */
+    hallucinationScore?: number;
+    hallucinationReason?: string;
+    timestamp: string;
+}
 interface VectorMatch {
     id: string | number;
     score: number;
@@ -244,6 +299,8 @@ interface ChatResponse {
     sources: VectorMatch[];
     graphData?: GraphSearchResult;
     ui_transformation?: unknown;
+    /** Observability trace — populated by the instrumented Pipeline. */
+    trace?: ObservabilityTrace;
 }
 interface GraphNode {
     id: string;
@@ -274,4 +331,50 @@ interface Product {
     description?: string;
 }
 
-export type { ChatMessage as C, EmbeddingConfig as E, GraphDBConfig as G, IngestDocument as I, LLMConfig as L, Product as P, RagMessage as R, UIConfig as U, VectorMatch as V, UseRagChatOptions as a, UseRagChatReturn as b, ChatOptions as c, ChatResponse as d, EmbeddingProvider as e, LLMProvider as f, RAGConfig as g, RagConfig as h, UpsertDocument as i, VectorDBConfig as j, VectorDBProvider as k, RetrievalResult as l, GraphNode as m, Edge as n, GraphSearchResult as o };
+/**
+ * Generic LLM Provider interface.
+ * Covers both chat completion and embedding generation so a single
+ * provider can handle both responsibilities when appropriate.
+ */
+
+interface EmbedOptions {
+    /** Override model for this specific embed call */
+    model?: string;
+    /** Specify the task type for models that require prefixes (e.g. nomic-embed-text) */
+    taskType?: 'query' | 'document';
+}
+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>;
+    /**
+     * Send a streaming chat completion request.
+     * @returns – an async iterable of text chunks
+     */
+    chatStream?(messages: ChatMessage[], context: string, options?: ChatOptions): AsyncIterable<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>;
+}
+
+export type { ChatMessage as C, EmbedOptions as E, GraphDBConfig as G, ILLMProvider as I, LLMConfig as L, ObservabilityTrace as O, Product as P, RagMessage as R, TokenUsage as T, UIConfig as U, VectorMatch as V, UseRagChatOptions as a, UseRagChatReturn as b, ChatOptions as c, ChatResponse as d, EmbeddingConfig as e, EmbeddingProvider as f, IngestDocument as g, LLMProvider as h, LatencyBreakdown as i, RAGConfig as j, RagConfig as k, RetrievedChunk as l, UpsertDocument as m, VectorDBConfig as n, VectorDBProvider as o, RetrievalResult as p, GraphNode as q, Edge as r, GraphSearchResult as s };

package/dist/MultiTablePostgresProvider-ZLGSKTJR.mjs

@@ -0,0 +1,8 @@
+import {
+  MultiTablePostgresProvider
+} from "./chunk-OZFBG4BA.mjs";
+import "./chunk-IMP6FUCY.mjs";
+import "./chunk-X4TOT24V.mjs";
+export {
+  MultiTablePostgresProvider
+};

package/dist/chunk-ICKRMZQK.mjs

@@ -0,0 +1,76 @@
+// src/utils/synonyms.ts
+var FIELD_SYNONYMS = {
+  name: ["product", "item", "title", "label", "heading", "subject", "product name", "item name"],
+  price: ["cost", "amount", "msrp", "price", "rate", "value", "price_usd"],
+  brand: ["manufacturer", "vendor", "make", "company", "brand_name", "supplier"],
+  image: [
+    "imageUrl",
+    "thumbnail",
+    "img",
+    "url",
+    "photo",
+    "picture",
+    "media",
+    "image_url",
+    "main_image",
+    "product_image",
+    "thumb"
+  ],
+  stock: [
+    "inventory",
+    "quantity",
+    "count",
+    "availability",
+    "stock_level",
+    "inStock",
+    "is_available",
+    "in stock",
+    "status"
+  ],
+  description: ["summary", "content", "body", "text", "info", "details"],
+  link: ["url", "href", "product_url", "page_url", "link"]
+};
+function addSynonyms(customSynonyms) {
+  for (const [key, aliases] of Object.entries(customSynonyms)) {
+    if (!FIELD_SYNONYMS[key]) {
+      FIELD_SYNONYMS[key] = [];
+    }
+    const existing = new Set(FIELD_SYNONYMS[key].map((s) => s.toLowerCase()));
+    for (const alias of aliases) {
+      if (!existing.has(alias.toLowerCase())) {
+        FIELD_SYNONYMS[key].push(alias);
+        existing.add(alias.toLowerCase());
+      }
+    }
+  }
+}
+function resolveMetadataValue(meta, uiKey) {
+  var _a;
+  const synonyms = (_a = FIELD_SYNONYMS[uiKey]) != null ? _a : [];
+  const keys = Object.keys(meta);
+  const systemKeys = ["namespace", "filename", "filesize", "filetype", "docid", "uploadedat", "dimension", "chunkindex"];
+  let match = keys.find((k) => k.toLowerCase() === uiKey.toLowerCase());
+  if (match !== void 0) return meta[match];
+  match = keys.find((k) => synonyms.map((s) => s.toLowerCase()).includes(k.toLowerCase()));
+  if (match !== void 0) return meta[match];
+  const isBlacklisted = (kl) => {
+    return systemKeys.includes(kl) || kl.startsWith("option1") || kl.startsWith("option2") || kl.startsWith("option3");
+  };
+  match = keys.find((k) => {
+    const kl = k.toLowerCase();
+    if (isBlacklisted(kl)) return false;
+    return kl.includes(uiKey.toLowerCase());
+  });
+  if (match !== void 0) return meta[match];
+  match = keys.find((k) => {
+    const kl = k.toLowerCase();
+    if (isBlacklisted(kl)) return false;
+    return synonyms.some((sk) => kl.includes(sk.toLowerCase()) || sk.toLowerCase().includes(kl));
+  });
+  return match !== void 0 ? meta[match] : void 0;
+}
+
+export {
+  addSynonyms,
+  resolveMetadataValue
+};