@absolutejs/voice 0.0.22-beta.468 → 0.0.22-beta.469

package/README.md

@@ -6,6 +6,61 @@ It gives your app the primitives hosted voice platforms usually keep behind thei
 
 Use it when you want Vapi/Retell/Bland-style voice-agent capability, but you want the orchestration, data, traces, storage, and UI to live inside the AbsoluteJS server you already operate.
 
+## What's new
+
+### 0.0.22-beta.469 · Vapi parity — RAG-as-a-tool helper
+
+`createVoiceRAGTool(collection, options?)` wraps any `@absolutejs/rag` `RAGCollection` (or any object that satisfies `VoiceRAGCollectionLike`) into a `VoiceAgentTool` shaped like Vapi's built-in `query` / `knowledgeBaseId` flow.
+
+```ts
+import { createInMemoryRAGStore, createRAGCollection } from "@absolutejs/rag";
+import { createVoiceAssistant, createVoiceRAGTool } from "@absolutejs/voice";
+
+const collection = createRAGCollection(
+  createInMemoryRAGStore(),
+  { embedding: openaiEmbeddings("text-embedding-3-small") },
+);
+
+const knowledgeBase = createVoiceRAGTool(collection, {
+  allowedFilterKeys: ["productLine"],
+  fixedFilter: ({ context }) => ({ tenantId: context.tenantId }),
+  maxChunkChars: 320,
+  scoreThreshold: 0.65,
+});
+
+const assistant = createVoiceAssistant({
+  id: "support",
+  model: openaiVoiceAssistantModel,
+  tools: [knowledgeBase],
+  system: "You are a support agent. Always cite the knowledge base.",
+});
+```
+
+Highlights:
+- Default tool name `searchKnowledgeBase` matches the conventional Vapi knowledge-base tool name.
+- Generated JSON-schema parameters expose `query` (required), `topK` (clamped to `maxTopK`), and an optional `filter` object whose keys are gated by `allowedFilterKeys`.
+- `fixedFilter` can be a static record or a `(context) => filter` function (use for tenant scoping, locale, etc.). Fixed values always win over LLM-supplied filters.
+- Default formatter returns numbered citations (`1. <title> (score 0.910): <chunk>`); override via `formatResult` or `resultToMessage`.
+- No hard dependency on `@absolutejs/rag` — `VoiceRAGCollectionLike` is structurally compatible with `RAGCollection`, so install rag (or any duck-typed retrieval backend) as a peer.
+
+### 0.0.22-beta.464 → 468 · Media pipeline issue codes across product surfaces
+
+`@absolutejs/voice` now projects compact `@absolutejs/media` reports into every buyer-facing voice surface so media health is gateable, linkable, and visible without buying a hosted dashboard.
+
+**Proof pack (beta.464–465)** — `summarizeVoiceMediaPipelineReport(report, { artifacts })` returns a compact `VoiceMediaPipelineProofSummary` with aggregated `issueCodes` and per-section status. `writeVoiceMediaPipelineArtifacts({ dir, report, hrefBase })` persists `media-quality.{json,md}`, `media-transport.{json,md}`, and `media-processor-graph.{json,md}` into a proof-pack run directory and returns href links to wire into the summary. Together these shrink the `mediaPipelineCalibrationAssertion` summary in voice proof packs from ~35 KB to ~1.7 KB (95% reduction) and trim the total proof JSON from ~170 KB to ~114 KB.
+
+**Production readiness (beta.464)** — `buildVoiceMediaPipelineReadinessChecks(report, { baseHref, label })` returns drop-in `VoiceProductionReadinessCheck[]` entries (overall, media quality, transport, processor graph, interruption). Spread them into `additionalChecks` for granular gating alongside the existing aggregate "Media pipeline quality" check.
+
+**Operations record (beta.466–467)** — `VoiceOperationsRecord.mediaPipeline` is a new optional `VoiceOperationsRecordMediaPipelineSummary` (status, qualityStatus, transportStatus, processorGraphStatus, issueCodes, jitterMs, frames, surface). Populate it by passing `mediaPipeline: VoiceMediaPipelineReport` to `buildVoiceOperationsRecord`, or pass `mediaPipeline` (a report or sessionId-keyed resolver) to `createVoiceOperationsRecordRoutes` so every `/api/voice-operations/:sessionId` response carries it automatically.
+
+**Failure replay (beta.466)** — `buildVoiceFailureReplay` reads `record.mediaPipeline` and adds `media.pipelineIssueCodes` + `media.pipelineStatus` to the report, appends `"Media pipeline issue: <code>"` entries to `summary.issues`, and demotes failure-replay status to `failed`/`degraded` when the pipeline is `fail`/`warn`. The Markdown incident artifact gets a new "Media Pipeline" section.
+
+**Incident timeline (beta.466)** — `VoiceIncidentTimelineOptions.extraEvents` accepts any custom event source. Feed `buildVoiceMediaPipelineIncidentEvents(report, { now, source, category })` into it to surface media-pipeline issues as `category: "monitor"` entries in `/api/voice/incident-timeline` alongside operational and failure-replay events.
+
+**Ops record renderers (beta.468)** — `renderVoiceOperationsRecordIncidentMarkdown` adds a one-line `Media pipeline` summary and an issue-code section. `renderVoiceOperationsRecordHTML` adds a nav anchor, a summary-grid card, and a `#media-pipeline` section listing surface, per-section status, frame/jitter, and codes.
+
+Requires `@absolutejs/media@0.0.1-beta.16+`. The voice bundle externalizes `@absolutejs/media` to keep browser bundles parseable; install media as a peer dependency.
+
 ## Why AbsoluteJS Voice
 
 - Self-hosted by default: your app owns sessions, traces, reviews, tasks, handoffs, retention, and provider keys.

