declare const VECTOR_DB_PROVIDERS: readonly ["pinecone", "pgvector", "postgresql", "mongodb", "qdrant", "milvus", "chromadb", "redis", "weaviate", "rest", "universal_rest", "custom"]; declare const LLM_PROVIDERS: readonly ["openai", "anthropic", "ollama", "gemini", "groq", "qwen", "rest", "universal_rest", "custom"]; declare const EMBEDDING_PROVIDERS: readonly ["openai", "ollama", "gemini", "qwen", "rest", "universal_rest", "custom"]; declare const GRAPH_DB_PROVIDERS: readonly ["neo4j", "memgraph", "simple", "custom"]; type WidgetPosition = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'; type ThemeMode = 'light' | 'dark' | 'system'; type AuthMode = 'public' | 'anonymous' | 'jwt' | 'oauth' | 'okta' | 'auth0' | 'supabase' | 'firebase' | 'sso' | 'custom_token'; interface ProjectBrandingSettings { companyName: string; botName: string; welcomeMessage: string; primaryColor: string; secondaryColor: string; fontFamily: string; borderRadius: number; logoUrl: string; avatarUrl: string; customCss: string; } interface ProjectAiSettings { defaultModel: string; embeddingModel: string; systemPrompt: string; memoryEnabled: boolean; multiModelEnabled: boolean; citationsEnabled: boolean; fileUploadEnabled: boolean; } interface ProjectAuthSettings { mode: AuthMode; allowedOrigins: string[]; requireVerifiedEmail: boolean; sessionTtlMinutes: number; } interface ProjectWidgetSettings { position: WidgetPosition; theme: ThemeMode; lazyLoad: boolean; autoReconnect: boolean; persistConversations: boolean; showRetrivoraBranding: boolean; } interface ProjectTelemetrySettings { enabled: boolean; collectBrowser: boolean; collectCountry: boolean; redactPii: boolean; retentionDays: number; } interface ProjectChatSettings { projectId: string; branding: ProjectBrandingSettings; ai: ProjectAiSettings; auth: ProjectAuthSettings; widget: ProjectWidgetSettings; telemetry: ProjectTelemetrySettings; lifecycleHooks: string[]; conversationFeatures: string[]; updatedAt?: string; } declare function createDefaultProjectSettings(projectId: string): ProjectChatSettings; declare function normalizeProjectSettings(projectId: string, input: Partial | null | undefined): ProjectChatSettings; declare function projectSettingsToUiConfig(settings: ProjectChatSettings): Partial; /** * Master configuration interface for Retrivora AI. * Each consuming project provides one RagConfig object to drive * vector DB selection, LLM selection, embedding, and UI branding. */ type VectorDBProvider = typeof VECTOR_DB_PROVIDERS[number]; interface VectorDBConfig { /** Which vector database to use */ provider: VectorDBProvider; /** The index / table name to query */ indexName: string; /** Provider-specific options (API keys, connection strings, etc.) * * For 'universal_rest', the following options are supported: * - baseUrl: string * - headers?: Record * - queryPath?: string * - upsertPath?: string * - queryPayloadTemplate?: string (e.g. '{"vector": {{vector}}, "limit": {{topK}}}') * - upsertPayloadTemplate?: string (e.g. '{"id": "{{id}}", "vector": {{vector}}}') * - responseExtractPath?: string (e.g. 'data.results') * - idPath?: string (e.g. '_id') * - scorePath?: string (e.g. 'similarity') * - contentPath?: string (e.g. 'text') * * For 'mongodb', the following options are also supported: * - numCandidates?: number // controls search recall depth * * For multi-table PostgreSQL search, the following options are also supported: * - tables?: string[] | string * - searchFields?: string[] | string // optional override for which columns receive exact-match boosts */ options: Record; } type GraphDBProvider = typeof GRAPH_DB_PROVIDERS[number]; interface GraphDBConfig { /** Which graph database to use */ provider: GraphDBProvider; /** Provider-specific options (URI, credentials, etc.) */ options: Record; } type LLMProvider = typeof LLM_PROVIDERS[number]; interface LLMConfig { /** Which LLM provider to use */ provider: LLMProvider; /** Model name, e.g. "gpt-4o", "claude-3-opus-20240229", "llama3" */ model: string; /** API key for cloud providers */ apiKey?: string; /** Base URL — required for Ollama or self-hosted endpoints */ baseUrl?: string; /** Custom system prompt injected before every chat */ systemPrompt?: string; /** Max tokens in the LLM response */ maxTokens?: number; /** Sampling temperature (0–1) */ temperature?: number; /** Provider-specific options * * For 'universal_rest', the following options are supported: * - headers?: Record * - chatPath?: string * - chatPayloadTemplate?: string (e.g. '{"prompt": "{{prompt}}", "max_tokens": {{maxTokens}}}') * - responseExtractPath?: string (e.g. 'choices[0].text' or 'response') */ options?: Record; } type EmbeddingProvider = typeof EMBEDDING_PROVIDERS[number]; interface EmbeddingConfig { /** Which embedding provider to use */ provider: EmbeddingProvider; /** Model name, e.g. "text-embedding-ada-002", "nomic-embed-text" */ model: string; /** API key (if needed) */ apiKey?: string; /** Base URL for custom / Ollama embedding endpoints */ baseUrl?: string; /** Output vector dimension — must match the index dimension */ dimensions?: number; /** Optional prefix to prepend to queries (for models like nomic-embed-text) */ queryPrefix?: string; /** Optional prefix to prepend to documents during ingestion */ documentPrefix?: string; /** Provider-specific options for custom adapters */ options?: Record; } interface UIConfig { /** Title shown in the chat header */ title?: string; /** Subtitle / description below the title */ subtitle?: string; /** Primary brand colour (CSS colour string) */ primaryColor?: string; /** Accent colour for user message bubbles */ accentColor?: string; /** URL to a logo image */ logoUrl?: string; /** Input placeholder text */ placeholder?: string; /** Show source cards after each answer */ showSources?: boolean; /** Welcome message shown on first load */ welcomeMessage?: string; /** Whether to show the floating chat widget. Defaults to true. */ showWidget?: boolean; /** Custom 'Powered by' text shown in the header */ poweredBy?: string; /** Visual style: 'glass' (default) or 'solid' */ visualStyle?: 'glass' | 'solid'; /** Border radius: 'none', 'sm', 'md', 'lg', 'xl', 'full' */ borderRadius?: 'none' | 'sm' | 'md' | 'lg' | 'xl' | 'full'; /** Whether to allow file uploads directly from the UI */ allowUpload?: boolean; /** Whether to allow manual resizing of the chat window. Defaults to true. */ allowResize?: boolean; /** Whether to enable voice search input. Defaults to true. */ enableVoiceInput?: boolean; theme?: 'light' | 'dark' | 'system'; } interface CAGConfig { /** Enable Cold RAG (Cache Augmented Generation) */ enabled?: boolean; /** Namespace containing the cold data (e.g., static manuals/guides) */ coldNamespace?: string; /** Limit of cold documents to retrieve at initialization and keep in cache/context */ coldLimit?: number; /** Specific search query to retrieve the cold documents (e.g., "manual", "documentation") */ coldQuery?: string; /** Specific document IDs to load as cold context */ coldDocumentIds?: string[]; } interface RAGConfig { /** Number of top-K chunks retrieved per query */ topK?: number; /** Minimum similarity score to include a chunk (0–1) */ scoreThreshold?: number; /** Target chunk size in tokens */ chunkSize?: number; /** Overlap between adjacent chunks in tokens */ chunkOverlap?: number; /** Characters used to split text, in order of priority */ separators?: string[]; /** Overall RAG architecture pattern */ architecture?: 'simple' | 'graph' | 'hybrid' | 'agentic' | 'naive' | 'retrieve-and-rerank' | 'multimodal' | 'agentic-router' | 'multi-agent'; /** Chunking strategy to use during ingestion */ chunkingStrategy?: 'recursive' | 'markdown' | 'semantic' | 'llamaindex'; /** Whether to use query transformation (e.g. HyDE) */ useQueryTransformation?: boolean; /** Whether to use graph-based retrieval */ useGraphRetrieval?: boolean; /** Whether to perform reranking on retrieved results */ useReranking?: boolean; /** List of metadata fields that are valid for filtering. * 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; /** * Custom keywords that signal graph-based retrieval should be used. * Defaults to built-in list (relationship, connect, hierarchy, etc.). */ graphKeywords?: string[]; /** * Custom keywords that signal vector-based retrieval should be used. * Defaults to built-in list (find, search, tell me about, etc.). */ vectorKeywords?: string[]; /** * Maximum number of tool-call iterations allowed in a single agentic request. * Applies to MultiAgentCoordinator (architecture: 'multi-agent' / mcpServers present). * Defaults to 5. */ agentMaxIterations?: number; /** Cold RAG (Cache Augmented Generation) configuration */ cag?: CAGConfig; /** Chat history configuration */ history?: { enabled?: boolean; tableName?: string; }; /** User feedback configuration */ feedback?: { enabled?: boolean; tableName?: string; }; } interface RetrievalConfig { /** Retrieval strategy selected by the host app. */ strategy?: 'vector' | 'keyword' | 'hybrid' | 'multi-query' | 'self-query' | 'parent-document' | 'contextual-compression' | 'ensemble' | 'recursive' | 'agentic'; /** Number of documents/chunks retrieved per query. */ topK?: number; /** Minimum similarity score to include a retrieved chunk. */ scoreThreshold?: number; /** Whether to rerank retrieved chunks before generation. */ useReranking?: boolean; /** Provider-specific retrieval options for future strategies. */ options?: Record; } interface WorkflowConfig { /** High-level workflow selector from the SDK prompt. */ type?: 'simple-rag' | 'rag' | 'hybrid-rag' | 'graph-rag' | 'agentic-rag' | 'agentic' | 'naive-rag' | 'retrieve-and-rerank' | 'multimodal-rag' | 'agentic-router' | 'multi-agent-rag' | 'multi-agent'; /** Future workflow/provider-specific options. */ options?: Record; } interface MCPServerConfig { name: string; transport: 'stdio' | 'sse'; url?: string; command?: string; args?: string[]; env?: Record; } interface RagConfig { /** License key for commercial production validation */ licenseKey?: string; /** * Unique identifier for the consuming project. * Used as the vector DB namespace to achieve multi-tenancy. */ projectId: string; /** Vector database configuration */ vectorDb: VectorDBConfig; /** LLM configuration */ llm: LLMConfig; /** Embedding configuration */ embedding: EmbeddingConfig; /** Optional UI branding overrides */ ui?: UIConfig; /** Optional dashboard-managed project chat settings */ projectSettings?: ProjectChatSettings; /** Optional RAG pipeline tuning knobs */ rag?: RAGConfig; /** Optional Graph database configuration */ graphDb?: GraphDBConfig; /** Optional Telemetry configuration for observability logging */ telemetry?: { enabled?: boolean; url?: string; }; /** Optional Model Context Protocol (MCP) server configurations */ mcpServers?: MCPServerConfig[]; } /** * Friendly SDK configuration accepted by the top-level Retrivora facade. * It supports the prompt's `vectorDatabase`, `retrieval`, and `workflow` * naming while normalizing to the internal RagConfig shape. */ type UniversalRagConfig = Partial> & { vectorDb?: Partial; vectorDatabase?: Partial; llm?: Partial; embedding?: Partial; graphDb?: Partial; retrieval?: RetrievalConfig; rag?: RAGConfig; workflow?: WorkflowConfig; }; type MessageRole = 'user' | 'assistant' | 'system'; interface ChatMessage { role: MessageRole; content: string; } 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; /** * Chain-of-thought reasoning from the LLM. * Populated by native Anthropic extended thinking or simulated tag stripping. */ thinking?: string; /** Wall-clock ms the model spent in the thinking phase. */ thinkingMs?: number; } interface ChatOptions { /** Override max tokens for this specific call */ maxTokens?: number; /** Override temperature for this specific call */ 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) */ apiUrl?: string; /** * Base URL for the Retrivora SDK catch-all route used for history, feedback, * and sessions endpoints. Defaults to '/api/retrivora'. * e.g. if your catch-all is at /api/retrivora/[[...retrivora]], set this to '/api/retrivora'. */ retrivoraApiBase?: string; /** Override project namespace */ namespace?: string; /** Persist chat history to localStorage (default: true) */ persist?: boolean; /** Called after each successful assistant reply */ onReply?: (message: RagMessage) => void; /** Called on error */ onError?: (error: string) => void; /** Optional custom headers to send with the chat request */ headers?: Record; /** Optional Retrivora license key override */ licenseKey?: string; /** Session ID for history and feedback tracking (default: 'default') */ sessionId?: string; } interface UseRagChatReturn { /** All messages in the current conversation */ messages: RagMessage[]; /** Whether a response is in flight */ isLoading: boolean; /** Current error message, or null */ error: string | null; /** Send a user message */ send: (text: string) => Promise; /** Clear the conversation (and localStorage if persist=true) */ clear: () => void; /** Retry the last failed send */ retry: () => Promise; /** Programmatically set the conversation (e.g. to restore from a DB) */ setMessages: React.Dispatch>; /** Abort the current active stream request */ stop: () => void; /** Load message history from database storage */ loadHistory: (sessionId: string) => Promise; /** Clear conversation history from database and locally */ clearHistory: (sessionId: string) => Promise; /** Submit rating and optional comment for a specific assistant message */ submitFeedback: (messageId: string, rating: 'thumbs_up' | 'thumbs_down', comment?: string) => Promise; } /** 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; 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; model?: string; provider?: string; /** 0 = fully grounded, 1 = likely hallucinated. */ hallucinationScore?: number; hallucinationReason?: string; timestamp: string; } interface VectorMatch { id: string | number; score: number; content: string; metadata?: Record; } interface UpsertDocument { id: string | number; vector: number[]; content: string; metadata?: Record; } interface IngestDocument { docId: string | number; content: string; metadata?: Record; } interface ChatResponse { reply: string; sources: VectorMatch[]; graphData?: GraphSearchResult; ui_transformation?: unknown; /** Observability trace — populated by the instrumented Pipeline. */ trace?: ObservabilityTrace; } interface GraphNode { id: string; label: string; properties?: Record; } interface Edge { source: string; target: string; type: string; properties?: Record; } interface GraphSearchResult { nodes: GraphNode[]; edges: Edge[]; } interface RetrievalResult { sources: VectorMatch[]; graphData?: GraphSearchResult; } interface IRetriever { retrieve(query: string, options?: Record): Promise; } interface SuggestionsResponse { suggestions: string[]; } interface Product { id: string | number; name: string; brand?: string; price?: string | number; image?: string; link?: string; description?: string; } /** * Supported UI visualization types */ type VisualizationType = 'pie_chart' | 'bar_chart' | 'line_chart' | 'histogram' | 'horizontal_bar' | 'scatter_plot' | 'radar_chart' | 'metric_card' | 'geo_map' | 'table' | 'product_carousel' | 'carousel' | 'text'; /** * Base structure for all UI transformation responses */ interface UITransformationResponse { type: VisualizationType; title: string; description?: string; data: unknown; } /** * Pie chart data structure */ interface PieChartData { label: string; value: number; inStockCount?: number; outOfStockCount?: number; [key: string]: unknown; } /** * Bar chart data structure */ interface BarChartData { category: string; value: number; inStockCount?: number; outOfStockCount?: number; [key: string]: unknown; } /** * Line chart data point */ interface LineChartDataPoint { timestamp: string | number; value: number; label?: string; [key: string]: unknown; } /** * Scatter plot data point */ interface ScatterPlotDataPoint { x: number; y: number; label?: string; [key: string]: unknown; } /** * KPI / metric card representation */ interface MetricCardData { label: string; value: number; operation?: 'sum' | 'average' | 'count' | 'min' | 'max' | 'median'; unit?: string; details?: Record; } /** * Table representation */ interface TableData { columns: string[]; rows: (string | number | boolean)[][]; } /** * Product carousel item */ interface CarouselProduct { id: string | number; name: string; price?: number | string; image?: string; inStock?: boolean; brand?: string; description?: string; [key: string]: unknown; } /** * Standardized Retrivora Metadata Schema for document vectors and storage. * Guarantees uniform metadata structure across vector DB backends (Pinecone, MongoDB, etc.). */ interface RetrivoraChunkMetadata { /** Document unique identifier */ docId: string; /** Original file name (e.g. report.pdf, data.json, sheets.xlsx) */ fileName: string; /** File format type identifier */ fileType: 'txt' | 'json' | 'pdf' | 'excel' | 'word' | 'md' | 'csv' | string; /** MIME type string */ mimeType: string; /** 0-indexed position of chunk within the parent document */ chunkIndex: number; /** Total count of chunks in the document */ totalChunks: number; /** Extracted text content of the chunk */ content: string; /** Character length of the chunk content */ characterCount: number; /** Workspace or Project ID */ workspaceId: string; /** Isolated vector database namespace (e.g. Pinecone namespace) */ pineconeNamespace: string; /** Retrivora Tier level */ tier: 'free' | 'enterprise'; /** ISO 8601 timestamp when the document was processed */ ingestedAt: string; /** Additional custom metadata Key-Value pairs */ customMetadata?: Record; } interface RetrivoraIngestedDocument { docId: string; fileName: string; fileType: string; mimeType: string; fileSizeBytes?: number; totalChunks: number; workspaceId: string; pineconeNamespace: string; ingestedAt: string; chunks: RetrivoraChunkMetadata[]; } /** * 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; /** * Send a streaming chat completion request. * @returns – an async iterable of text chunks */ chatStream?(messages: ChatMessage[], context: string, options?: ChatOptions): AsyncIterable; /** * 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; /** * 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; /** * Check if the provider endpoint is reachable. */ ping(): Promise; } export { type RetrivoraChunkMetadata as $, type AuthMode as A, createDefaultProjectSettings as B, type ChatMessage as C, normalizeProjectSettings as D, type EmbedOptions as E, projectSettingsToUiConfig as F, type GraphDBConfig as G, type GraphNode as H, type ILLMProvider as I, type Edge as J, type GraphSearchResult as K, type LLMConfig as L, type BarChartData as M, type CarouselProduct as N, type ObservabilityTrace as O, type Product as P, type IRetriever as Q, type RAGConfig as R, type LineChartDataPoint as S, type ThemeMode as T, type UITransformationResponse as U, type VectorDBConfig as V, type WidgetPosition as W, type MessageRole as X, type MetricCardData as Y, type PieChartData as Z, type RetrievalResult as _, type UseRagChatOptions as a, type RetrivoraIngestedDocument as a0, type ScatterPlotDataPoint as a1, type SuggestionsResponse as a2, type TableData as a3, type VisualizationType as a4, type UseRagChatReturn as b, type ProjectChatSettings as c, type ChatOptions as d, type ChatResponse as e, type EmbeddingConfig as f, type EmbeddingProvider as g, type IngestDocument as h, type LLMProvider as i, type LatencyBreakdown as j, type ProjectAiSettings as k, type ProjectAuthSettings as l, type ProjectBrandingSettings as m, type ProjectTelemetrySettings as n, type ProjectWidgetSettings as o, type RagConfig as p, type RagMessage as q, type RetrievalConfig as r, type RetrievedChunk as s, type TokenUsage as t, type UIConfig as u, type UniversalRagConfig as v, type UpsertDocument as w, type VectorDBProvider as x, type VectorMatch as y, type WorkflowConfig as z };