@absolutejs/voice 0.0.22-beta.518 → 0.0.22-beta.519

package/dist/index.js

@@ -3769,7 +3769,8 @@ var setTurnResult = (session, turnId, input) => {
   session.turns = session.turns.map((turn) => turn.id === turnId ? {
     ...turn,
     assistantText: input.assistantText ?? turn.assistantText,
-    result: input.result ?? turn.result
+    result: input.result ?? turn.result,
+    citations: input.citations && input.citations.length > 0 ? [...input.citations] : turn.citations
   } : turn);
 };
 var ensureCallLifecycleState = (session) => {
@@ -5157,6 +5158,7 @@ var createVoiceSession = (options) => {
     });
     const output = {
       assistantText: committedOutput?.assistantText,
+      citations: committedOutput?.citations,
       complete: committedOutput?.complete,
       escalate: committedOutput?.escalate,
       noAnswer: committedOutput?.noAnswer,
@@ -5164,6 +5166,12 @@ var createVoiceSession = (options) => {
       transfer: committedOutput?.transfer,
       voicemail: committedOutput?.voicemail
     };
+    if (output.citations && output.citations.length > 0) {
+      const turnCitations = output.citations;
+      await writeSession((currentSession) => {
+        setTurnResult(currentSession, turn.id, { citations: turnCitations });
+      });
+    }
     if (output?.assistantText) {
       const assistantTextStartedAt = Date.now();
       await writeSession((currentSession) => {
@@ -8733,6 +8741,159 @@ var assertVoiceCampaignDialerProofEvidence = (report, input = {}) => {
   }
   return assertion;
 };
+// src/ragTool.ts
+var extractVoiceRAGCitations = (toolResults, toolName = "searchKnowledgeBase") => {
+  const out = [];
+  for (const entry of toolResults) {
+    if (entry.toolName !== toolName) {
+      continue;
+    }
+    const result = entry.result;
+    const citations = result?.citations;
+    if (!Array.isArray(citations)) {
+      continue;
+    }
+    for (const citation of citations) {
+      out.push({
+        chunkId: citation.chunkId,
+        score: citation.score,
+        source: citation.source,
+        title: citation.title
+      });
+    }
+  }
+  return out;
+};
+var DEFAULT_TOOL_NAME = "searchKnowledgeBase";
+var DEFAULT_DESCRIPTION = "Search the knowledge base and return short grounded citations. Use this whenever the caller asks a question that may be answered by indexed reference material.";
+var DEFAULT_TOP_K = 6;
+var DEFAULT_MAX_TOP_K = 20;
+var DEFAULT_MAX_CHUNK_CHARS = 320;
+var truncate = (value, limit) => {
+  if (limit <= 0 || value.length <= limit)
+    return value;
+  return `${value.slice(0, Math.max(0, limit - 1)).trimEnd()}\u2026`;
+};
+var formatScore = (score) => {
+  if (!Number.isFinite(score))
+    return "n/a";
+  return score.toFixed(3);
+};
+var buildDefaultCitationMessage = (citations, args, maxChunkChars) => {
+  if (citations.length === 0) {
+    return `No knowledge base results for "${args.query}".`;
+  }
+  const lines = citations.map((citation, index) => {
+    const label = citation.title ?? citation.source ?? citation.chunkId;
+    const text = truncate(citation.chunkText, maxChunkChars);
+    return `${String(index + 1)}. ${label} (score ${formatScore(citation.score)}): ${text}`;
+  });
+  return [
+    `Knowledge base results for "${args.query}":`,
+    ...lines
+  ].join(`
+`);
+};
+var filterAllowedFilterKeys = (filter, allowedKeys) => {
+  if (!filter)
+    return;
+  if (!allowedKeys)
+    return filter;
+  const allowed = new Set(allowedKeys);
+  const entries = Object.entries(filter).filter(([key]) => allowed.has(key));
+  if (entries.length === 0)
+    return;
+  return Object.fromEntries(entries);
+};
+var mergeFilters = (...filters) => {
+  const present = filters.filter((entry) => entry !== undefined);
+  if (present.length === 0)
+    return;
+  return Object.assign({}, ...present);
+};
+var buildVoiceRAGToolParameters = (options) => {
+  if (options.parameters)
+    return options.parameters;
+  const defaultTopK = options.topK ?? DEFAULT_TOP_K;
+  const maxTopK = options.maxTopK ?? DEFAULT_MAX_TOP_K;
+  const properties = {
+    query: {
+      description: "Natural-language question to look up in the knowledge base.",
+      type: "string"
+    },
+    topK: {
+      default: defaultTopK,
+      description: `How many citations to return (1-${String(maxTopK)}).`,
+      maximum: maxTopK,
+      minimum: 1,
+      type: "integer"
+    }
+  };
+  if (options.allowedFilterKeys && options.allowedFilterKeys.length > 0) {
+    properties.filter = {
+      additionalProperties: false,
+      description: "Optional metadata filter. Only keys listed here are honored: " + options.allowedFilterKeys.join(", "),
+      properties: Object.fromEntries(options.allowedFilterKeys.map((key) => [key, {}])),
+      type: "object"
+    };
+  }
+  return {
+    additionalProperties: false,
+    properties,
+    required: ["query"],
+    type: "object"
+  };
+};
+var createVoiceRAGTool = (collection, options = {}) => {
+  const name = options.name ?? DEFAULT_TOOL_NAME;
+  const description = options.description ?? DEFAULT_DESCRIPTION;
+  const defaultTopK = options.topK ?? DEFAULT_TOP_K;
+  const maxTopK = options.maxTopK ?? DEFAULT_MAX_TOP_K;
+  const maxChunkChars = options.maxChunkChars ?? DEFAULT_MAX_CHUNK_CHARS;
+  const parameters = buildVoiceRAGToolParameters(options);
+  return createVoiceAgentTool({
+    description,
+    execute: async ({ args, context }) => {
+      const query = typeof args?.query === "string" ? args.query.trim() : "";
+      if (query.length === 0) {
+        const empty = {
+          citations: [],
+          message: "Knowledge base search requires a non-empty query.",
+          query: "",
+          topK: 0
+        };
+        return empty;
+      }
+      const requestedTopK = typeof args?.topK === "number" && Number.isFinite(args.topK) ? Math.min(maxTopK, Math.max(1, Math.floor(args.topK))) : defaultTopK;
+      const llmFilter = filterAllowedFilterKeys(args?.filter, options.allowedFilterKeys);
+      const fixedFilter = typeof options.fixedFilter === "function" ? options.fixedFilter({ context }) : options.fixedFilter;
+      const filter = mergeFilters(fixedFilter, llmFilter);
+      const rawResults = await collection.search({
+        filter,
+        query,
+        scoreThreshold: options.scoreThreshold,
+        topK: requestedTopK
+      });
+      const citations = Array.from(rawResults).slice(0, requestedTopK);
+      const formatter = options.formatResult ? options.formatResult : (entries, innerArgs) => buildDefaultCitationMessage(entries, innerArgs, maxChunkChars);
+      const message = formatter(citations, {
+        filter,
+        query,
+        topK: requestedTopK
+      });
+      return {
+        citations,
+        message,
+        query,
+        topK: requestedTopK
+      };
+    },
+    name,
+    parameters,
+    resultToMessage: options.resultToMessage ?? ((result) => result.message)
+  });
+};
+
 // src/agent.ts
 var normalizeText3 = (value) => typeof value === "string" ? value.trim() : "";
 var toErrorMessage3 = (error) => error instanceof Error ? error.message : String(error);
@@ -9106,9 +9267,11 @@ var createVoiceAgent = (options) => {
       turn: input.turn,
       type: "agent.result"
     });
+    const citations = extractVoiceRAGCitations(toolResults);
     return {
       agentId: options.id,
       assistantText: output.assistantText,
+      ...citations.length > 0 ? { citations } : {},
       complete: output.complete,
       escalate: output.escalate,
       handoff: output.handoff,
@@ -36341,158 +36504,6 @@ var createMonologueAMDDetector = (options = {}) => {
     intervalMs: options.intervalMs ?? 1000
   };
 };
-// src/ragTool.ts
-var extractVoiceRAGCitations = (toolResults, toolName = "searchKnowledgeBase") => {
-  const out = [];
-  for (const entry of toolResults) {
-    if (entry.toolName !== toolName) {
-      continue;
-    }
-    const result = entry.result;
-    const citations = result?.citations;
-    if (!Array.isArray(citations)) {
-      continue;
-    }
-    for (const citation of citations) {
-      out.push({
-        chunkId: citation.chunkId,
-        score: citation.score,
-        source: citation.source,
-        title: citation.title
-      });
-    }
-  }
-  return out;
-};
-var DEFAULT_TOOL_NAME = "searchKnowledgeBase";
-var DEFAULT_DESCRIPTION = "Search the knowledge base and return short grounded citations. Use this whenever the caller asks a question that may be answered by indexed reference material.";
-var DEFAULT_TOP_K = 6;
-var DEFAULT_MAX_TOP_K = 20;
-var DEFAULT_MAX_CHUNK_CHARS = 320;
-var truncate = (value, limit) => {
-  if (limit <= 0 || value.length <= limit)
-    return value;
-  return `${value.slice(0, Math.max(0, limit - 1)).trimEnd()}\u2026`;
-};
-var formatScore = (score) => {
-  if (!Number.isFinite(score))
-    return "n/a";
-  return score.toFixed(3);
-};
-var buildDefaultCitationMessage = (citations, args, maxChunkChars) => {
-  if (citations.length === 0) {
-    return `No knowledge base results for "${args.query}".`;
-  }
-  const lines = citations.map((citation, index) => {
-    const label = citation.title ?? citation.source ?? citation.chunkId;
-    const text = truncate(citation.chunkText, maxChunkChars);
-    return `${String(index + 1)}. ${label} (score ${formatScore(citation.score)}): ${text}`;
-  });
-  return [
-    `Knowledge base results for "${args.query}":`,
-    ...lines
-  ].join(`
-`);
-};
-var filterAllowedFilterKeys = (filter, allowedKeys) => {
-  if (!filter)
-    return;
-  if (!allowedKeys)
-    return filter;
-  const allowed = new Set(allowedKeys);
-  const entries = Object.entries(filter).filter(([key]) => allowed.has(key));
-  if (entries.length === 0)
-    return;
-  return Object.fromEntries(entries);
-};
-var mergeFilters = (...filters) => {
-  const present = filters.filter((entry) => entry !== undefined);
-  if (present.length === 0)
-    return;
-  return Object.assign({}, ...present);
-};
-var buildVoiceRAGToolParameters = (options) => {
-  if (options.parameters)
-    return options.parameters;
-  const defaultTopK = options.topK ?? DEFAULT_TOP_K;
-  const maxTopK = options.maxTopK ?? DEFAULT_MAX_TOP_K;
-  const properties = {
-    query: {
-      description: "Natural-language question to look up in the knowledge base.",
-      type: "string"
-    },
-    topK: {
-      default: defaultTopK,
-      description: `How many citations to return (1-${String(maxTopK)}).`,
-      maximum: maxTopK,
-      minimum: 1,
-      type: "integer"
-    }
-  };
-  if (options.allowedFilterKeys && options.allowedFilterKeys.length > 0) {
-    properties.filter = {
-      additionalProperties: false,
-      description: "Optional metadata filter. Only keys listed here are honored: " + options.allowedFilterKeys.join(", "),
-      properties: Object.fromEntries(options.allowedFilterKeys.map((key) => [key, {}])),
-      type: "object"
-    };
-  }
-  return {
-    additionalProperties: false,
-    properties,
-    required: ["query"],
-    type: "object"
-  };
-};
-var createVoiceRAGTool = (collection, options = {}) => {
-  const name = options.name ?? DEFAULT_TOOL_NAME;
-  const description = options.description ?? DEFAULT_DESCRIPTION;
-  const defaultTopK = options.topK ?? DEFAULT_TOP_K;
-  const maxTopK = options.maxTopK ?? DEFAULT_MAX_TOP_K;
-  const maxChunkChars = options.maxChunkChars ?? DEFAULT_MAX_CHUNK_CHARS;
-  const parameters = buildVoiceRAGToolParameters(options);
-  return createVoiceAgentTool({
-    description,
-    execute: async ({ args, context }) => {
-      const query = typeof args?.query === "string" ? args.query.trim() : "";
-      if (query.length === 0) {
-        const empty = {
-          citations: [],
-          message: "Knowledge base search requires a non-empty query.",
-          query: "",
-          topK: 0
-        };
-        return empty;
-      }
-      const requestedTopK = typeof args?.topK === "number" && Number.isFinite(args.topK) ? Math.min(maxTopK, Math.max(1, Math.floor(args.topK))) : defaultTopK;
-      const llmFilter = filterAllowedFilterKeys(args?.filter, options.allowedFilterKeys);
-      const fixedFilter = typeof options.fixedFilter === "function" ? options.fixedFilter({ context }) : options.fixedFilter;
-      const filter = mergeFilters(fixedFilter, llmFilter);
-      const rawResults = await collection.search({
-        filter,
-        query,
-        scoreThreshold: options.scoreThreshold,
-        topK: requestedTopK
-      });
-      const citations = Array.from(rawResults).slice(0, requestedTopK);
-      const formatter = options.formatResult ? options.formatResult : (entries, innerArgs) => buildDefaultCitationMessage(entries, innerArgs, maxChunkChars);
-      const message = formatter(citations, {
-        filter,
-        query,
-        topK: requestedTopK
-      });
-      return {
-        citations,
-        message,
-        query,
-        topK: requestedTopK
-      };
-    },
-    name,
-    parameters,
-    resultToMessage: options.resultToMessage ?? ((result) => result.message)
-  });
-};
 // src/agentTools.ts
 var createVoiceEndCallTool = (options = {}) => createVoiceAgentTool({
   description: options.description ?? "End the call gracefully. Call this only when the conversation is complete or the caller asks to hang up.",

package/dist/ragTool.d.ts

@@ -1,5 +1,5 @@
 import { type VoiceAgentTool } from "./agent";
-import type { VoiceSessionRecord } from "./types";
+import type { VoiceSessionRecord, VoiceTurnCitation } from "./types";
 export type VoiceRAGQueryResult = {
     chunkId: string;
     chunkText: string;
@@ -29,12 +29,7 @@ export type VoiceRAGToolResult = {
     query: string;
     topK: number;
 };
-export type VoiceRAGCitationSummary = {
-    chunkId: string;
-    score: number;
-    source?: string;
-    title?: string;
-};
+export type VoiceRAGCitationSummary = VoiceTurnCitation;
 export declare const extractVoiceRAGCitations: (toolResults: ReadonlyArray<{
     result?: unknown;
     toolName: string;

package/dist/testing/index.js

@@ -5628,7 +5628,8 @@ var setTurnResult = (session, turnId, input) => {
   session.turns = session.turns.map((turn) => turn.id === turnId ? {
     ...turn,
     assistantText: input.assistantText ?? turn.assistantText,
-    result: input.result ?? turn.result
+    result: input.result ?? turn.result,
+    citations: input.citations && input.citations.length > 0 ? [...input.citations] : turn.citations
   } : turn);
 };
 var ensureCallLifecycleState = (session) => {
@@ -7016,6 +7017,7 @@ var createVoiceSession = (options) => {
     });
     const output = {
       assistantText: committedOutput?.assistantText,
+      citations: committedOutput?.citations,
       complete: committedOutput?.complete,
       escalate: committedOutput?.escalate,
       noAnswer: committedOutput?.noAnswer,
@@ -7023,6 +7025,12 @@ var createVoiceSession = (options) => {
       transfer: committedOutput?.transfer,
       voicemail: committedOutput?.voicemail
     };
+    if (output.citations && output.citations.length > 0) {
+      const turnCitations = output.citations;
+      await writeSession((currentSession) => {
+        setTurnResult(currentSession, turn.id, { citations: turnCitations });
+      });
+    }
     if (output?.assistantText) {
       const assistantTextStartedAt = Date.now();
       await writeSession((currentSession) => {

package/dist/types.d.ts

@@ -247,6 +247,12 @@ export type VoiceReconnectClientState = {
     nextAttemptAt?: number;
     status: VoiceReconnectClientStatus;
 };
+export type VoiceTurnCitation = {
+    chunkId: string;
+    score: number;
+    source?: string;
+    title?: string;
+};
 export type VoiceTurnRecord<TResult = unknown> = {
     id: string;
     text: string;
@@ -254,6 +260,7 @@ export type VoiceTurnRecord<TResult = unknown> = {
     transcripts: Transcript[];
     assistantText?: string;
     attachments?: import("./agent").VoiceAgentMessageAttachment[];
+    citations?: VoiceTurnCitation[];
     committedAt: number;
     result?: TResult;
 };
@@ -502,6 +509,7 @@ export type VoiceRouteResult<TResult = unknown> = {
     complete?: boolean;
     result?: TResult;
     assistantText?: string;
+    citations?: ReadonlyArray<VoiceTurnCitation>;
     transfer?: {
         metadata?: Record<string, unknown>;
         reason?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@absolutejs/voice",
-  "version": "0.0.22-beta.518",
+  "version": "0.0.22-beta.519",
   "description": "Voice primitives and Elysia plugin for AbsoluteJS",
   "repository": {
     "type": "git",