@retrivora-ai/rag-engine 1.9.3 → 1.9.7

package/dist/index-B9J_XEh0.d.ts

@@ -0,0 +1,187 @@
+import { k as RagConfig, I as ILLMProvider, g as IngestDocument, C as ChatMessage, d as ChatResponse, u as RetrievalResult, n as UniversalRagConfig } from './ILLMProvider-Bhk6zJOK.js';
+
+/**
+ * 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[];
+}
+
+/**
+ * Pipeline — orchestrates the RAG flow: Embed → Search → Augment → Generate.
+ *
+ * Features:
+ * - Lazy initialization of providers
+ * - Batch processing with retry logic
+ * - Smart embedding strategy (integrated / separate / external)
+ * - Error recovery for transient failures
+ * - Multi-tenancy support via namespacing
+ * - LRU-bounded embedding cache (max 500 entries, prevents memory leaks)
+ * - Full observability tracing (latency, tokens, hallucination scoring)
+ */
+declare class Pipeline {
+    private config;
+    private vectorDB;
+    private graphDB?;
+    private llmProvider;
+    private embeddingProvider;
+    private llmRouter;
+    private chunker;
+    private llamaIngestor?;
+    private entityExtractor?;
+    private reranker;
+    private agent?;
+    /** LRU-bounded cache: avoids re-embedding identical queries within the same process. */
+    private embeddingCache;
+    private initialised;
+    constructor(config: RagConfig);
+    /**
+     * Expose the underlying LLM provider (set after initialize()).
+     * Used by the stream handler to pass to UITransformer.analyzeAndDecide().
+     */
+    getLLMProvider(): ILLMProvider | undefined;
+    initialize(): Promise<void>;
+    /**
+     * Ingest documents with automatic chunking, embedding, and batch upsert.
+     */
+    ingest(documents: IngestDocument[], namespace?: string): Promise<Array<{
+        docId: string | number;
+        chunksIngested: number;
+    }>>;
+    /** Step 1: Chunk the document content. */
+    private prepareChunks;
+    /**
+     * Step 2: Generate embeddings for chunks with retry logic.
+     * Uses batchEmbed when available for efficiency; falls back to sequential embedding.
+     */
+    private processEmbeddings;
+    /** Step 3: Upsert chunks to vector database with retry logic. */
+    private processUpserts;
+    /** Step 4: Optional graph-based entity extraction and ingestion. */
+    private processGraphIngestion;
+    ask(question: string, history?: ChatMessage[], namespace?: string): Promise<ChatResponse>;
+    /**
+     * High-performance streaming RAG flow.
+     * Yields text chunks first, then the retrieval metadata + observability trace at the end.
+     *
+     * Latency optimizations:
+     * - Strategy classification runs in parallel with query embedding (saves ~400ms)
+     * - Hallucination scoring is fire-and-forget (doesn't block metadata yield)
+     * - UITransformation is computed after text streaming and emitted with metadata
+     * - SchemaMapper.train runs while answer generation streams
+     */
+    askStream(question: string, history?: ChatMessage[], namespace?: string): AsyncIterable<string | ChatResponse>;
+    /**
+     * Universal retrieval method combining all enabled providers.
+     * Uses an LRU-bounded embedding cache to avoid re-embedding the same query.
+     */
+    private generateUiTransformation;
+    private applyStructuredFilters;
+    private resolveNumericPredicateValue;
+    private extractNumericValueFromContent;
+    private matchesNumericPredicate;
+    private normalizeComparableField;
+    private fieldSimilarityScore;
+    private fieldTokens;
+    private toFiniteNumber;
+    retrieve(query: string, options: {
+        namespace?: string;
+        topK?: number;
+        filter?: Record<string, unknown>;
+    }): Promise<RetrievalResult>;
+    /** Rewrite the user query for better retrieval performance. */
+    private rewriteQuery;
+    /** Generate 3-5 short, relevant questions based on the vector database content. */
+    getSuggestions(query: string, namespace?: string): Promise<string[]>;
+}
+
+/**
+ * Public SDK facade matching the prompt-level Retrivora API.
+ *
+ * It keeps provider details behind configuration and delegates execution to the
+ * existing Pipeline implementation.
+ */
+declare class Retrivora {
+    private readonly pipeline;
+    readonly config: RagConfig;
+    constructor(config?: UniversalRagConfig);
+    initialize(): Promise<void>;
+    ingest(documents: IngestDocument[], namespace?: string): Promise<Array<{
+        docId: string | number;
+        chunksIngested: number;
+    }>>;
+    ask(question: string, history?: ChatMessage[], namespace?: string): Promise<ChatResponse>;
+    askStream(question: string, history?: ChatMessage[], namespace?: string): AsyncIterable<string | ChatResponse>;
+    getPipeline(): Pipeline;
+}
+
+/**
+ * Named SDK exceptions make failures machine-readable for host applications.
+ */
+type RetrivoraErrorCode = 'PROVIDER_NOT_FOUND' | 'EMBEDDING_FAILED' | 'RETRIEVAL_FAILED' | 'RATE_LIMITED' | 'CONFIGURATION_ERROR' | 'AUTHENTICATION_ERROR';
+declare class RetrivoraError extends Error {
+    readonly code: RetrivoraErrorCode;
+    readonly details?: unknown;
+    constructor(message: string, code: RetrivoraErrorCode, details?: unknown);
+}
+declare class ProviderNotFoundException extends RetrivoraError {
+    constructor(providerType: string, provider: string, details?: unknown);
+}
+declare class EmbeddingFailedException extends RetrivoraError {
+    constructor(message?: string, details?: unknown);
+}
+declare class RetrievalException extends RetrivoraError {
+    constructor(message?: string, details?: unknown);
+}
+declare class RateLimitException extends RetrivoraError {
+    constructor(message?: string, details?: unknown);
+}
+declare class ConfigurationException extends RetrivoraError {
+    constructor(message: string, details?: unknown);
+}
+declare class AuthenticationException extends RetrivoraError {
+    constructor(message?: string, details?: unknown);
+}
+/**
+ * Wraps any unknown error into an appropriate RetrivoraError subclass.
+ */
+declare function wrapError(err: unknown, defaultCode: RetrivoraErrorCode, defaultMessage?: string): RetrivoraError;
+
+export { AuthenticationException as A, type Chunk as C, DocumentChunker as D, EmbeddingFailedException as E, ProviderNotFoundException as P, RateLimitException as R, type ChunkOptions as a, ConfigurationException as b, RetrievalException as c, Retrivora as d, RetrivoraError as e, type RetrivoraErrorCode as f, Pipeline as g, wrapError as w };

