@retrivora-ai/rag-engine 0.1.7 → 0.1.9

package/dist/server.d.mts

@@ -1,11 +1,162 @@
-import { a as RagConfig, C as ChatResponse, I as IngestDocument, c as VectorDBConfig, b as UpsertDocument, V as VectorMatch, L as LLMConfig, E as EmbeddingConfig } from './RagConfig-hBGXJmSx.mjs';
-export { R as RAGConfig, U as UIConfig } from './RagConfig-hBGXJmSx.mjs';
+import { a as RagConfig, C as ChatResponse, I as IngestDocument, c as VectorDBConfig, b as UpsertDocument, V as VectorMatch, L as LLMConfig, E as EmbeddingConfig, d as VectorDBProvider, e as LLMProvider, f as EmbeddingProvider } from './RagConfig-D_rSf8ep.mjs';
+export { R as RAGConfig, U as UIConfig } from './RagConfig-D_rSf8ep.mjs';
 import { C as ChatMessage, I as ILLMProvider, a as ChatOptions, E as EmbedOptions } from './DocumentChunker-BEyzadsv.mjs';
 export { b as Chunk, c as ChunkOptions, D as DocumentChunker } from './DocumentChunker-BEyzadsv.mjs';
-import { H as HealthCheckResult } from './index-Ck2pt7-8.mjs';
-export { c as createChatHandler, a as createHealthHandler, b as createIngestHandler, d as createUploadHandler } from './index-Ck2pt7-8.mjs';
+import { H as HealthCheckResult } from './index-BJ8CUArE.mjs';
+export { P as ProviderHealthCheck, c as createChatHandler, a as createHealthHandler, b as createIngestHandler, d as createUploadHandler } from './index-BJ8CUArE.mjs';
 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.
