@guava-ai/guava-sdk 0.23.0 → 0.25.0

package/src/helpers/llm.ts

@@ -1,5 +1,9 @@
-import type { Client } from "../client.ts";
+import * as z from "zod";
+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 +18,172 @@ 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,
+    });
+  }
+}
+
+export const _filterSchema = z.object({
+  matching_appointments: z.array(z.string()),
+  other_appointments: z.array(z.string()),
+});
+
+@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, z.toJSONSchema(_filterSchema));
+    const result = _filterSchema.parse(JSON.parse(text));
+    return [
+      result.matching_appointments.slice(0, maxResults),
+      result.other_appointments.slice(0, maxResults),
+    ];
+  }
+}
+
+export function _makeIntentSchema(choiceList: [string, ...string[]]) {
+  return z
+    .object({
+      possible_matches: z
+        .array(z.enum(choiceList))
+        .describe(
+          "Choices that could match the caller's intent, ordered by likelihood. Include all plausible matches.",
+        ),
+    })
+    .meta({ title: "ChoiceModel" });
+}
+
+@telemetryClient.trackClass()
+export class IntentRecognizer {
+  private readonly _client: Client;
+  private readonly _intentChoices: string[] | Record<string, string>;
+  private readonly _schema: ReturnType<typeof _makeIntentSchema>;
+
+  constructor(intentChoices: string[] | Record<string, string>) {
+    this._client = new Client();
+    this._intentChoices = intentChoices;
+    const choiceList = Array.isArray(intentChoices) ? intentChoices : Object.keys(intentChoices);
+    this._schema = _makeIntentSchema(choiceList as [string, ...string[]]);
+  }
+
+  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, z.toJSONSchema(this._schema));
+    const { possible_matches: keys } = this._schema.parse(JSON.parse(text));
+
+    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/index.ts

@@ -1,10 +1,12 @@
 export { Client, type InboundConnection } from "./client.ts";
+export { Runner } from "./runner.ts";
 export type { SmsMessage } from "./sms.ts";
 export { CallController, type TaskObjective } from "./call-controller.ts";
 export { Say, Field } from "./action-item.ts";
 export { Logger, getConsoleLogger, getDefaultLogger } from "./logging.ts";
 export { Agent, CallInfo } from "./agent.ts";
-export { Call } from "./call.ts";
+export { Call, DEFAULT_REACH_PERSON_OUTCOMES } from "./call.ts";
+export type { ReachPersonOutcome } from "./call.ts";
 export type { BotSessionEnded, TerminationReason, DTMFPressedEvent, DTMFDigit } from "./events.ts";
 export { TestSession } from "./testing/session.ts";
 export { MockCall } from "./testing/mocks.ts";

package/src/runner.ts

@@ -0,0 +1,39 @@
+import type { Agent } from "./agent.ts";
+import { MultiHealthContext, getHealthServer } from "./health.ts";
+
+export class Runner {
+  private _healthCtx = new MultiHealthContext();
+  private _tasks: Array<() => Promise<void>> = [];
+
+  listenPhone(agent: Agent, agentNumber: string): this {
+    const ctx = this._healthCtx.createCtx();
+    this._tasks.push(() => agent._listenInbound(ctx, { agent_number: agentNumber }));
+    return this;
+  }
+
+  listenWebrtc(agent: Agent, webrtcCode?: string): this {
+    const ctx = this._healthCtx.createCtx();
+    this._tasks.push(async () => {
+      const code = webrtcCode ?? (await agent._client.createWebrtcAgent(3600));
+      return agent._listenInbound(ctx, { webrtc_code: code });
+    });
+    return this;
+  }
+
+  listenSip(agent: Agent, sipCode: string): this {
+    const ctx = this._healthCtx.createCtx();
+    this._tasks.push(() => agent._listenInbound(ctx, { sip_code: sipCode }));
+    return this;
+  }
+
+  attachCampaign(agent: Agent, campaignCode: string): this {
+    const ctx = this._healthCtx.createCtx();
+    this._tasks.push(() => agent._serveCampaign(ctx, campaignCode));
+    return this;
+  }
+
+  async run(): Promise<void> {
+    await using _server = await getHealthServer(this._healthCtx);
+    await Promise.all(this._tasks.map((task) => task()));
+  }
+}

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/testing/session.ts

