@guava-ai/guava-sdk 0.1.0 → 0.3.0

package/examples/credit-card-activation.ts

@@ -0,0 +1,188 @@
+import { IntentRecognizer } from "../src/helpers/openai.ts";
+import * as guava from "../src/index.ts";
+import type { Logger } from "../src/logging.ts";
+
+interface Customer {
+  name: string;
+  ssn: string;
+  unactivated_cards: Record<string, number>;
+}
+
+const CUSTOMER_DB: Customer[] = [
+  {
+    name: "John Smith",
+    ssn: "123456789",
+    unactivated_cards: {
+      "6011002980139424": 567,
+    },
+  },
+];
+
+function findCustomerBySSN(ssn: string): Customer | undefined {
+  return CUSTOMER_DB.find((c) => c.ssn == ssn);
+}
+
+const ORGANIZATION_NAME = "Harper Valley Bank";
+
+class CreditCardActivationController extends guava.CallController {
+  private choices = ["activate credit card", "anything else"] as const;
+  private intentRecognizer: IntentRecognizer<typeof this.choices>;
+  constructor(logger: Logger) {
+    super(logger);
+    this.intentRecognizer = new IntentRecognizer(this.choices, logger);
+    this.setPersona({
+      organizationName: ORGANIZATION_NAME,
+      agentPurpose: `You are a customer service voice agent that activates credit cards for customers of ${ORGANIZATION_NAME}.`,
+    });
+    this.readScript(
+      `Hello, thank you for calling the credit card activation line for ${ORGANIZATION_NAME}. My name is Grace. Are you here to activate your credit card?`,
+    );
+    this.acceptCall();
+  }
+
+  override async onIntent(intent: string) {
+    const choice = await this.intentRecognizer.classify(intent);
+    this.logger.info(`Chosen intent: ${choice}`);
+    if (choice == "activate credit card") {
+      await this.activateCreditCard();
+      return null;
+    } else {
+      return "Unfortunately I'm not able to help with that.";
+    }
+  }
+
+  async findCustomer() {
+    let customer: Customer | undefined;
+    let cardNumber: string;
+    while (true) {
+      await this.awaitTask({
+        checklist: [
+          {
+            item_type: "field",
+            description: "Could you give me your social security number?",
+            key: "social_security_number",
+            field_type: "integer",
+            required: true,
+          },
+        ],
+      });
+
+      const ssn_data = this.getField("social_security_number");
+      let ssn: string;
+      if (typeof ssn_data == "string") {
+        ssn = ssn_data;
+      } else {
+        // Should we assume all payloads are strings? or leave room by returning unknown
+        ssn = JSON.stringify(ssn_data);
+      }
+      customer = findCustomerBySSN(ssn);
+      if (!customer) {
+        this.sendInstruction(
+          "We were unable to identify the customer using the SSN they provided. Let the caller know this, and ask if they have the correct social security number.",
+        );
+      } else {
+        await this.awaitTask({
+          objective:
+            "We were able to identify the customer using the Social Security Number they have provided. We're going to confirm the client's name.",
+          checklist: [
+            {
+              item_type: "field",
+              description: `We're going to confirm the client's name. Am I speaking with ${customer.name}?`,
+              key: "is_client",
+              field_type: "multiple_choice",
+              choices: ["yes", "no"],
+              required: true,
+            },
+          ],
+        });
+
+        if (this.getField("is_client") == "no") {
+          this.sendInstruction(
+            "We were unable to identify the client's name in our files. Let the caller know this, and re-ask their social security number.",
+          );
+        } else {
+          break;
+        }
+      }
+    }
+
+    this.sendInstruction(
+      "We were able to find the client's name in our files. Proceed to ask for their card number.",
+    );
+    while (true) {
+      await this.awaitTask({
+        checklist: [
+          {
+            item_type: "field",
+            field_type: "integer",
+            description:
+              "Could you read me the digits on the front of your credit card?",
+            key: "credit_card_number",
+            required: true,
+          },
+        ],
+      });
+
+      cardNumber = this.getField("credit_card_number") as string;
+      if (!(cardNumber in customer.unactivated_cards)) {
+        this.sendInstruction(
+          "We were unable to find the matching card number in our system. Let the caller know this, and re-ask for the credit card number.",
+        );
+      } else {
+        this.sendInstruction(
+          "We were able to find the matching card number in our system. Let the caller know this, and ask for security code on their card.",
+        );
+        break;
+      }
+    }
+
+    const correctCvv = customer.unactivated_cards[cardNumber];
+    while (true) {
+      await this.awaitTask({
+        checklist: [
+          {
+            item_type: "field",
+            field_type: "integer",
+            key: "security_code",
+            description:
+              "To wrap up, could I get the security code on your card?",
+            required: true,
+          },
+        ],
+      });
+
+      const security_code = this.getField("security_code") as string;
+      if (security_code != correctCvv.toString()) {
+        this.sendInstruction(
+          "We were unable to match the security code to the credit card. Let the caller know this and re-ask for the security code.",
+        );
+      } else {
+        break;
+      }
+    }
+    this.hangup(
+      "Explain to the caller that their credit card has now been activated. Thank them for using the bank's services, and hang up.",
+    );
+  }
+
+  async activateCreditCard() {
+    this.sendInstruction(
+      "We are starting the credit card activation process, which starts with asking the caller for their social security number.",
+    );
+
+    await this.findCustomer();
+  }
+}
+
+export function run(_args: string[]) {
+  const conn = new guava.Client().listenInbound(
+    {
+      agent_number: process.env.GUAVA_AGENT_NUMBER!,
+    },
+    (logger) => new CreditCardActivationController(logger),
+  );
+}
+
+if (import.meta.main) {
+  run([]);
+}