package/dist/index.d.ts

@@ -69,6 +69,8 @@ export { assertVoiceSimulationSuiteEvidence, createVoiceSimulationSuiteRoutes, e
 export { createVoiceWorkflowContract, createVoiceWorkflowContractHandler, createVoiceWorkflowContractPreset, createVoiceWorkflowScenario, recordVoiceWorkflowContractTrace, validateVoiceWorkflowRouteResult, } from "./workflowContract";
 export { createVoiceSessionListRoutes, createVoiceSessionReplayHTMLHandler, createVoiceSessionReplayJSONHandler, createVoiceSessionReplayRoutes, createVoiceSessionsHTMLHandler, createVoiceSessionsJSONHandler, renderVoiceSessionsHTML, summarizeVoiceProviderFallbackRecovery, summarizeVoiceSessions, summarizeVoiceSessionReplay, } from "./sessionReplay";
 export { createVoiceAgent, createVoiceAgentSquad, createVoiceAgentTool, } from "./agent";
+export { createVoiceRAGTool } from "./ragTool";
+export type { VoiceRAGCollectionLike, VoiceRAGQueryResult, VoiceRAGSearchInput, VoiceRAGToolArgs, VoiceRAGToolOptions, VoiceRAGToolResult, } from "./ragTool";
 export { assertVoiceAgentSquadContractEvidence, assertVoiceAgentSquadContract, evaluateVoiceAgentSquadContractEvidence, runVoiceAgentSquadContract, } from "./agentSquadContract";
 export { createVoiceToolIdempotencyKey, createVoiceToolRuntime, } from "./toolRuntime";
 export { assertVoiceToolContractEvidence, createVoiceToolContract, createVoiceToolContractHTMLHandler, createVoiceToolContractJSONHandler, createVoiceToolContractRoutes, createVoiceToolRuntimeContractDefaults, evaluateVoiceToolContractEvidence, renderVoiceToolContractHTML, runVoiceToolContractSuite, runVoiceToolContract, } from "./toolContract";

package/dist/index.js

@@ -34499,6 +34499,136 @@ var createVoiceWorkflowContractHandler = (input) => {
     return result;
   };
 };
+// src/ragTool.ts
+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/agentSquadContract.ts
 var normalizeIncludes = (value) => value.trim().toLowerCase();
 var resolveOutcome4 = (result) => {
@@ -43156,6 +43286,7 @@ export {
   createVoiceRealCallEvidenceRuntimeRoutes,
   createVoiceRealCallEvidenceRuntime,
   createVoiceReadinessProfile,
+  createVoiceRAGTool,
   createVoiceQualityRoutes,
   createVoiceProviderSloRoutes,
   createVoiceProviderRouter,

package/dist/ragTool.d.ts

@@ -0,0 +1,47 @@
+import { type VoiceAgentTool } from "./agent";
+import type { VoiceSessionRecord } from "./types";
+export type VoiceRAGQueryResult = {
+    chunkId: string;
+    chunkText: string;
+    score: number;
+    source?: string;
+    title?: string;
+    metadata?: Record<string, unknown>;
+};
+export type VoiceRAGSearchInput = {
+    filter?: Record<string, unknown>;
+    query: string;
+    scoreThreshold?: number;
+    signal?: AbortSignal;
+    topK?: number;
+};
+export type VoiceRAGCollectionLike = {
+    search: (input: VoiceRAGSearchInput) => Promise<readonly VoiceRAGQueryResult[]> | readonly VoiceRAGQueryResult[];
+};
+export type VoiceRAGToolArgs = {
+    filter?: Record<string, unknown>;
+    query: string;
+    topK?: number;
+};
+export type VoiceRAGToolResult = {
+    citations: VoiceRAGQueryResult[];
+    message: string;
+    query: string;
+    topK: number;
+};
+export type VoiceRAGToolOptions<TContext = unknown> = {
+    allowedFilterKeys?: readonly string[];
+    description?: string;
+    fixedFilter?: Record<string, unknown> | ((input: {
+        context: TContext;
+    }) => Record<string, unknown> | undefined);
+    formatResult?: (citations: readonly VoiceRAGQueryResult[], args: VoiceRAGToolArgs) => string;
+    maxChunkChars?: number;
+    maxTopK?: number;
+    name?: string;
+    parameters?: Record<string, unknown>;
+    resultToMessage?: (result: VoiceRAGToolResult) => string;
+    scoreThreshold?: number;
+    topK?: number;
+};
+export declare const createVoiceRAGTool: <TContext = unknown, TSession extends VoiceSessionRecord = VoiceSessionRecord>(collection: VoiceRAGCollectionLike, options?: VoiceRAGToolOptions<TContext>) => VoiceAgentTool<TContext, TSession, VoiceRAGToolArgs, VoiceRAGToolResult>;

package/package.json

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