@absolutejs/absolute 0.19.0-beta.530 → 0.19.0-beta.532

package/dist/types/ai.d.ts

@@ -1256,6 +1256,20 @@ export type RAGRerankerCandidate = {
     label?: string;
     rerank?: RAGRerankerProviderLike;
 };
+export type RAGRetrievalTraceComparisonSummary = {
+    totalCases: number;
+    modes: RAGHybridRetrievalMode[];
+    vectorCases: number;
+    lexicalCases: number;
+    transformedCases: number;
+    variantCases: number;
+    averageFinalCount: number;
+    averageVectorCount: number;
+    averageLexicalCount: number;
+    averageCandidateTopK: number;
+    averageLexicalTopK: number;
+    stageCounts: Partial<Record<RAGRetrievalTraceStage, number>>;
+};
 export type RAGRetrievalCandidate = {
     id: string;
     label?: string;
@@ -1268,6 +1282,7 @@ export type RAGRerankerComparisonEntry = {
     label: string;
     providerName?: string;
     response: RAGEvaluationResponse;
+    traceSummary?: RAGRetrievalTraceComparisonSummary;
 };
 export type RAGRerankerComparisonSummary = {
     bestByPassingRate?: string;
@@ -1286,6 +1301,7 @@ export type RAGRetrievalComparisonEntry = {
     label: string;
     retrievalMode: RAGHybridRetrievalMode;
     response: RAGEvaluationResponse;
+    traceSummary?: RAGRetrievalTraceComparisonSummary;
 };
 export type RAGRetrievalComparisonSummary = {
     bestByPassingRate?: string;
@@ -1500,6 +1516,7 @@ export type AIRetrievedMessage = {
     retrievedAt: number;
     retrievalDurationMs?: number;
     sources: RAGSource[];
+    trace?: RAGRetrievalTrace;
 };
 export type AIServerMessage = AIChunkMessage | AIThinkingMessage | AIToolStatusMessage | AIImageMessage | AICompleteMessage | AIRetrievingMessage | AIRetrievedMessage | AIErrorMessage;
 export type AIRole = 'user' | 'assistant' | 'system';
@@ -1626,6 +1643,7 @@ export type AIStoreAction = {
     retrievedAt: number;
     retrievalDurationMs?: number;
     sources: RAGSource[];
+    trace?: RAGRetrievalTrace;
 } | {
     type: 'send';
     content: string;
@@ -1679,6 +1697,7 @@ export type AIHTMXRenderConfig = {
         retrievalStartedAt?: number;
         retrievedAt?: number;
         retrievalDurationMs?: number;
+        trace?: RAGRetrievalTrace;
     }) => string;
     canceled?: () => string;
     error?: (message: string) => string;

package/dist/vue/ai/index.js

@@ -218,6 +218,7 @@ var serverMessageToAction = (msg) => {
         retrievalStartedAt: msg.retrievalStartedAt,
         retrievedAt: msg.retrievedAt,
         sources: msg.sources,
+        trace: msg.trace,
         type: "rag_retrieved"
       };
     case "error":
@@ -485,6 +486,7 @@ var handleRAGRetrieved = (state, action) => {
   message.retrievalStartedAt = action.retrievalStartedAt ?? message.retrievalStartedAt;
   message.retrievedAt = action.retrievedAt;
   message.retrievalDurationMs = action.retrievalDurationMs;
+  message.retrievalTrace = action.trace;
   conversation.messages = [...conversation.messages];
 };
 var handleRAGRetrieving = (state, action) => {
@@ -1027,8 +1029,19 @@ var createRAGClient = (options) => {
       return parseJson(response);
     },
     async search(input) {
-      const result = await this.searchDetailed(input);
-      return result.results;
+      const response = await fetchImpl(`${basePath}/search`, {
+        body: JSON.stringify(input),
+        headers: jsonHeaders,
+        method: "POST"
+      });
+      if (!response.ok) {
+        throw new Error(await toErrorMessage(response));
+      }
+      const payload = await parseJson(response);
+      if (!payload.ok) {
+        throw new Error(payload.error ?? "RAG search failed");
+      }
+      return payload.results ?? [];
     },
     async searchDetailed(input) {
       const response = await fetchImpl(`${basePath}/search`, {
@@ -1755,6 +1768,114 @@ var buildRAGAnswerGroundingEvaluationLeaderboard = (runs) => {
     totalCases: run.response.totalCases
   }));
 };
+var buildTraceStageCounts = (traces) => {
+  const counts = {};
+  for (const trace of traces) {
+    for (const step of trace.steps) {
+      counts[step.stage] = (counts[step.stage] ?? 0) + 1;
+    }
+  }
+  return counts;
+};
+var roundTraceAverage = (value, total) => total > 0 ? Number((value / total).toFixed(2)) : 0;
+var summarizeRetrievalTraces = (traces) => {
+  if (traces.length === 0) {
+    return;
+  }
+  const totalCases = traces.length;
+  const modeSet = new Set;
+  let vectorCases = 0;
+  let lexicalCases = 0;
+  let transformedCases = 0;
+  let variantCases = 0;
+  let finalCountSum = 0;
+  let vectorCountSum = 0;
+  let lexicalCountSum = 0;
+  let candidateTopKSum = 0;
+  let lexicalTopKSum = 0;
+  for (const trace of traces) {
+    modeSet.add(trace.mode);
+    if (trace.runVector) {
+      vectorCases += 1;
+    }
+    if (trace.runLexical) {
+      lexicalCases += 1;
+    }
+    if (trace.transformedQuery !== trace.query) {
+      transformedCases += 1;
+    }
+    if (trace.variantQueries.length > 0) {
+      variantCases += 1;
+    }
+    finalCountSum += trace.resultCounts.final;
+    vectorCountSum += trace.resultCounts.vector;
+    lexicalCountSum += trace.resultCounts.lexical;
+    candidateTopKSum += trace.candidateTopK;
+    lexicalTopKSum += trace.lexicalTopK;
+  }
+  return {
+    averageCandidateTopK: roundTraceAverage(candidateTopKSum, totalCases),
+    averageFinalCount: roundTraceAverage(finalCountSum, totalCases),
+    averageLexicalCount: roundTraceAverage(lexicalCountSum, totalCases),
+    averageLexicalTopK: roundTraceAverage(lexicalTopKSum, totalCases),
+    averageVectorCount: roundTraceAverage(vectorCountSum, totalCases),
+    lexicalCases,
+    modes: Array.from(modeSet),
+    stageCounts: buildTraceStageCounts(traces),
+    totalCases,
+    transformedCases,
+    variantCases,
+    vectorCases
+  };
+};
+var evaluateRAGCollectionCases = async ({
+  collection,
+  input,
+  defaultTopK = DEFAULT_TOP_K,
+  rerank,
+  includeTrace = false
+}) => {
+  if (input.dryRun) {
+    return executeDryRunRAGEvaluation(input, defaultTopK).map((caseResult) => ({
+      caseResult,
+      trace: undefined
+    }));
+  }
+  return Promise.all(input.cases.map(async (caseInput, caseIndex) => {
+    const startedAt = Date.now();
+    const mode = resolveEvaluationMode(caseInput);
+    const query = caseInput.query.trim();
+    const expectedIds = normalizeExpectedIds(mode === "chunkId" ? caseInput.expectedChunkIds ?? [] : mode === "source" ? caseInput.expectedSources ?? [] : caseInput.expectedDocumentIds ?? []);
+    const topK = typeof caseInput.topK === "number" ? caseInput.topK : typeof input.topK === "number" ? input.topK : defaultTopK;
+    const searchInput = {
+      filter: typeof caseInput.filter === "object" ? caseInput.filter : input.filter,
+      model: caseInput.model ?? input.model,
+      query,
+      rerank,
+      scoreThreshold: typeof caseInput.scoreThreshold === "number" ? caseInput.scoreThreshold : input.scoreThreshold,
+      topK
+    };
+    const searchOutcome = includeTrace ? await collection.searchWithTrace(searchInput) : {
+      results: await collection.search(searchInput),
+      trace: undefined
+    };
+    const sources = buildSources(searchOutcome.results);
+    const elapsedMs = Date.now() - startedAt;
+    const retrievedIds = normalizeExpectedIds(sources.map((source) => extractExpectedId(source, mode)));
+    return {
+      caseResult: summarizeRAGEvaluationCase({
+        caseIndex,
+        caseInput: { ...caseInput, topK },
+        elapsedMs,
+        expectedIds,
+        mode,
+        query,
+        retrievedIds
+      }),
+      trace: searchOutcome.trace
+    };
+  }));
+};
 var buildRAGAnswerGroundingCaseDifficultyLeaderboard = (entries) => {
   const grouped = new Map;
   for (const entry of entries) {
@@ -2390,17 +2511,20 @@ var compareRAGRerankers = async ({
   defaultTopK = DEFAULT_TOP_K
 }) => {
   const entries = await Promise.all(rerankers.map(async (candidate) => {
-    const response = await evaluateRAGCollection({
+    const evaluated = await evaluateRAGCollectionCases({
       collection,
       defaultTopK,
       input: suite.input,
+      includeTrace: true,
       rerank: candidate.rerank
     });
+    const response = buildRAGEvaluationResponse(evaluated.map((entry) => entry.caseResult));
     return {
       label: candidate.label ?? candidate.id,
       providerName: typeof candidate.rerank === "function" ? undefined : candidate.rerank?.providerName,
       response,
-      rerankerId: candidate.id
+      rerankerId: candidate.id,
+      traceSummary: summarizeRetrievalTraces(evaluated.map((entry) => entry.trace).filter((trace) => Boolean(trace)))
     };
   }));
   const leaderboard = buildRAGEvaluationLeaderboard(entries.map((entry) => ({
@@ -2455,25 +2579,37 @@ var compareRAGRetrievalStrategies = async ({
   defaultTopK = DEFAULT_TOP_K
 }) => {
   const entries = await Promise.all(retrievals.map(async (candidate) => {
-    const response = await evaluateRAGCollection({
+    const tracedCollection = {
+      ...collection,
+      search: (input) => collection.search({
+        ...input,
+        queryTransform: candidate.queryTransform ?? input.queryTransform,
+        rerank: candidate.rerank ?? input.rerank,
+        retrieval: candidate.retrieval ?? input.retrieval
+      }),
+      searchWithTrace: (input) => collection.searchWithTrace({
+        ...input,
+        queryTransform: candidate.queryTransform ?? input.queryTransform,
+        rerank: candidate.rerank ?? input.rerank,
+        retrieval: candidate.retrieval ?? input.retrieval
+      })
+    };
+    const evaluated = await evaluateRAGCollectionCases({
       collection: {
-        ...collection,
-        search: (input) => collection.search({
-          ...input,
-          queryTransform: candidate.queryTransform ?? input.queryTransform,
-          rerank: candidate.rerank ?? input.rerank,
-          retrieval: candidate.retrieval ?? input.retrieval
-        })
+        ...tracedCollection
       },
       defaultTopK,
       input: suite.input,
+      includeTrace: true,
       rerank: candidate.rerank
     });
+    const response = buildRAGEvaluationResponse(evaluated.map((entry) => entry.caseResult));
     return {
       label: candidate.label ?? candidate.id,
       response,
       retrievalId: candidate.id,
-      retrievalMode: resolveRetrievalMode(candidate)
+      retrievalMode: resolveRetrievalMode(candidate),
+      traceSummary: summarizeRetrievalTraces(evaluated.map((entry) => entry.trace).filter((trace) => Boolean(trace)))
     };
   }));
   const leaderboard = buildRAGEvaluationLeaderboard(entries.map((entry) => ({
@@ -2500,37 +2636,14 @@ var evaluateRAGCollection = async ({
   defaultTopK = DEFAULT_TOP_K,
   rerank
 }) => {
-  if (input.dryRun) {
-    return buildRAGEvaluationResponse(executeDryRunRAGEvaluation(input, defaultTopK));
-  }
-  const evaluated = await Promise.all(input.cases.map(async (caseInput, caseIndex) => {
-    const startedAt = Date.now();
-    const mode = resolveEvaluationMode(caseInput);
-    const query = caseInput.query.trim();
-    const expectedIds = normalizeExpectedIds(mode === "chunkId" ? caseInput.expectedChunkIds ?? [] : mode === "source" ? caseInput.expectedSources ?? [] : caseInput.expectedDocumentIds ?? []);
-    const topK = typeof caseInput.topK === "number" ? caseInput.topK : typeof input.topK === "number" ? input.topK : defaultTopK;
-    const searchResults = await collection.search({
-      filter: typeof caseInput.filter === "object" ? caseInput.filter : input.filter,
-      model: caseInput.model ?? input.model,
-      query,
-      rerank,
-      scoreThreshold: typeof caseInput.scoreThreshold === "number" ? caseInput.scoreThreshold : input.scoreThreshold,
-      topK
-    });
-    const sources = buildSources(searchResults);
-    const elapsedMs = Date.now() - startedAt;
-    const retrievedIds = normalizeExpectedIds(sources.map((source) => extractExpectedId(source, mode)));
-    return summarizeRAGEvaluationCase({
-      caseIndex,
-      caseInput: { ...caseInput, topK },
-      elapsedMs,
-      expectedIds,
-      mode,
-      query,
-      retrievedIds
-    });
-  }));
-  return buildRAGEvaluationResponse(evaluated);
+  const evaluated = await evaluateRAGCollectionCases({
+    collection,
+    defaultTopK,
+    includeTrace: false,
+    input,
+    rerank
+  });
+  return buildRAGEvaluationResponse(evaluated.map((entry) => entry.caseResult));
 };
 var executeDryRunRAGEvaluation = (input, defaultTopK = DEFAULT_TOP_K) => input.cases.map((caseInput, caseIndex) => {
   const mode = resolveEvaluationMode(caseInput);
@@ -3289,5 +3402,5 @@ export {
   AIStreamKey
 };
 
-//# debugId=4CD93E092D2A92E664756E2164756E21
+//# debugId=28BD639F9F0C6C1364756E2164756E21
 //# sourceMappingURL=index.js.map