@guava-ai/guava-sdk 0.1.0

package/src/helpers/openai.ts

@@ -0,0 +1,105 @@
+import OpenAI, { toFile } from "openai";
+import { type Logger } from "../logging.ts";
+
+// 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/";
+  // 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(),
+    apiKey: process.env.GUAVA_API_KEY,
+  });
+}
+
+export class IntentRecognizer {}
+
+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) {
+    this.client = client ?? beta_create_openai_client(logger);
+    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 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.metadata &&
+        vs.metadata["document_hash"] == document_hash
+      ) {
+        this.logger.info("Re-using existing vector store...");
+        return vs;
+      }
+    }
+
+   this.logger.info("Creating vector store...");
+
+    const vector_store = await this.client.vectorStores.create({
+      name: vector_store_name,
+      expires_after: {
+        anchor: "last_active_at",
+        days: 7,
+      },
+    });
+
+    this.logger.info("Uploading file...");
+    await this.client.vectorStores.files.uploadAndPoll(
+      vector_store.id,
+      await toFile(
+        new Blob([document], { type: "text/plain" }),
+        "document.txt",
+      ),
+    );
+
+    this.logger.info("Updating vector store metadata...");
+    await this.client.vectorStores.update(vector_store.id, {
+      metadata: {
+        document_hash,
+      },
+    });
+
+    return vector_store;
+  }
+
+  async ask(question: string): Promise<string> {
+    const response = await this.client.responses.create({
+      model: "gpt-5-mini",
+      instructions:
+        "You are a virtual contact center agent. Your task is to answer questions using the provided supporting document. Just answer the question - do not offer any follow-ups.",
+      input: question,
+      tools: [
+        {
+          type: "file_search",
+          vector_store_ids: [(await this.vector_store).id],
+        },
+      ],
+      reasoning: {
+        effort: "low",
+      },
+    });
+    return response.output_text;
+  }
+}

package/src/index.ts

