@signalwire/sdk 2.0.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/.github/workflows/publish.yml +27 -0
- package/.github/workflows/test.yml +17 -0
- package/CLAUDE.md +112 -0
- package/README.md +254 -0
- package/docs/MIGRATION-2.0.md +81 -0
- package/docs/agent-guide.md +869 -0
- package/docs/agent_guide.md +1026 -0
- package/docs/api-reference.md +2420 -0
- package/docs/api_reference.md +1301 -0
- package/docs/architecture.md +843 -0
- package/docs/cli-guide.md +579 -0
- package/docs/cli_guide.md +448 -0
- package/docs/cloud_functions_guide.md +474 -0
- package/docs/configuration.md +422 -0
- package/docs/contexts-guide.md +787 -0
- package/docs/contexts_guide.md +511 -0
- package/docs/datamap-guide.md +1141 -0
- package/docs/datamap_guide.md +595 -0
- package/docs/llm_parameters.md +239 -0
- package/docs/mcp_gateway_reference.md +648 -0
- package/docs/mcp_integration.md +108 -0
- package/docs/prefabs-guide.md +800 -0
- package/docs/sdk_features.md +477 -0
- package/docs/security.md +436 -0
- package/docs/serverless-guide.md +513 -0
- package/docs/skills-guide.md +857 -0
- package/docs/skills-system.md +301 -0
- package/docs/skills_parameter_schema.md +392 -0
- package/docs/skills_system.md +467 -0
- package/docs/swaig-reference.md +1627 -0
- package/docs/swaig_reference.md +910 -0
- package/docs/swml_service_guide.md +600 -0
- package/docs/third_party_skills.md +533 -0
- package/docs/web_service.md +677 -0
- package/examples/README.md +131 -0
- package/examples/advanced-datamap.ts +100 -0
- package/examples/advanced-dynamic-config.ts +70 -0
- package/examples/auto-vivified.ts +94 -0
- package/examples/call-flow.ts +63 -0
- package/examples/comprehensive-dynamic.ts +125 -0
- package/examples/contexts-steps.ts +65 -0
- package/examples/custom-path.ts +45 -0
- package/examples/datamap-tools.ts +55 -0
- package/examples/datasphere-multi-instance.ts +63 -0
- package/examples/datasphere-serverless-env.ts +68 -0
- package/examples/datasphere-webhook-env.ts +66 -0
- package/examples/datasphere.ts +37 -0
- package/examples/declarative.ts +100 -0
- package/examples/dynamic-config.ts +54 -0
- package/examples/dynamic-info-gatherer.ts +69 -0
- package/examples/dynamic-swml-service.ts +67 -0
- package/examples/gather-info.ts +71 -0
- package/examples/gather-per-question-functions-demo.ts +140 -0
- package/examples/joke-agent.ts +34 -0
- package/examples/kubernetes-agent.ts +45 -0
- package/examples/llm-params.ts +69 -0
- package/examples/mcp-agent.ts +84 -0
- package/examples/mcp-gateway.ts +35 -0
- package/examples/multi-agent.ts +73 -0
- package/examples/multi-endpoint.ts +79 -0
- package/examples/pom-prompt.ts +71 -0
- package/examples/prefab-concierge.ts +47 -0
- package/examples/prefab-faq.ts +54 -0
- package/examples/prefab-info-gatherer.ts +33 -0
- package/examples/prefab-receptionist.ts +36 -0
- package/examples/prefab-survey.ts +68 -0
- package/examples/record-call.ts +67 -0
- package/examples/relay-demo.ts +33 -0
- package/examples/room-and-sip.ts +94 -0
- package/examples/serverless-lambda.ts +35 -0
- package/examples/session-state.ts +83 -0
- package/examples/simple-agent.ts +36 -0
- package/examples/simple-static.ts +29 -0
- package/examples/skills-demo.ts +38 -0
- package/examples/step-function-inheritance-demo.ts +124 -0
- package/examples/swaig-features.ts +187 -0
- package/examples/swml-service-routing.ts +66 -0
- package/examples/swml-service.ts +38 -0
- package/examples/tap.ts +68 -0
- package/examples/verb-methods.ts +45 -0
- package/examples/web-search-multi-instance.ts +72 -0
- package/examples/web-search.ts +38 -0
- package/examples/wikipedia.ts +36 -0
- package/livewire/README.md +140 -0
- package/livewire/docs/migration-guide.md +228 -0
- package/livewire/examples/livewire-basic-agent.ts +74 -0
- package/livewire/examples/livewire-handoff.ts +197 -0
- package/livewire/examples/livewire-multi-tool.ts +117 -0
- package/package.json +38 -0
- package/relay/README.md +70 -0
- package/relay/RELAY_IMPLEMENTATION_GUIDE.md +1257 -0
- package/relay/docs/call-methods.md +474 -0
- package/relay/docs/client-reference.md +142 -0
- package/relay/docs/events.md +134 -0
- package/relay/docs/getting-started.md +134 -0
- package/relay/docs/guide.md +306 -0
- package/relay/docs/messaging.md +182 -0
- package/relay/examples/relay-inbound.ts +66 -0
- package/relay/examples/relay-messaging.ts +71 -0
- package/relay/examples/relay-outbound.ts +76 -0
- package/rest/README.md +95 -0
- package/rest/docs/calling.md +273 -0
- package/rest/docs/client-reference.md +107 -0
- package/rest/docs/compat.md +204 -0
- package/rest/docs/fabric.md +183 -0
- package/rest/docs/getting-started.md +110 -0
- package/rest/docs/guide.md +351 -0
- package/rest/docs/namespaces.md +285 -0
- package/rest/examples/rest-10dlc-registration.ts +161 -0
- package/rest/examples/rest-calling-ivr-and-ai.ts +102 -0
- package/rest/examples/rest-calling-play-and-record.ts +91 -0
- package/rest/examples/rest-client.ts +65 -0
- package/rest/examples/rest-compat-laml.ts +210 -0
- package/rest/examples/rest-datasphere-search.ts +82 -0
- package/rest/examples/rest-fabric-conferences-and-routing.ts +144 -0
- package/rest/examples/rest-fabric-subscribers-and-sip.ts +108 -0
- package/rest/examples/rest-fabric-swml-and-callflows.ts +99 -0
- package/rest/examples/rest-manage-resources.ts +65 -0
- package/rest/examples/rest-phone-number-management.ts +197 -0
- package/rest/examples/rest-queues-mfa-and-recordings.ts +143 -0
- package/rest/examples/rest-video-rooms.ts +186 -0
- package/src/AgentBase.ts +2489 -0
- package/src/AgentServer.ts +415 -0
- package/src/AuthHandler.ts +256 -0
- package/src/ConfigLoader.ts +447 -0
- package/src/ContextBuilder.ts +1150 -0
- package/src/DataMap.ts +449 -0
- package/src/FunctionResult.ts +866 -0
- package/src/Logger.ts +337 -0
- package/src/PomBuilder.ts +439 -0
- package/src/PromptManager.ts +133 -0
- package/src/SWMLHandler.ts +298 -0
- package/src/SWMLService.ts +717 -0
- package/src/SchemaUtils.ts +361 -0
- package/src/SecurityUtils.ts +153 -0
- package/src/ServerlessAdapter.ts +221 -0
- package/src/SessionManager.ts +311 -0
- package/src/SslConfig.ts +118 -0
- package/src/SwaigFunction.ts +276 -0
- package/src/SwmlBuilder.ts +258 -0
- package/src/SwmlVerbMethods.generated.ts +234 -0
- package/src/TypeInference.ts +181 -0
- package/src/WebService.ts +619 -0
- package/src/cli/agent-loader.ts +166 -0
- package/src/cli/mock-data.ts +111 -0
- package/src/cli/swaig-test.ts +452 -0
- package/src/generateVerbTypes.ts +322 -0
- package/src/index.ts +167 -0
- package/src/livewire/index.ts +950 -0
- package/src/prefabs/ConciergeAgent.ts +287 -0
- package/src/prefabs/FAQBotAgent.ts +384 -0
- package/src/prefabs/InfoGathererAgent.ts +339 -0
- package/src/prefabs/ReceptionistAgent.ts +366 -0
- package/src/prefabs/SurveyAgent.ts +646 -0
- package/src/prefabs/index.ts +27 -0
- package/src/relay/Action.ts +314 -0
- package/src/relay/Call.ts +854 -0
- package/src/relay/Deferred.ts +71 -0
- package/src/relay/Message.ts +148 -0
- package/src/relay/RelayClient.ts +1036 -0
- package/src/relay/RelayError.ts +14 -0
- package/src/relay/RelayEvent.ts +892 -0
- package/src/relay/constants.ts +132 -0
- package/src/relay/index.ts +123 -0
- package/src/relay/types.ts +149 -0
- package/src/rest/HttpClient.ts +103 -0
- package/src/rest/RestError.ts +31 -0
- package/src/rest/base/BaseResource.ts +19 -0
- package/src/rest/base/CrudResource.ts +51 -0
- package/src/rest/base/CrudWithAddresses.ts +26 -0
- package/src/rest/index.ts +200 -0
- package/src/rest/namespaces/addresses.ts +32 -0
- package/src/rest/namespaces/calling.ts +187 -0
- package/src/rest/namespaces/chat.ts +20 -0
- package/src/rest/namespaces/compat.ts +352 -0
- package/src/rest/namespaces/datasphere.ts +45 -0
- package/src/rest/namespaces/fabric.ts +222 -0
- package/src/rest/namespaces/imported-numbers.ts +20 -0
- package/src/rest/namespaces/logs.ts +84 -0
- package/src/rest/namespaces/lookup.ts +21 -0
- package/src/rest/namespaces/mfa.ts +30 -0
- package/src/rest/namespaces/number-groups.ts +38 -0
- package/src/rest/namespaces/phone-numbers.ts +44 -0
- package/src/rest/namespaces/project.ts +36 -0
- package/src/rest/namespaces/pubsub.ts +20 -0
- package/src/rest/namespaces/queues.ts +33 -0
- package/src/rest/namespaces/recordings.ts +28 -0
- package/src/rest/namespaces/registry.ts +101 -0
- package/src/rest/namespaces/short-codes.ts +28 -0
- package/src/rest/namespaces/sip-profile.ts +25 -0
- package/src/rest/namespaces/verified-callers.ts +27 -0
- package/src/rest/namespaces/video.ts +165 -0
- package/src/rest/pagination.ts +84 -0
- package/src/rest/types.ts +61 -0
- package/src/schema.json +12250 -0
- package/src/skills/SkillBase.ts +547 -0
- package/src/skills/SkillManager.ts +415 -0
- package/src/skills/SkillRegistry.ts +367 -0
- package/src/skills/builtin/api_ninjas_trivia.ts +280 -0
- package/src/skills/builtin/ask_claude.ts +241 -0
- package/src/skills/builtin/claude_skills.ts +978 -0
- package/src/skills/builtin/custom_skills.ts +312 -0
- package/src/skills/builtin/datasphere.ts +438 -0
- package/src/skills/builtin/datasphere_serverless.ts +339 -0
- package/src/skills/builtin/datetime.ts +130 -0
- package/src/skills/builtin/google_maps.ts +651 -0
- package/src/skills/builtin/index.ts +88 -0
- package/src/skills/builtin/info_gatherer.ts +405 -0
- package/src/skills/builtin/joke.ts +191 -0
- package/src/skills/builtin/math.ts +142 -0
- package/src/skills/builtin/mcp_gateway.ts +677 -0
- package/src/skills/builtin/native_vector_search.ts +901 -0
- package/src/skills/builtin/play_background_file.ts +358 -0
- package/src/skills/builtin/spider.ts +869 -0
- package/src/skills/builtin/swml_transfer.ts +635 -0
- package/src/skills/builtin/weather_api.ts +248 -0
- package/src/skills/builtin/web_search.ts +1074 -0
- package/src/skills/builtin/wikipedia_search.ts +299 -0
- package/src/skills/index.ts +12 -0
- package/src/types.ts +132 -0
- package/tests/AgentBase.test.ts +1093 -0
- package/tests/AgentServer.test.ts +126 -0
- package/tests/AuthHandler.test.ts +133 -0
- package/tests/ConfigLoader.test.ts +151 -0
- package/tests/ContextBuilder.test.ts +108 -0
- package/tests/DataMap.test.ts +367 -0
- package/tests/EphemeralSkillCopy.test.ts +107 -0
- package/tests/FunctionResult.test.ts +298 -0
- package/tests/GracefulShutdown.test.ts +46 -0
- package/tests/Logger.test.ts +420 -0
- package/tests/PomBuilder.test.ts +228 -0
- package/tests/ProxyDetection.test.ts +228 -0
- package/tests/SWMLService.test.ts +320 -0
- package/tests/SWMLVerbHandler.test.ts +523 -0
- package/tests/SchemaUtils.test.ts +106 -0
- package/tests/SchemaUtils.verb.test.ts +206 -0
- package/tests/SecurityUtils.test.ts +192 -0
- package/tests/ServerlessAdapter.test.ts +222 -0
- package/tests/SessionManager.test.ts +257 -0
- package/tests/SkillBaseFeatures.test.ts +130 -0
- package/tests/SkillMultiInstance.test.ts +102 -0
- package/tests/SkillParameterSchemas.test.ts +134 -0
- package/tests/SkillRegistrySchema.test.ts +84 -0
- package/tests/SslConfig.test.ts +97 -0
- package/tests/SwmlBuilder.test.ts +400 -0
- package/tests/TypeInference.test.ts +165 -0
- package/tests/VerbHandlerRegistry.test.ts +128 -0
- package/tests/cli/mock-data.test.ts +113 -0
- package/tests/cli/swaig-test.test.ts +108 -0
- package/tests/examples.test.ts +194 -0
- package/tests/fixtures/scrape-parity/README.md +53 -0
- package/tests/fixtures/scrape-parity/expected/01_simple_article.json +5 -0
- package/tests/fixtures/scrape-parity/expected/02_class_based_noise.json +5 -0
- package/tests/fixtures/scrape-parity/expected/03_nested_containers.json +5 -0
- package/tests/fixtures/scrape-parity/expected/04_bare_body.json +5 -0
- package/tests/fixtures/scrape-parity/expected/05_malformed.json +5 -0
- package/tests/fixtures/scrape-parity/expected/06_multi_class.json +5 -0
- package/tests/fixtures/scrape-parity/expected/07_anchor_pattern.json +5 -0
- package/tests/fixtures/scrape-parity/expected/08_inline_script.json +5 -0
- package/tests/fixtures/scrape-parity/expected/09_whitespace_nbsp.json +5 -0
- package/tests/fixtures/scrape-parity/expected/10_entity_unicode.json +5 -0
- package/tests/fixtures/scrape-parity/expected/11_cdata_comments.json +5 -0
- package/tests/fixtures/scrape-parity/expected/12_deep_nested_removals.json +5 -0
- package/tests/fixtures/scrape-parity/html/01_simple_article.html +18 -0
- package/tests/fixtures/scrape-parity/html/02_class_based_noise.html +18 -0
- package/tests/fixtures/scrape-parity/html/03_nested_containers.html +13 -0
- package/tests/fixtures/scrape-parity/html/04_bare_body.html +9 -0
- package/tests/fixtures/scrape-parity/html/05_malformed.html +11 -0
- package/tests/fixtures/scrape-parity/html/06_multi_class.html +18 -0
- package/tests/fixtures/scrape-parity/html/07_anchor_pattern.html +12 -0
- package/tests/fixtures/scrape-parity/html/08_inline_script.html +17 -0
- package/tests/fixtures/scrape-parity/html/09_whitespace_nbsp.html +21 -0
- package/tests/fixtures/scrape-parity/html/10_entity_unicode.html +10 -0
- package/tests/fixtures/scrape-parity/html/11_cdata_comments.html +13 -0
- package/tests/fixtures/scrape-parity/html/12_deep_nested_removals.html +24 -0
- package/tests/fixtures/scrape-parity/python_extract.py +109 -0
- package/tests/livewire/livewire.test.ts +780 -0
- package/tests/mcp.test.ts +221 -0
- package/tests/prefabs/prefabs.test.ts +1093 -0
- package/tests/relay/Action.test.ts +392 -0
- package/tests/relay/Call.test.ts +535 -0
- package/tests/relay/Deferred.test.ts +71 -0
- package/tests/relay/Message.test.ts +164 -0
- package/tests/relay/RelayClient.test.ts +779 -0
- package/tests/relay/RelayEvent.test.ts +463 -0
- package/tests/relay/helpers.ts +79 -0
- package/tests/rest/HttpClient.test.ts +274 -0
- package/tests/rest/RestError.test.ts +53 -0
- package/tests/rest/calling.test.ts +156 -0
- package/tests/rest/client.test.ts +197 -0
- package/tests/rest/compat.test.ts +335 -0
- package/tests/rest/datasphere.test.ts +71 -0
- package/tests/rest/fabric.test.ts +186 -0
- package/tests/rest/helpers.ts +95 -0
- package/tests/rest/logs.test.ts +68 -0
- package/tests/rest/pagination.test.ts +133 -0
- package/tests/rest/registry.test.ts +94 -0
- package/tests/rest/relay-rest.test.ts +290 -0
- package/tests/rest/video.test.ts +173 -0
- package/tests/setup.ts +6 -0
- package/tests/skills/SkillBase.test.ts +108 -0
- package/tests/skills/SkillManager.test.ts +268 -0
- package/tests/skills/SkillRegistry.test.ts +176 -0
- package/tests/skills/builtin.test.ts +1472 -0
- package/tests/skills/claude-skills.test.ts +54 -0
- package/tests/skills/custom-skills.test.ts +53 -0
- package/tests/skills/datasphere-serverless.test.ts +70 -0
- package/tests/skills/datasphere.test.ts +107 -0
- package/tests/skills/datetime.test.ts +101 -0
- package/tests/skills/google-maps.test.ts +78 -0
- package/tests/skills/info-gatherer.test.ts +411 -0
- package/tests/skills/joke.test.ts +81 -0
- package/tests/skills/math.test.ts +68 -0
- package/tests/skills/mcp-gateway.test.ts +101 -0
- package/tests/skills/play-background.test.ts +54 -0
- package/tests/skills/spider.test.ts +108 -0
- package/tests/skills/swml-transfer.test.ts +178 -0
- package/tests/skills/trivia.test.ts +54 -0
- package/tests/skills/vector-search.test.ts +135 -0
- package/tests/skills/weather-api.test.ts +77 -0
- package/tests/skills/web-search-parity.test.ts +59 -0
- package/tests/skills/web-search.test.ts +103 -0
- package/tests/skills/wikipedia.test.ts +63 -0
- package/tsconfig.json +18 -0
- package/vitest.config.ts +9 -0
|
@@ -0,0 +1,298 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* SWMLHandler - SWML verb handler framework.
|
|
3
|
+
*
|
|
4
|
+
* Consolidates the abstract {@link SWMLVerbHandler} base class, the
|
|
5
|
+
* concrete {@link AIVerbHandler} for the SWML "ai" verb (including its
|
|
6
|
+
* {@link AIVerbBuildOptions} build signature), and the {@link VerbHandlerRegistry}
|
|
7
|
+
* that maps verb names to handler instances.
|
|
8
|
+
*
|
|
9
|
+
* Verb handlers provide specialized logic for complex SWML verbs that
|
|
10
|
+
* cannot be handled generically by the schema-driven SwmlBuilder.
|
|
11
|
+
* The "ai" verb is complex and requires specialized handling, particularly
|
|
12
|
+
* for managing prompts, SWAIG functions, and AI configurations.
|
|
13
|
+
*
|
|
14
|
+
* Register implementations via {@link VerbHandlerRegistry.registerHandler}.
|
|
15
|
+
*
|
|
16
|
+
* Mirrors Python SDK's single-file layout in
|
|
17
|
+
* `signalwire/signalwire/core/swml_handler.py`.
|
|
18
|
+
*/
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* Abstract base class for pluggable SWML verb handlers.
|
|
22
|
+
*
|
|
23
|
+
* Each concrete handler owns one verb name and provides validate/build
|
|
24
|
+
* logic for that verb's configuration. Subclass this to create handlers
|
|
25
|
+
* for custom or complex SWML verbs that require specialized handling
|
|
26
|
+
* beyond generic schema-driven validation.
|
|
27
|
+
*
|
|
28
|
+
* @example
|
|
29
|
+
* ```ts
|
|
30
|
+
* class MyVerbHandler extends SWMLVerbHandler {
|
|
31
|
+
* getVerbName(): string { return 'my_verb'; }
|
|
32
|
+
* validateConfig(config: Record<string, unknown>): [boolean, string[]] {
|
|
33
|
+
* const errors: string[] = [];
|
|
34
|
+
* if (!config['url']) errors.push("Missing required field 'url'");
|
|
35
|
+
* return [errors.length === 0, errors];
|
|
36
|
+
* }
|
|
37
|
+
* buildConfig(opts: Record<string, unknown>): Record<string, unknown> {
|
|
38
|
+
* return { url: opts['url'] };
|
|
39
|
+
* }
|
|
40
|
+
* }
|
|
41
|
+
* ```
|
|
42
|
+
*/
|
|
43
|
+
export abstract class SWMLVerbHandler {
|
|
44
|
+
/**
|
|
45
|
+
* Get the name of the SWML verb this handler handles.
|
|
46
|
+
* @returns The verb name as a string (e.g. "ai", "play").
|
|
47
|
+
*/
|
|
48
|
+
abstract getVerbName(): string;
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* Validate the configuration for this verb.
|
|
52
|
+
* @param config - The configuration dictionary for this verb.
|
|
53
|
+
* @returns A `[isValid, errorMessages]` tuple where `isValid` is `true`
|
|
54
|
+
* when the config is valid and `errorMessages` lists any issues found.
|
|
55
|
+
*/
|
|
56
|
+
abstract validateConfig(config: Record<string, unknown>): [boolean, string[]];
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* Build a configuration object for this verb from the provided arguments.
|
|
60
|
+
* @param opts - Key-value arguments specific to this verb.
|
|
61
|
+
* @returns A configuration dictionary ready for inclusion in a SWML document.
|
|
62
|
+
*/
|
|
63
|
+
abstract buildConfig(opts: Record<string, unknown>): Record<string, unknown>;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/** Options accepted by {@link AIVerbHandler.buildConfig}. */
|
|
67
|
+
export interface AIVerbBuildOptions {
|
|
68
|
+
/** Text prompt for the AI (mutually exclusive with promptPom). */
|
|
69
|
+
promptText?: string;
|
|
70
|
+
/** POM structure for the AI prompt (mutually exclusive with promptText). */
|
|
71
|
+
promptPom?: Record<string, unknown>[];
|
|
72
|
+
/** Optional contexts and steps configuration (can be combined with text or pom). */
|
|
73
|
+
contexts?: Record<string, unknown>;
|
|
74
|
+
/** Optional post-prompt text. */
|
|
75
|
+
postPrompt?: string;
|
|
76
|
+
/** Optional URL for post-prompt processing. */
|
|
77
|
+
postPromptUrl?: string;
|
|
78
|
+
/** Optional SWAIG configuration. */
|
|
79
|
+
swaig?: Record<string, unknown>;
|
|
80
|
+
/** Additional AI parameters; see {@link AIVerbHandler.buildConfig} for routing rules. */
|
|
81
|
+
[key: string]: unknown;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/** Handler for the SWML 'ai' verb. */
|
|
85
|
+
export class AIVerbHandler extends SWMLVerbHandler {
|
|
86
|
+
/**
|
|
87
|
+
* Get the name of the verb this handler handles.
|
|
88
|
+
* @returns "ai" as the verb name.
|
|
89
|
+
*/
|
|
90
|
+
getVerbName(): string {
|
|
91
|
+
return 'ai';
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/**
|
|
95
|
+
* Validate the configuration for the AI verb.
|
|
96
|
+
*
|
|
97
|
+
* Checks that:
|
|
98
|
+
* - `prompt` is present and is an object
|
|
99
|
+
* - `prompt` contains exactly one of `text` or `pom` (mutually exclusive)
|
|
100
|
+
* - `prompt.contexts`, if present, is an object
|
|
101
|
+
* - `SWAIG`, if present, is an object
|
|
102
|
+
*
|
|
103
|
+
* @param config - The configuration dictionary for the AI verb.
|
|
104
|
+
* @returns A [isValid, errorMessages] tuple.
|
|
105
|
+
*/
|
|
106
|
+
validateConfig(config: Record<string, unknown>): [boolean, string[]] {
|
|
107
|
+
const errors: string[] = [];
|
|
108
|
+
|
|
109
|
+
// Check that prompt is present
|
|
110
|
+
if (!('prompt' in config)) {
|
|
111
|
+
errors.push("Missing required field 'prompt'");
|
|
112
|
+
return [false, errors];
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
const prompt = config['prompt'];
|
|
116
|
+
if (typeof prompt !== 'object' || prompt === null || Array.isArray(prompt)) {
|
|
117
|
+
errors.push("'prompt' must be an object");
|
|
118
|
+
return [false, errors];
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
const p = prompt as Record<string, unknown>;
|
|
122
|
+
|
|
123
|
+
// Check that prompt contains either text or pom (required, mutually exclusive)
|
|
124
|
+
const hasText = 'text' in p;
|
|
125
|
+
const hasPom = 'pom' in p;
|
|
126
|
+
const hasContexts = 'contexts' in p;
|
|
127
|
+
|
|
128
|
+
const basePromptCount = [hasText, hasPom].filter(Boolean).length;
|
|
129
|
+
if (basePromptCount === 0) {
|
|
130
|
+
errors.push("'prompt' must contain either 'text' or 'pom' as base prompt");
|
|
131
|
+
} else if (basePromptCount > 1) {
|
|
132
|
+
errors.push("'prompt' can only contain one of: 'text' or 'pom' (mutually exclusive)");
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
// Contexts are optional and can be combined with text or pom
|
|
136
|
+
if (hasContexts) {
|
|
137
|
+
const contexts = p['contexts'];
|
|
138
|
+
if (typeof contexts !== 'object' || contexts === null || Array.isArray(contexts)) {
|
|
139
|
+
errors.push("'prompt.contexts' must be an object");
|
|
140
|
+
}
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
// Validate SWAIG structure if present
|
|
144
|
+
if ('SWAIG' in config) {
|
|
145
|
+
const swaig = config['SWAIG'];
|
|
146
|
+
if (typeof swaig !== 'object' || swaig === null || Array.isArray(swaig)) {
|
|
147
|
+
errors.push("'SWAIG' must be an object");
|
|
148
|
+
}
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
return [errors.length === 0, errors];
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
/**
|
|
155
|
+
* Build a configuration for the AI verb.
|
|
156
|
+
*
|
|
157
|
+
* Requires exactly one of `promptText` or `promptPom` (mutually exclusive).
|
|
158
|
+
* Throws an `Error` if both or neither are provided.
|
|
159
|
+
*
|
|
160
|
+
* Extra keys in `opts` are routed as follows:
|
|
161
|
+
* - `languages`, `hints`, `pronounce`, `globalData` / `global_data` are placed at the top level of the config.
|
|
162
|
+
* - All other extra keys are placed into `config.params`.
|
|
163
|
+
*
|
|
164
|
+
* @param opts - Build options for the AI verb configuration.
|
|
165
|
+
* @returns AI verb configuration dictionary.
|
|
166
|
+
*/
|
|
167
|
+
buildConfig(opts: AIVerbBuildOptions = {}): Record<string, unknown> {
|
|
168
|
+
const {
|
|
169
|
+
promptText,
|
|
170
|
+
promptPom,
|
|
171
|
+
contexts,
|
|
172
|
+
postPrompt,
|
|
173
|
+
postPromptUrl,
|
|
174
|
+
swaig,
|
|
175
|
+
...rest
|
|
176
|
+
} = opts;
|
|
177
|
+
|
|
178
|
+
const config: Record<string, unknown> = {};
|
|
179
|
+
|
|
180
|
+
// Require either text or pom as base prompt (mutually exclusive)
|
|
181
|
+
const basePromptCount = [promptText, promptPom].filter((v) => v !== undefined).length;
|
|
182
|
+
if (basePromptCount === 0) {
|
|
183
|
+
throw new Error('Either promptText or promptPom must be provided as base prompt');
|
|
184
|
+
} else if (basePromptCount > 1) {
|
|
185
|
+
throw new Error('promptText and promptPom are mutually exclusive');
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
// Build prompt object with base prompt
|
|
189
|
+
const promptConfig: Record<string, unknown> = {};
|
|
190
|
+
if (promptText !== undefined) {
|
|
191
|
+
promptConfig['text'] = promptText;
|
|
192
|
+
} else if (promptPom !== undefined) {
|
|
193
|
+
promptConfig['pom'] = promptPom;
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
// Add contexts if provided (optional, activates steps feature)
|
|
197
|
+
if (contexts !== undefined) {
|
|
198
|
+
promptConfig['contexts'] = contexts;
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
config['prompt'] = promptConfig;
|
|
202
|
+
|
|
203
|
+
// Add post-prompt if provided
|
|
204
|
+
if (postPrompt !== undefined) {
|
|
205
|
+
config['post_prompt'] = { text: postPrompt };
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
// Add post-prompt URL if provided
|
|
209
|
+
if (postPromptUrl !== undefined) {
|
|
210
|
+
config['post_prompt_url'] = postPromptUrl;
|
|
211
|
+
}
|
|
212
|
+
|
|
213
|
+
// Add SWAIG if provided
|
|
214
|
+
if (swaig !== undefined) {
|
|
215
|
+
config['SWAIG'] = swaig;
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
// Add any additional parameters
|
|
219
|
+
// Match Python behavior: always initialize params dict
|
|
220
|
+
if (!('params' in config)) {
|
|
221
|
+
config['params'] = {} as Record<string, unknown>;
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
const topLevelKeys = new Set(['languages', 'hints', 'pronounce', 'global_data', 'globalData']);
|
|
225
|
+
for (const [key, value] of Object.entries(rest)) {
|
|
226
|
+
if (topLevelKeys.has(key)) {
|
|
227
|
+
// Route globalData to the snake_case key expected by SWML
|
|
228
|
+
config[key === 'globalData' ? 'global_data' : key] = value;
|
|
229
|
+
} else {
|
|
230
|
+
// Add to params object
|
|
231
|
+
(config['params'] as Record<string, unknown>)[key] = value;
|
|
232
|
+
}
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
return config;
|
|
236
|
+
}
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
/**
|
|
240
|
+
* Registry for SWML verb handlers.
|
|
241
|
+
*
|
|
242
|
+
* This class maintains a registry of handlers for special SWML verbs
|
|
243
|
+
* and provides methods for accessing and using them. The "ai" verb handler
|
|
244
|
+
* ({@link AIVerbHandler}) is registered automatically on construction.
|
|
245
|
+
*
|
|
246
|
+
* @example
|
|
247
|
+
* ```ts
|
|
248
|
+
* const registry = new VerbHandlerRegistry();
|
|
249
|
+
*
|
|
250
|
+
* // The "ai" handler is already registered
|
|
251
|
+
* registry.hasHandler('ai'); // true
|
|
252
|
+
*
|
|
253
|
+
* // Register a custom handler
|
|
254
|
+
* registry.registerHandler(new MyCustomVerbHandler());
|
|
255
|
+
*
|
|
256
|
+
* // Look up a handler
|
|
257
|
+
* const handler = registry.getHandler('ai');
|
|
258
|
+
* if (handler) {
|
|
259
|
+
* const [valid, errors] = handler.validateConfig(config);
|
|
260
|
+
* }
|
|
261
|
+
* ```
|
|
262
|
+
*/
|
|
263
|
+
export class VerbHandlerRegistry {
|
|
264
|
+
private handlers: Map<string, SWMLVerbHandler> = new Map();
|
|
265
|
+
|
|
266
|
+
/** Initialize the registry with default handlers. */
|
|
267
|
+
constructor() {
|
|
268
|
+
// Register default handlers (matches Python's __init__)
|
|
269
|
+
this.registerHandler(new AIVerbHandler());
|
|
270
|
+
}
|
|
271
|
+
|
|
272
|
+
/**
|
|
273
|
+
* Register a new verb handler, replacing any existing handler for the same verb name.
|
|
274
|
+
* @param handler - The handler to register.
|
|
275
|
+
*/
|
|
276
|
+
registerHandler(handler: SWMLVerbHandler): void {
|
|
277
|
+
const verbName = handler.getVerbName();
|
|
278
|
+
this.handlers.set(verbName, handler);
|
|
279
|
+
}
|
|
280
|
+
|
|
281
|
+
/**
|
|
282
|
+
* Get the handler for a specific verb.
|
|
283
|
+
* @param verbName - The name of the verb (e.g. "ai").
|
|
284
|
+
* @returns The handler if found, or `undefined` otherwise.
|
|
285
|
+
*/
|
|
286
|
+
getHandler(verbName: string): SWMLVerbHandler | undefined {
|
|
287
|
+
return this.handlers.get(verbName);
|
|
288
|
+
}
|
|
289
|
+
|
|
290
|
+
/**
|
|
291
|
+
* Check if a handler exists for a specific verb.
|
|
292
|
+
* @param verbName - The name of the verb.
|
|
293
|
+
* @returns `true` if a handler is registered for the verb, `false` otherwise.
|
|
294
|
+
*/
|
|
295
|
+
hasHandler(verbName: string): boolean {
|
|
296
|
+
return this.handlers.has(verbName);
|
|
297
|
+
}
|
|
298
|
+
}
|