@retrivora-ai/rag-engine 1.9.3 → 1.9.7

package/src/config/RagConfig.ts

@@ -199,6 +199,36 @@ export interface RAGConfig {
   vectorKeywords?: string[];
 }
 
+export 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<string, unknown>;
+}
+
+export interface WorkflowConfig {
+  /** High-level workflow selector from the SDK prompt. */
+  type?: 'simple-rag' | 'rag' | 'hybrid-rag' | 'graph-rag' | 'agentic-rag' | 'agentic';
+  /** Future workflow/provider-specific options. */
+  options?: Record<string, unknown>;
+}
+
 // ---------------------------------------------------------------------------
 // Root Config
 // ---------------------------------------------------------------------------
@@ -228,3 +258,20 @@ export interface RagConfig {
   /** Optional Graph database configuration */
   graphDb?: GraphDBConfig;
 }
+
+/**
+ * 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.
+ */
+export type UniversalRagConfig =
+  Partial<Omit<RagConfig, 'vectorDb' | 'rag' | 'llm' | 'embedding' | 'graphDb'>> & {
+    vectorDb?: Partial<VectorDBConfig>;
+    vectorDatabase?: Partial<VectorDBConfig>;
+    llm?: Partial<LLMConfig>;
+    embedding?: Partial<EmbeddingConfig>;
+    graphDb?: Partial<GraphDBConfig>;
+    retrieval?: RetrievalConfig;
+    rag?: RAGConfig;
+    workflow?: WorkflowConfig;
+  };

package/src/config/constants.ts

@@ -4,6 +4,7 @@
  * This file serves as the single source of truth for all statically supported
  * providers and stylistic options in the Retrivora AI RAG Engine.
  */
+export const VERSION = '1.9.6';
 
 export const VECTOR_DB_PROVIDERS = [
   'pinecone',

package/src/config/serverConfig.ts

@@ -167,6 +167,8 @@ export function getEnvConfig(env: Record<string, string | undefined> = process.e
       temperature: readNumber(env, 'LLM_TEMPERATURE', 0.7),
       options: {
         profile: readString(env, 'LLM_UNIVERSAL_PROFILE'),
+        thinking: readString(env, 'LLM_THINKING') === 'true' || readString(env, 'LLM_THINKING') === 'enabled' ? true : (readString(env, 'LLM_THINKING') === 'false' ? false : undefined),
+        thinkingBudget: env.LLM_THINKING_BUDGET ? parseInt(env.LLM_THINKING_BUDGET, 10) : undefined,
       },
     },
     embedding: {
@@ -202,6 +204,29 @@ export function getEnvConfig(env: Record<string, string | undefined> = process.e
       scoreThreshold: readNumber(env, 'RAG_SCORE_THRESHOLD', 0),
       chunkSize: readNumber(env, 'RAG_CHUNK_SIZE', 1000),
       chunkOverlap: readNumber(env, 'RAG_CHUNK_OVERLAP', 200),
+      filterableFields: readString(env, 'RAG_FILTERABLE_FIELDS')?.split(',').map(f => f.trim()),
+      // Query pipeline toggles — read from .env.local
+      useQueryTransformation: readString(env, 'RAG_USE_QUERY_TRANSFORMATION') === 'true',
+      useReranking: readString(env, 'RAG_USE_RERANKING') === 'true',
+      useGraphRetrieval: readString(env, 'RAG_USE_GRAPH_RETRIEVAL') === 'true',
+      architecture: (readString(env, 'RAG_ARCHITECTURE') ?? 'simple') as 'simple' | 'graph' | 'hybrid' | 'agentic',
+      chunkingStrategy: (readString(env, 'RAG_CHUNKING_STRATEGY') ?? 'recursive') as 'recursive' | 'markdown' | 'semantic' | 'llamaindex',
+      uiMapping: (() => {
+        const raw = readString(env, 'RAG_UI_MAPPING');
+        if (!raw) return undefined;
+        try { return JSON.parse(raw) as Record<string, string>; } catch { return undefined; }
+      })(),
     },
+    // Optional graph DB — driven by GRAPH_DB_PROVIDER env var
+    ...(readString(env, 'GRAPH_DB_PROVIDER') ? {
+      graphDb: {
+        provider: readString(env, 'GRAPH_DB_PROVIDER')! as 'neo4j' | 'memgraph' | 'simple' | 'custom',
+        options: {
+          uri: readString(env, 'GRAPH_DB_URI'),
+          username: readString(env, 'GRAPH_DB_USERNAME'),
+          password: readString(env, 'GRAPH_DB_PASSWORD'),
+        },
+      },
+    } : {}),
   };
 }

package/src/core/ConfigResolver.ts

@@ -6,7 +6,7 @@
  * environment variables are only parsed once per process, avoiding
  * repeated work in serverless cold starts and per-request handler calls.
  */
-import { RagConfig } from '../config/RagConfig';
+import { RagConfig, UniversalRagConfig, RAGConfig, RetrievalConfig, WorkflowConfig } from '../config/RagConfig';
 import { mergeDefined } from '../utils/templateUtils';
 import { getEnvConfig } from '../config/serverConfig';
 
