@absolutejs/absolute 0.19.0-beta.528 → 0.19.0-beta.529

package/dist/ai/index.js

@@ -4332,7 +4332,7 @@ var createRAGCollection = (options) => {
     validateRAGEmbeddingDimensions(vector, getExpectedDimensions(), context);
     return vector;
   };
-  const search = async (input) => {
+  const searchWithTrace = async (input) => {
     const model = input.model ?? options.defaultModel;
     const topK = input.topK ?? defaultTopK;
     const hasReranker = Boolean(input.rerank ?? options.rerank);
@@ -4355,11 +4355,47 @@ var createRAGCollection = (options) => {
     const runVector = shouldRunVectorRetrieval(retrieval.mode);
     const runLexical = shouldRunLexicalRetrieval(retrieval.mode, options.store);
     const lexicalTopK = Math.max(topK, Math.floor(retrieval.lexicalTopK ?? candidateTopK));
+    const steps = [
+      {
+        count: topK,
+        label: "Search input received",
+        metadata: {
+          candidateTopK,
+          hasQueryTransform,
+          hasReranker,
+          mode: retrieval.mode,
+          runLexical,
+          runVector,
+          topK
+        },
+        stage: "input"
+      }
+    ];
     const queryVector = runVector ? await embed({
       model,
       signal: input.signal,
       text: input.query
     }, "query") : [];
+    if (runVector) {
+      steps.push({
+        label: "Embedded primary query",
+        metadata: {
+          dimensions: queryVector.length,
+          query: input.query
+        },
+        stage: "embed"
+      });
+    }
+    if (transformed.query !== input.query || searchQueries.length > 1) {
+      steps.push({
+        label: "Expanded query variants",
+        metadata: {
+          transformedQuery: transformed.query,
+          variantCount: Math.max(0, searchQueries.length - 1)
+        },
+        stage: "query_transform"
+      });
+    }
     const resultGroups = await Promise.all(searchQueries.map(async (query, queryIndex) => {
       const [vectorResults2, lexicalResults2] = await Promise.all([
         runVector ? embed({
@@ -4383,7 +4419,29 @@ var createRAGCollection = (options) => {
       };
     }));
     const vectorResults = mergeQueryResults(resultGroups.flatMap((group) => group.vectorResults));
+    if (runVector) {
+      steps.push({
+        count: vectorResults.length,
+        label: "Collected vector candidates",
+        metadata: {
+          queryCount: searchQueries.length,
+          topK: candidateTopK
+        },
+        stage: "vector_search"
+      });
+    }
     const lexicalResults = mergeQueryResults(resultGroups.flatMap((group) => group.lexicalResults));
+    if (runLexical) {
+      steps.push({
+        count: lexicalResults.length,
+        label: "Collected lexical candidates",
+        metadata: {
+          queryCount: searchQueries.length,
+          topK: lexicalTopK
+        },
+        stage: "lexical_search"
+      });
+    }
     const results = retrieval.mode === "lexical" ? lexicalResults : retrieval.mode === "vector" ? vectorResults : fuseRAGQueryResults({
       fusion: retrieval.fusion,
       fusionConstant: retrieval.fusionConstant,
@@ -4392,6 +4450,14 @@ var createRAGCollection = (options) => {
       vector: vectorResults,
       vectorWeight: retrieval.vectorWeight
     });
+    steps.push({
+      count: results.length,
+      label: retrieval.mode === "hybrid" ? "Fused retrieval candidates" : "Selected retrieval candidates",
+      metadata: {
+        mode: retrieval.mode
+      },
+      stage: "fusion"
+    });
     const rerankInput = {
       candidateTopK,
       filter: input.filter,
@@ -4406,12 +4472,92 @@ var createRAGCollection = (options) => {
       input: rerankInput,
       reranker: input.rerank ?? options.rerank
     });
+    steps.push({
+      count: reranked.length,
+      label: hasReranker ? "Reranked retrieval candidates" : "Skipped reranking and kept retrieval order",
+      metadata: {
+        applied: hasReranker
+      },
+      stage: "rerank"
+    });
     const limited = reranked.slice(0, topK);
     if (typeof input.scoreThreshold !== "number") {
-      return limited;
+      steps.push({
+        count: limited.length,
+        label: "Finalized retrieval results",
+        metadata: {
+          appliedScoreThreshold: false
+        },
+        stage: "finalize"
+      });
+      return {
+        results: limited,
+        trace: {
+          candidateTopK,
+          lexicalTopK,
+          mode: retrieval.mode,
+          query: input.query,
+          resultCounts: {
+            final: limited.length,
+            fused: results.length,
+            lexical: lexicalResults.length,
+            reranked: reranked.length,
+            vector: vectorResults.length
+          },
+          runLexical,
+          runVector,
+          steps,
+          topK,
+          transformedQuery: transformed.query,
+          variantQueries: searchQueries.slice(1)
+        }
+      };
     }
     const { scoreThreshold } = input;
-    return limited.filter((entry) => entry.score >= scoreThreshold);
+    const filtered = limited.filter((entry) => entry.score >= scoreThreshold);
+    steps.push({
+      count: filtered.length,
+      label: "Applied score threshold",
+      metadata: {
+        scoreThreshold
+      },
+      stage: "score_filter"
+    });
+    steps.push({
+      count: filtered.length,
+      label: "Finalized retrieval results",
+      metadata: {
+        appliedScoreThreshold: true
+      },
+      stage: "finalize"
+    });
+    return {
+      results: filtered,
+      trace: {
+        candidateTopK,
+        lexicalTopK,
+        mode: retrieval.mode,
+        query: input.query,
+        resultCounts: {
+          final: filtered.length,
+          fused: results.length,
+          lexical: lexicalResults.length,
+          reranked: reranked.length,
+          vector: vectorResults.length
+        },
+        runLexical,
+        runVector,
+        scoreThreshold,
+        steps,
+        topK,
+        transformedQuery: transformed.query,
+        variantQueries: searchQueries.slice(1)
+      }
+    };
+  };
+  const search = async (input) => {
+    const result = await searchWithTrace(input);
+    return result.results;
   };
   const ingest = async (input) => {
     const chunks = await Promise.all(input.chunks.map(async (chunk) => {
@@ -4433,6 +4579,7 @@ var createRAGCollection = (options) => {
     clear: typeof options.store.clear === "function" ? () => options.store.clear?.() : undefined,
     getCapabilities: typeof getCapabilities === "function" ? () => getCapabilities() : undefined,
     getStatus: typeof getStatus === "function" ? () => getStatus() : undefined,
+    searchWithTrace,
     search,
     store: options.store,
     ingest
@@ -4547,6 +4694,13 @@ var buildSourceGroupKey = (source) => source.source ?? source.title ?? source.ch
 var buildSourceLabel = (source) => source.source ?? source.title ?? source.chunkId;
 var getContextNumber = (value) => typeof value === "number" && Number.isFinite(value) ? value : undefined;
 var getContextString = (value) => typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+var isRAGRetrievalTrace = (value) => {
+  if (!value || typeof value !== "object") {
+    return false;
+  }
+  const candidate = value;
+  return typeof candidate.query === "string" && typeof candidate.transformedQuery === "string" && Array.isArray(candidate.variantQueries) && Array.isArray(candidate.steps);
+};
 var formatTimestampLabel = (value) => {
   const timestamp = typeof value === "number" && Number.isFinite(value) ? value : typeof value === "string" ? Date.parse(value) : Number.NaN;
   if (!Number.isFinite(timestamp)) {
@@ -4814,6 +4968,7 @@ var buildRAGRetrievedState = (messages) => {
     retrievalDurationMs: message.retrievalDurationMs,
     retrievalStartedAt: message.retrievalStartedAt,
     retrievedAt: message.retrievedAt,
+    trace: isRAGRetrievalTrace(message.retrievalTrace) ? message.retrievalTrace : undefined,
     sourceGroups: buildRAGSourceGroups(sources),
     sourceSummaries: buildRAGSourceSummaries(sources),
     sources
@@ -6303,16 +6458,17 @@ var buildRAGContextFromQuery = async (config, topK, scoreThreshold, queryText, r
       sources: []
     };
   }
-  const queried = await collection.search({
+  const queried = await collection.searchWithTrace({
     model: embeddingModel ?? ragModel,
     query: queryText,
     scoreThreshold,
     topK
   });
-  const sources = buildSources2(queried);
+  const sources = buildSources2(queried.results);
   return {
-    ragContext: buildRAGContext(queried),
-    sources
+    ragContext: buildRAGContext(queried.results),
+    sources,
+    trace: queried.trace
   };
 };
 var ragChat = (config) => {
@@ -6439,7 +6595,7 @@ var ragChat = (config) => {
       conversation.title = message.content.slice(0, TITLE_MAX_LENGTH2);
     }
   };
-  const appendAssistantMessage = async (conversationId, messageId, content, sources, usage, model, retrievalStartedAt, retrievedAt, retrievalDurationMs) => {
+  const appendAssistantMessage = async (conversationId, messageId, content, sources, usage, model, retrievalStartedAt, retrievedAt, retrievalDurationMs, retrievalTrace) => {
     const conv = await store.get(conversationId);
     if (!conv) {
       return;
@@ -6452,6 +6608,7 @@ var ragChat = (config) => {
       role: "assistant",
       retrievalDurationMs,
       retrievalStartedAt,
+      retrievalTrace,
       retrievedAt,
       sources,
       timestamp: Date.now(),
@@ -6481,7 +6638,7 @@ var ragChat = (config) => {
       type: "branched"
     }));
   };
-  const handleRAGRetrieved = (ws, conversationId, messageId, sources, retrievalStartedAt, retrievedAt, retrievalDurationMs) => {
+  const handleRAGRetrieved = (ws, conversationId, messageId, sources, retrievalStartedAt, retrievedAt, retrievalDurationMs, trace) => {
     ws.send(JSON.stringify({
       conversationId,
       messageId,
@@ -6489,6 +6646,7 @@ var ragChat = (config) => {
       retrievalStartedAt,
       retrievedAt,
       sources,
+      trace,
       type: "rag_retrieved"
     }));
   };
@@ -6525,10 +6683,10 @@ var ragChat = (config) => {
     const rag = await buildRAGContextFromQuery(config, topK, scoreThreshold, content, ragModel, config.embedding, config.embeddingModel);
     const controller = new AbortController;
     abortControllers.set(conversationId, controller);
-    const { ragContext, sources } = rag;
+    const { ragContext, sources, trace } = rag;
     const retrievedAt = Date.now();
     const retrievalDurationMs = retrievedAt - retrievalStartedAt;
-    handleRAGRetrieved(ws, conversationId, assistantMessageId, sources, retrievalStartedAt, retrievedAt, retrievalDurationMs);
+    handleRAGRetrieved(ws, conversationId, assistantMessageId, sources, retrievalStartedAt, retrievedAt, retrievalDurationMs, trace);
     await streamAI(ws, conversationId, assistantMessageId, {
       completeMeta: includeCompleteSources ? { sources } : undefined,
       maxTurns: config.maxTurns,
@@ -6543,7 +6701,7 @@ var ragChat = (config) => {
       thinking: resolveThinking2(config, providerName, model),
       tools: resolveTools2(config, providerName, model),
       onComplete: async (fullResponse, usage) => {
-        await appendAssistantMessage(conversationId, assistantMessageId, fullResponse, sources, usage, model, retrievalStartedAt, retrievedAt, retrievalDurationMs);
+        await appendAssistantMessage(conversationId, assistantMessageId, fullResponse, sources, usage, model, retrievalStartedAt, retrievedAt, retrievalDurationMs, trace);
         abortControllers.delete(conversationId);
         config.onComplete?.(conversationId, fullResponse, usage, sources);
       }
@@ -6747,13 +6905,22 @@ var ragChat = (config) => {
     if (!collection) {
       return { error: "RAG collection is not configured", ok: false };
     }
-    const results = await collection.search({
+    const input = {
       filter: getObjectProperty(body, "filter"),
       model: getStringProperty(body, "model"),
       query,
       scoreThreshold: typeof body.scoreThreshold === "number" ? body.scoreThreshold : undefined,
       topK: typeof body.topK === "number" ? body.topK : undefined
-    });
+    };
+    if (getBooleanProperty(body, "includeTrace") === true) {
+      const result = await collection.searchWithTrace(input);
+      return {
+        ok: true,
+        results: buildSources2(result.results),
+        trace: result.trace
+      };
+    }
+    const results = await collection.search(input);
     return { ok: true, results: buildSources2(results) };
   };
   const summarizeDocuments = (documents) => ({
@@ -10933,8 +11100,12 @@ var createRAGClient = (options) => {
       return parseJson(response);
     },
     async search(input) {
+      const result = await this.searchDetailed(input);
+      return result.results;
+    },
+    async searchDetailed(input) {
       const response = await fetchImpl(`${basePath}/search`, {
-        body: JSON.stringify(input),
+        body: JSON.stringify({ ...input, includeTrace: true }),
         headers: jsonHeaders,
         method: "POST"
       });
@@ -10945,7 +11116,10 @@ var createRAGClient = (options) => {
       if (!payload.ok) {
         throw new Error(payload.error ?? "RAG search failed");
       }
-      return payload.results ?? [];
+      return {
+        results: payload.results ?? [],
+        trace: payload.trace
+      };
     },
     async status() {
       const response = await fetchImpl(`${basePath}/status`);
@@ -11107,5 +11281,5 @@ export {
   aiChat
 };
 
-//# debugId=DE622C67D301D24764756E2164756E21
+//# debugId=3C016671455736C564756E2164756E21
 //# sourceMappingURL=index.js.map