@guava-ai/guava-sdk 0.4.0 → 0.4.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md
CHANGED
|
@@ -1,19 +1,61 @@
|
|
|
1
1
|
# Guava Typescript SDK
|
|
2
|
+
|
|
2
3
|
|
|
3
|
-
|
|
4
|
+
This library allows you to build Guava voice agents using TypeScript or Javascript. Currently only NodeJS is officially supported as a runtime.
|
|
4
5
|
|
|
6
|
+
## Documentation
|
|
7
|
+
|
|
8
|
+
Full documentation for the TypeScript SDK can be found at [https://docs.goguava.ai/typescript-sdk/](https://docs.goguava.ai/typescript-sdk/)
|
|
9
|
+
|
|
10
|
+
## Try an Example
|
|
11
|
+
|
|
12
|
+
Export two environment variables. You should have received these in your beta invite email.
|
|
5
13
|
```bash
|
|
6
|
-
export GUAVA_API_KEY="..."
|
|
7
|
-
export GUAVA_AGENT_NUMBER="..."
|
|
14
|
+
$ export GUAVA_API_KEY="..." # Your API key for authentication.
|
|
15
|
+
$ export GUAVA_AGENT_NUMBER="..." # A phone number for your agent to use.
|
|
8
16
|
```
|
|
9
17
|
|
|
10
|
-
|
|
11
|
-
|
|
18
|
+
Run an outbound phone call example using `npx`. Replace the phone number with your own and your agent will call you.
|
|
12
19
|
```bash
|
|
13
|
-
npx
|
|
20
|
+
$ npx @guava-ai/guava-sdk scheduling-outbound +15556667777 # Your agent will call this number.
|
|
14
21
|
```
|
|
15
22
|
|
|
16
|
-
|
|
23
|
+
## Installation
|
|
24
|
+
|
|
25
|
+
Install the SDK using your preferred package manager.
|
|
26
|
+
|
|
17
27
|
```bash
|
|
18
|
-
|
|
28
|
+
$ npm install @guava-ai/guava-sdk
|
|
29
|
+
$ yarn add @guava-ai/guava-sdk
|
|
30
|
+
$ pnpm add @guava-ai/guava-sdk
|
|
19
31
|
```
|
|
32
|
+
|
|
33
|
+
The SDK can be used with Javascript, but TypeScript is highly recommended.
|
|
34
|
+
|
|
35
|
+
## Basic Usage
|
|
36
|
+
|
|
37
|
+
The Guava SDK is primarily used by subclassing `guava.CallController`. `CallController` subclasses implement callbacks that steer the call in real-time.
|
|
38
|
+
|
|
39
|
+
You can make outbound calls using a `CallController` instance.
|
|
40
|
+
|
|
41
|
+
```typescript
|
|
42
|
+
import * as guava from "@guava-ai/guava-sdk";
|
|
43
|
+
|
|
44
|
+
// Make an outbound call with a call controller.
|
|
45
|
+
new guava.Client().createOutbound(
|
|
46
|
+
agentNumber, toNumber,
|
|
47
|
+
new MyCallController(),
|
|
48
|
+
);
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
You can also accept inbound calls using Guava. You don't need to setup a server — inbound calls can be received on your dev machine, including behind NATs and most firewalls.
|
|
52
|
+
Instead of passing a controller, you will pass a factory function that constructs a controller upon receipt of a call.
|
|
53
|
+
|
|
54
|
+
```typescript
|
|
55
|
+
// Attach a listener to the phone number.
|
|
56
|
+
// Spawn new call controllers as calls come in.
|
|
57
|
+
new guava.Client().listenInbound(
|
|
58
|
+
{ agent_number: agentNumber },
|
|
59
|
+
() => new MyCallController(),
|
|
60
|
+
);
|
|
61
|
+
```
|
|
@@ -7,28 +7,42 @@ class SchedulingController extends guava.CallController {
|
|
|
7
7
|
constructor(patientName) {
|
|
8
8
|
super();
|
|
9
9
|
this.patientName = patientName;
|
|
10
|
+
// This is a basic appointment time selector that pulls from a mock list of appointments.
|
|
11
|
+
// In production, you would likely replace this with your own agentic scheduling backend.
|
|
10
12
|
this.datetimeFilter = new DatetimeFilter({
|
|
11
13
|
sourceList: mockAppointmentsForFuture(),
|
|
12
14
|
});
|
|
15
|
+
// Use setPersona to set basic information about the agent, as well as it's high-level purpose.
|
|
13
16
|
this.setPersona({
|
|
14
17
|
organizationName: "Bright Smile Dental",
|
|
15
18
|
agentName: "Grace",
|
|
16
19
|
agentPurpose: `You are calling ${patientName} to help them schedule a dental appointment`,
|
|
17
20
|
});
|
|
21
|
+
// reachPerson is a convenience function to confirm that we are talking to the intended recipient.
|
|
18
22
|
this.reachPerson(this.patientName, {
|
|
19
23
|
onSuccess: () => this.scheduleRecipient(),
|
|
20
24
|
onFailure: () => this.recipientUnavailable(),
|
|
21
25
|
});
|
|
22
26
|
}
|
|
23
27
|
scheduleRecipient() {
|
|
28
|
+
// In the branch where we reached the intended participant,
|
|
29
|
+
// set a task to collect the desired appointment time.
|
|
24
30
|
this.setTask({
|
|
31
|
+
// The check list is an ordered list of items for the agent to go through.
|
|
25
32
|
checklist: [
|
|
33
|
+
// guava.Say instructions are verbatim.
|
|
26
34
|
guava.Say("Let me look to see what appointment times we have available."),
|
|
35
|
+
// We have one field to collect, which is the appointment_time.
|
|
27
36
|
guava.Field({
|
|
28
37
|
key: "appointment_time",
|
|
29
38
|
fieldType: "calendar_slot",
|
|
30
39
|
description: "Find a time that works for the caller",
|
|
40
|
+
// This field has a choice generator attached. The agent will invoke this function
|
|
41
|
+
// with a natural language query, allowing the caller to select between the different options.
|
|
42
|
+
// The agent can potentially invoke the callback multiple times if the caller rejects the options
|
|
43
|
+
// or provides a new query.
|
|
31
44
|
choiceGenerator: async (query) => {
|
|
45
|
+
// Use the simple DatetimeFilter class we instantiated earlier.
|
|
32
46
|
const result = await this.datetimeFilter.filter(query, { maxResults: 3 });
|
|
33
47
|
this.logger.info("Choice generator results: %s", JSON.stringify(result));
|
|
34
48
|
return result;
|
|
@@ -42,6 +56,7 @@ class SchedulingController extends guava.CallController {
|
|
|
42
56
|
this.hangup("Apologize for your mistake and hang up the call.");
|
|
43
57
|
}
|
|
44
58
|
onSessionDone() {
|
|
59
|
+
// This callback is invoked at the end of the bot session.
|
|
45
60
|
const selectedTime = this.getField("appointment_time");
|
|
46
61
|
if (selectedTime) {
|
|
47
62
|
this.logger.info(`Appointment confirmed for: ${selectedTime}`);
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"scheduling-outbound.js","sourceRoot":"","sources":["../../examples/scheduling-outbound.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,iBAAiB,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAC;AAEnE,MAAM,oBAAqB,SAAQ,KAAK,CAAC,cAAc;IACpC,WAAW,CAAS;IACpB,cAAc,CAAiB;IAEhD,YAAY,WAAmB;QAC7B,KAAK,EAAE,CAAC;QAER,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;
|
|
1
|
+
{"version":3,"file":"scheduling-outbound.js","sourceRoot":"","sources":["../../examples/scheduling-outbound.ts"],"names":[],"mappings":"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"}
|
package/dist/package.json
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@guava-ai/guava-sdk",
|
|
3
|
-
"
|
|
3
|
+
"description": "The official TypeScript SDK for building Guava voice agents.",
|
|
4
|
+
"homepage": "https://docs.goguava.ai/typescript-sdk/",
|
|
5
|
+
"version": "0.4.2",
|
|
4
6
|
"type": "module",
|
|
5
7
|
"main": "dist/src/index.js",
|
|
6
8
|
"types": "dist/src/index.d.ts",
|
|
@@ -10,16 +10,21 @@ class SchedulingController extends guava.CallController {
|
|
|
10
10
|
super();
|
|
11
11
|
|
|
12
12
|
this.patientName = patientName;
|
|
13
|
+
|
|
14
|
+
// This is a basic appointment time selector that pulls from a mock list of appointments.
|
|
15
|
+
// In production, you would likely replace this with your own agentic scheduling backend.
|
|
13
16
|
this.datetimeFilter = new DatetimeFilter({
|
|
14
17
|
sourceList: mockAppointmentsForFuture(),
|
|
15
18
|
});
|
|
16
19
|
|
|
20
|
+
// Use setPersona to set basic information about the agent, as well as it's high-level purpose.
|
|
17
21
|
this.setPersona({
|
|
18
22
|
organizationName: "Bright Smile Dental",
|
|
19
23
|
agentName: "Grace",
|
|
20
24
|
agentPurpose: `You are calling ${patientName} to help them schedule a dental appointment`,
|
|
21
25
|
});
|
|
22
26
|
|
|
27
|
+
// reachPerson is a convenience function to confirm that we are talking to the intended recipient.
|
|
23
28
|
this.reachPerson(this.patientName, {
|
|
24
29
|
onSuccess: () => this.scheduleRecipient(),
|
|
25
30
|
onFailure: () => this.recipientUnavailable(),
|
|
@@ -27,15 +32,26 @@ class SchedulingController extends guava.CallController {
|
|
|
27
32
|
}
|
|
28
33
|
|
|
29
34
|
private scheduleRecipient() {
|
|
35
|
+
// In the branch where we reached the intended participant,
|
|
36
|
+
// set a task to collect the desired appointment time.
|
|
30
37
|
this.setTask(
|
|
31
38
|
{
|
|
39
|
+
// The check list is an ordered list of items for the agent to go through.
|
|
32
40
|
checklist: [
|
|
41
|
+
// guava.Say instructions are verbatim.
|
|
33
42
|
guava.Say("Let me look to see what appointment times we have available."),
|
|
43
|
+
// We have one field to collect, which is the appointment_time.
|
|
34
44
|
guava.Field({
|
|
35
45
|
key: "appointment_time",
|
|
36
46
|
fieldType: "calendar_slot",
|
|
37
47
|
description: "Find a time that works for the caller",
|
|
48
|
+
|
|
49
|
+
// This field has a choice generator attached. The agent will invoke this function
|
|
50
|
+
// with a natural language query, allowing the caller to select between the different options.
|
|
51
|
+
// The agent can potentially invoke the callback multiple times if the caller rejects the options
|
|
52
|
+
// or provides a new query.
|
|
38
53
|
choiceGenerator: async (query: string) => {
|
|
54
|
+
// Use the simple DatetimeFilter class we instantiated earlier.
|
|
39
55
|
const result = await this.datetimeFilter.filter(query, { maxResults: 3 });
|
|
40
56
|
this.logger.info("Choice generator results: %s", JSON.stringify(result));
|
|
41
57
|
return result;
|
|
@@ -53,6 +69,7 @@ class SchedulingController extends guava.CallController {
|
|
|
53
69
|
}
|
|
54
70
|
|
|
55
71
|
override onSessionDone() {
|
|
72
|
+
// This callback is invoked at the end of the bot session.
|
|
56
73
|
const selectedTime = this.getField("appointment_time");
|
|
57
74
|
if (selectedTime) {
|
|
58
75
|
this.logger.info(`Appointment confirmed for: ${selectedTime}`);
|
package/package.json
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@guava-ai/guava-sdk",
|
|
3
|
-
"
|
|
3
|
+
"description": "The official TypeScript SDK for building Guava voice agents.",
|
|
4
|
+
"homepage": "https://docs.goguava.ai/typescript-sdk/",
|
|
5
|
+
"version": "0.4.2",
|
|
4
6
|
"type": "module",
|
|
5
7
|
"main": "dist/src/index.js",
|
|
6
8
|
"types": "dist/src/index.d.ts",
|