package/examples/property-insurance.ts

@@ -3,8 +3,8 @@ import * as guava from "../src/index.ts";
 import { DocumentQA } from "../src/helpers/openai.ts";
 import { readFileSync } from "node:fs";
 import * as path from "node:path";
-import { type Logger } from "../src/logging.ts";
-import {PROPERTY_INSURANCE_POLICY} from "../src/example_data.ts";
+import type { Logger } from "../src/logging.ts";
+import { PROPERTY_INSURANCE_POLICY } from "../src/example_data.ts";
 
 class InsuranceCallController extends guava.CallController {
   private documentQA: DocumentQA;
@@ -17,11 +17,15 @@ class InsuranceCallController extends guava.CallController {
       logger,
     );
   }
+
   override async onCallStart(): Promise<void> {
-    await this.setPersona("Harper Valley Property Insurance");
-    await this.setTask(
-      "You are making an outbound call to a potential customer. Your task is to answer questions regarding property insurance policy until there are no more questions.",
-    );
+    await this.setPersona({
+      organizationName: "Harper Valley Property Insurance",
+    });
+    this.setTask({
+      objective:
+        "You are making an outbound call to a potential customer. Your task is to answer questions regarding property insurance policy until there are no more questions.",
+    });
   }
 
   override async onQuestion(question: string): Promise<string> {
@@ -45,5 +49,5 @@ export function run(args: string[]) {
 }
 
 if (import.meta.main) {
-  run(process.argv.slice(2))
+  run(process.argv.slice(2));
 }

package/examples/thai-palace.ts

@@ -0,0 +1,74 @@
+import * as guava from "../src/index.ts";
+import { getConsoleLogger, type Logger } from "../src/logging.ts";
+import { IntentRecognizer } from "../src/helpers/openai.ts";
+
+class ThaiPalaceCallController extends guava.CallController {
+  private choices = ["restaurant waitlist", "anything else"] as const;
+  private intentRecognizer: IntentRecognizer<typeof this.choices>;
+  constructor(logger: Logger) {
+    super(logger);
+    this.intentRecognizer = new IntentRecognizer(this.choices, logger);
+    this.setPersona({
+      organizationName: "Thai Palace",
+    });
+  }
+
+  override async onIncomingCall(from_number?: string): Promise<void> {
+    await super.onIncomingCall(from_number);
+    this.acceptCall();
+    this.setThaiPalaceTask();
+  }
+
+  setThaiPalaceTask() {
+    this.setTask(
+      {
+        objective: `You are a virtual assistant for a restaurant called Thai Palace.
+ Your job is to add callers to the waitlist.`,
+        checklist: [
+          {
+            item_type: "field",
+            key: "caller_name",
+            field_type: "text",
+            description: "The name to be added to the waitlist",
+          },
+          {
+            item_type: "field",
+            key: "party_size",
+            field_type: "integer",
+            description: "The number of people attending",
+          },
+          {
+            item_type: "field",
+            key: "phone_number",
+            field_type: "text",
+            description: "phone number to text when table is ready",
+          },
+          "Read the phone number back to the caller to make sure you got it right",
+        ],
+      },
+      () => this.hangup(),
+    );
+  }
+
+  override async onIntent(intent: string) {
+    const choice = await this.intentRecognizer.classify(intent);
+    this.logger.info(`Chosen intent: ${choice}`);
+    if (choice == "restaurant waitlist") {
+      this.setThaiPalaceTask();
+      return null;
+    } else {
+      return "Tell them we only handle waitlist additions at this number.";
+    }
+  }
+}
+
+export function run(_args: string[]) {
+  new guava.Client().listenInbound(
+    { agent_number: process.env.GUAVA_AGENT_NUMBER! },
+    (logger) => new ThaiPalaceCallController(getConsoleLogger("debug")),
+  );
+}
+
+if (import.meta.main) {
+  run([]);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guava-ai/guava-sdk",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "type": "module",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
@@ -37,4 +37,4 @@
     "/examples",
     "/bin"
   ]
-}
+}

