@retrivora-ai/rag-engine 0.4.4 → 1.0.0

package/dist/server.d.ts

@@ -1,96 +1,11 @@
-import { c as RagConfig, C as ChatResponse, I as IngestDocument, e as VectorDBConfig, d as UpsertDocument, V as VectorMatch, G as GraphDBConfig, g as GraphNode, h as Edge, i as GraphSearchResult, L as LLMConfig, E as EmbeddingConfig, f as VectorDBProvider, b as LLMProvider, a as EmbeddingProvider } from './RagConfig-BgRDL9Vy.js';
-export { R as RAGConfig, U as UIConfig } from './RagConfig-BgRDL9Vy.js';
-import { C as ChatMessage, I as ILLMProvider, a as ChatOptions, E as EmbedOptions } from './DocumentChunker-3yElxTO3.js';
-export { b as Chunk, c as ChunkOptions, D as DocumentChunker } from './DocumentChunker-3yElxTO3.js';
-import { H as HealthCheckResult } from './index-DowY4_K0.js';
-export { P as ProviderHealthCheck, c as createChatHandler, a as createHealthHandler, b as createIngestHandler, d as createUploadHandler } from './index-DowY4_K0.js';
+import { e as VectorDBConfig, L as LLMConfig, E as EmbeddingConfig, c as RagConfig, C as ChatResponse, I as IngestDocument, g as RetrievalResult, d as UpsertDocument, V as VectorMatch, G as GraphDBConfig, h as GraphNode, i as Edge, j as GraphSearchResult, f as VectorDBProvider, b as LLMProvider, a as EmbeddingProvider } from './RagConfig-DRJO4hGU.js';
+export { R as RAGConfig, U as UIConfig } from './RagConfig-DRJO4hGU.js';
+import { C as ChatMessage, I as ILLMProvider, a as ChatOptions, E as EmbedOptions } from './DocumentChunker-C-sCZPhi.js';
+export { b as Chunk, c as ChunkOptions, D as DocumentChunker } from './DocumentChunker-C-sCZPhi.js';
+import { H as HealthCheckResult, I as IProviderValidator, a as IProviderHealthChecker } from './index-CrGMwXfO.js';
+export { C as ConfigValidator, V as ValidationError, c as createChatHandler, b as createHealthHandler, d as createIngestHandler, e as createUploadHandler } from './index-CrGMwXfO.js';
 import 'next/server';
 