+ *
+ * Provides exponential backoff, partial failure tracking, and
+ * configurable batch sizing for efficient bulk operations.
+ */
+interface BatchOptions {
+    /** Maximum number of items per batch */
+    batchSize?: number;
+    /** Maximum number of retries for transient failures */
+    maxRetries?: number;
+    /** Initial delay before retry in milliseconds */
+    initialDelayMs?: number;
+    /** Maximum delay between retries in milliseconds */
+    maxDelayMs?: number;
+    /** Multiplier for exponential backoff */
+    backoffMultiplier?: number;
+    /** Whether to throw on any partial failure */
+    throwOnPartialFailure?: boolean;
+}
+interface BatchResult<T> {
+    results: T[];
+    errors: Array<{
+        index: number;
+        error: Error;
+        itemCount?: number;
+    }>;
+    totalProcessed: number;
+    totalFailed: number;
+}
+declare class BatchProcessor {
+    /**
+     * Processes an array of items in configurable batches with retry logic.
+     *
+     * @param items - Items to process
+     * @param processor - Async function that processes a batch of items
+     * @param options - Configuration for batch size, retries, etc.
+     * @returns Object with results, errors, and statistics
+     *
+     * @example
+     * const docs = [...];
+     * const result = await BatchProcessor.processBatch(
+     *   docs,
+     *   (batch) => vectorDB.batchUpsert(batch),
+     *   { batchSize: 100, maxRetries: 3 }
+     * );
+     */
+    static processBatch<T, R>(items: T[], processor: (batch: T[]) => Promise<R>, options?: BatchOptions): Promise<BatchResult<R>>;
+    /**
+     * Processes items sequentially (one at a time) with retry logic.
+     * Useful for operations that don't support batching or when granular
+     * error tracking is needed.
+     */
+    static processSequential<T, R>(items: T[], processor: (item: T) => Promise<R>, options?: BatchOptions): Promise<BatchResult<R>>;
+    /**
+     * Maps over items with retry logic, returning results in order.
+     * Like Array.map() but with async processing and automatic retries.
+     */
+    static mapWithRetry<T, R>(items: T[], mapper: (item: T) => Promise<R>, options?: BatchOptions): Promise<R[]>;
+    /**
+     * Parallel processor with concurrency limit.
+     * Processes up to `concurrency` items at the same time.
+     */
+    static processConcurrent<T, R>(items: T[], processor: (item: T) => Promise<R>, concurrency?: number, options?: BatchOptions): Promise<BatchResult<R>>;
+}
+
 /**
  * VectorPlugin — main orchestrator class.
  * This is the primary interface for host applications.
@@ -76,9 +227,9 @@ declare class VectorPlugin {
  * Features:
  * - Lazy initialization of providers
  * - Batch processing with retry logic
- * - Configurable embedding strategies
+ * - Smart embedding strategy (integrated / separate / external)
  * - Error recovery for transient failures
- * - Support for multi-tenancy via namespacing
+ * - Multi-tenancy support via namespacing
  */
 declare class Pipeline {
     private vectorDB;
@@ -90,7 +241,7 @@ declare class Pipeline {
     constructor(config: RagConfig);
     initialize(): Promise<void>;
     /**
-     * Ingest documents with automatic chunking, embedding, and batch processing.
+     * Ingest documents with automatic chunking, embedding, and batch upsert.
      * Handles retries for transient failures.
      */
     ingest(documents: IngestDocument[], namespace?: string): Promise<Array<{
@@ -160,15 +311,24 @@ declare abstract class BaseVectorProvider {
 
 /**
  * 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()
  */
 declare class ProviderRegistry {
     private static vectorProviders;
     /**
-     * Register a custom vector provider.
+     * Register a custom vector provider class by name.
+     * The name must match the provider value used in VectorDBConfig.provider.
+     *
+     * @example
+     * ProviderRegistry.registerVectorProvider('my-db', MyCustomProvider);
      */
     static registerVectorProvider(name: string, providerClass: new (config: VectorDBConfig) => BaseVectorProvider): void;
     /**
      * Creates a vector database provider based on the configuration.
+     * Built-in providers are dynamically imported to avoid bundling all SDKs.
      */
     static createVectorProvider(config: VectorDBConfig): Promise<BaseVectorProvider>;
     /**
@@ -182,10 +342,323 @@ declare class ProviderRegistry {
  *
  * This keeps secrets server-side and never exposes them to the browser.
  * Consumer projects set these env vars in their .env.local file.
+ *
+ * Supported VECTOR_DB_PROVIDER values and their required env vars:
+ *   pinecone      → PINECONE_API_KEY, PINECONE_INDEX
+ *   pgvector /
+ *   postgresql    → PGVECTOR_CONNECTION_STRING, VECTOR_DB_INDEX
+ *   mongodb       → MONGODB_URI, MONGODB_DB, MONGODB_COLLECTION
+ *   qdrant        → QDRANT_URL, QDRANT_API_KEY
+ *   milvus        → MILVUS_URL (e.g. http://localhost:19530)
+ *   chromadb      → CHROMADB_URL (e.g. http://localhost:8000)
+ *   weaviate      → WEAVIATE_URL, WEAVIATE_API_KEY
+ *   redis         → REDIS_URL, REDIS_API_KEY
+ *   rest /
+ *   universal_rest→ VECTOR_BASE_URL, VECTOR_DB_REST_API_KEY
  */
 
 declare function getRagConfig(env?: Record<string, string | undefined>): RagConfig;
 
+/**
+ * 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);
+ */
+
+declare class ConfigBuilder {
+    private config;
+    /**
+     * Set the project/application ID for namespacing
+     */
+    projectId(id: string): this;
+    /**
+     * Configure the vector database provider
+     */
+    vectorDb(provider: VectorDBProvider | 'universal-rest' | 'auto', options?: Record<string, unknown>): this;
+    /**
+     * Configure the LLM provider for chat
+     */
+    llm(provider: LLMProvider | 'auto', model?: string, apiKey?: string, options?: Record<string, unknown>): this;
+    /**
+     * Configure the embedding provider
+     */
+    embedding(provider: EmbeddingProvider | 'auto', model?: string, apiKey?: string, options?: Record<string, unknown>): this;
+    /**
+     * Set RAG-specific parameters
+     */
+    rag(options: {
+        chunkSize?: number;
+        chunkOverlap?: number;
+        topK?: number;
+    }): this;
+    /**
+     * Set UI/UX parameters
+     */
+    ui(options: {
+        branding?: string;
+        primaryColor?: string;
+        darkMode?: boolean;
+    }): this;
+    /**
+     * Build and return the configuration
+     */
+    build(): RagConfig;
+    /**
+     * Build and return as JSON for serialization
+     */
+    toJSON(): string;
+    private autoDetectVectorDb;
+    private autoDetectLLM;
+    private autoDetectEmbedding;
+}
+/**
+ * Preset configurations for common provider combinations
+ */
+declare const PRESETS: {
+    /**
+     * OpenAI + Pinecone: Production-ready cloud setup
+     */
+    readonly 'openai-pinecone': {
+        readonly vectorDb: "pinecone";
+        readonly llm: "openai";
+        readonly embedding: "openai";
+    };
+    /**
+     * Claude + Qdrant: Open-source vector DB + proprietary LLM
+     */
+    readonly 'claude-qdrant': {
+        readonly vectorDb: "qdrant";
+        readonly llm: "anthropic";
+        readonly embedding: "openai";
+    };
+    /**
+     * Local development: Ollama + local Qdrant
+     */
+    readonly 'local-dev': {
+        readonly vectorDb: "qdrant";
+        readonly llm: "ollama";
+        readonly embedding: "ollama";
+    };
+    /**
+     * Fully open-source: Ollama LLM + Qdrant vector DB + Ollama embeddings
+     */
+    readonly 'fully-open-source': {
+        readonly vectorDb: "qdrant";
+        readonly llm: "ollama";
+        readonly embedding: "ollama";
+    };
+    /**
+     * PostgreSQL stack: pgvector + OpenAI
+     */
+    readonly 'postgres-openai': {
+        readonly vectorDb: "postgresql";
+        readonly llm: "openai";
+        readonly embedding: "openai";
+    };
+    /**
+     * Enterprise MongoDB: MongoDB Atlas with OpenAI
+     */
+    readonly 'mongodb-openai': {
+        readonly vectorDb: "mongodb";
+        readonly llm: "openai";
+        readonly embedding: "openai";
+    };
+    /**
+     * Redis stack for caching + search
+     */
+    readonly 'redis-openai': {
+        readonly vectorDb: "redis";
+        readonly llm: "openai";
+        readonly embedding: "openai";
+    };
+};
+type PresetName = keyof typeof PRESETS;
+/**
+ * Helper to create config from preset
+ */
+declare function createFromPreset(presetName: PresetName): ConfigBuilder;
+
+/**
+ * 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.
+ */
+
+declare 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"
+}
+interface EmbeddingStrategyResult {
+    strategy: EmbeddingStrategy;
+    embeddingProvider: ILLMProvider;
+    llmProvider: ILLMProvider;
+}
+/**
+ * Determines the optimal embedding strategy and initializes providers
+ */
+declare class EmbeddingStrategyResolver {
+    /**
+     * Determine strategy based on LLM and embedding configs
+     */
+    static determineStrategy(llmConfig: LLMConfig, embeddingConfig?: EmbeddingConfig): EmbeddingStrategy;
+    /**
+     * Resolve and initialize providers according to the strategy
+     */
+    static resolve(llmConfig: LLMConfig, embeddingConfig?: EmbeddingConfig): Promise<EmbeddingStrategyResult>;
+    /**
+     * Check if an LLM provider natively supports embeddings
+     */
+    private static supportsEmbedding;
+    /**
+     * Get a human-readable description of the strategy
+     */
+    static getDescription(strategy: EmbeddingStrategy): string;
+}
+
+/**
+ * Pre-configured templates for popular AI and Vector services.
+ * Use these as defaults in the Universal Adapters.
+ */
+declare const LLM_PROFILES: {
+    'openai-compatible': {
+        chatPath: string;
+        embedPath: string;
+        responseExtractPath: string;
+        embedExtractPath: string;
+        chatPayloadTemplate: string;
+    };
+    litellm: {
+        chatPayloadTemplate: string;
+        chatPath: string;
+        embedPath: string;
+        responseExtractPath: string;
+        embedExtractPath: string;
+    };
+    'anthropic-claude': {
+        chatPath: string;
+        responseExtractPath: string;
+        headers: {
+            'anthropic-version': string;
+        };
+        chatPayloadTemplate: string;
+    };
+    'google-gemini': {
+        chatPath: string;
+        responseExtractPath: string;
+        chatPayloadTemplate: string;
+    };
+    'github-copilot': {
+        chatPayloadTemplate: string;
+        chatPath: string;
+        embedPath: string;
+        responseExtractPath: string;
+        embedExtractPath: string;
+    };
+    'ollama-standard': {
+        chatPath: string;
+        embedPath: string;
+        responseExtractPath: string;
+        embedExtractPath: string;
+        chatPayloadTemplate: string;
+        embedPayloadTemplate: string;
+    };
+};
+declare const VECTOR_PROFILES: {
+    'pinecone-rest': {
+        queryPath: string;
+        upsertPath: string;
+        responseExtractPath: string;
+        idPath: string;
+        scorePath: string;
+        contentPath: string;
+        metadataPath: string;
+        queryPayloadTemplate: string;
+    };
+    'mongodb-atlas': {
+        queryPath: string;
+        responseExtractPath: string;
+        idPath: string;
+        scorePath: string;
+        contentPath: string;
+        metadataPath: string;
+        queryPayloadTemplate: string;
+    };
+    chromadb: {
+        queryPath: string;
+        upsertPath: string;
+        responseExtractPath: string;
+        idPath: string;
+        scorePath: string;
+        contentPath: string;
+        metadataPath: string;
+    };
+    qdrant: {
+        queryPath: string;
+        upsertPath: string;
+        responseExtractPath: string;
+        idPath: string;
+        scorePath: string;
+        contentPath: string;
+        metadataPath: string;
+    };
+};
+
+/**
+ * DocumentParser — handles text extraction from various file formats.
+ * Supported: .txt, .md, .json, .csv, .pdf (requires pdf-parse), .docx (requires mammoth)
+ */
+declare class DocumentParser {
+    /**
+     * Extract text from a File or Buffer based on its type.
+     */
+    static parse(file: File | Buffer, fileName: string, mimeType: string): Promise<string>;
+    private static readAsText;
+}
+
+/**
+ * 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;
@@ -220,6 +693,41 @@ declare class PostgreSQLProvider extends BaseVectorProvider {
     disconnect(): Promise<void>;
 }
 
+/**
+ * MultiTablePostgresProvider — PostgreSQL implementation that searches across
+ * multiple existing tables with pre-existing embeddings.
+ *
+ * Extends BaseVectorProvider so it can be registered with ProviderRegistry.
+ * Upsert operations are not supported — data is assumed to be managed externally
+ * or via custom ingestion scripts that write directly to each table.
+ */
+declare class MultiTablePostgresProvider extends BaseVectorProvider {
+    private pool;
+    private readonly dimensions;
+    private readonly connectionString;
+    private readonly tables;
+    constructor(config: VectorDBConfig);
+    initialize(): Promise<void>;
+    /**
+     * Upsert is not supported for MultiTablePostgresProvider as it's designed for
+     * searching across pre-existing tables with varying schemas.
+     */
+    upsert(_doc: UpsertDocument, _namespace?: string): Promise<void>;
+    /**
+     * Batch upsert is not supported for MultiTablePostgresProvider.
+     */
+    batchUpsert(_docs: UpsertDocument[], _namespace?: string): Promise<void>;
+    /**
+     * Query all configured tables and merge results, sorted by cosine similarity score.
+     */
+    query(vector: number[], topK: number, _namespace?: string, // eslint-disable-line @typescript-eslint/no-unused-vars
+    _filter?: Record<string, unknown>): Promise<VectorMatch[]>;
+    delete(_id: string | number, _namespace?: string): Promise<void>;
+    deleteNamespace(_namespace: string): Promise<void>;
+    ping(): Promise<boolean>;
+    disconnect(): Promise<void>;
+}
+
 /**
  * MongoDBProvider — MongoDB Atlas Vector Search implementation.
  */
@@ -244,7 +752,14 @@ declare class MongoDBProvider extends BaseVectorProvider {
 }
 
 /**
- * MilvusProvider — implementation for Milvus using its REST API.
+ * MilvusProvider — Milvus implementation using its REST API v1.
+ *
+ * Required options:
+ *   { baseUrl: string } — e.g. "http://localhost:19530"
+ *   OR { uri: string }  — alias for baseUrl
+ *   OR { host: string, port: number } — auto-constructs baseUrl
+ *
+ * Optional: { apiKey?: string, headers?: Record<string, string> }
  */
 declare class MilvusProvider extends BaseVectorProvider {
     private http;
@@ -254,7 +769,7 @@ declare class MilvusProvider extends BaseVectorProvider {
     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>;
+    deleteNamespace(namespace: string): Promise<void>;
     ping(): Promise<boolean>;
     disconnect(): Promise<void>;
 }
@@ -290,24 +805,41 @@ declare class QdrantProvider extends BaseVectorProvider {
 }
 
 /**
- * ChromaDBProvider — implementation for ChromaDB using its REST API.
+ * ChromaDBProvider — ChromaDB implementation using its REST API.
+ *
+ * Required options: { baseUrl: string } — e.g. "http://localhost:8000"
+ * Optional: { host?: string, port?: number } — used to construct baseUrl when baseUrl not set
  */
 declare class ChromaDBProvider extends BaseVectorProvider {
     private http;
     private collectionId;
     constructor(config: VectorDBConfig);
+    /**
+     * Get or create the ChromaDB collection.
+     */
     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, _namespace?: string): Promise<void>;
-    deleteNamespace(_namespace: string): Promise<void>;
+    delete(id: string, namespace?: string): Promise<void>;
+    deleteNamespace(namespace: string): Promise<void>;
     ping(): Promise<boolean>;
     disconnect(): Promise<void>;
 }
 
 /**
- * RedisProvider — implementation for Redis (e.g. Upstash) using its REST API.
+ * RedisProvider — Redis Vector Search implementation using Upstash REST API.
+ *
+ * Required options:
+ *   { baseUrl: string } — Upstash REST endpoint
+ *   OR { url: string }  — alias for baseUrl
+ *   OR { host: string, port: number } — auto-constructs baseUrl
+ *
+ * Optional: { apiKey?: string } — bearer token (required for Upstash)
+ *
+ * Note: This provider targets the Upstash Vector REST API.
+ * For bare Redis with RediSearch, use a custom REST wrapper or the
+ * UniversalVectorProvider with custom templates.
  */
 declare class RedisProvider extends BaseVectorProvider {
     private http;
@@ -317,13 +849,23 @@ declare class RedisProvider extends BaseVectorProvider {
     batchUpsert(docs: UpsertDocument[], namespace?: string): Promise<void>;
     query(vector: number[], topK: number, namespace?: string, _filter?: Record<string, unknown>): Promise<VectorMatch[]>;
     delete(id: string, namespace?: string): Promise<void>;
-    deleteNamespace(_namespace: string): Promise<void>;
+    deleteNamespace(namespace: string): Promise<void>;
+    /**
+     * Redis is TCP-based and has no HTTP health endpoint.
+     * Returns true; actual connectivity is validated on the first operation.
+     */
     ping(): Promise<boolean>;
     disconnect(): Promise<void>;
 }
 
 /**
- * WeaviateProvider — implementation for Weaviate using its REST/GraphQL API.
+ * WeaviateProvider — Weaviate implementation using its REST/GraphQL API.
+ *
+ * Required options:
+ *   { baseUrl: string } — e.g. "http://localhost:8080"
+ *   OR { url: string }  — alias accepted for backwards compatibility
+ *
+ * Optional: { apiKey?: string }
  */
 declare class WeaviateProvider extends BaseVectorProvider {
     private http;
@@ -338,6 +880,34 @@ declare class WeaviateProvider extends BaseVectorProvider {
     disconnect(): Promise<void>;
 }
 
+/**
+ * UniversalVectorProvider — Template-based REST integration for any vector database
+ *
+ * Enables connecting to any REST-based vector database with minimal configuration
+ * through request/response mapping templates.
+ *
+ * Features:
+ * - Template-based request/response mapping
+ * - Automatic JSON path extraction
+ * - Retry logic with exponential backoff
+ * - Request batching
+ * - Custom header support
+ */
+
+declare class UniversalVectorProvider extends BaseVectorProvider {
+    private http;
+    private readonly opts;
+    constructor(config: VectorDBConfig);
+    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>;
+    ping(): Promise<boolean>;
+    disconnect(): Promise<void>;
+}
+
 /**
  * LLMFactory — instantiates the correct ILLMProvider based on llmConfig.provider.
  *
@@ -431,4 +1001,18 @@ declare class OllamaProvider implements ILLMProvider {
     ping(): Promise<boolean>;
 }
 
-export { AnthropicProvider, BaseVectorProvider, ChatMessage, ChatOptions, ChatResponse, ChromaDBProvider, ConfigResolver, EmbedOptions, EmbeddingConfig, ILLMProvider, IngestDocument, LLMConfig, LLMFactory, MilvusProvider, MongoDBProvider, OllamaProvider, OpenAIProvider, PineconeProvider, Pipeline, PostgreSQLProvider, ProviderRegistry, QdrantProvider, RagConfig, RedisProvider, UpsertDocument, VectorDBConfig, VectorMatch, VectorPlugin, WeaviateProvider, getRagConfig };
+declare class UniversalLLMAdapter implements ILLMProvider {
+    private readonly http;
+    private readonly model;
+    private readonly opts;
+    private readonly systemPrompt;
+    private readonly maxTokens;
+    private readonly temperature;
+    constructor(config: LLMConfig | EmbeddingConfig);
+    chat(messages: ChatMessage[], context?: string): Promise<string>;
+    embed(text: string): Promise<number[]>;
+    batchEmbed(texts: string[]): Promise<number[][]>;
+    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 };