package/dist/index-BJ4cd-t5.d.mts

@@ -0,0 +1,187 @@
+import { k as RagConfig, I as ILLMProvider, g as IngestDocument, C as ChatMessage, d as ChatResponse, u as RetrievalResult, n as UniversalRagConfig } from './ILLMProvider-Bhk6zJOK.mjs';
+
+/**
+ * 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[];
+}
+
+/**
+ * Pipeline — orchestrates the RAG flow: Embed → Search → Augment → Generate.
+ *
+ * Features:
+ * - Lazy initialization of providers
+ * - Batch processing with retry logic
+ * - Smart embedding strategy (integrated / separate / external)
+ * - Error recovery for transient failures
+ * - Multi-tenancy support via namespacing
+ * - LRU-bounded embedding cache (max 500 entries, prevents memory leaks)
+ * - Full observability tracing (latency, tokens, hallucination scoring)
+ */
+declare class Pipeline {
+    private config;
+    private vectorDB;
+    private graphDB?;
+    private llmProvider;
+    private embeddingProvider;
+    private llmRouter;
+    private chunker;
+    private llamaIngestor?;
+    private entityExtractor?;
+    private reranker;
+    private agent?;
+    /** LRU-bounded cache: avoids re-embedding identical queries within the same process. */
+    private embeddingCache;
+    private initialised;
+    constructor(config: RagConfig);
+    /**
+     * Expose the underlying LLM provider (set after initialize()).
+     * Used by the stream handler to pass to UITransformer.analyzeAndDecide().
+     */
+    getLLMProvider(): ILLMProvider | undefined;
+    initialize(): Promise<void>;
+    /**
+     * Ingest documents with automatic chunking, embedding, and batch upsert.
+     */
+    ingest(documents: IngestDocument[], namespace?: string): Promise<Array<{
+        docId: string | number;
+        chunksIngested: number;
+    }>>;
+    /** Step 1: Chunk the document content. */
+    private prepareChunks;
+    /**
+     * Step 2: Generate embeddings for chunks with retry logic.
+     * Uses batchEmbed when available for efficiency; falls back to sequential embedding.
+     */
+    private processEmbeddings;
+    /** Step 3: Upsert chunks to vector database with retry logic. */
+    private processUpserts;
+    /** Step 4: Optional graph-based entity extraction and ingestion. */
+    private processGraphIngestion;
+    ask(question: string, history?: ChatMessage[], namespace?: string): Promise<ChatResponse>;
+    /**
+     * High-performance streaming RAG flow.
+     * Yields text chunks first, then the retrieval metadata + observability trace at the end.
+     *
+     * Latency optimizations:
+     * - Strategy classification runs in parallel with query embedding (saves ~400ms)
+     * - Hallucination scoring is fire-and-forget (doesn't block metadata yield)
+     * - UITransformation is computed after text streaming and emitted with metadata
+     * - SchemaMapper.train runs while answer generation streams
+     */
+    askStream(question: string, history?: ChatMessage[], namespace?: string): AsyncIterable<string | ChatResponse>;
+    /**
+     * Universal retrieval method combining all enabled providers.
+     * Uses an LRU-bounded embedding cache to avoid re-embedding the same query.
+     */
+    private generateUiTransformation;
+    private applyStructuredFilters;
+    private resolveNumericPredicateValue;
+    private extractNumericValueFromContent;
+    private matchesNumericPredicate;
+    private normalizeComparableField;
+    private fieldSimilarityScore;
+    private fieldTokens;
+    private toFiniteNumber;
+    retrieve(query: string, options: {
+        namespace?: string;
+        topK?: number;
+        filter?: Record<string, unknown>;
+    }): Promise<RetrievalResult>;
+    /** Rewrite the user query for better retrieval performance. */
+    private rewriteQuery;
+    /** Generate 3-5 short, relevant questions based on the vector database content. */
+    getSuggestions(query: string, namespace?: string): Promise<string[]>;
+}
+
+/**
+ * Public SDK facade matching the prompt-level Retrivora API.
+ *
+ * It keeps provider details behind configuration and delegates execution to the
+ * existing Pipeline implementation.
+ */
+declare class Retrivora {
+    private readonly pipeline;
+    readonly config: RagConfig;
+    constructor(config?: UniversalRagConfig);
+    initialize(): Promise<void>;
+    ingest(documents: IngestDocument[], namespace?: string): Promise<Array<{
+        docId: string | number;
+        chunksIngested: number;
+    }>>;
+    ask(question: string, history?: ChatMessage[], namespace?: string): Promise<ChatResponse>;
+    askStream(question: string, history?: ChatMessage[], namespace?: string): AsyncIterable<string | ChatResponse>;
+    getPipeline(): Pipeline;
+}
+
+/**
+ * Named SDK exceptions make failures machine-readable for host applications.
+ */
+type RetrivoraErrorCode = 'PROVIDER_NOT_FOUND' | 'EMBEDDING_FAILED' | 'RETRIEVAL_FAILED' | 'RATE_LIMITED' | 'CONFIGURATION_ERROR' | 'AUTHENTICATION_ERROR';
+declare class RetrivoraError extends Error {
+    readonly code: RetrivoraErrorCode;
+    readonly details?: unknown;
+    constructor(message: string, code: RetrivoraErrorCode, details?: unknown);
+}
+declare class ProviderNotFoundException extends RetrivoraError {
+    constructor(providerType: string, provider: string, details?: unknown);
+}
+declare class EmbeddingFailedException extends RetrivoraError {
+    constructor(message?: string, details?: unknown);
+}
+declare class RetrievalException extends RetrivoraError {
+    constructor(message?: string, details?: unknown);
+}
+declare class RateLimitException extends RetrivoraError {
+    constructor(message?: string, details?: unknown);
+}
+declare class ConfigurationException extends RetrivoraError {
+    constructor(message: string, details?: unknown);
+}
+declare class AuthenticationException extends RetrivoraError {
+    constructor(message?: string, details?: unknown);
+}
+/**
+ * Wraps any unknown error into an appropriate RetrivoraError subclass.
+ */
+declare function wrapError(err: unknown, defaultCode: RetrivoraErrorCode, defaultMessage?: string): RetrivoraError;
+
+export { AuthenticationException as A, type Chunk as C, DocumentChunker as D, EmbeddingFailedException as E, ProviderNotFoundException as P, RateLimitException as R, type ChunkOptions as a, ConfigurationException as b, RetrievalException as c, Retrivora as d, RetrivoraError as e, type RetrivoraErrorCode as f, Pipeline as g, wrapError as w };