package/src/action_item.ts

@@ -14,11 +14,14 @@ export const fieldItem = z
     description: z.string(),
     field_type: fieldItemType,
     required: z.boolean().default(true),
-    choices: z.array(z.string()),
+    choices: z.array(z.string()).default([]),
   })
   .refine((field) => {
     if (field.field_type == "multiple_choice" && field.choices.length > 10) {
-      process.emitWarning("Performance degrades with large number of choices for multiple choice field.", "ACTION_ITEM")
+      process.emitWarning(
+        "Performance degrades with large number of choices for multiple choice field.",
+        "ACTION_ITEM",
+      );
     }
     return true;
   });

package/src/commands.ts

@@ -13,12 +13,18 @@ export const listenInboundCommand = z
   .strictObject({
     command_type: z.literal("listen-inbound"),
 
-    agent_number: z.e164().optional(),
-    webrtc_code: z.string().optional(),
+    agent_number: z.e164().nullish().default(null),
+    webrtc_code: z.string().nullish().default(null),
   })
-  .refine((obj) => {
-    !!obj.agent_number || !!obj.webrtc_code;
-  });
+  .refine(
+    (obj) => {
+      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 const rejectInboundCallCommand = z.strictObject({

package/src/example_data.ts

@@ -606,4 +606,4 @@ Coverage limitations, definitions, and premium rating methodologies may vary by
 The actual insurance policy, including Declarations, core forms, endorsements, and any applicable riders, constitutes the entire contract between HVPI and the policyholder.
 
 End of Harper Valley Property Insurance
-Comprehensive Residential Program Manual.`
+Comprehensive Residential Program Manual.`;

package/src/helpers/openai.ts

@@ -1,16 +1,14 @@
 import OpenAI, { toFile } from "openai";
 import { type Logger } from "../logging.ts";
+import * as z from "zod";
 
 // from beta.py
 // TODO: Remove after beta
 function beta_create_openai_client(logger: Logger) {
   const baseUrl =
-    process.env.GUAVA_BASE_URL ?? "wss://guava-dev.gridspace.com/guava/";
+    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);
-  basedUrl.protocol = /^wss:\/\//.test(basedUrl.toString())
-    ? "https:"
-    : "http:";
   logger.info(`Creating beta OpenAI client`);
   return new OpenAI({
     baseURL: basedUrl.toString(),
@@ -18,13 +16,43 @@ function beta_create_openai_client(logger: Logger) {
   });
 }
 
-export class IntentRecognizer {}
+export class IntentRecognizer<Choices extends readonly string[]> {
+  private client: OpenAI;
+  private intentChoices: Choices;
+  private choiceModel: z.ZodType<Choices[number]>;
+  constructor(choices: Choices, logger: Logger, client?: OpenAI) {
+    this.intentChoices = choices;
+    this.client = client ?? beta_create_openai_client(logger);
+    this.choiceModel = z.union(choices.map((s) => z.literal(s)));
+  }
+
+  async classify(intent: string): Promise<Choices[number]> {
+    const response = await this.client.responses.parse({
+      model: "gpt-5-mini",
+      input: `
+Pick the choice in the list of choices that best reflects the given intent.
+Intent: "${intent}".
+Possible Choices: ${this.intentChoices}.
+      `.trim(),
+      reasoning: {
+        effort: "low",
+      },
+    });
+    const parsed_output = this.choiceModel.parse(response.output_text);
+    return parsed_output;
+  }
+}
 
 export class DocumentQA {
   private client: OpenAI;
   private vector_store: Promise<OpenAI.VectorStore>;
   private logger: Logger;
-  constructor(vector_store_name: string, document: string, logger: Logger, client?: OpenAI) {
+  constructor(
+    vector_store_name: string,
+    document: string,
+    logger: Logger,
+    client?: OpenAI,
+  ) {
     this.client = client ?? beta_create_openai_client(logger);
     this.vector_store = this.getOrCreateVectorStore(
       vector_store_name,
@@ -55,7 +83,7 @@ export class DocumentQA {
       }
     }
 
-   this.logger.info("Creating vector store...");
+    this.logger.info("Creating vector store...");
 
     const vector_store = await this.client.vectorStores.create({
       name: vector_store_name,