@@ -7,7 +7,7 @@ import { _generate } from "../helpers/llm.ts";
 
 type SessionEvent = InjectASR | BotTTS;
 
-const _evalResponseSchema = z.object({
+export const _evalResponseSchema = z.object({
   results: z.array(
     z.object({
       passed: z.boolean(),
@@ -166,28 +166,8 @@ ${transcript || "(empty — no conversation occurred)"}
 Criteria:
 ${criteriaList}`;
 
-    const evalSchema = {
-      type: "object",
-      properties: {
-        results: {
-          type: "array",
-          items: {
-            type: "object",
-            properties: {
-              passed: { type: "boolean" },
-              reasoning: { type: "string" },
-            },
-            required: ["passed"],
-            additionalProperties: false,
-          },
-        },
-      },
-      required: ["results"],
-      additionalProperties: false,
-    };
-
     const evalResponse = _evalResponseSchema.parse(
-      JSON.parse(await _generate(this._client, prompt, evalSchema)),
+      JSON.parse(await _generate(this._client, prompt, z.toJSONSchema(_evalResponseSchema))),
     );
 
     if (evalResponse.results.length !== allCriteria.length) {

package/src/version.ts

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

package/dist/examples/example.test.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"example.test.js","sourceRoot":"","sources":["../../examples/example.test.ts"],"names":[],"mappings":";AAAA;;;GAGG;;AAGH,mDAA+C;AAC/C,sEAA+D;AAE/D,QAAQ,CAAC,eAAe,EAAE,GAAG,EAAE;IAC7B,IAAI,CAAC,kDAAkD,EAAE,KAAK,IAAI,EAAE;QAClE,MAAM,UAAU,GAAG,MAAM,iBAAK,CAAC,QAAQ,CAAC,eAAe,CAAC,IAAI,oBAAQ,EAAE,EAAE,qBAAqB,CAAC,CAAC;QAC/F,MAAM,CAAC,UAAU,CAAC,CAAC,cAAc,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACpD,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,8BAA8B,EAAE,KAAK,IAAI,EAAE;QAC9C,MAAM,OAAO,GAAG,MAAM,iBAAK,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;YACjD,iFAAiF;YACjF,MAAM,OAAO,CAAC,WAAW,EAAE,CAAC;YAC5B,OAAO,CAAC,GAAG,CAAC,yCAAyC,CAAC,CAAC;YAEvD,6CAA6C;YAC7C,MAAM,OAAO,CAAC,UAAU,EAAE,CAAC;QAC7B,CAAC,CAAC,CAAC;QAEH,mEAAmE;QAEnE,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QACnD,MAAM,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IACzD,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,gCAAgC,EAAE,KAAK,IAAI,EAAE;QAChD,mFAAmF;QACnF,MAAM,OAAO,GAAG,MAAM,iBAAK,CAAC,YAAY,CAAC,6CAA6C,CAAC,CAAC;QAExF,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QACnD,MAAM,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;IACzD,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC,yCAAyC,EAAE,KAAK,IAAI,EAAE;QACzD,4EAA4E;QAC5E,MAAM,OAAO,GAAG,iBAAK,CAAC,KAAK,EAAE,CAAC;QAE9B,OAAO,CAAC,QAAQ,CAAC,OAAO,EAAE,KAAK,EAAE,IAAU,EAAE,EAAE;YAC7C,IAAI,CAAC,MAAM,CACT,8GAA8G,CAC/G,CAAC;QACJ,CAAC,CAAC,CAAC;QAEH,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,YAAY,CAAC,6CAA6C,CAAC,CAAC;QAE1F,8FAA8F;QAC9F,MAAM,OAAO,CAAC,QAAQ,CAAC;YACrB,YAAY,EAAE,CAAC,sEAAsE,CAAC;YACtF,YAAY,EAAE,CAAC,2DAA2D,CAAC;SAC5E,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}