package/dist/{index-B70ZLkfG.d.mts → index-Bu7T6xgr.d.ts}

@@ -1,4 +1,4 @@
-import { k as RagConfig, I as ILLMProvider, C as ChatMessage, d as ChatResponse, g as IngestDocument } from './ILLMProvider-Bw2A28nU.mjs';
+import { k as RagConfig, I as ILLMProvider, C as ChatMessage, d as ChatResponse, g as IngestDocument } from './ILLMProvider-Bhk6zJOK.js';
 import { NextRequest, NextResponse } from 'next/server';
 
 interface ValidationError {
@@ -110,7 +110,7 @@ declare class VectorPlugin {
     /**
      * Run a streaming chat query.
      */
-    chatStream(message: string, history?: ChatMessage[], namespace?: string): AsyncGenerator<string | ChatResponse, void, any>;
+    chatStream(message: string, history?: ChatMessage[], namespace?: string): AsyncGenerator<string | ChatResponse, void, unknown>;
     /**
      * Ingest documents into the vector database.
      */
@@ -224,5 +224,22 @@ declare function createSuggestionsHandler(configOrPlugin?: Partial<RagConfig> |
 }> | NextResponse<{
     suggestions: string[];
 }>>;
+/**
+ * createRagHandler — factory that returns GET and POST handlers for a catch-all route
+ * (e.g. `src/app/api/retrivora/[[...retrivora]]/route.ts`).
+ */
+declare function createRagHandler(configOrPlugin?: Partial<RagConfig> | VectorPlugin): {
+    GET: (req: NextRequest, context: any) => Promise<NextResponse<{
+        timestamp: string;
+        vectorDb: HealthCheckResult;
+        llm: HealthCheckResult;
+        embedding?: HealthCheckResult;
+        allHealthy: boolean;
+        status: string;
+    }> | NextResponse<{
+        error: string;
+    }>>;
+    POST: (req: NextRequest, context: any) => Promise<Response>;
+};
 
-export { ConfigValidator as C, type HealthCheckResult as H, type IProviderValidator as I, type ValidationError as V, type IProviderHealthChecker as a, VectorPlugin as b, createChatHandler as c, createHealthHandler as d, createIngestHandler as e, createStreamHandler as f, createUploadHandler as g, sseFrame as h, sseMetaFrame as i, sseTextFrame as j, createSuggestionsHandler as k, sseObservabilityFrame as l, sseUIFrame as m, sseErrorFrame as s };
+export { ConfigValidator as C, type HealthCheckResult as H, type IProviderValidator as I, type ValidationError as V, type IProviderHealthChecker as a, VectorPlugin as b, createChatHandler as c, createHealthHandler as d, createIngestHandler as e, createRagHandler as f, createStreamHandler as g, createUploadHandler as h, sseFrame as i, sseMetaFrame as j, sseTextFrame as k, createSuggestionsHandler as l, sseObservabilityFrame as m, sseUIFrame as n, sseErrorFrame as s };

package/dist/{index-DVu-mkAM.d.ts → index-C3SVtPYg.d.mts}

@@ -1,4 +1,4 @@
-import { k as RagConfig, I as ILLMProvider, C as ChatMessage, d as ChatResponse, g as IngestDocument } from './ILLMProvider-Bw2A28nU.js';
+import { k as RagConfig, I as ILLMProvider, C as ChatMessage, d as ChatResponse, g as IngestDocument } from './ILLMProvider-Bhk6zJOK.mjs';
 import { NextRequest, NextResponse } from 'next/server';
 
 interface ValidationError {
@@ -110,7 +110,7 @@ declare class VectorPlugin {
     /**
      * Run a streaming chat query.
      */
-    chatStream(message: string, history?: ChatMessage[], namespace?: string): AsyncGenerator<string | ChatResponse, void, any>;
+    chatStream(message: string, history?: ChatMessage[], namespace?: string): AsyncGenerator<string | ChatResponse, void, unknown>;
     /**
      * Ingest documents into the vector database.
      */
@@ -224,5 +224,22 @@ declare function createSuggestionsHandler(configOrPlugin?: Partial<RagConfig> |
 }> | NextResponse<{
     suggestions: string[];
 }>>;
+/**
+ * createRagHandler — factory that returns GET and POST handlers for a catch-all route
+ * (e.g. `src/app/api/retrivora/[[...retrivora]]/route.ts`).
+ */
+declare function createRagHandler(configOrPlugin?: Partial<RagConfig> | VectorPlugin): {
+    GET: (req: NextRequest, context: any) => Promise<NextResponse<{
+        timestamp: string;
+        vectorDb: HealthCheckResult;
+        llm: HealthCheckResult;
+        embedding?: HealthCheckResult;
+        allHealthy: boolean;
+        status: string;
+    }> | NextResponse<{
+        error: string;
+    }>>;
+    POST: (req: NextRequest, context: any) => Promise<Response>;
+};
 
-export { ConfigValidator as C, type HealthCheckResult as H, type IProviderValidator as I, type ValidationError as V, type IProviderHealthChecker as a, VectorPlugin as b, createChatHandler as c, createHealthHandler as d, createIngestHandler as e, createStreamHandler as f, createUploadHandler as g, sseFrame as h, sseMetaFrame as i, sseTextFrame as j, createSuggestionsHandler as k, sseObservabilityFrame as l, sseUIFrame as m, sseErrorFrame as s };
+export { ConfigValidator as C, type HealthCheckResult as H, type IProviderValidator as I, type ValidationError as V, type IProviderHealthChecker as a, VectorPlugin as b, createChatHandler as c, createHealthHandler as d, createIngestHandler as e, createRagHandler as f, createStreamHandler as g, createUploadHandler as h, sseFrame as i, sseMetaFrame as j, sseTextFrame as k, createSuggestionsHandler as l, sseObservabilityFrame as m, sseUIFrame as n, sseErrorFrame as s };