@@ -0,0 +1,463 @@
+import WebSocket from "ws";
+import { type Logger, getConsoleLogger } from "./logging.ts";
+import {
+  acceptInboundCallCommand,
+  type Command,
+  startOutboundCallCommand,
+  setPersona,
+  setTaskCommand,
+  answerQuestionCommand,
+  sendInstructionCommand,
+  readScriptCommand,
+  rejectInboundCallCommand,
+  transferCommand,
+  listenInboundCommand,
+} from "./commands.ts";
+import * as z from "zod";
+import {
+  errorEvent,
+  type GuavaEvent,
+  sessionStartedEvent,
+  decodeEvent,
+  type CallerSpeechEvent,
+  type AgentSpeechEvent,
+} from "./events.ts";
+import type { ActionItem, Field, Say, Todo } from "./action_item.ts";
+import pkgdata from "../package.json" with { type: "json" };
+import os from "node:os";
+
+const DEFAULT_BASE_URL = "wss://guava-dev.gridspace.com/guava/";
+const DEFAULT_LOG_LEVEL = "info";
+
+/**
+ * @description convenience function for stringifying data according to a schema
+ */
+function stringifyZod<Schema extends z.ZodType>(
+  schema: Schema,
+  data: z.input<Schema>,
+): string {
+  return JSON.stringify(schema.parse(data));
+}
+
+export class CallController {
+  private _commandQueue: Command[] = [];
+  private _on_complete_current_task?: () => void;
+  // private _field_values: Record<string, any>;
+  private _current_task_id?: string;
+  private _logger: Logger;
+  // drain functions are expected to cleanup
+  // the part of the queue that is successfully sent from its
+  // input (mutating it) (i.e. _drain should use Array.splice)
+  private _drain?: (_: Command[]) => Promise<void>;
+
+  constructor(logger: Logger) {
+    // Set up the default logger.
+    this._logger = logger;
+  }
+
+  setDrain(newDrain: (_: Command[]) => Promise<void>) {
+    this._drain = newDrain;
+    this.flush();
+  }
+
+  protected async acceptCall() {
+    await this.sendCommand(acceptInboundCallCommand, {
+      command_type: "accept-inbound",
+    });
+  }
+
+  protected async readScript(script: string) {
+    await this.sendCommand(readScriptCommand, {
+      command_type: "read-script",
+      script: script,
+    });
+  }
+
+  protected async rejectCall() {
+    await this.sendCommand(rejectInboundCallCommand, {
+      command_type: "reject-inbound",
+    });
+  }
+
+  protected async addInfo(info: string) {
+    throw new Error("not implemeneted");
+  }
+
+  protected async sendInstruction(instruction: string) {
+    await this.sendCommand(sendInstructionCommand, {
+      command_type: "send-instruction",
+      instruction: instruction,
+    });
+  }
+
+  protected async setPersona(
+    organization_name?: string,
+    agent_name?: string,
+    agent_purpose?: string,
+  ) {
+    await this.sendCommand(setPersona, {
+      command_type: "set-persona",
+      organization_name: organization_name,
+      agent_name: agent_name,
+      agent_purpose: agent_purpose,
+    });
+  }
+
+  protected async setTask(
+    objective: string = "",
+    checklist?: (Field | Say | string)[],
+    on_complete: (...c) => void = () => {},
+    ...args
+  ) {
+    if (!objective && !checklist) {
+      throw new Error(
+        "At least one of args ['objective','checklist'] must be provided.",
+      );
+    }
+    this._current_task_id = Math.random().toString(16).substring(2, 8);
+    checklist = checklist ?? [];
+    const action_items = checklist.map((item) =>
+      typeof item == "string"
+        ? ({
+            item_type: "todo",
+            description: item,
+          } satisfies Todo)
+        : item,
+    ) satisfies ActionItem[];
+    this._on_complete_current_task = on_complete.apply(this, args);
+    this.sendCommand(setTaskCommand, {
+      command_type: "set-task",
+      task_id: this._current_task_id,
+      objective: objective,
+      action_items: action_items,
+    });
+  }
+
+  protected async hangup(final_instructions: string = "") {
+    let instructions: string;
+    if (final_instructions) {
+      instructions = `Start ending the conversation. Here are your final instructions: ${final_instructions} Once you've completed the final instructions, naturally end the conversation and hang up the call.`;
+    } else {
+      instructions = "Naturally end the conversation and hang up the call.";
+    }
+
+    this.sendInstruction(instructions);
+  }
+
+  protected transfer(to_number: string, transfer_message?: string) {
+    const message = transfer_message ?? "I'm transferring you now";
+    this.sendCommand(transferCommand, {
+      command_type: "transfer-call",
+      transfer_message: message,
+      to_number: to_number,
+    });
+  }
+
+  private async sendCommand<C extends Command, Schema extends z.ZodType<C>>(
+    schema: Schema,
+    data: z.input<Schema>,
+  ) {
+    const command = schema.parse(data);
+    this._commandQueue.push(command);
+    this._logger.debug(`Command queued: ${JSON.stringify(command)}`);
+    await this.flush();
+  }
+
+  private async flush() {
+    await this._drain?.call(this, this._commandQueue);
+  }
+
+  async onEvent(event: GuavaEvent) {
+    if (event.event_type == "caller-speech") {
+      this.onCallerSpeech(event);
+    } else if (event.event_type == "agent-speech") {
+      this.onAgentSpeech(event);
+    } else if (event.event_type == "agent-question") {
+      try {
+        this._logger.info(`Received question from bot: ${event.question}`);
+        const answer = await this.onQuestion(event.question);
+        await this.sendCommand(answerQuestionCommand, {
+          command_type: "answer-question",
+          question_id: event.question_id,
+          answer: answer,
+        });
+      } catch (e) {
+        this._logger.error("Error occured while answering question.");
+        await this.sendCommand(answerQuestionCommand, {
+          command_type: "answer-question",
+          question_id: event.question_id,
+          answer: "An error occured and the question could not be answered.",
+        });
+      }
+    } else if (event.event_type == "intent") {
+      this._logger.info(
+        `Received intent ${event.intent_id} from bot: ${event.intent_summary}`,
+      );
+      const intent_response = await this.onIntent(event.intent_summary);
+      if (intent_response) {
+        const response_str = `Responding to intent ${event.intent_id}: ${event.intent_summary}`;
+        this._logger.info(response_str);
+        this.sendInstruction(response_str);
+      }
+    } else if (event.event_type == "task-done") {
+      // ignore obsolete task_completed events
+      if (event.task_id == this._current_task_id) {
+        // assertion is implied
+        const on_complete = this._on_complete_current_task;
+        this._on_complete_current_task = undefined;
+        if (on_complete) {
+          on_complete();
+        }
+      }
+    } else if (event.event_type == "action-item-done") {
+      // self._field_values...
+    } else if (event.event_type == "inbound-call") {
+      this.onIncomingCall(event.caller_number);
+    } else if (
+      event.event_type == "outbound-call-connected" ||
+      event.event_type == "bot-session-ended"
+    ) {
+      // no-op, don't warn
+    } else if (event.event_type == "error") {
+      this._logger.error(`The Guava agent reported an error: ${event.content}`);
+    } else {
+      this._logger.warn(`Unhandled event: ${JSON.stringify(event)}`);
+    }
+  }
+
+  // callbacks
+
+  /**
+   * @requires super call
+   */
+  async onIncomingCall(from_number?: string) {
+    await this.onCallStart();
+  }
+
+  async onCallStart(): Promise<void> {}
+
+  async onCallerSpeech(event: CallerSpeechEvent) {}
+  async onAgentSpeech(event: AgentSpeechEvent) {}
+  async onIntent(intent: string): Promise<string | null> {
+    return "Unfortunately I'm not able to help with that.";
+  }
+  async onQuestion(question: string): Promise<string> {
+    return "I don't have an answer to that question.";
+  }
+}
+
+export type InboundConnection =
+  | { agent_number: string }
+  | { webrtc_code: string };
+
+const ws_start = /^ws:\/\//;
+const wss_start = /^wss:\/\//;
+export class Client {
+  private _apiKey: string;
+  private _baseUrl: string;
+  private _logger: Logger;
+  private _ws?: WebSocket;
+  private _controller?: CallController;
+  private messageHandler?: (_: WebSocket.MessageEvent) => void;
+
+  constructor(apiKey?: string, baseUrl?: string, logger?: Logger) {
+    // Set up the default logger.
+    if (logger) {
+      this._logger = logger;
+    } else {
+      this._logger = getConsoleLogger(DEFAULT_LOG_LEVEL);
+    }
+
+    // Resolve the API base URL.
+    if (baseUrl) {
+      this._baseUrl = baseUrl;
+    } else if (process.env.GUAVA_BASE_URL) {
+      this._baseUrl = process.env.GUAVA_BASE_URL;
+    } else {
+      this._baseUrl = DEFAULT_BASE_URL;
+    }
+
+    // Resolve the API key.
+    if (apiKey) {
+      this._apiKey = apiKey;
+    } else if (process.env.GUAVA_API_KEY) {
+      this._apiKey = process.env.GUAVA_API_KEY;
+    } else {
+      throw new Error(
+        "Guava API key must be provided either as argument to client constructor, or in environment variable GUAVA_API_KEY.",
+      );
+    }
+  }
+
+  private getHttpBase() {
+    if (ws_start.test(this._baseUrl)) {
+      return `ws://${this._baseUrl.substring("ws://".length)}`;
+    } else if (wss_start.test(this._baseUrl)) {
+      return `wss://${this._baseUrl.substring("wss://".length)}`;
+    } else {
+      throw new Error(`Invalid base URL: ${this._baseUrl}}`);
+    }
+  }
+
+  private getWebsocketBase() {
+    return this._baseUrl;
+  }
+
+  private headers() {
+    return {
+      Authorization: `Bearer ${this._apiKey}`,
+      "x-guava-platform": os.platform(),
+      "x-guava-runtime": process.release.name,
+      "x-guava-runtime-version": process.version,
+      "x-guava-sdk": "typescript-sdk",
+      "x-guava-sdk-version": pkgdata.version,
+    };
+  }
+
+  createOutbound(
+    fromNumber: string | undefined,
+    toNumber: string,
+    callControllerFactory?: (logger: Logger) => CallController,
+  ) {
+    const url = new URL("create-outbound", this.getWebsocketBase()).toString();
+    const ws = new WebSocket(url, {
+      headers: this.headers(),
+    });
+    const callController = (callControllerFactory ?? ((_) => undefined))(this._logger);
+
+    ws.addEventListener("open", async (_ev) => {
+      ws.send(
+        stringifyZod(startOutboundCallCommand, {
+          command_type: "start-outbound",
+          to_number: toNumber,
+          from_number: fromNumber,
+        }),
+      );
+      await callController?.onCallStart();
+    });
+    ws.addEventListener("close", (_ev) => {
+      // we are closing the socket, so don't trigger any other listeners
+      ws.removeAllListeners();
+      this._ws = undefined;
+      this._controller = undefined;
+    });
+
+    this._ws = ws;
+    this._controller = callController;
+    this.replaceHandler(this.uninitializedOutbound.bind(this));
+
+    // set the callController drain function to send all commands
+    // through the websocket
+    callController?.setDrain(async (commands) => {
+      for (const command of commands.splice(0)) {
+        this._logger.debug(`Sending command ${JSON.stringify(command)}`);
+        ws.send(JSON.stringify(command));
+      }
+    });
+  }
+
+  replaceHandler(newHandler?: (_: WebSocket.MessageEvent) => void) {
+    if (this.messageHandler) {
+      this._ws?.removeEventListener("message", this.messageHandler);
+    }
+    if (newHandler) {
+      this._ws?.addEventListener("message", newHandler);
+    }
+    this.messageHandler = newHandler;
+  }
+
+  // eventlistener handlers for server events
+  // (a state machine in functions)
+  private uninitializedOutbound(ev: WebSocket.MessageEvent) {
+    // for correctness (and type correctness)
+    if (!this._ws) {
+      throw new Error("[internal] Uninitialized WebSocket");
+    }
+
+    const session_started = z
+      .union([sessionStartedEvent, errorEvent])
+      .parse(JSON.parse(ev.data.toString("utf8")));
+    if (session_started.event_type == "error") {
+      throw new Error(`Outbound call failed: ${session_started.content}`);
+    } else {
+      this._logger.info(
+        `Started session with ID: ${session_started.session_id}`,
+      );
+      // move to next state
+      this.replaceHandler(this.initializedOutbound.bind(this));
+    }
+
+    // this._controller?.flush();
+  }
+
+  private async initializedOutbound(ev: WebSocket.MessageEvent) {
+    // for correctness (and type correctness)
+    if (!this._ws) {
+      throw new Error("[internal] Uninitialized WebSocket");
+    }
+
+    // handle the received event
+    const event = decodeEvent(ev.data);
+    if (event) {
+      if (this._controller) {
+        await this._controller.onEvent(event);
+      }
+      if (
+        event.event_type == "outbound-call-failed" ||
+        event.event_type == "bot-session-ended"
+      ) {
+        // shutdown the websocket
+        this._ws.close();
+      }
+    }
+
+    // this._controller?.flush();
+  }
+
+  setInboundHandler(
+    agent_number: string,
+    public_url: string,
+    inbound_token: string,
+  ) {
+    // TODO
+  }
+
+  // why use a typevar here and not for outbound?
+  listenInbound<U extends CallController>(
+    conn: InboundConnection,
+    controller_class: U,
+  ) {
+    const call_controllers: Record<string, U> = {};
+
+    const url = new URL("listen-inbound", this.getWebsocketBase()).toString();
+    const ws = new WebSocket(url, {
+      headers: this.headers(),
+    });
+    let agent_number: string | undefined;
+    let webrtc_code: string | undefined;
+    if ("agent_number" in conn) {
+      agent_number = conn.agent_number;
+    } else {
+      webrtc_code = conn.webrtc_code;
+    }
+
+    ws.send(
+      stringifyZod(listenInboundCommand, {
+        command_type: "listen-inbound",
+        agent_number: agent_number,
+        webrtc_code: webrtc_code,
+      }),
+    );
+
+    this._logger.info(`Listening for calls to ${agent_number ?? webrtc_code}`);
+
+    if (webrtc_code) {
+      // converted to print, but should be logger?
+      const debugurl = new URL(
+        `debug-webrtc?webrtc_code=${webrtc_code}`,
+        this.getHttpBase(),
+      );
+      this._logger.debug(`WebRTC DebugURL: ${new URL("debug-webrtc?we")}`);
+    }
+  }
+}

