@guava-ai/guava-sdk 0.23.0 → 0.24.0

package/src/call.ts

@@ -9,6 +9,7 @@ import {
   TransferCommand,
   ReadScriptCommand,
   RetryTaskCommand,
+  SetAgentDTMFCommand,
 } from "./commands.ts";
 import type * as z from "zod";
 import type {
@@ -20,6 +21,7 @@ import type {
 } from "./action-item.ts";
 import { Say } from "./action-item.ts";
 import { telemetryClient } from "./telemetry.ts";
+import type { CallInfo } from "./socket/call-info.ts";
 
 export type TaskObjective =
   | { objective: string }
@@ -33,6 +35,8 @@ export type ReachPersonOutcome = {
 
 @telemetryClient.trackClass()
 export class Call {
+  private _callId: string;
+  private _callInfo: CallInfo;
   protected _commandQueue: Command[] = [];
   private _variables: Record<string, any> = {};
   protected logger: Logger;
@@ -42,8 +46,17 @@ export class Call {
   // input (mutating it) (i.e. _drain should use Array.splice)
   private _drain?: (_: Command[]) => Promise<void>;
   _fieldValues: Record<string, unknown> = {};
+  _fieldKeysByTaskId: Record<string, string[]> = {};
+
+  constructor(
+    callId: string,
+    callInfo: CallInfo,
+    variables: Record<string, any> = {},
+    logger: Logger = getDefaultLogger(),
+  ) {
+    this._callId = callId;
+    this._callInfo = callInfo;
 
-  constructor(variables: Record<string, any> = {}, logger: Logger = getDefaultLogger()) {
     // Set initial variables.
     this._variables = { ...variables };
 
@@ -51,6 +64,14 @@ export class Call {
     this.logger = logger;
   }
 
+  get id(): string {
+    return this._callId;
+  }
+
+  get callInfo(): CallInfo {
+    return this._callInfo;
+  }
+
   /**
    * @description Supply a function used to consume commands from the internal command queue.
    *
@@ -75,6 +96,10 @@ export class Call {
     }
   }
 
+  hasField(key: string): boolean {
+    return key in this._fieldValues;
+  }
+
   async sendCommand<C extends Command, Schema extends z.ZodType<C>>(
     schema: Schema,
     data: z.input<Schema>,
@@ -84,6 +109,13 @@ export class Call {
     await this.flush();
   }
 
+  async setAgentDtmf(enabled: boolean) {
+    await this.sendCommand(SetAgentDTMFCommand, {
+      command_type: "set-agent-dtmf",
+      enabled,
+    });
+  }
+
   async setLanguageMode(args: { primary?: Language; secondary?: Language[] }) {
     await this.sendCommand(SetLanguageModeCommand, {
       command_type: "set-language-mode",
@@ -128,6 +160,7 @@ export class Call {
       throw new Error("At least one of ['objective', 'checklist'] must be provided.");
     }
 
+    const fieldKeys: string[] = [];
     const action_items = checklist.map((item): ActionItem => {
       if (typeof item === "string") {
         return { item_type: "todo", description: item } satisfies TodoItem;
@@ -138,12 +171,15 @@ export class Call {
             "choiceGenerator is not compatible with the Agent / Call API. Use searchable=true and register a handler.",
           );
         }
+        fieldKeys.push(item.key);
         const { choiceGenerator: _, ...fieldData } = item;
         return { ...fieldData, is_search_field: item.searchable } satisfies SerializableFieldItem;
       }
       return item;
     });
 
+    this._fieldKeysByTaskId[taskId] = fieldKeys;
+
     await this.sendCommand(SetTaskCommand, {
       command_type: "set-task",
       task_id: taskId,

package/src/commands.ts

@@ -94,14 +94,21 @@ export const RegisteredHooksCommand = z.strictObject({
   has_on_question: z.boolean(),
   has_on_intent: z.boolean(),
   has_on_action_requested: z.boolean().optional().default(false),
+  has_on_escalate: z.boolean().optional().default(false),
+  accept_dtmf_for_numbers: z.boolean().default(true),
 });
 export type RegisteredHooksCommand = z.input<typeof RegisteredHooksCommand>;
 
+export const ActionCandidate = z.strictObject({
+  key: z.string(),
+  description: z.string().default(""),
+});
+export type ActionCandidate = z.input<typeof ActionCandidate>;
+
 export const ActionSuggestionCommand = z.strictObject({
   command_type: z.literal("action-suggestion"),
   intent_id: z.string(),
-  action_key: z.string().nullable(),
-  action_description: z.string().default(""),
+  actions: z.array(ActionCandidate),
 });
 export type ActionSuggestionCommand = z.input<typeof ActionSuggestionCommand>;
 
@@ -120,6 +127,12 @@ export const RetryTaskCommand = z.strictObject({
 });
 export type RetryTaskCommand = z.input<typeof RetryTaskCommand>;
 
+export const SetAgentDTMFCommand = z.strictObject({
+  command_type: z.literal("set-agent-dtmf"),
+  enabled: z.boolean(),
+});
+export type SetAgentDTMFCommand = z.input<typeof SetAgentDTMFCommand>;
+
 export const AnyCommand = z.union([
   StartOutboundCallCommand,
   ListenInboundCommand,
@@ -136,6 +149,7 @@ export const AnyCommand = z.union([
   ChoiceResultCommand,
   ActionSuggestionCommand,
   RetryTaskCommand,
+  SetAgentDTMFCommand,
 ]);
 export type Command = z.input<typeof AnyCommand>;
 

package/src/events.ts

@@ -14,12 +14,14 @@ export const InboundCallEvent = z.object({
 export type InboundCallEvent = z.infer<typeof InboundCallEvent>;
 
 /**
- * @description The caller has said something.
+ * @description The caller has said something. For utterances with the same id,
+ * all but the latest is out of date.
  */
 export const CallerSpeechEvent = z.object({
   event_type: z.literal("caller-speech"),
 
   utterance: z.string(),
+  utterance_id: z.string().optional(),
 });
 export type CallerSpeechEvent = z.infer<typeof CallerSpeechEvent>;
 
@@ -145,9 +147,16 @@ export type DTMFDigit =
 export const DTMFPressedEvent = z.object({
   event_type: z.literal("dtmf"),
   digit: z.enum(["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "*", "#", "A", "B", "C", "D"]),
+  recent_digits: z.string().default(""),
 });
 export type DTMFPressedEvent = z.infer<typeof DTMFPressedEvent>;
 
+export const EscalateEvent = z.object({
+  event_type: z.literal("escalate"),
+  requested_by: z.enum(["human", "agent"]).default("human"),
+});
+export type EscalateEvent = z.infer<typeof EscalateEvent>;
+
 export const GuavaEvent = z.discriminatedUnion("event_type", [
   SessionStartedEvent,
   InboundCallEvent,
@@ -165,6 +174,7 @@ export const GuavaEvent = z.discriminatedUnion("event_type", [
   ChoiceQueryEvent,
   ActionRequestEvent,
   ExecuteActionEvent,
+  EscalateEvent,
   DTMFPressedEvent,
 ]);
 export type GuavaEvent = z.infer<typeof GuavaEvent>;

package/src/health.ts

@@ -0,0 +1,120 @@
+import { type Server, createServer } from "node:http";
+import { getDefaultLogger, type Logger } from "./logging.ts";
+
+export type HealthState = "starting" | "live" | "stopped";
+
+export class HealthContext {
+  private _state: HealthState = "starting";
+
+  setState(newState: HealthState): void {
+    this._state = newState;
+  }
+
+  ready(): void {
+    this.setState("live");
+  }
+
+  stopped(): void {
+    this.setState("stopped");
+  }
+
+  isLive(): boolean {
+    return this._state === "live";
+  }
+}
+
+export class MultiHealthContext {
+  private _ctxs: HealthContext[] = [];
+
+  createCtx(): HealthContext {
+    const ctx = new HealthContext();
+    this._ctxs.push(ctx);
+    return ctx;
+  }
+
+  isLive(): boolean {
+    return this._ctxs.length > 0 && this._ctxs.every((ctx) => ctx.isLive());
+  }
+}
+
+export interface HealthServerOptions {
+  host?: string;
+  port?: number;
+  logger?: Logger;
+}
+
+export class HealthServer implements AsyncDisposable {
+  private readonly _server: Server;
+  private readonly _logger: Logger;
+  private _stopping: Promise<void> | null = null;
+
+  private constructor(server: Server, logger: Logger) {
+    this._server = server;
+    this._logger = logger;
+  }
+
+  static async start(
+    healthCtx: HealthContext | MultiHealthContext,
+    options: HealthServerOptions = {},
+  ): Promise<HealthServer> {
+    const host = options.host ?? "0.0.0.0";
+    const port = options.port ?? 4828;
+    const logger = options.logger ?? getDefaultLogger();
+
+    const server = createServer((req, res) => {
+      if (req.method === "GET" && req.url === "/live") {
+        res.statusCode = healthCtx.isLive() ? 200 : 503;
+      } else {
+        res.statusCode = 404;
+      }
+      res.end();
+    });
+
+    await new Promise<void>((resolve, reject) => {
+      server.once("error", reject);
+      server.listen(port, host, () => {
+        server.off("error", reject);
+        resolve();
+      });
+    });
+
+    logger.info("Health check server listening on http://%s:%d/live", host, port);
+    return new HealthServer(server, logger);
+  }
+
+  stop(): Promise<void> {
+    if (this._stopping) return this._stopping;
+    this._logger.info("Health check server shutting down.");
+    this._stopping = new Promise<void>((resolve, reject) => {
+      this._server.closeAllConnections();
+      this._server.close((err) => (err ? reject(err) : resolve()));
+    });
+    return this._stopping;
+  }
+
+  async [Symbol.asyncDispose](): Promise<void> {
+    await this.stop();
+  }
+}
+
+const NOOP_DISPOSABLE: AsyncDisposable = {
+  async [Symbol.asyncDispose]() {},
+};
+
+function isEnabled(): boolean {
+  const value = (process.env.GUAVA_HEALTH_SERVER ?? "false").toLowerCase().trim();
+  return value === "yes" || value === "true" || value === "on";
+}
+
+/**
+ * Returns an AsyncDisposable that, when the GUAVA_HEALTH_SERVER env var is
+ * truthy ("yes", "true", "on"), starts an HTTP health check server exposing
+ * `/live` on port 4828. Otherwise returns a no-op disposable. Intended for use
+ * with `await using`.
+ */
+export async function getHealthServer(
+  healthCtx: HealthContext | MultiHealthContext,
+): Promise<AsyncDisposable> {
+  if (!isEnabled()) return NOOP_DISPOSABLE;
+  return HealthServer.start(healthCtx);
+}

package/src/helpers/index.ts

@@ -0,0 +1,2 @@
+/* This file must not include the OpenAI helpers. */
+export { DatetimeFilter, DocumentQA, IntentRecognizer } from "./llm.ts";

package/src/helpers/llm.ts

@@ -1,5 +1,8 @@
-import type { Client } from "../client.ts";
+import type { SuggestedAction } from "../agent.ts";
+import { Client } from "../client.ts";
+import { telemetryClient } from "../telemetry.ts";
 import { fetchOrThrow } from "../utils.ts";
+import { ServerRAG } from "./server-rag.ts";
 
 export async function _generate(
   client: Client,
@@ -14,7 +17,181 @@ export async function _generate(
     method: "POST",
     headers: { ...(await client.headers()), "Content-Type": "application/json" },
     body: JSON.stringify(body),
+    signal: AbortSignal.timeout(60_000),
   });
 
   return ((await response.json()) as { text: string }).text;
 }
+
+@telemetryClient.trackClass()
+export class DocumentQA {
+  private readonly _rag: ServerRAG;
+  private readonly _instructions: string | undefined;
+  private readonly _initialized: Promise<void>;
+
+  constructor({
+    documents,
+    ids,
+    instructions,
+    namespace,
+  }: {
+    documents?: string | string[];
+    ids?: string[];
+    instructions?: string;
+    namespace?: string;
+  } = {}) {
+    this._rag = new ServerRAG(new Client(), { namespace });
+    this._instructions = instructions;
+
+    if (documents !== undefined) {
+      const docs = typeof documents === "string" ? [documents] : documents;
+      this._initialized = this._rag.reconcile(docs, ids);
+    } else {
+      this._initialized = Promise.resolve();
+    }
+  }
+
+  async upsertDocument(key: string, text: string): Promise<void> {
+    await this._initialized;
+    await this._rag.upsertDocument(key, text);
+  }
+
+  async addDocument(text: string): Promise<void> {
+    await this._initialized;
+    await this._rag.addDocument(text);
+  }
+
+  async deleteDocument(key: string): Promise<void> {
+    await this._initialized;
+    await this._rag.removeDocument(key);
+  }
+
+  async clear(): Promise<void> {
+    await this._initialized;
+    await this._rag.clear();
+  }
+
+  async ask(question: string): Promise<string> {
+    await this._initialized;
+    const trackedKeys = this._rag.trackedKeys;
+    return this._rag.ask(question, {
+      documentKeys: trackedKeys.size > 0 ? [...trackedKeys] : undefined,
+      instructions: this._instructions,
+    });
+  }
+}
+
+const _filterSchema = {
+  type: "object",
+  properties: {
+    matching_appointments: { type: "array", items: { type: "string" } },
+    other_appointments: { type: "array", items: { type: "string" } },
+  },
+  required: ["matching_appointments", "other_appointments"],
+  additionalProperties: false,
+};
+
+@telemetryClient.trackClass()
+export class DatetimeFilter {
+  private readonly _client: Client;
+  private readonly _slotsStr: string;
+
+  constructor(sourceList: string[]) {
+    this._client = new Client();
+    this._slotsStr = sourceList.join("\n");
+  }
+
+  async filter(
+    query: string,
+    { maxResults = 5 }: { maxResults?: number } = {},
+  ): Promise<[string[], string[]]> {
+    const today = new Date().toLocaleDateString("en-US", {
+      month: "long",
+      day: "numeric",
+      year: "numeric",
+    });
+
+    const prompt = `Return datetime slots from the list that match the query.
+If none match, return close alternatives in other_appointments instead.
+Never return datetimes that are not in the list.
+
+Query: <query>${query}</query>
+Today's Date: ${today}
+Available slots:
+${this._slotsStr}
+
+Return at most ${maxResults} items per list.`;
+
+    const text = await _generate(this._client, prompt, _filterSchema);
+    const result = JSON.parse(text) as {
+      matching_appointments: string[];
+      other_appointments: string[];
+    };
+    return [
+      result.matching_appointments.slice(0, maxResults),
+      result.other_appointments.slice(0, maxResults),
+    ];
+  }
+}
+
+@telemetryClient.trackClass()
+export class IntentRecognizer {
+  private readonly _client: Client;
+  private readonly _intentChoices: string[] | Record<string, string>;
+  private readonly _schema: object;
+
+  constructor(intentChoices: string[] | Record<string, string>) {
+    this._client = new Client();
+    this._intentChoices = intentChoices;
+    const choiceList = Array.isArray(intentChoices) ? intentChoices : Object.keys(intentChoices);
+    this._schema = {
+      type: "object",
+      title: "ChoiceModel",
+      properties: {
+        possible_matches: {
+          type: "array",
+          items: { type: "string", enum: choiceList },
+          description:
+            "Choices that could match the caller's intent, ordered by likelihood. Include all plausible matches.",
+        },
+      },
+      required: ["possible_matches"],
+      additionalProperties: false,
+    };
+  }
+
+  async classify(intent: string): Promise<SuggestedAction[] | null> {
+    const choiceList = Array.isArray(this._intentChoices)
+      ? this._intentChoices
+      : Object.keys(this._intentChoices);
+
+    let prompt = `Classify the intent below into the most appropriate choice(s) from the list.
+
+Intent: <intent>${intent}</intent>
+Available Choices: ${JSON.stringify(choiceList)}
+
+Rules:
+- Default to returning a single choice — the one that best matches the intent.
+- Only return additional choices when the intent is genuinely ambiguous: a reasonable person reading it would be unable to decide which category it belongs to. Thematic overlap or partial relevance is NOT enough — do not include weakly or tangentially related choices.
+- Order matches by likelihood (most likely first).
+- If no choice plausibly matches, return an empty list.`;
+
+    if (!Array.isArray(this._intentChoices)) {
+      const descriptionString = Object.entries(this._intentChoices)
+        .map(([key, val]) => `${key}: ${val}`)
+        .join("\n  ");
+      prompt += `\n\nDetailed descriptions of each choice:\n  ${descriptionString}`;
+    }
+
+    const text = await _generate(this._client, prompt, this._schema);
+    const keys = (JSON.parse(text) as { possible_matches: string[] }).possible_matches;
+
+    if (!keys.length) return null;
+
+    if (!Array.isArray(this._intentChoices)) {
+      const choices = this._intentChoices;
+      return keys.map((k) => ({ key: k, description: choices[k] }));
+    }
+    return keys.map((k) => ({ key: k }));
+  }
+}

package/src/helpers/server-rag.ts

@@ -0,0 +1,132 @@
+import { createHash } from "node:crypto";
+import type { Client } from "../client.ts";
+import { fetchOrThrow } from "../utils.ts";
+
+export function _contentKey(text: string): string {
+  return createHash("sha256").update(text).digest("hex").slice(0, 16);
+}
+
+export function _prefixedKey(namespace: string | undefined, key: string): string {
+  return namespace ? `${namespace}.${key}` : key;
+}
+
+export class ServerRAG {
+  private readonly _client: Client;
+  private readonly _namespace: string | undefined;
+  readonly trackedKeys = new Set<string>();
+
+  constructor(client: Client, { namespace }: { namespace?: string } = {}) {
+    this._client = client;
+    this._namespace = namespace;
+  }
+
+  async uploadDocument(key: string, text: string): Promise<void> {
+    const url = new URL("v1/rag/documents", this._client.getHttpBase());
+    await fetchOrThrow(url, {
+      method: "POST",
+      headers: { ...(await this._client.headers()), "Content-Type": "application/json" },
+      body: JSON.stringify({ key, text }),
+      signal: AbortSignal.timeout(60_000),
+    });
+  }
+
+  async deleteDocument(key: string): Promise<void> {
+    const url = new URL(`v1/rag/documents/${key}`, this._client.getHttpBase());
+    await fetchOrThrow(url, {
+      method: "DELETE",
+      headers: await this._client.headers(),
+      signal: AbortSignal.timeout(30_000),
+    });
+  }
+
+  async listDocuments(): Promise<{ key: string }[]> {
+    const url = new URL("v1/rag/documents", this._client.getHttpBase());
+    const response = await fetchOrThrow(url, {
+      headers: await this._client.headers(),
+      signal: AbortSignal.timeout(30_000),
+    });
+    return (await response.json()) as { key: string }[];
+  }
+
+  async ask(
+    question: string,
+    { documentKeys, instructions }: { documentKeys?: string[]; instructions?: string } = {},
+  ): Promise<string> {
+    const url = new URL("v1/rag/ask", this._client.getHttpBase());
+    const payload: Record<string, unknown> = { question };
+    if (documentKeys !== undefined) payload.document_keys = documentKeys;
+    if (instructions !== undefined) payload.instructions = instructions;
+
+    const response = await fetchOrThrow(url, {
+      method: "POST",
+      headers: { ...(await this._client.headers()), "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(120_000),
+    });
+    const result = (await response.json()) as { answer: string; warning?: string };
+    if (result.warning) console.warn(`Guava RAG: ${result.warning}`);
+    return result.answer;
+  }
+
+  async reconcile(documents: string[], ids?: string[]): Promise<void> {
+    if (ids !== undefined && ids.length !== documents.length) {
+      throw new Error(
+        `ids length (${ids.length}) must match documents length (${documents.length})`,
+      );
+    }
+
+    const desired = new Map<string, string>();
+    if (ids !== undefined) {
+      for (let i = 0; i < documents.length; i++) {
+        desired.set(_prefixedKey(this._namespace, ids[i]!), documents[i]!);
+      }
+    } else {
+      for (const doc of documents) {
+        desired.set(_prefixedKey(this._namespace, _contentKey(doc)), doc);
+      }
+    }
+
+    const existing = await this.listDocuments();
+    const existingKeys = new Set(existing.map((d) => d.key));
+    const scopedKeys = this._namespace
+      ? new Set([...existingKeys].filter((k) => k.startsWith(`${this._namespace}.`)))
+      : existingKeys;
+
+    for (const [key, doc] of desired) {
+      if (ids !== undefined || !existingKeys.has(key)) {
+        await this.uploadDocument(key, doc);
+      }
+      this.trackedKeys.add(key);
+    }
+
+    const stale = [...scopedKeys].filter((k) => !desired.has(k));
+    for (const key of stale) {
+      await this.deleteDocument(key);
+    }
+  }
+
+  async upsertDocument(key: string, text: string): Promise<void> {
+    const fullKey = _prefixedKey(this._namespace, key);
+    await this.uploadDocument(fullKey, text);
+    this.trackedKeys.add(fullKey);
+  }
+
+  async addDocument(text: string): Promise<void> {
+    const fullKey = _prefixedKey(this._namespace, _contentKey(text));
+    await this.uploadDocument(fullKey, text);
+    this.trackedKeys.add(fullKey);
+  }
+
+  async removeDocument(key: string): Promise<void> {
+    const fullKey = _prefixedKey(this._namespace, key);
+    await this.deleteDocument(fullKey);
+    this.trackedKeys.delete(fullKey);
+  }
+
+  async clear(): Promise<void> {
+    for (const key of this.trackedKeys) {
+      await this.deleteDocument(key);
+    }
+    this.trackedKeys.clear();
+  }
+}

package/src/testing/mocks.ts

@@ -1,7 +1,24 @@
+import crypto from "node:crypto";
 import { Call } from "../call.ts";
+import type { CallInfo } from "../socket/call-info.ts";
 import type { Command } from "../commands.ts";
 
 export class MockCall extends Call {
+  constructor(
+    args: { callId?: string; callInfo?: CallInfo; variables?: Record<string, any> } = {},
+  ) {
+    super(
+      args.callId ?? `mock-${crypto.randomBytes(6).toString("hex")}`,
+      args.callInfo ?? {
+        call_type: "pstn",
+        from_number: null,
+        to_number: "+15555555555",
+        caller_id: null,
+      },
+      args.variables ?? {},
+    );
+  }
+
   get commands(): Command[] {
     return this._commandQueue;
   }

package/src/version.ts

@@ -1 +1 @@
-export const SDK_VERSION = "0.23.0";
+export const SDK_VERSION = "0.24.0";