@guava-ai/guava-sdk 0.3.0 → 0.4.0

package/src/commands.ts

@@ -1,15 +1,15 @@
 import * as z from "zod";
-import { actionItem } from "./action_item.ts";
+import { ActionItem } from "./action_item.ts";
 
-export const startOutboundCallCommand = z.strictObject({
+export const StartOutboundCallCommand = z.strictObject({
   command_type: z.literal("start-outbound"),
 
   from_number: z.e164().optional(),
   to_number: z.e164(),
 });
-export type StartOutboundCallCommand = z.input<typeof startOutboundCallCommand>;
+export type StartOutboundCallCommand = z.input<typeof StartOutboundCallCommand>;
 
-export const listenInboundCommand = z
+export const ListenInboundCommand = z
   .strictObject({
     command_type: z.literal("listen-inbound"),
 
@@ -18,83 +18,99 @@ export const listenInboundCommand = z
   })
   .refine(
     (obj) => {
-      return (
-        typeof obj.agent_number == "string" ||
-        typeof obj.webrtc_code == "string"
-      );
+      return typeof obj.agent_number === "string" || typeof obj.webrtc_code === "string";
     },
     { error: "one of ['agent_number', 'webrtc_code'] must be set" },
   );
-export type ListenInboundCommand = z.input<typeof listenInboundCommand>;
+export type ListenInboundCommand = z.input<typeof ListenInboundCommand>;
 
-export const rejectInboundCallCommand = z.strictObject({
+export const RejectInboundCallCommand = z.strictObject({
   command_type: z.literal("reject-inbound"),
 });
-export type RejectInboundCallCommand = z.input<typeof rejectInboundCallCommand>;
+export type RejectInboundCallCommand = z.input<typeof RejectInboundCallCommand>;
 
-export const acceptInboundCallCommand = z.strictObject({
+export const AcceptInboundCallCommand = z.strictObject({
   command_type: z.literal("accept-inbound"),
 });
-export type AcceptInboundCallCommand = z.input<typeof acceptInboundCallCommand>;
+export type AcceptInboundCallCommand = z.input<typeof AcceptInboundCallCommand>;
 
-export const setTaskCommand = z.strictObject({
+export const SetTaskCommand = z.strictObject({
   command_type: z.literal("set-task"),
   task_id: z.string(),
   objective: z.string(),
-  action_items: z.array(actionItem),
+  action_items: z.array(ActionItem),
 });
-export type SetTaskCommand = z.input<typeof setTaskCommand>;
+export type SetTaskCommand = z.input<typeof SetTaskCommand>;
 
-export const readScriptCommand = z.strictObject({
+export const ReadScriptCommand = z.strictObject({
   command_type: z.literal("read-script"),
   script: z.string(),
 });
-export type ReadScriptCommand = z.input<typeof readScriptCommand>;
+export type ReadScriptCommand = z.input<typeof ReadScriptCommand>;
 
-export const answerQuestionCommand = z.strictObject({
+export const AnswerQuestionCommand = z.strictObject({
   command_type: z.literal("answer-question"),
   question_id: z.string(),
   answer: z.string(),
 });
-export type AnswerQuestionCommand = z.input<typeof answerQuestionCommand>;
+export type AnswerQuestionCommand = z.input<typeof AnswerQuestionCommand>;
 
-export const setPersona = z.strictObject({
+export const SetPersona = z.strictObject({
   command_type: z.literal("set-persona"),
   agent_name: z.string().optional(),
   organization_name: z.string().optional(),
   agent_purpose: z.string().optional(),
+  voice: z.string().optional(),
 });
-export type SetPersona = z.input<typeof setPersona>;
+export type SetPersona = z.input<typeof SetPersona>;
 
-export const sendInstructionCommand = z.strictObject({
+export const SendInstructionCommand = z.strictObject({
   command_type: z.literal("send-instruction"),
   instruction: z.string(),
 });
-export type SendInstructionCommand = z.input<typeof sendInstructionCommand>;
+export type SendInstructionCommand = z.input<typeof SendInstructionCommand>;
 
-export const transferCommand = z.strictObject({
+export const TransferCommand = z.strictObject({
   command_type: z.literal("transfer-call"),
   transfer_message: z.string(),
   to_number: z.string(),
 });
-export type TransferCommand = z.input<typeof transferCommand>;
-
-export const anyCommand = z.union([
-  startOutboundCallCommand,
-  listenInboundCommand,
-  rejectInboundCallCommand,
-  acceptInboundCallCommand,
-  setTaskCommand,
-  readScriptCommand,
-  answerQuestionCommand,
-  setPersona,
-  sendInstructionCommand,
-  transferCommand,
+export type TransferCommand = z.input<typeof TransferCommand>;
+
+export const RegisteredHooksCommand = z.strictObject({
+  command_type: z.literal("registered-hooks"),
+  has_on_question: z.boolean(),
+  has_on_intent: z.boolean(),
+});
+export type RegisteredHooksCommand = z.input<typeof RegisteredHooksCommand>;
+
+export const ChoiceResultCommand = z.strictObject({
+  command_type: z.literal("choice-query-result"),
+  field_key: z.string(),
+  query_id: z.string(),
+  matched_choices: z.array(z.string()),
+  other_choices: z.array(z.string()),
+});
+export type ChoiceResultCommand = z.input<typeof ChoiceResultCommand>;
+
+export const AnyCommand = z.union([
+  StartOutboundCallCommand,
+  ListenInboundCommand,
+  RejectInboundCallCommand,
+  AcceptInboundCallCommand,
+  SetTaskCommand,
+  ReadScriptCommand,
+  AnswerQuestionCommand,
+  SetPersona,
+  SendInstructionCommand,
+  TransferCommand,
+  RegisteredHooksCommand,
+  ChoiceResultCommand,
 ]);
-export type Command = z.input<typeof anyCommand>;
+export type Command = z.input<typeof AnyCommand>;
 
-export const inboundTunnelCommand = z.strictObject({
+export const InboundTunnelCommand = z.strictObject({
   call_id: z.string(),
-  command: anyCommand,
+  command: AnyCommand,
 });
-export type InboundTunnelCommand = z.input<typeof inboundTunnelCommand>;
+export type InboundTunnelCommand = z.input<typeof InboundTunnelCommand>;

package/src/events.ts

@@ -1,123 +1,136 @@
 import * as z from "zod";
 
-export const sessionStartedEvent = z.object({
+export const SessionStartedEvent = z.object({
   event_type: z.literal("session-started"),
   session_id: z.string(),
 });
-export type SessionStartedEvent = z.input<typeof sessionStartedEvent>;
+export type SessionStartedEvent = z.infer<typeof SessionStartedEvent>;
 
-export const inboundCallEvent = z.object({
+export const InboundCallEvent = z.object({
   event_type: z.literal("inbound-call"),
   caller_number: z.e164().optional(),
   agent_number: z.e164().optional(),
 });
-export type InboundCallEvent = z.input<typeof inboundCallEvent>;
+export type InboundCallEvent = z.infer<typeof InboundCallEvent>;
 
 /**
  * @description The caller has said something.
  */
-export const callerSpeechEvent = z.object({
+export const CallerSpeechEvent = z.object({
   event_type: z.literal("caller-speech"),
 
   utterance: z.string(),
 });
-export type CallerSpeechEvent = z.input<typeof callerSpeechEvent>;
+export type CallerSpeechEvent = z.infer<typeof CallerSpeechEvent>;
 
 /**
  * @description The agent has said something.
  */
-export const agentSpeechEvent = z.object({
+export const AgentSpeechEvent = z.object({
   event_type: z.literal("agent-speech"),
 
   utterance: z.string(),
   interrupted: z.boolean().default(false),
 });
-export type AgentSpeechEvent = z.input<typeof agentSpeechEvent>;
+export type AgentSpeechEvent = z.infer<typeof AgentSpeechEvent>;
 
-export const errorEvent = z.object({
+export const ErrorEvent = z.object({
   event_type: z.literal("error"),
   content: z.string(),
 });
-export type ErrorEvent = z.input<typeof errorEvent>;
+export type ErrorEvent = z.infer<typeof ErrorEvent>;
 
-export const warningEvent = z.object({
+export const WarningEvent = z.object({
   event_type: z.literal("warning"),
   content: z.string(),
 });
-export type WarningEvent = z.input<typeof warningEvent>;
+export type WarningEvent = z.infer<typeof WarningEvent>;
 
-export const agentQuestionEvent = z.object({
+export const AgentQuestionEvent = z.object({
   event_type: z.literal("agent-question"),
   question_id: z.string(),
   question: z.string(),
 });
-export type AgentQuestionEvent = z.input<typeof agentQuestionEvent>;
+export type AgentQuestionEvent = z.infer<typeof AgentQuestionEvent>;
 
-export const intentEvent = z.object({
+export const IntentEvent = z.object({
   event_type: z.literal("intent"),
   intent_id: z.string(),
   intent_summary: z.string(),
 });
-export type IntentEvent = z.input<typeof intentEvent>;
+export type IntentEvent = z.infer<typeof IntentEvent>;
 
-export const actionItemCompletedEvent = z.object({
+export const ActionItemCompletedEvent = z.object({
   event_type: z.literal("action-item-done"),
   key: z.string(),
   payload: z.unknown(),
 });
-export type ActionItemCompletedEvent = z.input<typeof actionItemCompletedEvent>;
+export type ActionItemCompletedEvent = z.infer<typeof ActionItemCompletedEvent>;
 
-export const taskCompletedEvent = z.object({
+export const TaskCompletedEvent = z.object({
   event_type: z.literal("task-done"),
 
   task_id: z.string(),
 });
-export type TaskCompletedEvent = z.input<typeof taskCompletedEvent>;
+export type TaskCompletedEvent = z.infer<typeof TaskCompletedEvent>;
 
-export const outboundCallConnected = z.object({
+export const OutboundCallConnected = z.object({
   event_type: z.literal("outbound-call-connected"),
 });
-export type OutboundCallConnected = z.input<typeof outboundCallConnected>;
+export type OutboundCallConnected = z.infer<typeof OutboundCallConnected>;
 
-export const outboundCallFailed = z.object({
+export const OutboundCallFailed = z.object({
   event_type: z.literal("outbound-call-failed"),
 
   error_code: z.int(),
   error_reason: z.string(),
 });
-export type OutboundCallFailed = z.input<typeof outboundCallFailed>;
+export type OutboundCallFailed = z.infer<typeof OutboundCallFailed>;
 
-export const botSessionEnded = z.object({
+export const BotSessionEnded = z.object({
   event_type: z.literal("bot-session-ended"),
 });
-export type BotSessionEnded = z.input<typeof botSessionEnded>;
-
-export const anyEvent = z.union([
-  sessionStartedEvent,
-  inboundCallEvent,
-  callerSpeechEvent,
-  agentSpeechEvent,
-  errorEvent,
-  warningEvent,
-  agentQuestionEvent,
-  intentEvent,
-  actionItemCompletedEvent,
-  taskCompletedEvent,
-  outboundCallConnected,
-  outboundCallFailed,
-  botSessionEnded,
+export type BotSessionEnded = z.infer<typeof BotSessionEnded>;
+
+export const ChoiceQueryEvent = z.object({
+  event_type: z.literal("choice-query"),
+  field_key: z.string(),
+  query: z.string(),
+  query_id: z.string(),
+});
+export type ChoiceQueryEvent = z.infer<typeof ChoiceQueryEvent>;
+
+export const GuavaEvent = z.union([
+  SessionStartedEvent,
+  InboundCallEvent,
+  CallerSpeechEvent,
+  AgentSpeechEvent,
+  ErrorEvent,
+  WarningEvent,
+  AgentQuestionEvent,
+  IntentEvent,
+  ActionItemCompletedEvent,
+  TaskCompletedEvent,
+  OutboundCallConnected,
+  OutboundCallFailed,
+  BotSessionEnded,
+  ChoiceQueryEvent,
 ]);
-export type GuavaEvent = z.input<typeof anyEvent>;
+export type GuavaEvent = z.infer<typeof GuavaEvent>;
+
+const _KNOWN_EVENT_TYPES = new Set(
+  GuavaEvent.options.map((schema) => schema.shape.event_type.value),
+);
 
 export function decodeEvent(
   serialized_event: string | ArrayBuffer | Buffer | Buffer[],
 ): GuavaEvent | null {
   let data: Record<string, any>;
-  if (typeof serialized_event == "string") {
+  if (typeof serialized_event === "string") {
     data = JSON.parse(serialized_event);
   } else if (serialized_event instanceof ArrayBuffer) {
     data = JSON.parse(new TextDecoder().decode(serialized_event));
-  } else if (serialized_event instanceof Array) {
+  } else if (Array.isArray(serialized_event)) {
     let decoded = "";
     for (const buf of serialized_event) {
       decoded += buf.toString("utf8");
@@ -127,16 +140,18 @@ export function decodeEvent(
     data = JSON.parse(serialized_event.toString("utf8"));
   }
 
-  try {
-    return anyEvent.parse(data);
-  } catch (e) {
-    // TODO logging global use signleton to warn
+  if (!_KNOWN_EVENT_TYPES.has(data.event_type)) {
+    process.emitWarning(
+      `Received an unknown event type ${data.event_type}. Update to a newer version of this SDK.`,
+    );
     return null;
   }
+
+  return GuavaEvent.parse(data);
 }
 
-export const inboundTunnelEvent = z.object({
+export const InboundTunnelEvent = z.object({
   call_id: z.string(),
-  event: anyEvent,
+  event: GuavaEvent,
 });
-export type inboundTunnelEvent = z.input<typeof inboundTunnelEvent>;
+export type InboundTunnelEvent = z.infer<typeof InboundTunnelEvent>;

package/src/example_data.ts

@@ -1,3 +1,45 @@
+export function mockAppointmentsForFuture(nextNDays: number = 25): string[] {
+  const timeZone = "America/Los_Angeles";
+  const mockAppointments: string[] = [];
+
+  const now = new Date();
+
+  // Get today's date parts in America/Los_Angeles
+  const laDateParts = new Intl.DateTimeFormat("en-CA", {
+    timeZone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  }).formatToParts(now);
+
+  const year = Number(laDateParts.find((p) => p.type === "year")?.value);
+  const month = Number(laDateParts.find((p) => p.type === "month")?.value);
+  const day = Number(laDateParts.find((p) => p.type === "day")?.value);
+
+  const times = [
+    [9, 0],
+    [10, 30],
+    [13, 0],
+    [15, 30],
+  ] as const;
+
+  for (let offset = 1; offset <= nextNDays; offset++) {
+    const baseDate = new Date(Date.UTC(year, month - 1, day + offset));
+
+    const y = baseDate.getUTCFullYear();
+    const m = String(baseDate.getUTCMonth() + 1).padStart(2, "0");
+    const d = String(baseDate.getUTCDate()).padStart(2, "0");
+
+    for (const [hour, minute] of times) {
+      const hh = String(hour).padStart(2, "0");
+      const mm = String(minute).padStart(2, "0");
+      mockAppointments.push(`${y}-${m}-${d}T${hh}:${mm}:00`);
+    }
+  }
+
+  return mockAppointments;
+}
+
 export const PROPERTY_INSURANCE_POLICY = `HARPER VALLEY PROPERTY INSURANCE
 COMPREHENSIVE RESIDENTIAL PROGRAM MANUAL
 

package/src/helpers/openai.ts

@@ -1,12 +1,13 @@
 import OpenAI, { toFile } from "openai";
-import { type Logger } from "../logging.ts";
+import { zodTextFormat } from "openai/helpers/zod";
+import { type Logger, getDefaultLogger } from "../logging.ts";
 import * as z from "zod";
+import { telemetryClient } from "../telemetry.ts";
 
 // from beta.py
 // TODO: Remove after beta
 function beta_create_openai_client(logger: Logger) {
-  const baseUrl =
-    process.env.GUAVA_BASE_URL ?? "https://guava-dev.gridspace.com/";
+  const baseUrl = process.env.GUAVA_BASE_URL ?? "https://guava-dev.gridspace.com/";
   // to get it working with OpenAI TS/JS client
   const basedUrl = new URL("openai/v1/", baseUrl);
   logger.info(`Creating beta OpenAI client`);
@@ -16,6 +17,7 @@ function beta_create_openai_client(logger: Logger) {
   });
 }
 
+@telemetryClient.trackClass()
 export class IntentRecognizer<Choices extends readonly string[]> {
   private client: OpenAI;
   private intentChoices: Choices;
@@ -43,40 +45,36 @@ Possible Choices: ${this.intentChoices}.
   }
 }
 
+@telemetryClient.trackClass()
 export class DocumentQA {
   private client: OpenAI;
   private vector_store: Promise<OpenAI.VectorStore>;
   private logger: Logger;
+
   constructor(
     vector_store_name: string,
     document: string,
-    logger: Logger,
+    logger: Logger = getDefaultLogger(),
     client?: OpenAI,
   ) {
     this.client = client ?? beta_create_openai_client(logger);
-    this.vector_store = this.getOrCreateVectorStore(
-      vector_store_name,
-      document,
-    );
+    this.vector_store = this.getOrCreateVectorStore(vector_store_name, document);
     this.logger = logger;
   }
 
   async getOrCreateVectorStore(vector_store_name: string, document: string) {
     const encoder = new TextEncoder();
     const document_buffer = encoder.encode(document);
-    const document_hash_buffer = await crypto.subtle.digest(
-      "SHA-256",
-      document_buffer,
-    );
+    const document_hash_buffer = await crypto.subtle.digest("SHA-256", document_buffer);
     const u8view = new Uint8Array(document_hash_buffer);
     const document_hash: string = Array.from(u8view)
       .map((b) => b.toString(16).padStart(2, "0"))
       .join("");
     for await (const vs of this.client.vectorStores.list()) {
       if (
-        vs.name == vector_store_name &&
+        vs.name === vector_store_name &&
         vs.metadata &&
-        vs.metadata["document_hash"] == document_hash
+        vs.metadata.document_hash === document_hash
       ) {
         this.logger.info("Re-using existing vector store...");
         return vs;
@@ -96,10 +94,7 @@ export class DocumentQA {
     this.logger.info("Uploading file...");
     await this.client.vectorStores.files.uploadAndPoll(
       vector_store.id,
-      await toFile(
-        new Blob([document], { type: "text/plain" }),
-        "document.txt",
-      ),
+      await toFile(new Blob([document], { type: "text/plain" }), "document.txt"),
     );
 
     this.logger.info("Updating vector store metadata...");
@@ -131,3 +126,63 @@ export class DocumentQA {
     return response.output_text;
   }
 }
+
+const filterSchema = z.object({
+  matchingAppointments: z.array(z.string()).describe("List of datetimes matching the query."),
+  otherAppointments: z
+    .array(z.string())
+    .describe("If no datetimes match the query, list of datetimes to suggest."),
+});
+
+@telemetryClient.trackClass()
+export class DatetimeFilter {
+  private client: OpenAI;
+  private sourceList: string[];
+
+  constructor(
+    { sourceList, client }: { sourceList: string[]; client?: OpenAI },
+    logger: Logger = getDefaultLogger(),
+  ) {
+    this.sourceList = sourceList;
+    this.client = client ?? beta_create_openai_client(logger);
+  }
+
+  async filter(
+    query: string,
+    { maxResults = 5 }: { maxResults?: number } = {},
+  ): Promise<[string[], string[]]> {
+    const appointmentTimesStr = this.sourceList.join("\n");
+    const today = new Date().toLocaleDateString("en-US", {
+      month: "long",
+      day: "numeric",
+      year: "numeric",
+    });
+    const prompt = `\
+Return a few datetimes in the list matching the query. If no datetimes match the query, return a few other datetimes from the list that can be used as close suggestions.
+NEVER HALLUCINATE DATETIMES THAT ARE NOT IN THE LIST.
+Query: ${query}
+Today's Date: ${today}
+Appointment Times:
+${appointmentTimesStr}
+==================
+You must return at most ${maxResults} options per list.`;
+
+    const response = await this.client.responses.parse({
+      model: "gpt-5-mini",
+      input: [{ role: "system", content: prompt }],
+      text: { format: zodTextFormat(filterSchema, "filter") },
+      reasoning: { effort: "medium" },
+    });
+
+    const output = response.output_parsed;
+
+    if (!output) {
+      throw new Error("Failed to produce parseable output.");
+    }
+
+    return [
+      output.matchingAppointments.slice(0, maxResults),
+      output.otherAppointments.slice(0, maxResults),
+    ];
+  }
+}