@jambonz/sdk 0.12.0 → 0.13.0

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.
Files changed (40) hide show
  1. package/dist/client/index.d.cts +2 -2
  2. package/dist/client/index.d.ts +2 -2
  3. package/dist/harness/index.cjs +843 -0
  4. package/dist/harness/index.cjs.map +1 -0
  5. package/dist/harness/index.d.cts +503 -0
  6. package/dist/harness/index.d.ts +503 -0
  7. package/dist/harness/index.js +832 -0
  8. package/dist/harness/index.js.map +1 -0
  9. package/dist/index.cjs +14 -0
  10. package/dist/index.cjs.map +1 -1
  11. package/dist/index.d.cts +3 -3
  12. package/dist/index.d.ts +3 -3
  13. package/dist/index.js +14 -0
  14. package/dist/index.js.map +1 -1
  15. package/dist/{rest-0m9Hgjmn.d.cts → rest-B-7QX4TM.d.cts} +1 -1
  16. package/dist/{rest-CqS2POQv.d.ts → rest-r1vLsPCg.d.ts} +1 -1
  17. package/dist/types/index.d.cts +2 -2
  18. package/dist/types/index.d.ts +2 -2
  19. package/dist/{verb-builder-C1id83_f.d.cts → verb-builder-UVx6Exh1.d.ts} +3 -1
  20. package/dist/{verb-builder-YFevoXCs.d.ts → verb-builder-tc7P_MTy.d.cts} +3 -1
  21. package/dist/{verbs-DQ6zJ0bn.d.cts → verbs-D461pHTq.d.cts} +52 -6
  22. package/dist/{verbs-DQ6zJ0bn.d.ts → verbs-D461pHTq.d.ts} +52 -6
  23. package/dist/webhook/index.cjs +6 -0
  24. package/dist/webhook/index.cjs.map +1 -1
  25. package/dist/webhook/index.d.cts +2 -2
  26. package/dist/webhook/index.d.ts +2 -2
  27. package/dist/webhook/index.js +6 -0
  28. package/dist/webhook/index.js.map +1 -1
  29. package/dist/websocket/index.cjs +14 -0
  30. package/dist/websocket/index.cjs.map +1 -1
  31. package/dist/websocket/index.d.cts +5 -3
  32. package/dist/websocket/index.d.ts +5 -3
  33. package/dist/websocket/index.js +14 -0
  34. package/dist/websocket/index.js.map +1 -1
  35. package/examples/harness/README.md +73 -0
  36. package/examples/harness/harness.ts +99 -0
  37. package/examples/harness/package.json +21 -0
  38. package/examples/harness/tsconfig.json +12 -0
  39. package/examples/openai-realtime/ws-app.ts +18 -14
  40. package/package.json +13 -2
