@absolutejs/absolute 0.19.0-beta.613 → 0.19.0-beta.615

package/dist/ai/index.js

@@ -3772,10 +3772,35 @@ var buildRAGRetrievalTracePresentation = (trace) => {
   ];
   const details = [
     { label: "Transformed query", value: trace.transformedQuery },
+    ...trace.queryTransformLabel || trace.queryTransformProvider ? [
+      {
+        label: "Query transform",
+        value: trace.queryTransformLabel ?? trace.queryTransformProvider ?? "configured"
+      },
+      ...trace.queryTransformReason ? [
+        {
+          label: "Query transform reason",
+          value: trace.queryTransformReason
+        }
+      ] : []
+    ] : [],
     {
       label: "Variant queries",
       value: trace.variantQueries.length > 0 ? trace.variantQueries.join(" \xB7 ") : "none"
     },
+    ...trace.requestedMode && trace.requestedMode !== trace.mode ? [{ label: "Requested mode", value: trace.requestedMode }] : [],
+    ...trace.routingLabel || trace.routingProvider ? [
+      {
+        label: "Routing decision",
+        value: trace.routingLabel ?? trace.routingProvider ?? "configured"
+      },
+      ...trace.routingReason ? [
+        {
+          label: "Routing reason",
+          value: trace.routingReason
+        }
+      ] : []
+    ] : [],
     { label: "Candidate topK", value: String(trace.candidateTopK) },
     { label: "Lexical topK", value: String(trace.lexicalTopK) }
   ];