-/**
- * ConfigValidator.ts — Comprehensive configuration validation.
- *
- * Validates RagConfig against provider requirements and best practices.
- * Returns detailed errors for misconfiguration.
- *
- * Key invariant: option keys validated here MUST match the keys each
- * Provider constructor reads. See each provider's constructor for the
- * canonical option names.
- */
-
-interface ValidationError {
-    field: string;
-    message: string;
-    suggestion?: string;
-    severity: 'error' | 'warning';
-}
-declare class ConfigValidator {
-    /**
-     * Validates the entire RagConfig object.
-     * Returns an array of validation errors. Empty array = valid config.
-     */
-    static validate(config: RagConfig): ValidationError[];
-    private static validateVectorDbConfig;
-    /**
-     * Pinecone — only needs apiKey (environment was removed in SDK v7+).
-     * Options key: { apiKey: string }
-     */
-    private static validatePineconeConfig;
-    /**
-     * PostgreSQL / pgvector — needs a connection string.
-     * Options key: { connectionString: string }
-     */
-    private static validatePostgresConfig;
-    /**
-     * MongoDB — needs uri, database, and collection.
-     * Options keys: { uri: string, database: string, collection: string }
-     */
-    private static validateMongoDBConfig;
-    /**
-     * Milvus — accepts baseUrl OR uri (preferred) OR host+port.
-     * MilvusProvider reads opts.baseUrl ?? opts.uri.
-     * Options keys: { baseUrl?: string, uri?: string, host?: string, port?: number }
-     */
-    private static validateMilvusConfig;
-    /**
-     * Qdrant — needs baseUrl (or url alias).
-     * Options keys: { baseUrl: string, apiKey?: string }
-     */
-    private static validateQdrantConfig;
-    /**
-     * ChromaDB — accepts baseUrl OR host.
-     * ChromaDBProvider reads opts.baseUrl.
-     * Options keys: { baseUrl?: string, host?: string, port?: number }
-     */
-    private static validateChromaDBConfig;
-    /**
-     * Redis — accepts baseUrl OR url OR host+port.
-     * RedisProvider reads opts.baseUrl.
-     * Options keys: { baseUrl?: string, url?: string, host?: string, port?: number, apiKey?: string }
-     */
-    private static validateRedisConfig;
-    /**
-     * Weaviate — accepts baseUrl OR url.
-     * WeaviateProvider reads opts.baseUrl.
-     * Options keys: { baseUrl?: string, url?: string, apiKey?: string }
-     */
-    private static validateWeaviateConfig;
-    /**
-     * Universal REST / custom REST adapter.
-     * Options key: { baseUrl: string }
-     */
-    private static validateRestConfig;
-    private static validateLLMConfig;
-    private static validateEmbeddingConfig;
-    private static validateUIConfig;
-    private static validateRAGConfig;
-    private static isValidCSSColor;
-    /**
-     * Throws if there are error-level validation issues.
-     * Logs warnings to console.
-     */
-    static validateAndThrow(config: RagConfig): void;
-}
-
 /**
  * BatchProcessor.ts — Handles batch operations with retry logic.
  *
@@ -157,6 +72,31 @@ declare class BatchProcessor {
     static processConcurrent<T, R>(items: T[], processor: (item: T) => Promise<R>, concurrency?: number, options?: BatchOptions): Promise<BatchResult<R>>;
 }
 
+/**
+ * ProviderHealthCheck.ts — Pre-flight validation for vector DB and LLM providers.
+ * Performs connectivity tests, credential validation, and capability checks.
+ */
+declare class ProviderHealthCheck {
+    /**
+     * Validates vector database configuration before initialization.
+     */
+    static checkVectorProvider(config: VectorDBConfig): Promise<HealthCheckResult>;
+    private static fallbackVectorHealthCheck;
+    /**
+     * Validates LLM provider configuration.
+     */
+    static checkLLMProvider(config: LLMConfig): Promise<HealthCheckResult>;
+    /**
+     * Runs comprehensive health checks on all configured providers in parallel.
+     */
+    static checkAll(vectorDbConfig: VectorDBConfig, llmConfig: LLMConfig, embeddingConfig?: EmbeddingConfig): Promise<{
+        vectorDb: HealthCheckResult;
+        llm: HealthCheckResult;
+        embedding?: HealthCheckResult;
+        allHealthy: boolean;
+    }>;
+}
+
 /**
  * VectorPlugin — main orchestrator class.
  * This is the primary interface for host applications.
@@ -232,13 +172,17 @@ declare class VectorPlugin {
  * - Multi-tenancy support via namespacing
  */
 declare class Pipeline {
+    private config;
     private vectorDB;
     private graphDB?;
     private llmProvider;
     private embeddingProvider;
     private chunker;
+    private llamaIngestor?;
     private entityExtractor?;
-    private config;
+    private reranker;
+    private agent?;
+    private embeddingCache;
     private initialised;
     constructor(config: RagConfig);
     initialize(): Promise<void>;
@@ -250,7 +194,36 @@ declare class Pipeline {
         docId: string | number;
         chunksIngested: number;
     }>>;
+    /**
+     * Step 1: Chunk the document content.
+     */
+    private prepareChunks;
+    /**
+     * Step 2: Generate embeddings for chunks with retry logic.
+     */
+    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 at the end.
+     */
+    askStream(question: string, history?: ChatMessage[], namespace?: string): AsyncIterable<string | ChatResponse>;
+    /**
+     * Universal retrieval method combining all enabled providers.
+     */
+    retrieve(query: string, options: {
+        namespace?: string;
+        topK?: number;
+        filter?: Record<string, unknown>;
+    }): Promise<RetrievalResult>;
     /**
      * Rewrite the user query for better retrieval performance.
      */
@@ -313,6 +286,14 @@ declare abstract class BaseVectorProvider {
      * Gracefully close the connection.
      */
     abstract disconnect(): Promise<void>;
+    /**
+     * Returns a validator for this provider's configuration.
+     */
+    static getValidator?(): IProviderValidator;
+    /**
+     * Returns a health checker for this provider.
+     */
+    static getHealthChecker?(): IProviderHealthChecker;
     /**
      * Remove internal keys (starting with __) and queryText from a filter object
      * before passing it to an external provider that might not support them.
@@ -354,31 +335,25 @@ declare abstract class BaseGraphProvider {
 
 /**
  * ProviderRegistry — dynamic provider loader for Vector DBs and LLMs.
- *
- * Supports:
- * - Built-in providers loaded on-demand via dynamic imports (tree-shaking friendly)
- * - Custom provider registration via registerVectorProvider()
  */
+type VectorProviderClass = {
+    new (config: VectorDBConfig): BaseVectorProvider;
+    getValidator?: () => IProviderValidator;
+    getHealthChecker?: () => IProviderHealthChecker;
+};
 declare class ProviderRegistry {
     private static vectorProviders;
     private static graphProviders;
-    static registerVectorProvider(name: string, providerClass: new (config: VectorDBConfig) => BaseVectorProvider): void;
-    /**
-     * Register a custom graph provider class by name.
-     */
-    static registerGraphProvider(name: string, providerClass: new (config: GraphDBConfig) => BaseGraphProvider): void;
-    /**
-     * Creates a vector database provider based on the configuration.
-     * Built-in providers are dynamically imported to avoid bundling all SDKs.
-     */
+    private static vectorValidators;
+    private static vectorHealthCheckers;
+    private static llmValidators;
+    private static llmHealthCheckers;
+    static registerVectorProvider(name: string, providerClass: VectorProviderClass): void;
+    static getVectorValidator(provider: string): Promise<IProviderValidator | null>;
+    static getVectorHealthChecker(provider: string): Promise<IProviderHealthChecker | null>;
+    private static loadVectorProviderClass;
     static createVectorProvider(config: VectorDBConfig): Promise<BaseVectorProvider>;
-    /**
-     * Creates a graph database provider based on the configuration.
-     */
     static createGraphProvider(config: GraphDBConfig): Promise<BaseGraphProvider>;
-    /**
-     * Creates an LLM provider based on the configuration.
-     */
     static createLLMProvider(llmConfig: LLMConfig, embeddingConfig?: EmbeddingConfig): ILLMProvider;
 }
 
@@ -698,16 +673,13 @@ declare class DocumentParser {
 
 /**
  * PineconeProvider — Pinecone vector database implementation.
- *
- * Compatible with @pinecone-database/pinecone v7.x SDK.
- *
- * Required options: { apiKey: string }
- * The `environment` option is no longer needed (removed in SDK v5+).
  */
 declare class PineconeProvider extends BaseVectorProvider {
     private client;
     private readonly apiKey;
     constructor(config: VectorDBConfig);
+    static getValidator(): IProviderValidator;
+    static getHealthChecker(): IProviderHealthChecker;
     initialize(): Promise<void>;
     private index;
     upsert(doc: UpsertDocument, namespace?: string): Promise<void>;
@@ -728,6 +700,8 @@ declare class PostgreSQLProvider extends BaseVectorProvider {
     private readonly connectionString;
     private readonly tableName;
     constructor(config: VectorDBConfig);
+    static getValidator(): IProviderValidator;
+    static getHealthChecker(): IProviderHealthChecker;
     initialize(): Promise<void>;
     upsert(doc: UpsertDocument, namespace?: string): Promise<void>;
     batchUpsert(docs: UpsertDocument[], namespace?: string): Promise<void>;
@@ -786,16 +760,14 @@ declare class MongoDBProvider extends BaseVectorProvider {
     private contentKey;
     private metadataKey;
     constructor(config: VectorDBConfig);
+    static getValidator(): IProviderValidator;
+    static getHealthChecker(): IProviderHealthChecker;
     initialize(): Promise<void>;
     upsert(doc: UpsertDocument, namespace?: string): Promise<void>;
     batchUpsert(docs: UpsertDocument[], namespace?: string): Promise<void>;
     query(vector: number[], topK: number, namespace?: string, filter?: Record<string, unknown>): Promise<VectorMatch[]>;
     delete(id: string | number, namespace?: string): Promise<void>;
     deleteNamespace(namespace: string): Promise<void>;
-    /**
-     * Sanitise and flatten filter for MongoDB.
-     * Strips internal engine fields and keywords.
-     */
     protected sanitizeFilter(filter?: Record<string, unknown>): Record<string, unknown>;
     ping(): Promise<boolean>;
     disconnect(): Promise<void>;
@@ -960,33 +932,20 @@ declare class UniversalVectorProvider extends BaseVectorProvider {
 
 /**
  * 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.
  */
-
 declare class LLMFactory {
     static create(llmConfig: LLMConfig, embeddingConfig?: EmbeddingConfig): ILLMProvider;
+    static getValidator(provider: LLMProvider): IProviderValidator | null;
+    static getHealthChecker(provider: LLMProvider): IProviderHealthChecker | null;
+    private static getProviderClass;
     /**
      * Creates a dedicated embedding-only provider.
-     * Useful when the LLM provider (e.g. Anthropic) doesn't support embeddings.
      */
     static createEmbeddingProvider(embeddingConfig: EmbeddingConfig): ILLMProvider;
 }
 
 /**
  * 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"
  */
 
 declare class OpenAIProvider implements ILLMProvider {
@@ -994,6 +953,8 @@ declare class OpenAIProvider implements ILLMProvider {
     private readonly llmConfig;
     private readonly embeddingConfig?;
     constructor(llmConfig: LLMConfig, embeddingConfig?: EmbeddingConfig);
+    static getValidator(): IProviderValidator;
+    static getHealthChecker(): IProviderHealthChecker;
     chat(messages: ChatMessage[], context: string, options?: ChatOptions): Promise<string>;
     embed(text: string, options?: EmbedOptions): Promise<number[]>;
     batchEmbed(texts: string[], options?: EmbedOptions): Promise<number[][]>;
@@ -1002,14 +963,6 @@ declare class OpenAIProvider implements ILLMProvider {
 
 /**
  * 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"
  */
 
 declare class AnthropicProvider implements ILLMProvider {
@@ -1017,12 +970,9 @@ declare class AnthropicProvider implements ILLMProvider {
     private readonly llmConfig;
     private readonly embeddingConfig?;
     constructor(llmConfig: LLMConfig, embeddingConfig?: EmbeddingConfig);
+    static getValidator(): IProviderValidator;
+    static getHealthChecker(): IProviderHealthChecker;
     chat(messages: ChatMessage[], context: string, options?: ChatOptions): Promise<string>;
-    /**
-     * 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).
-     */
     embed(text: string, options?: EmbedOptions): Promise<number[]>;
     batchEmbed(texts: string[], options?: EmbedOptions): Promise<number[][]>;
     ping(): Promise<boolean>;
@@ -1030,14 +980,6 @@ declare class AnthropicProvider implements ILLMProvider {
 
 /**
  * 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")
  */
 
 declare class OllamaProvider implements ILLMProvider {
@@ -1045,7 +987,11 @@ declare class OllamaProvider implements ILLMProvider {
     private readonly llmConfig;
     private readonly embeddingConfig?;
     constructor(llmConfig: LLMConfig, embeddingConfig?: EmbeddingConfig);
+    static getValidator(): IProviderValidator;
+    static getHealthChecker(): IProviderHealthChecker;
     chat(messages: ChatMessage[], context: string, options?: ChatOptions): Promise<string>;
+    chatStream(messages: ChatMessage[], context: string, options?: ChatOptions): AsyncIterable<string>;
+    private buildSystemPrompt;
     embed(text: string, options?: EmbedOptions): Promise<number[]>;
     batchEmbed(texts: string[], options?: EmbedOptions): Promise<number[][]>;
     ping(): Promise<boolean>;
@@ -1065,4 +1011,4 @@ declare class UniversalLLMAdapter implements ILLMProvider {
     ping(): Promise<boolean>;
 }
 
-export { AnthropicProvider, BaseVectorProvider, type BatchOptions, BatchProcessor, type BatchResult, ChatMessage, ChatOptions, ChatResponse, ChromaDBProvider, ConfigBuilder, ConfigResolver, ConfigValidator, DocumentParser, EmbedOptions, EmbeddingConfig, EmbeddingProvider, EmbeddingStrategy, EmbeddingStrategyResolver, HealthCheckResult, ILLMProvider, IngestDocument, LLMConfig, LLMFactory, LLMProvider, LLM_PROFILES, MilvusProvider, MongoDBProvider, MultiTablePostgresProvider, OllamaProvider, OpenAIProvider, PRESETS, PineconeProvider, Pipeline, PostgreSQLProvider, ProviderRegistry, QdrantProvider, RagConfig, RedisProvider, UniversalLLMAdapter, UniversalVectorProvider, UpsertDocument, VECTOR_PROFILES, type ValidationError, VectorDBConfig, VectorDBProvider, VectorMatch, VectorPlugin, WeaviateProvider, createFromPreset, getRagConfig };
+export { AnthropicProvider, BaseVectorProvider, type BatchOptions, BatchProcessor, type BatchResult, ChatMessage, ChatOptions, ChatResponse, ChromaDBProvider, ConfigBuilder, ConfigResolver, DocumentParser, EmbedOptions, EmbeddingConfig, EmbeddingProvider, EmbeddingStrategy, EmbeddingStrategyResolver, HealthCheckResult, ILLMProvider, IProviderHealthChecker, IProviderValidator, IngestDocument, LLMConfig, LLMFactory, LLMProvider, LLM_PROFILES, MilvusProvider, MongoDBProvider, MultiTablePostgresProvider, OllamaProvider, OpenAIProvider, PRESETS, PineconeProvider, Pipeline, PostgreSQLProvider, ProviderHealthCheck, ProviderRegistry, QdrantProvider, RagConfig, RedisProvider, UniversalLLMAdapter, UniversalVectorProvider, UpsertDocument, VECTOR_PROFILES, VectorDBConfig, VectorDBProvider, VectorMatch, VectorPlugin, WeaviateProvider, createFromPreset, getRagConfig };