@jambonz/sdk 0.8.2 → 0.8.3
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/dist/types/index.cjs.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../../src/types/llm-vendors.generated.ts"],"names":[],"mappings":";;;AAQO,IAAM,WAAA,GAAc;AAAA,EACzB,QAAA;AAAA,EACA,WAAA;AAAA,EACA,QAAA;AAAA,EACA,eAAA;AAAA,EACA,eAAA;AAAA,EACA,SAAA;AAAA,EACA,UAAA;AAAA,EACA,SAAA;AAAA,EACA,cAAA;AAAA,EACA,MAAA;AAAA,EACA,aAAA;AAAA,EACA,UAAA;AAAA,EACA;AACF","file":"index.cjs","sourcesContent":["// AUTO-GENERATED — DO NOT EDIT BY HAND.\n// Source of truth: @jambonz/schema@0.3.
|
|
1
|
+
{"version":3,"sources":["../../src/types/llm-vendors.generated.ts"],"names":[],"mappings":";;;AAQO,IAAM,WAAA,GAAc;AAAA,EACzB,QAAA;AAAA,EACA,WAAA;AAAA,EACA,QAAA;AAAA,EACA,eAAA;AAAA,EACA,eAAA;AAAA,EACA,SAAA;AAAA,EACA,UAAA;AAAA,EACA,SAAA;AAAA,EACA,cAAA;AAAA,EACA,MAAA;AAAA,EACA,aAAA;AAAA,EACA,UAAA;AAAA,EACA;AACF","file":"index.cjs","sourcesContent":["// AUTO-GENERATED — DO NOT EDIT BY HAND.\n// Source of truth: @jambonz/schema@0.3.19 verbs/agent.schema.json (llm.vendor.enum)\n// Regenerate with: npm run gen:types\n//\n// This file derives the LLM vendor list from the JSON schema so the SDK's\n// types never drift from the schema when a new vendor is added.\n\n/** Supported LLM vendors for the agent verb, derived from the schema enum. */\nexport const LLM_VENDORS = [\n 'openai',\n 'anthropic',\n 'google',\n 'vertex-gemini',\n 'vertex-openai',\n 'bedrock',\n 'deepseek',\n 'baseten',\n 'azure-openai',\n 'groq',\n 'huggingface',\n 'moonshot',\n 'zai',\n] as const;\n\n/** Union of LLM vendor ids accepted by the agent verb's `llm.vendor`. */\nexport type LlmVendor = (typeof LLM_VENDORS)[number];\n"]}
|
package/dist/types/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"sources":["../../src/types/llm-vendors.generated.ts"],"names":[],"mappings":";AAQO,IAAM,WAAA,GAAc;AAAA,EACzB,QAAA;AAAA,EACA,WAAA;AAAA,EACA,QAAA;AAAA,EACA,eAAA;AAAA,EACA,eAAA;AAAA,EACA,SAAA;AAAA,EACA,UAAA;AAAA,EACA,SAAA;AAAA,EACA,cAAA;AAAA,EACA,MAAA;AAAA,EACA,aAAA;AAAA,EACA,UAAA;AAAA,EACA;AACF","file":"index.js","sourcesContent":["// AUTO-GENERATED — DO NOT EDIT BY HAND.\n// Source of truth: @jambonz/schema@0.3.
|
|
1
|
+
{"version":3,"sources":["../../src/types/llm-vendors.generated.ts"],"names":[],"mappings":";AAQO,IAAM,WAAA,GAAc;AAAA,EACzB,QAAA;AAAA,EACA,WAAA;AAAA,EACA,QAAA;AAAA,EACA,eAAA;AAAA,EACA,eAAA;AAAA,EACA,SAAA;AAAA,EACA,UAAA;AAAA,EACA,SAAA;AAAA,EACA,cAAA;AAAA,EACA,MAAA;AAAA,EACA,aAAA;AAAA,EACA,UAAA;AAAA,EACA;AACF","file":"index.js","sourcesContent":["// AUTO-GENERATED — DO NOT EDIT BY HAND.\n// Source of truth: @jambonz/schema@0.3.19 verbs/agent.schema.json (llm.vendor.enum)\n// Regenerate with: npm run gen:types\n//\n// This file derives the LLM vendor list from the JSON schema so the SDK's\n// types never drift from the schema when a new vendor is added.\n\n/** Supported LLM vendors for the agent verb, derived from the schema enum. */\nexport const LLM_VENDORS = [\n 'openai',\n 'anthropic',\n 'google',\n 'vertex-gemini',\n 'vertex-openai',\n 'bedrock',\n 'deepseek',\n 'baseten',\n 'azure-openai',\n 'groq',\n 'huggingface',\n 'moonshot',\n 'zai',\n] as const;\n\n/** Union of LLM vendor ids accepted by the agent verb's `llm.vendor`. */\nexport type LlmVendor = (typeof LLM_VENDORS)[number];\n"]}
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# Conference Supervision
|
|
2
|
+
|
|
3
|
+
Monitor, coach, and barge into live conferences, and tap a room's audio for
|
|
4
|
+
transcription — the core patterns behind a call-center supervision tool,
|
|
5
|
+
distilled into two small files.
|
|
6
|
+
|
|
7
|
+
A complete reference application built on these patterns (React console,
|
|
8
|
+
diarized live transcript, closed-loop e2e tests) is at
|
|
9
|
+
https://github.com/jambonz/room-monitor — see its `docs/ADAPTING.md`.
|
|
10
|
+
|
|
11
|
+
## What It Demonstrates
|
|
12
|
+
|
|
13
|
+
- **Tagging members** — `memberTag: 'agent'` at join, and mid-call
|
|
14
|
+
`tag`/`untag` via `injectCommand('conf:participant-action', ...)`
|
|
15
|
+
- **The supervisor leg** — one conference member whose join options and
|
|
16
|
+
participant actions produce three modes: silent monitor (`joinMuted`),
|
|
17
|
+
coach (audio delivered only to `agent`-tagged members), and barge-in
|
|
18
|
+
- **Mid-call mode switching** — `conferenceParticipantAction`
|
|
19
|
+
(`coach`/`uncoach`) + `conf_mute_status` via the REST client: no re-dial,
|
|
20
|
+
the room is never interrupted
|
|
21
|
+
- **Conference listen fork** — jambonz streams the room's mixed audio (L16
|
|
22
|
+
PCM) to your WebSocket for transcription/AI; your `metadata` arrives
|
|
23
|
+
verbatim as the fork's first text frame
|
|
24
|
+
- **Application env vars** — the caller flow's room name (`ROOM_NAME`) is
|
|
25
|
+
declared via OPTIONS discovery so operators edit it from the jambonz portal
|
|
26
|
+
|
|
27
|
+
## Prerequisites
|
|
28
|
+
|
|
29
|
+
- A jambonz account with API credentials
|
|
30
|
+
- Three applications pointed at this app's paths (or one application and
|
|
31
|
+
custom `X-` headers — see the reference app): `/caller`, `/agent`,
|
|
32
|
+
`/supervisor`
|
|
33
|
+
- Conference-level listen (`/Conferences/{name}/listen`) requires a jambonz
|
|
34
|
+
release with MediaJam-based conferencing that includes it
|
|
35
|
+
|
|
36
|
+
## Environment Variables
|
|
37
|
+
|
|
38
|
+
- `JAMBONZ_BASE_URL` — jambonz API URL (default: `https://api.jambonz.us`)
|
|
39
|
+
- `JAMBONZ_ACCOUNT_SID` — your account SID
|
|
40
|
+
- `JAMBONZ_API_KEY` — your API key
|
|
41
|
+
- `FORK_URL` — public ws(s):// URL of this app's `/fork` path (the media
|
|
42
|
+
server dials out to it)
|
|
43
|
+
|
|
44
|
+
## Files
|
|
45
|
+
|
|
46
|
+
- `ws-app.ts` — the jambonz application: caller/agent/supervisor call flows +
|
|
47
|
+
the audio-fork sink
|
|
48
|
+
- `monitor.ts` — REST-side supervision driver: list live rooms, switch the
|
|
49
|
+
supervisor's mode (monitor → coach → barge), tag/untag a participant,
|
|
50
|
+
start/stop the transcription fork
|
|
51
|
+
|
|
52
|
+
## Try It
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
npm install @jambonz/sdk tsx
|
|
56
|
+
npx tsx ws-app.ts # the application (port 3000)
|
|
57
|
+
npx tsx monitor.ts # walk a live room through the supervision modes
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Place two calls into a room (one via `/agent`, one via `/caller`), then run
|
|
61
|
+
`monitor.ts` with the supervisor's call_sid to step through the modes.
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
import { JambonzClient } from '@jambonz/sdk/client';
|
|
2
|
+
|
|
3
|
+
/*
|
|
4
|
+
* Conference supervision — the REST-side driver.
|
|
5
|
+
*
|
|
6
|
+
* Walks a live room through the supervision modes using mid-call commands on
|
|
7
|
+
* the supervisor's existing leg (started via ws-app.ts /supervisor). Nothing
|
|
8
|
+
* here re-dials or interrupts the room.
|
|
9
|
+
*
|
|
10
|
+
* Usage:
|
|
11
|
+
* JAMBONZ_ACCOUNT_SID=... JAMBONZ_API_KEY=... \
|
|
12
|
+
* npx tsx monitor.ts <supervisor_call_sid> [room_name]
|
|
13
|
+
*/
|
|
14
|
+
|
|
15
|
+
const baseUrl = process.env.JAMBONZ_BASE_URL || 'https://api.jambonz.us';
|
|
16
|
+
const accountSid = process.env.JAMBONZ_ACCOUNT_SID || '';
|
|
17
|
+
const apiKey = process.env.JAMBONZ_API_KEY || '';
|
|
18
|
+
const forkUrl = process.env.FORK_URL || 'wss://your-host/fork';
|
|
19
|
+
|
|
20
|
+
const supervisorCallSid = process.argv[2];
|
|
21
|
+
const roomName = process.argv[3] || 'support-room';
|
|
22
|
+
if (!accountSid || !apiKey || !supervisorCallSid) {
|
|
23
|
+
console.error('usage: JAMBONZ_ACCOUNT_SID=.. JAMBONZ_API_KEY=.. npx tsx monitor.ts <supervisor_call_sid> [room]');
|
|
24
|
+
process.exit(1);
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
const client = new JambonzClient({ baseUrl, accountSid, apiKey });
|
|
28
|
+
const pause = (ms: number) => new Promise((r) => setTimeout(r, ms));
|
|
29
|
+
|
|
30
|
+
/* -- discovery: what rooms are live? --------------------------------------- */
|
|
31
|
+
const conferences = await client.conferences.list();
|
|
32
|
+
console.log('live conferences:', conferences);
|
|
33
|
+
|
|
34
|
+
// On releases with the enriched listing, get participants + tags in one call:
|
|
35
|
+
// GET /Accounts/{sid}/Conferences?expand=participants
|
|
36
|
+
// → [{ id, name, durationSec, participants: [{ call_sid, label, memberTag, isAgent }] }]
|
|
37
|
+
// Derive agent counts (and whether Coach should be offered) from memberTag,
|
|
38
|
+
// and filter out memberTag === 'supervisor' legs before displaying counts.
|
|
39
|
+
|
|
40
|
+
/* -- transcription tap: stream the room mix to our websocket --------------- */
|
|
41
|
+
// jambonz only transports audio — the consumer (ws-app.ts /fork) decides what
|
|
42
|
+
// to do with it. The fork needs no participant leg, is excluded from counts,
|
|
43
|
+
// and is torn down automatically when the room ends.
|
|
44
|
+
const res = await fetch(
|
|
45
|
+
`${baseUrl}/v1/Accounts/${accountSid}/Conferences/${encodeURIComponent(roomName)}/listen`, {
|
|
46
|
+
method: 'POST',
|
|
47
|
+
headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
|
|
48
|
+
body: JSON.stringify({
|
|
49
|
+
url: forkUrl,
|
|
50
|
+
sampleRate: 16000,
|
|
51
|
+
metadata: { room: roomName, sampleRate: 16000 }, // delivered verbatim to the sink
|
|
52
|
+
}),
|
|
53
|
+
});
|
|
54
|
+
console.log(`listen fork: ${res.status}`);
|
|
55
|
+
|
|
56
|
+
/* -- the three supervision modes, as mid-call commands --------------------- */
|
|
57
|
+
|
|
58
|
+
// COACH: audio delivered only to members tagged 'agent'; the caller — and the
|
|
59
|
+
// audio fork — cannot hear it
|
|
60
|
+
console.log('coach mode: only agents hear the supervisor');
|
|
61
|
+
await client.calls.update(supervisorCallSid, {
|
|
62
|
+
conferenceParticipantAction: { action: 'coach', tag: 'agent' },
|
|
63
|
+
});
|
|
64
|
+
await client.calls.update(supervisorCallSid, { conf_mute_status: 'unmute' });
|
|
65
|
+
await pause(10000);
|
|
66
|
+
|
|
67
|
+
// BARGE-IN: heard by everyone
|
|
68
|
+
console.log('barge-in: everyone hears the supervisor');
|
|
69
|
+
await client.calls.update(supervisorCallSid, {
|
|
70
|
+
conferenceParticipantAction: { action: 'uncoach' },
|
|
71
|
+
});
|
|
72
|
+
await pause(10000);
|
|
73
|
+
|
|
74
|
+
// back to SILENT MONITOR
|
|
75
|
+
console.log('silent monitor: heard by no one');
|
|
76
|
+
await client.calls.update(supervisorCallSid, { conf_mute_status: 'mute' });
|
|
77
|
+
|
|
78
|
+
/* -- tags are dynamic too --------------------------------------------------
|
|
79
|
+
// promote/demote any live participant without a re-join; an active coach
|
|
80
|
+
// starts/stops reaching them immediately:
|
|
81
|
+
// await client.calls.update(someCallSid, {
|
|
82
|
+
// conferenceParticipantAction: { action: 'tag', tag: 'agent' },
|
|
83
|
+
// });
|
|
84
|
+
// await client.calls.update(someCallSid, {
|
|
85
|
+
// conferenceParticipantAction: { action: 'untag' },
|
|
86
|
+
// });
|
|
87
|
+
--------------------------------------------------------------------------- */
|
|
88
|
+
|
|
89
|
+
/* -- stop the transcription tap -------------------------------------------- */
|
|
90
|
+
await fetch(
|
|
91
|
+
`${baseUrl}/v1/Accounts/${accountSid}/Conferences/${encodeURIComponent(roomName)}/listen`,
|
|
92
|
+
{ method: 'DELETE', headers: { Authorization: `Bearer ${apiKey}` } });
|
|
93
|
+
console.log('listen fork stopped');
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
import http from 'http';
|
|
2
|
+
import { createEndpoint } from '@jambonz/sdk/websocket';
|
|
3
|
+
import type { Session, AudioStream } from '@jambonz/sdk/websocket';
|
|
4
|
+
|
|
5
|
+
/*
|
|
6
|
+
* Conference supervision — the jambonz application side.
|
|
7
|
+
*
|
|
8
|
+
* Three call flows on one endpoint (point one jambonz application at each
|
|
9
|
+
* path), plus the audio sink that receives a conference listen fork:
|
|
10
|
+
*
|
|
11
|
+
* /caller a normal participant; which room they join is the
|
|
12
|
+
* application's ROOM_NAME env var (portal-editable via
|
|
13
|
+
* OPTIONS discovery)
|
|
14
|
+
* /agent joins the same room tagged 'agent' — the coach target
|
|
15
|
+
* /supervisor joins muted (silent monitor); mode changes come later as
|
|
16
|
+
* mid-call participant actions (see monitor.ts)
|
|
17
|
+
* /fork receives the room's mixed audio (L16 PCM) when a
|
|
18
|
+
* conference listen fork is started (see monitor.ts)
|
|
19
|
+
*
|
|
20
|
+
* Full reference app: https://github.com/jambonz/room-monitor
|
|
21
|
+
*/
|
|
22
|
+
|
|
23
|
+
const envVars = {
|
|
24
|
+
ROOM_NAME: {
|
|
25
|
+
type: 'string' as const,
|
|
26
|
+
description: 'Conference room inbound callers join',
|
|
27
|
+
default: 'support-room',
|
|
28
|
+
},
|
|
29
|
+
};
|
|
30
|
+
|
|
31
|
+
const server = http.createServer();
|
|
32
|
+
const makeService = createEndpoint({ server, port: 3000, envVars });
|
|
33
|
+
|
|
34
|
+
const room = (session: Session): string =>
|
|
35
|
+
(session.data.env_vars as Record<string, string> | undefined)?.ROOM_NAME || 'support-room';
|
|
36
|
+
|
|
37
|
+
/* -- a normal caller ------------------------------------------------------ */
|
|
38
|
+
makeService({ path: '/caller' }).on('session:new', (session) => {
|
|
39
|
+
session
|
|
40
|
+
.answer()
|
|
41
|
+
.say({ text: 'Connecting you now.' })
|
|
42
|
+
.conference({
|
|
43
|
+
name: room(session),
|
|
44
|
+
startConferenceOnEnter: true,
|
|
45
|
+
endConferenceOnExit: false,
|
|
46
|
+
})
|
|
47
|
+
.send();
|
|
48
|
+
});
|
|
49
|
+
|
|
50
|
+
/* -- an agent: tagged, so coaching reaches them ---------------------------- */
|
|
51
|
+
makeService({ path: '/agent' }).on('session:new', (session) => {
|
|
52
|
+
session
|
|
53
|
+
.answer()
|
|
54
|
+
.conference({
|
|
55
|
+
name: room(session),
|
|
56
|
+
memberTag: 'agent', // <- the coach target; also drives supervision UIs
|
|
57
|
+
startConferenceOnEnter: true,
|
|
58
|
+
endConferenceOnExit: false,
|
|
59
|
+
})
|
|
60
|
+
.send();
|
|
61
|
+
|
|
62
|
+
// Tags are dynamic: promote/demote a live member without re-joining, e.g.
|
|
63
|
+
// session.injectCommand('conf:participant-action', { action: 'untag' });
|
|
64
|
+
// session.injectCommand('conf:participant-action', { action: 'tag', tag: 'agent' });
|
|
65
|
+
});
|
|
66
|
+
|
|
67
|
+
/* -- the supervisor: joins silent; modes switch mid-call ------------------- */
|
|
68
|
+
makeService({ path: '/supervisor' }).on('session:new', (session) => {
|
|
69
|
+
console.log(`supervisor leg ${session.callSid} — use this call_sid with monitor.ts`);
|
|
70
|
+
session
|
|
71
|
+
.answer()
|
|
72
|
+
.conference({
|
|
73
|
+
name: room(session),
|
|
74
|
+
joinMuted: true, // hears everything, heard by no one
|
|
75
|
+
memberTag: 'supervisor', // lets tooling filter this leg out of counts
|
|
76
|
+
startConferenceOnEnter: false, // never create/destroy the room being watched
|
|
77
|
+
endConferenceOnExit: false,
|
|
78
|
+
actionHook: '/conf-done',
|
|
79
|
+
})
|
|
80
|
+
.send();
|
|
81
|
+
|
|
82
|
+
session.on('/conf-done', () => {
|
|
83
|
+
session.hangup().reply();
|
|
84
|
+
});
|
|
85
|
+
});
|
|
86
|
+
|
|
87
|
+
/* -- the audio fork sink: the room mix arrives here ------------------------ */
|
|
88
|
+
makeService.audio({ path: '/fork' }).on('connection', (stream: AudioStream) => {
|
|
89
|
+
// the metadata you passed when starting the fork arrives verbatim as the
|
|
90
|
+
// first text frame — make it self-describing (room, sampleRate)
|
|
91
|
+
console.log('fork connected:', stream.metadata);
|
|
92
|
+
|
|
93
|
+
let bytes = 0;
|
|
94
|
+
stream.on('audio', (pcm: Buffer) => {
|
|
95
|
+
bytes += pcm.length;
|
|
96
|
+
// feed your STT / AI / recorder here — this is raw L16 PCM of the room
|
|
97
|
+
// mix. Note: coached (whispered) audio is never present in this stream.
|
|
98
|
+
});
|
|
99
|
+
stream.on('close', () => console.log(`fork closed after ${bytes} bytes`));
|
|
100
|
+
});
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@jambonz/sdk",
|
|
3
|
-
"version": "0.8.
|
|
3
|
+
"version": "0.8.3",
|
|
4
4
|
"description": "jambonz SDK for building voice applications — optimized for AI agents",
|
|
5
5
|
"author": "Dave Horton",
|
|
6
6
|
"license": "MIT",
|
|
@@ -98,7 +98,7 @@
|
|
|
98
98
|
"postpublish": "npm run clean-docs"
|
|
99
99
|
},
|
|
100
100
|
"dependencies": {
|
|
101
|
-
"@jambonz/schema": "^0.3.
|
|
101
|
+
"@jambonz/schema": "^0.3.19",
|
|
102
102
|
"ajv": "^8.17.1",
|
|
103
103
|
"ws": "^8.18.0"
|
|
104
104
|
},
|