@@ -4668,10 +4693,10 @@ var buildRAGSectionRetrievalDiagnostics = (sources, trace) => {
     const vectorHits = channels.includes("vector") ? 1 : 0;
     const lexicalHits = channels.includes("lexical") ? 1 : 0;
     const hybridHits = isHybrid ? 1 : 0;
-    const queryOrigin = source.metadata?.retrievalQueryOrigin;
-    const primaryHits = queryOrigin === "primary" ? 1 : 0;
-    const transformedHits = queryOrigin === "transformed" ? 1 : 0;
-    const variantHits = queryOrigin === "variant" ? 1 : 0;
+    const queryOrigins = Array.isArray(source.metadata?.retrievalQueryOrigins) ? source.metadata.retrievalQueryOrigins.filter((value) => value === "primary" || value === "transformed" || value === "variant") : source.metadata?.retrievalQueryOrigin === "primary" || source.metadata?.retrievalQueryOrigin === "transformed" || source.metadata?.retrievalQueryOrigin === "variant" ? [source.metadata.retrievalQueryOrigin] : [];
+    const primaryHits = queryOrigins.includes("primary") ? 1 : 0;
+    const transformedHits = queryOrigins.includes("transformed") ? 1 : 0;
+    const variantHits = queryOrigins.includes("variant") ? 1 : 0;
     if (!existing) {
       sections.set(key, {
         bestScore: source.score,
@@ -4878,7 +4903,14 @@ var buildRAGSectionRetrievalDiagnostics = (sources, trace) => {
         transformedHits: section.transformedHits,
         variantHits: section.variantHits
       },
+      requestedMode: trace?.requestedMode,
       retrievalMode: trace?.mode,
+      routingLabel: trace?.routingLabel,
+      routingProvider: trace?.routingProvider,
+      routingReason: trace?.routingReason,
+      queryTransformLabel: trace?.queryTransformLabel,
+      queryTransformProvider: trace?.queryTransformProvider,
+      queryTransformReason: trace?.queryTransformReason,
       reasons,
       rerankApplied: trace?.steps.some((step) => step.stage === "rerank" && step.metadata?.applied === true),
       scoreShare,
@@ -8356,7 +8388,17 @@ var STOP_WORDS3 = new Set([
   "which",
   "why"
 ]);
-var collectMetadataStrings2 = (value) => {
+var INTERNAL_RETRIEVAL_METADATA_KEYS = new Set([
+  "retrievalChannels",
+  "retrievalQuery",
+  "retrievalQueryIndex",
+  "retrievalQueryOrigin",
+  "retrievalQueryOrigins"
+]);
+var collectMetadataStrings2 = (value, key) => {
+  if (typeof key === "string" && INTERNAL_RETRIEVAL_METADATA_KEYS.has(key)) {
+    return [];
+  }
   if (typeof value === "string" || typeof value === "number") {
     return [String(value)];
   }
@@ -8364,7 +8406,7 @@ var collectMetadataStrings2 = (value) => {
     return value.flatMap((entry) => collectMetadataStrings2(entry));
   }
   if (value && typeof value === "object") {
-    return Object.values(value).flatMap((entry) => collectMetadataStrings2(entry));
+    return Object.entries(value).flatMap(([entryKey, entry]) => collectMetadataStrings2(entry, entryKey));
   }
   return [];
 };
@@ -10538,9 +10580,17 @@ var mergeQueryResults = (results) => {
   const merged = new Map;
   for (const result of results) {
     const existing = merged.get(result.chunkId);
-    if (!existing || result.score > existing.score) {
-      merged.set(result.chunkId, result);
-    }
+    const existingOrigins = Array.isArray(existing?.metadata?.retrievalQueryOrigins) ? existing.metadata.retrievalQueryOrigins.filter((value) => typeof value === "string") : typeof existing?.metadata?.retrievalQueryOrigin === "string" ? [existing.metadata.retrievalQueryOrigin] : [];
+    const resultOrigins = Array.isArray(result.metadata?.retrievalQueryOrigins) ? result.metadata.retrievalQueryOrigins.filter((value) => typeof value === "string") : typeof result.metadata?.retrievalQueryOrigin === "string" ? [result.metadata.retrievalQueryOrigin] : [];
+    const mergedOrigins = Array.from(new Set([...existingOrigins, ...resultOrigins]));
+    const preferred = !existing || result.score > existing.score ? result : existing;
+    merged.set(result.chunkId, {
+      ...preferred,
+      metadata: {
+        ...preferred.metadata ?? {},
+        retrievalQueryOrigins: mergedOrigins
+      }
+    });
   }
   return [...merged.values()].sort((left, right) => {
     if (right.score !== left.score) {
@@ -10744,6 +10794,19 @@ var annotateRetrievalQueryOrigin = (input) => {
 };
 var shouldRunVectorRetrieval = (mode) => mode === "vector" || mode === "hybrid";
 var shouldRunLexicalRetrieval = (mode, store) => mode === "lexical" || mode === "hybrid" && Boolean(store.queryLexical);
+var resolveRAGRetrievalStrategy = (retrievalStrategy) => {
+  if (!retrievalStrategy) {
+    return null;
+  }
+  if (typeof retrievalStrategy === "function") {
+    return {
+      defaultLabel: undefined,
+      providerName: undefined,
+      select: retrievalStrategy
+    };
+  }
+  return retrievalStrategy;
+};
 var createRAGCollection = (options) => {
   const defaultTopK = options.defaultTopK ?? DEFAULT_TOP_K2;
   const defaultCandidateMultiplier = Math.max(1, Math.floor(options.defaultCandidateMultiplier ?? 4));
@@ -10760,10 +10823,11 @@ var createRAGCollection = (options) => {
     const model = input.model ?? options.defaultModel;
     const topK = input.topK ?? defaultTopK;
     const hasReranker = Boolean(input.rerank ?? options.rerank);
-    const retrieval = resolveRAGHybridSearchOptions(input.retrieval);
+    const requestedRetrieval = resolveRAGHybridSearchOptions(input.retrieval);
     const hasQueryTransform = Boolean(input.queryTransform ?? options.queryTransform);
-    const shouldExpandCandidates = hasReranker || hasQueryTransform || retrieval.mode !== "vector";
+    const shouldExpandCandidates = hasReranker || hasQueryTransform || requestedRetrieval.mode !== "vector";
     const candidateTopK = Math.max(topK, Math.floor(input.candidateTopK ?? (shouldExpandCandidates ? topK * defaultCandidateMultiplier : topK)));
+    const resolvedQueryTransform = resolveRAGQueryTransform(input.queryTransform ?? options.queryTransform);
     const transformed = await applyRAGQueryTransform({
       input: {
         candidateTopK,
@@ -10773,9 +10837,25 @@ var createRAGCollection = (options) => {
         scoreThreshold: input.scoreThreshold,
         topK
       },
-      queryTransform: input.queryTransform ?? options.queryTransform
+      queryTransform: resolvedQueryTransform ?? undefined
     });
     const searchQueries = Array.from(new Set([transformed.query, ...transformed.variants ?? []])).filter(Boolean);
+    const resolvedRetrievalStrategy = resolveRAGRetrievalStrategy(input.retrievalStrategy ?? options.retrievalStrategy);
+    const retrievalDecision = resolvedRetrievalStrategy ? await Promise.resolve(resolvedRetrievalStrategy.select({
+      candidateTopK,
+      filter: input.filter,
+      model,
+      query: input.query,
+      retrieval: requestedRetrieval,
+      scoreThreshold: input.scoreThreshold,
+      topK,
+      transformedQuery: transformed.query,
+      variantQueries: searchQueries.slice(1)
+    })) : undefined;
+    const retrieval = retrievalDecision ? {
+      ...requestedRetrieval,
+      ...retrievalDecision
+    } : requestedRetrieval;
     const runVector = shouldRunVectorRetrieval(retrieval.mode);
     const runLexical = shouldRunLexicalRetrieval(retrieval.mode, options.store);
     const lexicalTopK = Math.max(topK, Math.floor(retrieval.lexicalTopK ?? candidateTopK));
@@ -10818,12 +10898,31 @@ var createRAGCollection = (options) => {
       steps.push({
         label: "Expanded query variants",
         metadata: {
+          label: transformed.label ?? resolvedQueryTransform?.providerName ?? null,
+          providerName: resolvedQueryTransform?.providerName ?? null,
+          reason: transformed.reason ?? null,
           transformedQuery: transformed.query,
-          variantCount: Math.max(0, searchQueries.length - 1)
+          variantCount: Math.max(0, searchQueries.length - 1),
+          ...transformed.metadata ?? {}
         },
         stage: "query_transform"
       });
     }
+    if (retrievalDecision || requestedRetrieval.mode !== retrieval.mode || requestedRetrieval.lexicalTopK !== retrieval.lexicalTopK) {
+      steps.push({
+        label: retrievalDecision?.label ?? "Selected retrieval strategy",
+        metadata: {
+          applied: Boolean(retrievalDecision),
+          label: retrievalDecision?.label ?? resolvedRetrievalStrategy?.defaultLabel ?? null,
+          providerName: resolvedRetrievalStrategy?.providerName ?? null,
+          reason: retrievalDecision?.reason ?? null,
+          requestedMode: requestedRetrieval.mode,
+          selectedMode: retrieval.mode,
+          ...retrievalDecision?.metadata ?? {}
+        },
+        stage: "routing"
+      });
+    }
     const resultGroups = await Promise.all(searchQueries.map(async (query, queryIndex) => {
       const [vectorResults2, lexicalResults2] = await Promise.all([
         runVector ? embed({
@@ -10982,6 +11081,9 @@ var createRAGCollection = (options) => {
           mode: retrieval.mode,
           diversityStrategy: retrieval.diversityStrategy,
           query: input.query,
+          queryTransformLabel: transformed.label,
+          queryTransformProvider: resolvedQueryTransform?.providerName,
+          queryTransformReason: transformed.reason,
           resultCounts: {
             final: limited.length,
             fused: results.length,
@@ -10989,8 +11091,12 @@ var createRAGCollection = (options) => {
             reranked: diversified.length,
             vector: vectorResults.length
           },
+          requestedMode: requestedRetrieval.mode,
           runLexical,
           runVector,
+          routingLabel: retrievalDecision?.label ?? resolvedRetrievalStrategy?.defaultLabel,
+          routingProvider: resolvedRetrievalStrategy?.providerName,
+          routingReason: retrievalDecision?.reason,
           sourceBalanceStrategy: retrieval.sourceBalanceStrategy,
           steps,
           topK,
@@ -11031,6 +11137,9 @@ var createRAGCollection = (options) => {
         mode: retrieval.mode,
         diversityStrategy: retrieval.diversityStrategy,
         query: input.query,
+        queryTransformLabel: transformed.label,
+        queryTransformProvider: resolvedQueryTransform?.providerName,
+        queryTransformReason: transformed.reason,
         resultCounts: {
           final: filtered.length,
           fused: results.length,
@@ -11038,8 +11147,12 @@ var createRAGCollection = (options) => {
           reranked: diversified.length,
           vector: vectorResults.length
         },
+        requestedMode: requestedRetrieval.mode,
         runLexical,
         runVector,
+        routingLabel: retrievalDecision?.label ?? resolvedRetrievalStrategy?.defaultLabel,
+        routingProvider: resolvedRetrievalStrategy?.providerName,
+        routingReason: retrievalDecision?.reason,
         scoreThreshold,
         sourceBalanceStrategy: retrieval.sourceBalanceStrategy,
         steps,
@@ -18100,6 +18213,64 @@ var ragChat = (config) => {
 // src/ai/rag/htmxConfig.ts
 var createRAGHTMXConfig = (config) => config;
 var createRAGHTMXWorkflowRenderConfig = (config) => config;
+// src/ai/rag/retrievalStrategies.ts
+var tokenize4 = (value) => value.toLowerCase().split(/[^a-z0-9]+/i).map((token) => token.trim()).filter((token) => token.length > 0);
+var hasAnyToken2 = (tokens, values) => values.some((value) => tokens.includes(value));
+var createHeuristicRAGRetrievalStrategy = (options = {}) => ({
+  defaultLabel: options.defaultLabel ?? "Heuristic retrieval routing",
+  providerName: options.providerName ?? "heuristic_retrieval_strategy",
+  select: (input) => {
+    const scopedSource = typeof input.filter?.source === "string" && input.filter.source.trim().length > 0;
+    const scopedDocumentId = typeof input.filter?.documentId === "string" && input.filter.documentId.trim().length > 0;
+    if ((scopedSource || scopedDocumentId) && input.retrieval.mode !== "vector") {
+      return {
+        label: "Scoped direct route",
+        mode: "vector",
+        reason: scopedDocumentId ? "documentId filter narrows retrieval to one target document" : "source filter narrows retrieval to one source family",
+        metadata: {
+          selector: "scoped_direct_route"
+        }
+      };
+    }
+    const tokens = tokenize4(input.query);
+    const transformedTokens = tokenize4(input.transformedQuery);
+    const combined = Array.from(new Set([...tokens, ...transformedTokens]));
+    const hasVariants = input.variantQueries.length > 0;
+    const supportLexical = hasAnyToken2(combined, ["faq", "policy", "password", "billing"]) && !hasVariants;
+    if (supportLexical) {
+      return {
+        label: "Support lexical route",
+        mode: "lexical",
+        reason: "faq/support phrase matched",
+        metadata: {
+          selector: "support_lexical"
+        }
+      };
+    }
+    const sourceNativeHybrid = hasVariants || hasAnyToken2(combined, [
+      "sheet",
+      "worksheet",
+      "workbook",
+      "spreadsheet",
+      "timestamp",
+      "transcript",
+      "attachment",
+      "archive"
+    ]);
+    if (sourceNativeHybrid && input.retrieval.mode === "vector") {
+      return {
+        label: "Source-native hybrid route",
+        mode: "hybrid",
+        lexicalTopK: Math.max(input.topK, Math.floor(input.retrieval.lexicalTopK ?? input.candidateTopK)),
+        reason: hasVariants ? "query expansion introduced source-native variants" : "source-native terminology benefits from hybrid retrieval",
+        metadata: {
+          selector: "source_native_hybrid"
+        }
+      };
+    }
+    return;
+  }
+});
 // src/ai/rag/embeddingProviders.ts
 var DEFAULT_OPENAI_BASE_URL = "https://api.openai.com";
 var DEFAULT_GEMINI_BASE_URL = "https://generativelanguage.googleapis.com";
@@ -22361,6 +22532,7 @@ export {
   createMemoryStore,
   createLegacyDocumentExtractor,
   createInMemoryRAGStore,
+  createHeuristicRAGRetrievalStrategy,
   createHeuristicRAGReranker,
   createHeuristicRAGQueryTransform,
   createEmailExtractor,
@@ -22374,56 +22546,21 @@ export {
   buildRAGUpsertInputFromURLs,
   buildRAGUpsertInputFromDocuments,
   buildRAGUpsertInputFromDirectory,
-  buildRAGSyncSourcePresentations,
-  buildRAGSyncSourcePresentation,
-  buildRAGSyncOverviewPresentation,
-  buildRAGSourceSummaries,
-  buildRAGSourceGroups,
   buildRAGSearchTraceRecord,
   buildRAGSearchTraceDiff,
-  buildRAGRetrievalTracePresentation,
   buildRAGRetrievalTraceHistoryTrend,
   buildRAGRetrievalReleaseVerdict,
-  buildRAGRetrievalOverviewPresentation,
-  buildRAGRetrievalComparisonPresentations,
-  buildRAGRetrievalComparisonOverviewPresentation,
   buildRAGRetrievalComparisonDecisionSummary,
-  buildRAGRerankerOverviewPresentation,
-  buildRAGRerankerComparisonPresentations,
-  buildRAGRerankerComparisonOverviewPresentation,
-  buildRAGReadinessPresentation,
-  buildRAGQualityOverviewPresentation,
   buildRAGLexicalHaystack,
-  buildRAGGroundingReferences,
-  buildRAGGroundingProviderPresentations,
-  buildRAGGroundingProviderOverviewPresentation,
-  buildRAGGroundingProviderCaseComparisonPresentations,
-  buildRAGGroundingOverviewPresentation,
-  buildRAGGroundedAnswer,
   buildRAGEvaluationRunDiff,
   buildRAGEvaluationResponse,
   buildRAGEvaluationLeaderboard,
-  buildRAGEvaluationHistoryRows,
-  buildRAGEvaluationHistoryPresentation,
-  buildRAGEvaluationCaseTracePresentations,
-  buildRAGCorpusHealthPresentation,
   buildRAGContext,
-  buildRAGComparisonTraceSummaryRows,
-  buildRAGComparisonTraceDiffRows,
-  buildRAGCitations,
-  buildRAGCitationReferenceMap,
-  buildRAGAnswerGroundingHistoryRows,
-  buildRAGAnswerGroundingHistoryPresentation,
   buildRAGAnswerGroundingEvaluationRunDiff,
   buildRAGAnswerGroundingEvaluationResponse,
   buildRAGAnswerGroundingEvaluationLeaderboard,
-  buildRAGAnswerGroundingCaseSnapshotPresentations,
   buildRAGAnswerGroundingCaseDifficultyRunDiff,
   buildRAGAnswerGroundingCaseDifficultyLeaderboard,
-  buildRAGAdminJobPresentations,
-  buildRAGAdminJobPresentation,
-  buildRAGAdminActionPresentations,
-  buildRAGAdminActionPresentation,
   applyRAGReranking,
   applyRAGQueryTransform,
   anthropicOCR,
@@ -22432,5 +22569,5 @@ export {
   aiChat
 };
 
-//# debugId=13C12436C949ED5964756E2164756E21
+//# debugId=2EBD38302AA26EE564756E2164756E21
 //# sourceMappingURL=index.js.map