@signalwire/sdk 3.7.2 → 3.9.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.
- package/CHANGELOG.md +154 -0
- package/README.md +1 -0
- package/dist/AgentBase.d.ts +107 -2
- package/dist/AgentBase.js +259 -13
- package/dist/AgentBase.js.map +1 -1
- package/dist/AiEvents.d.ts +70 -0
- package/dist/AiEvents.js +94 -0
- package/dist/AiEvents.js.map +1 -0
- package/dist/ContextBuilder.d.ts +181 -9
- package/dist/ContextBuilder.js +407 -9
- package/dist/ContextBuilder.js.map +1 -1
- package/dist/FunctionResult.d.ts +129 -0
- package/dist/FunctionResult.js +170 -0
- package/dist/FunctionResult.js.map +1 -1
- package/dist/PostPrompt.d.ts +19 -0
- package/dist/PostPrompt.js +43 -0
- package/dist/PostPrompt.js.map +1 -1
- package/dist/SWMLService.d.ts +97 -1
- package/dist/SWMLService.js +129 -2
- package/dist/SWMLService.js.map +1 -1
- package/dist/SemanticGate.d.ts +61 -1
- package/dist/SemanticGate.js +108 -15
- package/dist/SemanticGate.js.map +1 -1
- package/dist/SwaigFunction.d.ts +85 -9
- package/dist/SwaigFunction.js +214 -58
- package/dist/SwaigFunction.js.map +1 -1
- package/dist/ToolMiddleware.d.ts +82 -0
- package/dist/ToolMiddleware.js +131 -0
- package/dist/ToolMiddleware.js.map +1 -0
- package/dist/TypeInference.d.ts +1 -1
- package/dist/TypeInference.js.map +1 -1
- package/dist/cli/tsdocs/api-index.json +1 -1
- package/dist/cli/tsdocs/topics.js +24 -4
- package/dist/cli/tsdocs/topics.js.map +1 -1
- package/dist/index.d.ts +22 -8
- package/dist/index.js +15 -5
- package/dist/index.js.map +1 -1
- package/dist/llms.txt +1 -0
- package/dist/patterns/Proposal.d.ts +146 -0
- package/dist/patterns/Proposal.js +212 -0
- package/dist/patterns/Proposal.js.map +1 -0
- package/dist/patterns/RequestList.d.ts +136 -0
- package/dist/patterns/RequestList.js +169 -0
- package/dist/patterns/RequestList.js.map +1 -0
- package/dist/skills/SkillBase.d.ts +24 -1
- package/dist/skills/SkillBase.js +12 -1
- package/dist/skills/SkillBase.js.map +1 -1
- package/dist/speech/numbers.d.ts +66 -0
- package/dist/speech/numbers.js +281 -0
- package/dist/speech/numbers.js.map +1 -0
- package/dist/speech/spelling.d.ts +71 -0
- package/dist/speech/spelling.js +294 -0
- package/dist/speech/spelling.js.map +1 -0
- package/dist/testing/CallSimulator.d.ts +281 -0
- package/dist/testing/CallSimulator.js +666 -0
- package/dist/testing/CallSimulator.js.map +1 -0
- package/docs/agent-guide.md +2 -2
- package/docs/api-reference.md +277 -20
- package/docs/architecture.md +8 -4
- package/docs/cli-guide.md +2 -0
- package/docs/contexts-guide.md +45 -3
- package/docs/conversation_patterns.md +257 -0
- package/docs/mcp_integration.md +1 -1
- package/docs/programmatically_governed_inference.md +1 -1
- package/docs/swaig-reference.md +95 -3
- package/package.json +1 -1
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What the caller asked for while the agent was busy with something else.
|
|
3
|
+
*
|
|
4
|
+
* A caller in the middle of one task often asks for another: "and can you also
|
|
5
|
+
* check my balance?" Taking it up at once loses the first task; ignoring it
|
|
6
|
+
* loses the second. A tool notes the request, and the agent tells the caller
|
|
7
|
+
* it's noted for right after this. When the first task is done, the step's
|
|
8
|
+
* text, which shows the list, has the agent take up the next one.
|
|
9
|
+
*
|
|
10
|
+
* The list lives in the call's `global_data`, so it lasts for the call and a
|
|
11
|
+
* step's text can show it, as `${global_data.<key>_text}`.
|
|
12
|
+
*/
|
|
13
|
+
import { FunctionResult } from '../FunctionResult.js';
|
|
14
|
+
/** One request the caller made. */
|
|
15
|
+
export interface NotedRequest {
|
|
16
|
+
/** The kind of request, one of the app's (it picks the opener). */
|
|
17
|
+
kind: string;
|
|
18
|
+
/** What it's about, in a few words. */
|
|
19
|
+
about: string;
|
|
20
|
+
}
|
|
21
|
+
/** Options for a {@link RequestList}. */
|
|
22
|
+
export interface RequestListOptions {
|
|
23
|
+
/**
|
|
24
|
+
* How the agent opens each kind of request when it takes it up, keyed by
|
|
25
|
+
* kind, with `{about}` for what it's about. A kind without one opens with
|
|
26
|
+
* what it's about.
|
|
27
|
+
*/
|
|
28
|
+
openers?: Record<string, string>;
|
|
29
|
+
/** The first line of the list's text. Default "Noted for right after this:". */
|
|
30
|
+
heading?: string;
|
|
31
|
+
}
|
|
32
|
+
/**
|
|
33
|
+
* The caller's requests to come back to, in the order they asked.
|
|
34
|
+
*
|
|
35
|
+
* @example
|
|
36
|
+
* ```ts
|
|
37
|
+
* import { AgentBase, RequestList } from '@signalwire/sdk';
|
|
38
|
+
*
|
|
39
|
+
* const agent = new AgentBase({ name: 'bank' });
|
|
40
|
+
* const later = new RequestList('later', {
|
|
41
|
+
* openers: {
|
|
42
|
+
* balance: 'You also asked about your balance.',
|
|
43
|
+
* question: 'You had a question: {about}.',
|
|
44
|
+
* },
|
|
45
|
+
* });
|
|
46
|
+
*
|
|
47
|
+
* agent.setGlobalData(later.defaults());
|
|
48
|
+
* agent.defineTool({
|
|
49
|
+
* name: 'note_request',
|
|
50
|
+
* description: 'Note a request to come back to',
|
|
51
|
+
* parameters: {
|
|
52
|
+
* type: 'object',
|
|
53
|
+
* properties: { kind: { type: 'string' }, about: { type: 'string' } },
|
|
54
|
+
* required: ['kind', 'about'],
|
|
55
|
+
* },
|
|
56
|
+
* handler: (args, rawData) => later.note(rawData, String(args.kind), String(args.about)),
|
|
57
|
+
* });
|
|
58
|
+
* const ctx = agent.defineContexts().addContext('default');
|
|
59
|
+
* ctx.addStep('take_order').setText("Take the caller's order.\n\n${global_data.later_text}");
|
|
60
|
+
* ```
|
|
61
|
+
*
|
|
62
|
+
* A step's text is expanded when the step is entered, so the list it shows is
|
|
63
|
+
* the one from then; the model hears of each new request in the tool result.
|
|
64
|
+
* Return `refreshStep()` with the note to show it at once.
|
|
65
|
+
*/
|
|
66
|
+
export declare class RequestList {
|
|
67
|
+
/** The `global_data` key the list is kept under. */
|
|
68
|
+
globalKey: string;
|
|
69
|
+
/** The `global_data` key its text for step text is kept under: `<globalKey>_text`. */
|
|
70
|
+
textKey: string;
|
|
71
|
+
/** How the agent opens each kind of request. */
|
|
72
|
+
openers: Record<string, string>;
|
|
73
|
+
/** The first line of the list's text. */
|
|
74
|
+
heading: string;
|
|
75
|
+
/**
|
|
76
|
+
* @param globalKey - The `global_data` key the list is kept under. Its text
|
|
77
|
+
* for step text is kept under `<globalKey>_text`.
|
|
78
|
+
* @param opts - `openers` and `heading`.
|
|
79
|
+
*/
|
|
80
|
+
constructor(globalKey: string, opts?: RequestListOptions);
|
|
81
|
+
/**
|
|
82
|
+
* The `global_data` to start a call with, an empty list, so step text that
|
|
83
|
+
* shows it has a value before anything is noted.
|
|
84
|
+
* @returns The global data.
|
|
85
|
+
*/
|
|
86
|
+
defaults(): Record<string, unknown>;
|
|
87
|
+
/**
|
|
88
|
+
* The requests a call has noted, oldest first, from its request's `global_data`.
|
|
89
|
+
* @param rawData - The call's request.
|
|
90
|
+
* @returns The requests.
|
|
91
|
+
*/
|
|
92
|
+
pending(rawData: Record<string, unknown> | null | undefined): NotedRequest[];
|
|
93
|
+
/**
|
|
94
|
+
* Note a request to come back to, and tell the model so.
|
|
95
|
+
*
|
|
96
|
+
* The model gets "Noted for right after this: <about>.", with a tool prompt to
|
|
97
|
+
* tell the caller and carry on with what it was doing. The same request noted
|
|
98
|
+
* twice is kept once.
|
|
99
|
+
*
|
|
100
|
+
* @param rawData - The noting call's request.
|
|
101
|
+
* @param kind - The kind of request, one of the app's (it picks the opener).
|
|
102
|
+
* @param about - What it's about, in a few words.
|
|
103
|
+
* @param result - A result to add to.
|
|
104
|
+
* @returns The result.
|
|
105
|
+
*/
|
|
106
|
+
note(rawData: Record<string, unknown> | null | undefined, kind: string, about: string, result?: FunctionResult): FunctionResult;
|
|
107
|
+
/**
|
|
108
|
+
* The oldest request not yet taken up, with its `opener`, or null.
|
|
109
|
+
* @param rawData - The call's request.
|
|
110
|
+
* @returns The request.
|
|
111
|
+
*/
|
|
112
|
+
next(rawData: Record<string, unknown> | null | undefined): (NotedRequest & {
|
|
113
|
+
opener: string;
|
|
114
|
+
}) | null;
|
|
115
|
+
/**
|
|
116
|
+
* Remove the oldest request, once it has been taken up.
|
|
117
|
+
* @param rawData - The call's request.
|
|
118
|
+
* @param result - A result to add to.
|
|
119
|
+
* @returns The result.
|
|
120
|
+
*/
|
|
121
|
+
done(rawData: Record<string, unknown> | null | undefined, result?: FunctionResult): FunctionResult;
|
|
122
|
+
/**
|
|
123
|
+
* How the agent opens a request when it takes it up.
|
|
124
|
+
* @param request - The request.
|
|
125
|
+
* @returns The opener.
|
|
126
|
+
*/
|
|
127
|
+
opener(request: Partial<NotedRequest>): string;
|
|
128
|
+
/**
|
|
129
|
+
* The list as step text: the heading and one numbered line a request, or ""
|
|
130
|
+
* when there are none.
|
|
131
|
+
* @param requests - The requests.
|
|
132
|
+
* @returns The text.
|
|
133
|
+
*/
|
|
134
|
+
asText(requests: readonly NotedRequest[]): string;
|
|
135
|
+
private store;
|
|
136
|
+
}
|
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What the caller asked for while the agent was busy with something else.
|
|
3
|
+
*
|
|
4
|
+
* A caller in the middle of one task often asks for another: "and can you also
|
|
5
|
+
* check my balance?" Taking it up at once loses the first task; ignoring it
|
|
6
|
+
* loses the second. A tool notes the request, and the agent tells the caller
|
|
7
|
+
* it's noted for right after this. When the first task is done, the step's
|
|
8
|
+
* text, which shows the list, has the agent take up the next one.
|
|
9
|
+
*
|
|
10
|
+
* The list lives in the call's `global_data`, so it lasts for the call and a
|
|
11
|
+
* step's text can show it, as `${global_data.<key>_text}`.
|
|
12
|
+
*/
|
|
13
|
+
import { FunctionResult } from '../FunctionResult.js';
|
|
14
|
+
/**
|
|
15
|
+
* The caller's requests to come back to, in the order they asked.
|
|
16
|
+
*
|
|
17
|
+
* @example
|
|
18
|
+
* ```ts
|
|
19
|
+
* import { AgentBase, RequestList } from '@signalwire/sdk';
|
|
20
|
+
*
|
|
21
|
+
* const agent = new AgentBase({ name: 'bank' });
|
|
22
|
+
* const later = new RequestList('later', {
|
|
23
|
+
* openers: {
|
|
24
|
+
* balance: 'You also asked about your balance.',
|
|
25
|
+
* question: 'You had a question: {about}.',
|
|
26
|
+
* },
|
|
27
|
+
* });
|
|
28
|
+
*
|
|
29
|
+
* agent.setGlobalData(later.defaults());
|
|
30
|
+
* agent.defineTool({
|
|
31
|
+
* name: 'note_request',
|
|
32
|
+
* description: 'Note a request to come back to',
|
|
33
|
+
* parameters: {
|
|
34
|
+
* type: 'object',
|
|
35
|
+
* properties: { kind: { type: 'string' }, about: { type: 'string' } },
|
|
36
|
+
* required: ['kind', 'about'],
|
|
37
|
+
* },
|
|
38
|
+
* handler: (args, rawData) => later.note(rawData, String(args.kind), String(args.about)),
|
|
39
|
+
* });
|
|
40
|
+
* const ctx = agent.defineContexts().addContext('default');
|
|
41
|
+
* ctx.addStep('take_order').setText("Take the caller's order.\n\n${global_data.later_text}");
|
|
42
|
+
* ```
|
|
43
|
+
*
|
|
44
|
+
* A step's text is expanded when the step is entered, so the list it shows is
|
|
45
|
+
* the one from then; the model hears of each new request in the tool result.
|
|
46
|
+
* Return `refreshStep()` with the note to show it at once.
|
|
47
|
+
*/
|
|
48
|
+
export class RequestList {
|
|
49
|
+
/** The `global_data` key the list is kept under. */
|
|
50
|
+
globalKey;
|
|
51
|
+
/** The `global_data` key its text for step text is kept under: `<globalKey>_text`. */
|
|
52
|
+
textKey;
|
|
53
|
+
/** How the agent opens each kind of request. */
|
|
54
|
+
openers;
|
|
55
|
+
/** The first line of the list's text. */
|
|
56
|
+
heading;
|
|
57
|
+
/**
|
|
58
|
+
* @param globalKey - The `global_data` key the list is kept under. Its text
|
|
59
|
+
* for step text is kept under `<globalKey>_text`.
|
|
60
|
+
* @param opts - `openers` and `heading`.
|
|
61
|
+
*/
|
|
62
|
+
constructor(globalKey, opts = {}) {
|
|
63
|
+
this.globalKey = globalKey;
|
|
64
|
+
this.textKey = `${globalKey}_text`;
|
|
65
|
+
this.openers = { ...(opts.openers ?? {}) };
|
|
66
|
+
this.heading = opts.heading ?? 'Noted for right after this:';
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* The `global_data` to start a call with, an empty list, so step text that
|
|
70
|
+
* shows it has a value before anything is noted.
|
|
71
|
+
* @returns The global data.
|
|
72
|
+
*/
|
|
73
|
+
defaults() {
|
|
74
|
+
return { [this.globalKey]: [], [this.textKey]: '' };
|
|
75
|
+
}
|
|
76
|
+
/**
|
|
77
|
+
* The requests a call has noted, oldest first, from its request's `global_data`.
|
|
78
|
+
* @param rawData - The call's request.
|
|
79
|
+
* @returns The requests.
|
|
80
|
+
*/
|
|
81
|
+
pending(rawData) {
|
|
82
|
+
if (!isRecord(rawData))
|
|
83
|
+
return [];
|
|
84
|
+
const globalData = rawData['global_data'];
|
|
85
|
+
const stored = isRecord(globalData) ? globalData[this.globalKey] : undefined;
|
|
86
|
+
if (!Array.isArray(stored))
|
|
87
|
+
return [];
|
|
88
|
+
return stored.filter(isRecord).map((r) => ({
|
|
89
|
+
kind: String(r['kind'] ?? ''),
|
|
90
|
+
about: String(r['about'] ?? ''),
|
|
91
|
+
}));
|
|
92
|
+
}
|
|
93
|
+
/**
|
|
94
|
+
* Note a request to come back to, and tell the model so.
|
|
95
|
+
*
|
|
96
|
+
* The model gets "Noted for right after this: <about>.", with a tool prompt to
|
|
97
|
+
* tell the caller and carry on with what it was doing. The same request noted
|
|
98
|
+
* twice is kept once.
|
|
99
|
+
*
|
|
100
|
+
* @param rawData - The noting call's request.
|
|
101
|
+
* @param kind - The kind of request, one of the app's (it picks the opener).
|
|
102
|
+
* @param about - What it's about, in a few words.
|
|
103
|
+
* @param result - A result to add to.
|
|
104
|
+
* @returns The result.
|
|
105
|
+
*/
|
|
106
|
+
note(rawData, kind, about, result) {
|
|
107
|
+
const requests = this.pending(rawData);
|
|
108
|
+
if (!requests.some((r) => r.kind === kind && r.about === about)) {
|
|
109
|
+
requests.push({ kind, about });
|
|
110
|
+
}
|
|
111
|
+
const out = (result ?? new FunctionResult()).setToolResponse(`Noted for right after this: ${about}.`, "Tell the caller you've noted it for right after this, and carry on " +
|
|
112
|
+
'with what you were doing.');
|
|
113
|
+
return this.store(out, requests);
|
|
114
|
+
}
|
|
115
|
+
/**
|
|
116
|
+
* The oldest request not yet taken up, with its `opener`, or null.
|
|
117
|
+
* @param rawData - The call's request.
|
|
118
|
+
* @returns The request.
|
|
119
|
+
*/
|
|
120
|
+
next(rawData) {
|
|
121
|
+
const first = this.pending(rawData)[0];
|
|
122
|
+
return first ? { ...first, opener: this.opener(first) } : null;
|
|
123
|
+
}
|
|
124
|
+
/**
|
|
125
|
+
* Remove the oldest request, once it has been taken up.
|
|
126
|
+
* @param rawData - The call's request.
|
|
127
|
+
* @param result - A result to add to.
|
|
128
|
+
* @returns The result.
|
|
129
|
+
*/
|
|
130
|
+
done(rawData, result) {
|
|
131
|
+
return this.store(result ?? new FunctionResult(), this.pending(rawData).slice(1));
|
|
132
|
+
}
|
|
133
|
+
/**
|
|
134
|
+
* How the agent opens a request when it takes it up.
|
|
135
|
+
* @param request - The request.
|
|
136
|
+
* @returns The opener.
|
|
137
|
+
*/
|
|
138
|
+
opener(request) {
|
|
139
|
+
const about = String(request.about ?? '');
|
|
140
|
+
const kind = String(request.kind ?? '');
|
|
141
|
+
const template = Object.hasOwn(this.openers, kind) ? this.openers[kind] : undefined;
|
|
142
|
+
return template ? template.replaceAll('{about}', () => about) : about;
|
|
143
|
+
}
|
|
144
|
+
/**
|
|
145
|
+
* The list as step text: the heading and one numbered line a request, or ""
|
|
146
|
+
* when there are none.
|
|
147
|
+
* @param requests - The requests.
|
|
148
|
+
* @returns The text.
|
|
149
|
+
*/
|
|
150
|
+
asText(requests) {
|
|
151
|
+
if (requests.length === 0)
|
|
152
|
+
return '';
|
|
153
|
+
return [
|
|
154
|
+
this.heading,
|
|
155
|
+
...requests.map((r, n) => `${n + 1}. ${this.opener(r)}`),
|
|
156
|
+
"When the current task is done, take these up in order, then ask if there's anything else.",
|
|
157
|
+
].join('\n');
|
|
158
|
+
}
|
|
159
|
+
store(result, requests) {
|
|
160
|
+
return result.updateGlobalData({
|
|
161
|
+
[this.globalKey]: requests,
|
|
162
|
+
[this.textKey]: this.asText(requests),
|
|
163
|
+
});
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
function isRecord(value) {
|
|
167
|
+
return typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
168
|
+
}
|
|
169
|
+
//# sourceMappingURL=RequestList.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"RequestList.js","sourceRoot":"","sources":["../../src/patterns/RequestList.ts"],"names":[],"mappings":"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"}
|
|
@@ -4,6 +4,7 @@
|
|
|
4
4
|
* Skills are modular capabilities that can be added to an agent.
|
|
5
5
|
* They define tools, prompt sections, hints, and global data.
|
|
6
6
|
*/
|
|
7
|
+
import type { ToolMiddleware } from '../ToolMiddleware.js';
|
|
7
8
|
import type { SwaigHandler } from '../SwaigFunction.js';
|
|
8
9
|
import type { FillerPhrases, SemanticGate } from '../SemanticGate.js';
|
|
9
10
|
import type { SwaigRequest } from '../SwaigContracts.js';
|
|
@@ -54,6 +55,28 @@ export interface SkillToolDefinition {
|
|
|
54
55
|
gates?: ReadonlyArray<SemanticGate | Record<string, unknown>>;
|
|
55
56
|
/** Phrases the AI says while the gates are checked, shaped like `fillers`. */
|
|
56
57
|
gate_fillers?: FillerPhrases;
|
|
58
|
+
/**
|
|
59
|
+
* Whether the model must vouch that the arguments came from the user (see
|
|
60
|
+
* `SwaigFunctionOptions.vouched`). Wins over the skill's `swaig_fields`.
|
|
61
|
+
*/
|
|
62
|
+
vouched?: boolean;
|
|
63
|
+
/**
|
|
64
|
+
* Whether optional arguments take null (see
|
|
65
|
+
* `SwaigFunctionOptions.nullableOptional`). Wins over the skill's
|
|
66
|
+
* `swaig_fields`.
|
|
67
|
+
*/
|
|
68
|
+
nullable_optional?: boolean;
|
|
69
|
+
/**
|
|
70
|
+
* Whether the handler reads the conversation (see
|
|
71
|
+
* `SwaigFunctionOptions.needsConversation`). Wins over the skill's
|
|
72
|
+
* `swaig_fields`.
|
|
73
|
+
*/
|
|
74
|
+
needs_conversation?: boolean;
|
|
75
|
+
/**
|
|
76
|
+
* Middleware around this tool's calls (see `SwaigFunctionOptions.middleware`).
|
|
77
|
+
* Wins over the skill's `swaig_fields`.
|
|
78
|
+
*/
|
|
79
|
+
middleware?: readonly ToolMiddleware[];
|
|
57
80
|
}
|
|
58
81
|
/**
|
|
59
82
|
* Build a {@link SkillToolDefinition} whose `handler` args are *inferred* from
|
|
@@ -112,7 +135,7 @@ export interface SkillToolDefinition {
|
|
|
112
135
|
export declare function defineSkillTool<const P extends ToolParameters = ToolParameters, const R extends readonly PropertyKey[] = []>(toolDef: Omit<SkillToolDefinition, 'parameters' | 'required' | 'handler'> & {
|
|
113
136
|
parameters?: P;
|
|
114
137
|
required?: R;
|
|
115
|
-
handler: (args: ToolArgs<P, R>, rawData: SwaigRequest, agent?: AgentBase) => FunctionResult | Record<string, unknown> | string | Promise<FunctionResult | Record<string, unknown> | string>;
|
|
138
|
+
handler: (args: ToolArgs<P, R>, rawData: SwaigRequest, agent?: AgentBase) => FunctionResult | Record<string, unknown> | string | null | undefined | void | Promise<FunctionResult | Record<string, unknown> | string | null | undefined | void>;
|
|
116
139
|
}): SkillToolDefinition;
|
|
117
140
|
/** A section of prompt content injected into the agent's system prompt by a skill. */
|
|
118
141
|
export interface SkillPromptSection {
|
package/dist/skills/SkillBase.js
CHANGED
|
@@ -337,9 +337,20 @@ export class SkillBase {
|
|
|
337
337
|
*/
|
|
338
338
|
defineTool(toolDef) {
|
|
339
339
|
const swaigDefaults = this.swaigFields;
|
|
340
|
+
// A tool given as SwaigFunctionOptions spells these in camel case; its own
|
|
341
|
+
// value is carried in the snake-case spelling too, so it wins over the
|
|
342
|
+
// skill's default for it
|
|
343
|
+
const own = { ...toolDef };
|
|
344
|
+
for (const [camel, snake] of [
|
|
345
|
+
['nullableOptional', 'nullable_optional'],
|
|
346
|
+
['needsConversation', 'needs_conversation'],
|
|
347
|
+
]) {
|
|
348
|
+
if (own[camel] !== undefined && own[snake] === undefined)
|
|
349
|
+
own[snake] = own[camel];
|
|
350
|
+
}
|
|
340
351
|
const merged = {
|
|
341
352
|
...swaigDefaults,
|
|
342
|
-
...
|
|
353
|
+
...own,
|
|
343
354
|
};
|
|
344
355
|
this._dynamicTools.push(merged);
|
|
345
356
|
}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"SkillBase.js","sourceRoot":"","sources":["../../src/skills/SkillBase.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;
|
|
1
|
+
{"version":3,"file":"SkillBase.js","sourceRoot":"","sources":["../../src/skills/SkillBase.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Numbers as an English text-to-speech voice should say them.
|
|
3
|
+
*
|
|
4
|
+
* The platform normalizes text before its pronunciation rules run, so a bare
|
|
5
|
+
* number is already words by then: `addPronunciation` can't make "10001" read
|
|
6
|
+
* digit by digit. Give the model, or a `say` action, the words instead.
|
|
7
|
+
*/
|
|
8
|
+
/**
|
|
9
|
+
* `n` in English words: `numberWords(1405)` is "one thousand four hundred five".
|
|
10
|
+
* @param n - A whole number, as a safe integer or a bigint.
|
|
11
|
+
* @returns The words.
|
|
12
|
+
* @throws Error for a number that isn't whole, or of a quadrillion or more.
|
|
13
|
+
*/
|
|
14
|
+
export declare function numberWords(n: number | bigint): string;
|
|
15
|
+
/** Options for {@link sayDigits} and {@link sayLastDigits}. */
|
|
16
|
+
export interface SayDigitsOptions {
|
|
17
|
+
/** The word for 0, such as "oh". Default "zero". */
|
|
18
|
+
zero?: string;
|
|
19
|
+
}
|
|
20
|
+
/**
|
|
21
|
+
* The digits in `text`, one word each, as a voice should read a ZIP code, an
|
|
22
|
+
* account number or a phone number.
|
|
23
|
+
*
|
|
24
|
+
* `sayDigits('415-555-0192')` is "four one five, five five five, zero one nine
|
|
25
|
+
* two": with `group` left out, the groups are the ones the text has, separated
|
|
26
|
+
* by anything that isn't a digit. `group` 3 splits the digits into threes;
|
|
27
|
+
* `[3, 3, 4]` into those sizes, the rest in a last group. A comma between
|
|
28
|
+
* groups makes the voice pause.
|
|
29
|
+
*
|
|
30
|
+
* @param text - The digits, with any separators.
|
|
31
|
+
* @param group - The group size, or the sizes in order.
|
|
32
|
+
* @param opts - `zero`, the word for 0.
|
|
33
|
+
* @returns The words, or "" when `text` has no digits.
|
|
34
|
+
* @throws Error for a group size that isn't a positive whole number.
|
|
35
|
+
*/
|
|
36
|
+
export declare function sayDigits(text: string | number | bigint, group?: number | readonly number[] | null, opts?: SayDigitsOptions): string;
|
|
37
|
+
/**
|
|
38
|
+
* The last `n` digits of `text`, one word each: for "a card ending in ..." or
|
|
39
|
+
* "the account ending in ...".
|
|
40
|
+
*
|
|
41
|
+
* `sayLastDigits('4111 1111 1111 1234')` is "one two three four".
|
|
42
|
+
*
|
|
43
|
+
* @param text - The number, with any separators.
|
|
44
|
+
* @param n - How many of its last digits. Default 4.
|
|
45
|
+
* @param opts - `zero`, the word for 0.
|
|
46
|
+
* @returns The words, or "" when `text` has no digits.
|
|
47
|
+
* @throws Error for an `n` that isn't a positive whole number.
|
|
48
|
+
*/
|
|
49
|
+
export declare function sayLastDigits(text: string | number | bigint, n?: number, opts?: SayDigitsOptions): string;
|
|
50
|
+
/**
|
|
51
|
+
* An amount of money in words: `sayMoney(14.5)` is "fourteen dollars and fifty
|
|
52
|
+
* cents".
|
|
53
|
+
*
|
|
54
|
+
* The amount is rounded to the currency's smallest unit, half up, from its
|
|
55
|
+
* decimal text, so `sayMoney(0.125)` is "thirteen cents" and `sayMoney('2.675')`
|
|
56
|
+
* "two dollars and sixty-eight cents". The currencies are USD, CAD, AUD, NZD,
|
|
57
|
+
* EUR, GBP, MXN, INR and JPY.
|
|
58
|
+
*
|
|
59
|
+
* @param amount - The amount, in the currency's major unit (dollars, not
|
|
60
|
+
* cents): a number, a bigint, or a decimal string such as "14.50".
|
|
61
|
+
* @param currency - The ISO 4217 code. Default "USD".
|
|
62
|
+
* @returns The words, such as "one dollar", "five cents" or "minus two pounds
|
|
63
|
+
* and one penny".
|
|
64
|
+
* @throws Error for an amount that isn't a finite number, or another currency.
|
|
65
|
+
*/
|
|
66
|
+
export declare function sayMoney(amount: number | bigint | string, currency?: string): string;
|