package/src/logging.ts

@@ -0,0 +1,38 @@
+type LogLevel = "off" | "error" | "warn" | "info" | "debug";
+
+const LOG_RANKS: Record<LogLevel, number> = {
+  off: 0,
+  error: 1,
+  warn: 2,
+  info: 3,
+  debug: 4,
+};
+
+export interface Logger {
+  debug(format: string, ...args: unknown[]);
+  info(format: string, ...args: unknown[]);
+  warn(format: string, ...args: unknown[]);
+  error(format: string, ...args: unknown[]);
+}
+
+function shouldLog(messageLevel: LogLevel, loggerLevel: LogLevel) {
+  if (!LOG_RANKS.hasOwnProperty(messageLevel)) {
+    throw new Error(`Invalid log level: ${String(messageLevel)}`);
+  }
+  if (!LOG_RANKS.hasOwnProperty(loggerLevel)) {
+    throw new Error(`Invalid logger level: ${String(loggerLevel)}`);
+  }
+
+  return LOG_RANKS[messageLevel] <= LOG_RANKS[loggerLevel];
+}
+
+function noop(format: string, ...args: unknown[]) {}
+
+export function getConsoleLogger(loggerLevel: LogLevel): Logger {
+  return {
+    debug: shouldLog("debug", loggerLevel) ? console.debug.bind(console) : noop,
+    info: shouldLog("info", loggerLevel) ? console.info.bind(console) : noop,
+    warn: shouldLog("warn", loggerLevel) ? console.warn.bind(console) : noop,
+    error: shouldLog("error", loggerLevel) ? console.error.bind(console) : noop,
+  };
+}