@@ -31,39 +31,56 @@ export class ConfigResolver {
       projectId: hostConfig.projectId || envConfig.projectId,
       vectorDb: hostConfig.vectorDb
         ? {
-            ...envConfig.vectorDb,
-            ...hostConfig.vectorDb,
-            options: {
-              ...envConfig.vectorDb.options,
-              ...(hostConfig.vectorDb.options || {}),
-            },
-          }
+          ...envConfig.vectorDb,
+          ...hostConfig.vectorDb,
+          options: {
+            ...envConfig.vectorDb.options,
+            ...(hostConfig.vectorDb.options || {}),
+          },
+        }
         : envConfig.vectorDb,
       llm: hostConfig.llm
         ? {
-            ...envConfig.llm,
-            ...hostConfig.llm,
-            options: {
-              ...(envConfig.llm.options || {}),
-              ...(hostConfig.llm.options || {}),
-            },
-          }
+          ...envConfig.llm,
+          ...hostConfig.llm,
+          options: {
+            ...(envConfig.llm.options || {}),
+            ...(hostConfig.llm.options || {}),
+          },
+        }
         : envConfig.llm,
       embedding: hostConfig.embedding
         ? {
-            ...envConfig.embedding,
-            ...hostConfig.embedding,
-            options: {
-              ...(envConfig.embedding.options || {}),
-              ...(hostConfig.embedding.options || {}),
-            },
-          }
+          ...envConfig.embedding,
+          ...hostConfig.embedding,
+          options: {
+            ...(envConfig.embedding.options || {}),
+            ...(hostConfig.embedding.options || {}),
+          },
+        }
         : envConfig.embedding,
       ui: hostConfig.ui ? mergeDefined(envConfig.ui, hostConfig.ui) : envConfig.ui,
       rag: hostConfig.rag ? { ...envConfig.rag, ...hostConfig.rag } : envConfig.rag,
     };
   }
 
+  /**
+   * Resolves the public SDK config shape used by `new Retrivora({...})`.
+   * Supports aliases from the product prompt while preserving existing env
+   * fallback behavior.
+   */
+  static resolveUniversal(hostConfig?: UniversalRagConfig, env: Record<string, string | undefined> = process.env): RagConfig {
+    if (!hostConfig) return this.resolve(undefined, env);
+
+    const normalized: Partial<RagConfig> = {
+      ...hostConfig,
+      vectorDb: hostConfig.vectorDb ?? hostConfig.vectorDatabase,
+      rag: this.mergeRetrievalWorkflow(hostConfig.rag, hostConfig.retrieval, hostConfig.workflow),
+    } as Partial<RagConfig>;
+
+    return this.resolve(normalized, env);
+  }
+
   /**
    * Validates the configuration for required fields.
    */
@@ -78,4 +95,38 @@ export class ConfigResolver {
       throw new Error('[ConfigResolver] llm.provider is required');
     }
   }
+
+  private static mergeRetrievalWorkflow(
+    rag?: RAGConfig,
+    retrieval?: RetrievalConfig,
+    workflow?: WorkflowConfig,
+  ): RAGConfig | undefined {
+    if (!rag && !retrieval && !workflow) return undefined;
+
+    const normalized: RAGConfig = { ...(rag ?? {}) };
+
+    if (retrieval) {
+      normalized.topK = retrieval.topK ?? normalized.topK;
+      normalized.scoreThreshold = retrieval.scoreThreshold ?? normalized.scoreThreshold;
+      normalized.useReranking = retrieval.useReranking ?? normalized.useReranking;
+
+      if (retrieval.strategy === 'hybrid') normalized.architecture = normalized.architecture ?? 'hybrid';
+      if (retrieval.strategy === 'agentic') normalized.architecture = 'agentic';
+      if (retrieval.strategy === 'contextual-compression') normalized.useReranking = true;
+    }
+
+    if (workflow?.type) {
+      const type = workflow.type;
+      if (type === 'agentic' || type === 'agentic-rag') normalized.architecture = 'agentic';
+      else if (type === 'hybrid-rag') normalized.architecture = 'hybrid';
+      else if (type === 'graph-rag') {
+        normalized.architecture = 'graph';
+        normalized.useGraphRetrieval = true;
+      } else if (type === 'simple-rag' || type === 'rag') {
+        normalized.architecture = normalized.architecture ?? 'simple';
+      }
+    }
+
+    return normalized;
+  }
 }

package/src/core/ConfigValidator.ts

@@ -4,6 +4,7 @@ import {
 } from '../config/constants';
 import { ProviderRegistry } from './ProviderRegistry';
 import { LLMFactory } from '../llm/LLMFactory';
+import { ConfigurationException } from '../exceptions';
 
 export interface ValidationError {
   field: string;
@@ -190,7 +191,7 @@ export class ConfigValidator {
       const message = errorItems
         .map((e) => `${e.field}: ${e.message}${e.suggestion ? ` (${e.suggestion})` : ''}`)
         .join('\n  ');
-      throw new Error(`[ConfigValidator] Configuration validation failed:\n  ${message}`);
+      throw new ConfigurationException(`[ConfigValidator] Configuration validation failed:\n  ${message}`, errorItems);
     }
   }
 }