@@ -0,0 +1,99 @@
1
+ /**
2
+ * A minimal jambonz custom harness.
3
+ *
4
+ * Out of the box createHarness() is a pass-through: it sends the conversation to an OpenAI-compatible
5
+ * model and streams the reply back to jambonz. This example adds three small hooks:
6
+ * - beforeModel routes each turn by keyword to a procedure with its own prompt and tools
7
+ * - a tool of its own (lookup_outage), run in-process
8
+ * - checkSentence, which never lets a long digit string be read out
9
+ */
10
+ import { createHarness } from '@jambonz/sdk/harness';
11
+ import { pino } from 'pino';
12
+
13
+ const logger = pino({ level: process.env.LOG_LEVEL ?? 'info' });
14
+ const port = Number(process.env.PORT ?? 8080);
15
+
16
+ // pretend outage data; a real harness would call its own systems here
17
+ const OUTAGES: Record<string, { area: string; until: string }> = {
18
+ 'main street': { area: 'Main Street', until: '5 pm today' },
19
+ };
20
+
21
+ const PROCEDURES = {
22
+ outage: {
23
+ keywords: ['outage', 'power', 'electricity', 'lights'],
24
+ prompt:
25
+ 'You help callers report and check power outages for Acme Energy. Ask for the street if you do not have it, ' +
26
+ 'then use lookup_outage. Keep answers to one or two short sentences; they are spoken aloud.',
27
+ tools: ['lookup_outage'],
28
+ },
29
+ billing: {
30
+ keywords: ['bill', 'billing', 'payment', 'charge', 'invoice'],
31
+ prompt:
32
+ 'You answer billing questions for Acme Energy. You cannot see account details; offer to transfer the caller ' +
33
+ 'to billing if they need their account. Keep answers short; they are spoken aloud.',
34
+ tools: [] as string[],
35
+ },
36
+ };
37
+
38
+ function route(text: string): keyof typeof PROCEDURES | undefined {
39
+ const lower = text.toLowerCase();
40
+ return (Object.keys(PROCEDURES) as Array<keyof typeof PROCEDURES>).find((p) =>
41
+ PROCEDURES[p].keywords.some((k) => lower.includes(k)),
42
+ );
43
+ }
44
+
45
+ createHarness({
46
+ logger,
47
+ apiKey: process.env.HARNESS_API_KEY, // the key in the jambonz Harness credential
48
+ model: process.env.MODEL ?? 'gpt-4.1-mini',
49
+ instructions:
50
+ 'You answer phone calls for Acme Energy. Be warm and brief: one or two sentences, plain text, no lists or markdown.',
51
+ greeting: 'Thanks for calling Acme Energy. How can I help you today?',
52
+
53
+ onSessionStart(session, ctx) {
54
+ ctx.log.info({ from: session.from, metadata: session.metadata }, 'new call');
55
+ },
56
+
57
+ // routing: once a procedure is chosen it stays in force for later turns
58
+ beforeModel(turn, ctx) {
59
+ const picked = route(turn.text) ?? (ctx.state.get('procedure') as keyof typeof PROCEDURES | undefined);
60
+ if (!picked) return { route: 'chat' };
61
+ ctx.state.set('procedure', picked);
62
+ const p = PROCEDURES[picked];
63
+ ctx.record('procedures', [picked]);
64
+ return { route: 'procedure', instructions: p.prompt, tools: p.tools };
65
+ },
66
+
67
+ tools: {
68
+ lookup_outage: {
69
+ description: 'Find a reported power outage on a street',
70
+ parameters: {
71
+ type: 'object',
72
+ properties: { street: { type: 'string', description: 'Street name, e.g. "Main Street"' } },
73
+ required: ['street'],
74
+ },
75
+ run: ({ street }) => {
76
+ const hit = OUTAGES[String(street).toLowerCase()];
77
+ return hit ? { outage: true, ...hit } : { outage: false };
78
+ },
79
+ },
80
+ },
81
+
82
+ // never read out anything that looks like an account or card number
83
+ checkSentence: (sentence) => (/\d{6,}/.test(sentence) ? "I can't read that number out over the phone." : true),
84
+
85
+ onEvent: {
86
+ // the caller pressed 0: hand them to a person, if an operator number is configured
87
+ async dtmf(e, ctx) {
88
+ if (e.digits !== '0' || !process.env.OPERATOR_NUMBER) return;
89
+ ctx.say('Connecting you to a person now.');
90
+ const result = await ctx.command('transfer', { to: process.env.OPERATOR_NUMBER });
91
+ if (!result.ok) ctx.log.warn({ error: result.error }, 'transfer to operator failed');
92
+ },
93
+ },
94
+ })
95
+ .listen(port)
96
+ .catch((err) => {
97
+ logger.error({ err }, 'could not start the harness');
98
+ process.exit(1);
99
+ });
@@ -0,0 +1,21 @@
1
+ {
2
+ "name": "jambonz-harness-example",
3
+ "version": "1.0.0",
4
+ "private": true,
5
+ "description": "A minimal jambonz custom harness built with @jambonz/sdk/harness",
6
+ "type": "module",
7
+ "scripts": {
8
+ "start": "tsx harness.ts",
9
+ "build": "tsc",
10
+ "typecheck": "tsc --noEmit"
11
+ },
12
+ "dependencies": {
13
+ "@jambonz/sdk": "^0.13.0",
14
+ "pino": "^9.14.0"
15
+ },
16
+ "devDependencies": {
17
+ "@types/node": "^22.0.0",
18
+ "tsx": "^4.19.0",
19
+ "typescript": "^5.6.0"
20
+ }
21
+ }
@@ -0,0 +1,12 @@
1
+ {
2
+ "compilerOptions": {
3
+ "target": "ES2022",
4
+ "module": "Node16",
5
+ "moduleResolution": "node16",
6
+ "strict": true,
7
+ "esModuleInterop": true,
8
+ "skipLibCheck": true,
9
+ "outDir": "dist"
10
+ },
11
+ "include": ["harness.ts"]
12
+ }
@@ -30,7 +30,7 @@ svc.on('session:new', (session) => {
30
30
 
31
31
  session
32
32
  .on('/event', (_evt: Record<string, any>) => {
33
- // OpenAI Realtime events (conversation.item.*, response.audio_transcript.done, etc.)
33
+ // OpenAI Realtime events (conversation.item.*, response.output_audio_transcript.done, etc.)
34
34
  })
35
35
  .on('/toolCall', async (evt: Record<string, any>) => {
36
36
  const { name, args, tool_call_id } = evt;
@@ -78,26 +78,25 @@ svc.on('session:new', (session) => {
78
78
  .answer()
79
79
  .pause({ length: 1 })
80
80
  .openai_s2s({
81
- model: 'gpt-4o-realtime-preview-2024-12-17',
81
+ model: 'gpt-realtime-2.1',
82
82
  auth: { apiKey },
83
83
  actionHook: '/final',
84
84
  eventHook: '/event',
85
85
  toolHook: '/toolCall',
86
86
  events: [
87
87
  'conversation.item.*',
88
- 'response.audio_transcript.done',
88
+ 'response.output_audio_transcript.done',
89
89
  'input_audio_buffer.committed',
90
90
  ],
91
91
  llmOptions: {
92
92
  response_create: {
93
- modalities: ['text', 'audio'],
94
- instructions: 'Please assist the user with their request.',
95
- voice: 'alloy',
96
- output_audio_format: 'pcm16',
97
- temperature: 0.8,
93
+ output_modalities: ['audio'],
94
+ instructions: 'Greet the caller and ask how you can help.',
98
95
  max_output_tokens: 4096,
99
96
  },
100
97
  session_update: {
98
+ type: 'realtime',
99
+ instructions: 'Please assist the user with their request.',
101
100
  tools: [
102
101
  {
103
102
  name: 'get_weather',
@@ -114,12 +113,17 @@ svc.on('session:new', (session) => {
114
113
  },
115
114
  ],
116
115
  tool_choice: 'auto',
117
- input_audio_transcription: { model: 'whisper-1' },
118
- turn_detection: {
119
- type: 'server_vad',
120
- threshold: 0.8,
121
- prefix_padding_ms: 300,
122
- silence_duration_ms: 500,
116
+ audio: {
117
+ input: {
118
+ transcription: { model: 'gpt-live-transcribe' },
119
+ turn_detection: {
120
+ type: 'server_vad',
121
+ threshold: 0.8,
122
+ prefix_padding_ms: 300,
123
+ silence_duration_ms: 500,
124
+ },
125
+ },
126
+ output: { voice: 'alloy' },
123
127
  },
124
128
  },
125
129
  },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jambonz/sdk",
3
- "version": "0.12.0",
3
+ "version": "0.13.0",
4
4
  "description": "jambonz SDK for building voice applications — optimized for AI agents",
5
5
  "author": "Dave Horton",
6
6
  "license": "MIT",
@@ -74,6 +74,16 @@
74
74
  "types": "./dist/types/index.d.cts",
75
75
  "default": "./dist/types/index.cjs"
76
76
  }
77
+ },
78
+ "./harness": {
79
+ "import": {
80
+ "types": "./dist/harness/index.d.ts",
81
+ "default": "./dist/harness/index.js"
82
+ },
83
+ "require": {
84
+ "types": "./dist/harness/index.d.cts",
85
+ "default": "./dist/harness/index.cjs"
86
+ }
77
87
  }
78
88
  },
79
89
  "files": [
@@ -95,8 +105,9 @@
95
105
  "postpublish": "npm run clean-docs"
96
106
  },
97
107
  "dependencies": {
98
- "@jambonz/schema": "^0.4.29",
108
+ "@jambonz/schema": "^0.4.46",
99
109
  "ajv": "^8.17.1",
110
+ "pino": "^9.14.0",
100
111
  "ws": "^8.18.0"
101
112
  },
102
113
  "devDependencies": {