@signalwire/sdk 2.0.1 → 2.0.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.
Files changed (610) hide show
  1. package/dist/AgentBase.d.ts +1045 -0
  2. package/dist/AgentBase.js +2375 -0
  3. package/dist/AgentBase.js.map +1 -0
  4. package/dist/AgentServer.d.ts +146 -0
  5. package/dist/AgentServer.js +388 -0
  6. package/dist/AgentServer.js.map +1 -0
  7. package/dist/AuthHandler.d.ts +127 -0
  8. package/dist/AuthHandler.js +212 -0
  9. package/dist/AuthHandler.js.map +1 -0
  10. package/dist/ConfigLoader.d.ts +170 -0
  11. package/dist/ConfigLoader.js +393 -0
  12. package/dist/ConfigLoader.js.map +1 -0
  13. package/dist/ContextBuilder.d.ts +652 -0
  14. package/dist/ContextBuilder.js +1115 -0
  15. package/dist/ContextBuilder.js.map +1 -0
  16. package/dist/DataMap.d.ts +271 -0
  17. package/dist/DataMap.js +430 -0
  18. package/dist/DataMap.js.map +1 -0
  19. package/dist/FunctionResult.d.ts +481 -0
  20. package/dist/FunctionResult.js +775 -0
  21. package/dist/FunctionResult.js.map +1 -0
  22. package/dist/Logger.d.ts +113 -0
  23. package/dist/Logger.js +320 -0
  24. package/dist/Logger.js.map +1 -0
  25. package/dist/PomBuilder.d.ts +208 -0
  26. package/dist/PomBuilder.js +409 -0
  27. package/dist/PomBuilder.js.map +1 -0
  28. package/dist/PromptManager.d.ts +85 -0
  29. package/dist/PromptManager.js +108 -0
  30. package/dist/PromptManager.js.map +1 -0
  31. package/dist/SWMLHandler.d.ts +159 -0
  32. package/dist/SWMLHandler.js +229 -0
  33. package/dist/SWMLHandler.js.map +1 -0
  34. package/dist/SWMLService.d.ts +326 -0
  35. package/dist/SWMLService.js +610 -0
  36. package/dist/SWMLService.js.map +1 -0
  37. package/dist/SchemaUtils.d.ts +108 -0
  38. package/dist/SchemaUtils.js +317 -0
  39. package/dist/SchemaUtils.js.map +1 -0
  40. package/dist/SecurityUtils.d.ts +60 -0
  41. package/{src/SecurityUtils.ts → dist/SecurityUtils.js} +82 -83
  42. package/dist/SecurityUtils.js.map +1 -0
  43. package/dist/ServerlessAdapter.d.ts +119 -0
  44. package/dist/ServerlessAdapter.js +188 -0
  45. package/dist/ServerlessAdapter.js.map +1 -0
  46. package/dist/SessionManager.d.ts +142 -0
  47. package/dist/SessionManager.js +260 -0
  48. package/dist/SessionManager.js.map +1 -0
  49. package/dist/SslConfig.d.ts +77 -0
  50. package/dist/SslConfig.js +100 -0
  51. package/dist/SslConfig.js.map +1 -0
  52. package/dist/SwaigFunction.d.ts +159 -0
  53. package/dist/SwaigFunction.js +209 -0
  54. package/dist/SwaigFunction.js.map +1 -0
  55. package/dist/SwmlBuilder.d.ts +165 -0
  56. package/dist/SwmlBuilder.js +247 -0
  57. package/dist/SwmlBuilder.js.map +1 -0
  58. package/dist/SwmlVerbMethods.generated.d.ts +254 -0
  59. package/dist/SwmlVerbMethods.generated.js +9 -0
  60. package/dist/SwmlVerbMethods.generated.js.map +1 -0
  61. package/dist/TypeInference.d.ts +71 -0
  62. package/dist/TypeInference.js +164 -0
  63. package/dist/TypeInference.js.map +1 -0
  64. package/dist/WebService.d.ts +148 -0
  65. package/dist/WebService.js +532 -0
  66. package/dist/WebService.js.map +1 -0
  67. package/dist/cli/agent-loader.d.ts +22 -0
  68. package/dist/cli/agent-loader.js +144 -0
  69. package/dist/cli/agent-loader.js.map +1 -0
  70. package/dist/cli/mock-data.d.ts +37 -0
  71. package/dist/cli/mock-data.js +80 -0
  72. package/dist/cli/mock-data.js.map +1 -0
  73. package/dist/cli/swaig-test.d.ts +32 -0
  74. package/dist/cli/swaig-test.js +418 -0
  75. package/dist/cli/swaig-test.js.map +1 -0
  76. package/dist/generateVerbTypes.d.ts +11 -0
  77. package/dist/generateVerbTypes.js +265 -0
  78. package/dist/generateVerbTypes.js.map +1 -0
  79. package/{src/index.ts → dist/index.d.ts} +13 -100
  80. package/dist/index.js +152 -0
  81. package/dist/index.js.map +1 -0
  82. package/dist/livewire/index.d.ts +653 -0
  83. package/dist/livewire/index.js +992 -0
  84. package/dist/livewire/index.js.map +1 -0
  85. package/dist/prefabs/ConciergeAgent.d.ts +89 -0
  86. package/dist/prefabs/ConciergeAgent.js +245 -0
  87. package/dist/prefabs/ConciergeAgent.js.map +1 -0
  88. package/dist/prefabs/FAQBotAgent.d.ts +113 -0
  89. package/dist/prefabs/FAQBotAgent.js +329 -0
  90. package/dist/prefabs/FAQBotAgent.js.map +1 -0
  91. package/dist/prefabs/InfoGathererAgent.d.ts +126 -0
  92. package/dist/prefabs/InfoGathererAgent.js +287 -0
  93. package/dist/prefabs/InfoGathererAgent.js.map +1 -0
  94. package/dist/prefabs/ReceptionistAgent.d.ts +104 -0
  95. package/dist/prefabs/ReceptionistAgent.js +303 -0
  96. package/dist/prefabs/ReceptionistAgent.js.map +1 -0
  97. package/dist/prefabs/SurveyAgent.d.ts +148 -0
  98. package/dist/prefabs/SurveyAgent.js +540 -0
  99. package/dist/prefabs/SurveyAgent.js.map +1 -0
  100. package/{src/prefabs/index.ts → dist/prefabs/index.d.ts} +1 -15
  101. package/dist/prefabs/index.js +14 -0
  102. package/dist/prefabs/index.js.map +1 -0
  103. package/dist/relay/Action.d.ts +258 -0
  104. package/dist/relay/Action.js +402 -0
  105. package/dist/relay/Action.js.map +1 -0
  106. package/dist/relay/Call.d.ts +697 -0
  107. package/dist/relay/Call.js +1062 -0
  108. package/dist/relay/Call.js.map +1 -0
  109. package/dist/relay/Deferred.d.ts +44 -0
  110. package/dist/relay/Deferred.js +69 -0
  111. package/dist/relay/Deferred.js.map +1 -0
  112. package/dist/relay/Message.d.ts +103 -0
  113. package/dist/relay/Message.js +169 -0
  114. package/dist/relay/Message.js.map +1 -0
  115. package/dist/relay/RelayClient.d.ts +302 -0
  116. package/dist/relay/RelayClient.js +1026 -0
  117. package/dist/relay/RelayClient.js.map +1 -0
  118. package/dist/relay/RelayError.d.ts +15 -0
  119. package/dist/relay/RelayError.js +20 -0
  120. package/dist/relay/RelayError.js.map +1 -0
  121. package/dist/relay/RelayEvent.d.ts +254 -0
  122. package/dist/relay/RelayEvent.js +509 -0
  123. package/dist/relay/RelayEvent.js.map +1 -0
  124. package/dist/relay/constants.d.ts +90 -0
  125. package/{src/relay/constants.ts → dist/relay/constants.js} +11 -29
  126. package/dist/relay/constants.js.map +1 -0
  127. package/dist/relay/index.d.ts +16 -0
  128. package/dist/relay/index.js +18 -0
  129. package/dist/relay/index.js.map +1 -0
  130. package/dist/relay/types.d.ts +142 -0
  131. package/dist/relay/types.js +5 -0
  132. package/dist/relay/types.js.map +1 -0
  133. package/dist/rest/HttpClient.d.ts +80 -0
  134. package/dist/rest/HttpClient.js +148 -0
  135. package/dist/rest/HttpClient.js.map +1 -0
  136. package/dist/rest/RestError.d.ts +30 -0
  137. package/dist/rest/RestError.js +39 -0
  138. package/dist/rest/RestError.js.map +1 -0
  139. package/dist/rest/base/BaseResource.d.ts +24 -0
  140. package/dist/rest/base/BaseResource.js +29 -0
  141. package/dist/rest/base/BaseResource.js.map +1 -0
  142. package/dist/rest/base/CrudResource.d.ts +68 -0
  143. package/dist/rest/base/CrudResource.js +82 -0
  144. package/dist/rest/base/CrudResource.js.map +1 -0
  145. package/dist/rest/base/CrudWithAddresses.d.ts +22 -0
  146. package/dist/rest/base/CrudWithAddresses.js +25 -0
  147. package/dist/rest/base/CrudWithAddresses.js.map +1 -0
  148. package/dist/rest/index.d.ts +131 -0
  149. package/{src/rest/index.ts → dist/rest/index.js} +101 -136
  150. package/dist/rest/index.js.map +1 -0
  151. package/dist/rest/namespaces/addresses.d.ts +46 -0
  152. package/dist/rest/namespaces/addresses.js +55 -0
  153. package/dist/rest/namespaces/addresses.js.map +1 -0
  154. package/dist/rest/namespaces/calling.d.ts +382 -0
  155. package/dist/rest/namespaces/calling.js +478 -0
  156. package/dist/rest/namespaces/calling.js.map +1 -0
  157. package/dist/rest/namespaces/chat.d.ts +22 -0
  158. package/dist/rest/namespaces/chat.js +26 -0
  159. package/dist/rest/namespaces/chat.js.map +1 -0
  160. package/dist/rest/namespaces/compat.d.ts +585 -0
  161. package/dist/rest/namespaces/compat.js +735 -0
  162. package/dist/rest/namespaces/compat.js.map +1 -0
  163. package/dist/rest/namespaces/datasphere.d.ts +66 -0
  164. package/dist/rest/namespaces/datasphere.js +77 -0
  165. package/dist/rest/namespaces/datasphere.js.map +1 -0
  166. package/dist/rest/namespaces/fabric.d.ts +282 -0
  167. package/dist/rest/namespaces/fabric.js +373 -0
  168. package/dist/rest/namespaces/fabric.js.map +1 -0
  169. package/dist/rest/namespaces/imported-numbers.d.ts +22 -0
  170. package/dist/rest/namespaces/imported-numbers.js +26 -0
  171. package/dist/rest/namespaces/imported-numbers.js.map +1 -0
  172. package/dist/rest/namespaces/logs.d.ts +105 -0
  173. package/dist/rest/namespaces/logs.js +133 -0
  174. package/dist/rest/namespaces/logs.js.map +1 -0
  175. package/dist/rest/namespaces/lookup.d.ts +29 -0
  176. package/dist/rest/namespaces/lookup.js +32 -0
  177. package/dist/rest/namespaces/lookup.js.map +1 -0
  178. package/dist/rest/namespaces/mfa.d.ts +46 -0
  179. package/dist/rest/namespaces/mfa.js +54 -0
  180. package/dist/rest/namespaces/mfa.js.map +1 -0
  181. package/dist/rest/namespaces/number-groups.d.ts +49 -0
  182. package/dist/rest/namespaces/number-groups.js +58 -0
  183. package/dist/rest/namespaces/number-groups.js.map +1 -0
  184. package/dist/rest/namespaces/phone-numbers.d.ts +60 -0
  185. package/dist/rest/namespaces/phone-numbers.js +67 -0
  186. package/dist/rest/namespaces/phone-numbers.js.map +1 -0
  187. package/dist/rest/namespaces/project.d.ts +46 -0
  188. package/dist/rest/namespaces/project.js +56 -0
  189. package/dist/rest/namespaces/project.js.map +1 -0
  190. package/dist/rest/namespaces/pubsub.d.ts +22 -0
  191. package/dist/rest/namespaces/pubsub.js +26 -0
  192. package/dist/rest/namespaces/pubsub.js.map +1 -0
  193. package/dist/rest/namespaces/queues.d.ts +42 -0
  194. package/dist/rest/namespaces/queues.js +49 -0
  195. package/dist/rest/namespaces/queues.js.map +1 -0
  196. package/dist/rest/namespaces/recordings.d.ts +38 -0
  197. package/dist/rest/namespaces/recordings.js +45 -0
  198. package/dist/rest/namespaces/recordings.js.map +1 -0
  199. package/dist/rest/namespaces/registry.d.ts +141 -0
  200. package/dist/rest/namespaces/registry.js +178 -0
  201. package/dist/rest/namespaces/registry.js.map +1 -0
  202. package/dist/rest/namespaces/short-codes.d.ts +39 -0
  203. package/dist/rest/namespaces/short-codes.js +46 -0
  204. package/dist/rest/namespaces/short-codes.js.map +1 -0
  205. package/dist/rest/namespaces/sip-profile.d.ts +28 -0
  206. package/dist/rest/namespaces/sip-profile.js +34 -0
  207. package/dist/rest/namespaces/sip-profile.js.map +1 -0
  208. package/dist/rest/namespaces/verified-callers.d.ts +33 -0
  209. package/dist/rest/namespaces/verified-callers.js +39 -0
  210. package/dist/rest/namespaces/verified-callers.js.map +1 -0
  211. package/dist/rest/namespaces/video.d.ts +235 -0
  212. package/dist/rest/namespaces/video.js +297 -0
  213. package/dist/rest/namespaces/video.js.map +1 -0
  214. package/{src/rest/pagination.ts → dist/rest/pagination.d.ts} +2 -61
  215. package/dist/rest/pagination.js +78 -0
  216. package/dist/rest/pagination.js.map +1 -0
  217. package/dist/rest/types.d.ts +54 -0
  218. package/dist/rest/types.js +5 -0
  219. package/dist/rest/types.js.map +1 -0
  220. package/dist/skills/SkillBase.d.ts +404 -0
  221. package/dist/skills/SkillBase.js +471 -0
  222. package/dist/skills/SkillBase.js.map +1 -0
  223. package/dist/skills/SkillManager.d.ts +195 -0
  224. package/dist/skills/SkillManager.js +378 -0
  225. package/dist/skills/SkillManager.js.map +1 -0
  226. package/dist/skills/SkillRegistry.d.ts +176 -0
  227. package/dist/skills/SkillRegistry.js +310 -0
  228. package/dist/skills/SkillRegistry.js.map +1 -0
  229. package/dist/skills/builtin/api_ninjas_trivia.d.ts +47 -0
  230. package/dist/skills/builtin/api_ninjas_trivia.js +211 -0
  231. package/dist/skills/builtin/api_ninjas_trivia.js.map +1 -0
  232. package/dist/skills/builtin/ask_claude.d.ts +37 -0
  233. package/dist/skills/builtin/ask_claude.js +162 -0
  234. package/dist/skills/builtin/ask_claude.js.map +1 -0
  235. package/dist/skills/builtin/claude_skills.d.ts +75 -0
  236. package/dist/skills/builtin/claude_skills.js +753 -0
  237. package/dist/skills/builtin/claude_skills.js.map +1 -0
  238. package/dist/skills/builtin/custom_skills.d.ts +79 -0
  239. package/dist/skills/builtin/custom_skills.js +227 -0
  240. package/dist/skills/builtin/custom_skills.js.map +1 -0
  241. package/dist/skills/builtin/datasphere.d.ts +73 -0
  242. package/dist/skills/builtin/datasphere.js +350 -0
  243. package/dist/skills/builtin/datasphere.js.map +1 -0
  244. package/dist/skills/builtin/datasphere_serverless.d.ts +89 -0
  245. package/dist/skills/builtin/datasphere_serverless.js +291 -0
  246. package/dist/skills/builtin/datasphere_serverless.js.map +1 -0
  247. package/dist/skills/builtin/datetime.d.ts +40 -0
  248. package/dist/skills/builtin/datetime.js +118 -0
  249. package/dist/skills/builtin/datetime.js.map +1 -0
  250. package/dist/skills/builtin/google_maps.d.ts +48 -0
  251. package/dist/skills/builtin/google_maps.js +470 -0
  252. package/dist/skills/builtin/google_maps.js.map +1 -0
  253. package/dist/skills/builtin/index.d.ts +31 -0
  254. package/{src/skills/builtin/index.ts → dist/skills/builtin/index.js} +30 -36
  255. package/dist/skills/builtin/index.js.map +1 -0
  256. package/dist/skills/builtin/info_gatherer.d.ts +115 -0
  257. package/dist/skills/builtin/info_gatherer.js +328 -0
  258. package/dist/skills/builtin/info_gatherer.js.map +1 -0
  259. package/dist/skills/builtin/joke.d.ts +41 -0
  260. package/dist/skills/builtin/joke.js +156 -0
  261. package/dist/skills/builtin/joke.js.map +1 -0
  262. package/dist/skills/builtin/math.d.ts +39 -0
  263. package/dist/skills/builtin/math.js +119 -0
  264. package/dist/skills/builtin/math.js.map +1 -0
  265. package/dist/skills/builtin/mcp_gateway.d.ts +82 -0
  266. package/dist/skills/builtin/mcp_gateway.js +574 -0
  267. package/dist/skills/builtin/mcp_gateway.js.map +1 -0
  268. package/dist/skills/builtin/native_vector_search.d.ts +128 -0
  269. package/dist/skills/builtin/native_vector_search.js +752 -0
  270. package/dist/skills/builtin/native_vector_search.js.map +1 -0
  271. package/dist/skills/builtin/play_background_file.d.ts +59 -0
  272. package/dist/skills/builtin/play_background_file.js +274 -0
  273. package/dist/skills/builtin/play_background_file.js.map +1 -0
  274. package/dist/skills/builtin/spider.d.ts +91 -0
  275. package/dist/skills/builtin/spider.js +758 -0
  276. package/dist/skills/builtin/spider.js.map +1 -0
  277. package/dist/skills/builtin/swml_transfer.d.ts +66 -0
  278. package/dist/skills/builtin/swml_transfer.js +475 -0
  279. package/dist/skills/builtin/swml_transfer.js.map +1 -0
  280. package/dist/skills/builtin/weather_api.d.ts +59 -0
  281. package/dist/skills/builtin/weather_api.js +196 -0
  282. package/dist/skills/builtin/weather_api.js.map +1 -0
  283. package/dist/skills/builtin/web_search.d.ts +160 -0
  284. package/dist/skills/builtin/web_search.js +894 -0
  285. package/dist/skills/builtin/web_search.js.map +1 -0
  286. package/dist/skills/builtin/wikipedia_search.d.ts +77 -0
  287. package/dist/skills/builtin/wikipedia_search.js +241 -0
  288. package/dist/skills/builtin/wikipedia_search.js.map +1 -0
  289. package/{src/skills/index.ts → dist/skills/index.d.ts} +0 -1
  290. package/dist/skills/index.js +10 -0
  291. package/dist/skills/index.js.map +1 -0
  292. package/dist/types.d.ts +118 -0
  293. package/dist/types.js +5 -0
  294. package/dist/types.js.map +1 -0
  295. package/package.json +7 -1
  296. package/.github/workflows/publish.yml +0 -27
  297. package/.github/workflows/test.yml +0 -17
  298. package/CLAUDE.md +0 -112
  299. package/docs/MIGRATION-2.0.md +0 -81
  300. package/docs/agent-guide.md +0 -869
  301. package/docs/agent_guide.md +0 -1026
  302. package/docs/api-reference.md +0 -2420
  303. package/docs/api_reference.md +0 -1301
  304. package/docs/architecture.md +0 -843
  305. package/docs/cli-guide.md +0 -579
  306. package/docs/cli_guide.md +0 -448
  307. package/docs/cloud_functions_guide.md +0 -474
  308. package/docs/configuration.md +0 -422
  309. package/docs/contexts-guide.md +0 -787
  310. package/docs/contexts_guide.md +0 -511
  311. package/docs/datamap-guide.md +0 -1141
  312. package/docs/datamap_guide.md +0 -595
  313. package/docs/llm_parameters.md +0 -239
  314. package/docs/mcp_gateway_reference.md +0 -648
  315. package/docs/mcp_integration.md +0 -108
  316. package/docs/prefabs-guide.md +0 -800
  317. package/docs/sdk_features.md +0 -477
  318. package/docs/security.md +0 -436
  319. package/docs/serverless-guide.md +0 -513
  320. package/docs/skills-guide.md +0 -857
  321. package/docs/skills-system.md +0 -301
  322. package/docs/skills_parameter_schema.md +0 -392
  323. package/docs/skills_system.md +0 -467
  324. package/docs/swaig-reference.md +0 -1627
  325. package/docs/swaig_reference.md +0 -910
  326. package/docs/swml_service_guide.md +0 -600
  327. package/docs/third_party_skills.md +0 -533
  328. package/docs/web_service.md +0 -677
  329. package/examples/README.md +0 -131
  330. package/examples/advanced-datamap.ts +0 -100
  331. package/examples/advanced-dynamic-config.ts +0 -70
  332. package/examples/auto-vivified.ts +0 -94
  333. package/examples/call-flow.ts +0 -63
  334. package/examples/comprehensive-dynamic.ts +0 -125
  335. package/examples/contexts-steps.ts +0 -65
  336. package/examples/custom-path.ts +0 -45
  337. package/examples/datamap-tools.ts +0 -55
  338. package/examples/datasphere-multi-instance.ts +0 -63
  339. package/examples/datasphere-serverless-env.ts +0 -68
  340. package/examples/datasphere-webhook-env.ts +0 -66
  341. package/examples/datasphere.ts +0 -37
  342. package/examples/declarative.ts +0 -100
  343. package/examples/dynamic-config.ts +0 -54
  344. package/examples/dynamic-info-gatherer.ts +0 -69
  345. package/examples/dynamic-swml-service.ts +0 -67
  346. package/examples/gather-info.ts +0 -71
  347. package/examples/gather-per-question-functions-demo.ts +0 -140
  348. package/examples/joke-agent.ts +0 -34
  349. package/examples/kubernetes-agent.ts +0 -45
  350. package/examples/llm-params.ts +0 -69
  351. package/examples/mcp-agent.ts +0 -84
  352. package/examples/mcp-gateway.ts +0 -35
  353. package/examples/multi-agent.ts +0 -73
  354. package/examples/multi-endpoint.ts +0 -79
  355. package/examples/pom-prompt.ts +0 -71
  356. package/examples/prefab-concierge.ts +0 -47
  357. package/examples/prefab-faq.ts +0 -54
  358. package/examples/prefab-info-gatherer.ts +0 -33
  359. package/examples/prefab-receptionist.ts +0 -36
  360. package/examples/prefab-survey.ts +0 -68
  361. package/examples/record-call.ts +0 -67
  362. package/examples/relay-demo.ts +0 -33
  363. package/examples/room-and-sip.ts +0 -94
  364. package/examples/serverless-lambda.ts +0 -35
  365. package/examples/session-state.ts +0 -83
  366. package/examples/simple-agent.ts +0 -36
  367. package/examples/simple-static.ts +0 -29
  368. package/examples/skills-demo.ts +0 -38
  369. package/examples/step-function-inheritance-demo.ts +0 -124
  370. package/examples/swaig-features.ts +0 -187
  371. package/examples/swml-service-routing.ts +0 -66
  372. package/examples/swml-service.ts +0 -38
  373. package/examples/tap.ts +0 -68
  374. package/examples/verb-methods.ts +0 -45
  375. package/examples/web-search-multi-instance.ts +0 -72
  376. package/examples/web-search.ts +0 -38
  377. package/examples/wikipedia.ts +0 -36
  378. package/livewire/README.md +0 -140
  379. package/livewire/docs/migration-guide.md +0 -228
  380. package/livewire/examples/livewire-basic-agent.ts +0 -74
  381. package/livewire/examples/livewire-handoff.ts +0 -197
  382. package/livewire/examples/livewire-multi-tool.ts +0 -117
  383. package/relay/README.md +0 -70
  384. package/relay/RELAY_IMPLEMENTATION_GUIDE.md +0 -1257
  385. package/relay/docs/call-methods.md +0 -474
  386. package/relay/docs/client-reference.md +0 -142
  387. package/relay/docs/events.md +0 -134
  388. package/relay/docs/getting-started.md +0 -134
  389. package/relay/docs/guide.md +0 -306
  390. package/relay/docs/messaging.md +0 -182
  391. package/relay/examples/relay-inbound.ts +0 -66
  392. package/relay/examples/relay-messaging.ts +0 -71
  393. package/relay/examples/relay-outbound.ts +0 -76
  394. package/rest/README.md +0 -95
  395. package/rest/docs/calling.md +0 -273
  396. package/rest/docs/client-reference.md +0 -107
  397. package/rest/docs/compat.md +0 -204
  398. package/rest/docs/fabric.md +0 -183
  399. package/rest/docs/getting-started.md +0 -110
  400. package/rest/docs/guide.md +0 -351
  401. package/rest/docs/namespaces.md +0 -285
  402. package/rest/examples/rest-10dlc-registration.ts +0 -161
  403. package/rest/examples/rest-calling-ivr-and-ai.ts +0 -102
  404. package/rest/examples/rest-calling-play-and-record.ts +0 -91
  405. package/rest/examples/rest-client.ts +0 -65
  406. package/rest/examples/rest-compat-laml.ts +0 -210
  407. package/rest/examples/rest-datasphere-search.ts +0 -82
  408. package/rest/examples/rest-fabric-conferences-and-routing.ts +0 -144
  409. package/rest/examples/rest-fabric-subscribers-and-sip.ts +0 -108
  410. package/rest/examples/rest-fabric-swml-and-callflows.ts +0 -99
  411. package/rest/examples/rest-manage-resources.ts +0 -65
  412. package/rest/examples/rest-phone-number-management.ts +0 -197
  413. package/rest/examples/rest-queues-mfa-and-recordings.ts +0 -143
  414. package/rest/examples/rest-video-rooms.ts +0 -186
  415. package/src/AgentBase.ts +0 -2598
  416. package/src/AgentServer.ts +0 -442
  417. package/src/AuthHandler.ts +0 -256
  418. package/src/ConfigLoader.ts +0 -447
  419. package/src/ContextBuilder.ts +0 -1181
  420. package/src/DataMap.ts +0 -477
  421. package/src/FunctionResult.ts +0 -903
  422. package/src/Logger.ts +0 -337
  423. package/src/PomBuilder.ts +0 -467
  424. package/src/PromptManager.ts +0 -133
  425. package/src/SWMLHandler.ts +0 -298
  426. package/src/SWMLService.ts +0 -749
  427. package/src/SchemaUtils.ts +0 -361
  428. package/src/ServerlessAdapter.ts +0 -240
  429. package/src/SessionManager.ts +0 -311
  430. package/src/SslConfig.ts +0 -118
  431. package/src/SwaigFunction.ts +0 -276
  432. package/src/SwmlBuilder.ts +0 -283
  433. package/src/SwmlVerbMethods.generated.ts +0 -234
  434. package/src/TypeInference.ts +0 -199
  435. package/src/WebService.ts +0 -641
  436. package/src/cli/agent-loader.ts +0 -166
  437. package/src/cli/mock-data.ts +0 -111
  438. package/src/cli/swaig-test.ts +0 -452
  439. package/src/generateVerbTypes.ts +0 -322
  440. package/src/livewire/index.ts +0 -1252
  441. package/src/prefabs/ConciergeAgent.ts +0 -309
  442. package/src/prefabs/FAQBotAgent.ts +0 -415
  443. package/src/prefabs/InfoGathererAgent.ts +0 -379
  444. package/src/prefabs/ReceptionistAgent.ts +0 -395
  445. package/src/prefabs/SurveyAgent.ts +0 -671
  446. package/src/relay/Action.ts +0 -482
  447. package/src/relay/Call.ts +0 -1270
  448. package/src/relay/Deferred.ts +0 -94
  449. package/src/relay/Message.ts +0 -199
  450. package/src/relay/RelayClient.ts +0 -1185
  451. package/src/relay/RelayError.ts +0 -20
  452. package/src/relay/RelayEvent.ts +0 -944
  453. package/src/relay/index.ts +0 -123
  454. package/src/relay/types.ts +0 -149
  455. package/src/rest/HttpClient.ts +0 -164
  456. package/src/rest/RestError.ts +0 -45
  457. package/src/rest/base/BaseResource.ts +0 -32
  458. package/src/rest/base/CrudResource.ts +0 -98
  459. package/src/rest/base/CrudWithAddresses.ts +0 -37
  460. package/src/rest/namespaces/addresses.ts +0 -64
  461. package/src/rest/namespaces/calling.ts +0 -534
  462. package/src/rest/namespaces/chat.ts +0 -31
  463. package/src/rest/namespaces/compat.ts +0 -812
  464. package/src/rest/namespaces/datasphere.ts +0 -88
  465. package/src/rest/namespaces/fabric.ts +0 -417
  466. package/src/rest/namespaces/imported-numbers.ts +0 -31
  467. package/src/rest/namespaces/logs.ts +0 -151
  468. package/src/rest/namespaces/lookup.ts +0 -38
  469. package/src/rest/namespaces/mfa.ts +0 -61
  470. package/src/rest/namespaces/number-groups.ts +0 -68
  471. package/src/rest/namespaces/phone-numbers.ts +0 -76
  472. package/src/rest/namespaces/project.ts +0 -65
  473. package/src/rest/namespaces/pubsub.ts +0 -31
  474. package/src/rest/namespaces/queues.ts +0 -58
  475. package/src/rest/namespaces/recordings.ts +0 -53
  476. package/src/rest/namespaces/registry.ts +0 -200
  477. package/src/rest/namespaces/short-codes.ts +0 -54
  478. package/src/rest/namespaces/sip-profile.ts +0 -40
  479. package/src/rest/namespaces/verified-callers.ts +0 -46
  480. package/src/rest/namespaces/video.ts +0 -332
  481. package/src/rest/types.ts +0 -61
  482. package/src/skills/SkillBase.ts +0 -582
  483. package/src/skills/SkillManager.ts +0 -419
  484. package/src/skills/SkillRegistry.ts +0 -367
  485. package/src/skills/builtin/api_ninjas_trivia.ts +0 -285
  486. package/src/skills/builtin/ask_claude.ts +0 -246
  487. package/src/skills/builtin/claude_skills.ts +0 -983
  488. package/src/skills/builtin/custom_skills.ts +0 -327
  489. package/src/skills/builtin/datasphere.ts +0 -447
  490. package/src/skills/builtin/datasphere_serverless.ts +0 -347
  491. package/src/skills/builtin/datetime.ts +0 -137
  492. package/src/skills/builtin/google_maps.ts +0 -656
  493. package/src/skills/builtin/info_gatherer.ts +0 -415
  494. package/src/skills/builtin/joke.ts +0 -196
  495. package/src/skills/builtin/math.ts +0 -149
  496. package/src/skills/builtin/mcp_gateway.ts +0 -685
  497. package/src/skills/builtin/native_vector_search.ts +0 -910
  498. package/src/skills/builtin/play_background_file.ts +0 -367
  499. package/src/skills/builtin/spider.ts +0 -874
  500. package/src/skills/builtin/swml_transfer.ts +0 -645
  501. package/src/skills/builtin/weather_api.ts +0 -255
  502. package/src/skills/builtin/web_search.ts +0 -1083
  503. package/src/skills/builtin/wikipedia_search.ts +0 -304
  504. package/src/types.ts +0 -132
  505. package/tests/AgentBase.test.ts +0 -1093
  506. package/tests/AgentServer.test.ts +0 -126
  507. package/tests/AuthHandler.test.ts +0 -133
  508. package/tests/ConfigLoader.test.ts +0 -151
  509. package/tests/ContextBuilder.test.ts +0 -108
  510. package/tests/DataMap.test.ts +0 -367
  511. package/tests/EphemeralSkillCopy.test.ts +0 -107
  512. package/tests/FunctionResult.test.ts +0 -298
  513. package/tests/GracefulShutdown.test.ts +0 -46
  514. package/tests/Logger.test.ts +0 -420
  515. package/tests/PomBuilder.test.ts +0 -228
  516. package/tests/ProxyDetection.test.ts +0 -228
  517. package/tests/SWMLService.test.ts +0 -320
  518. package/tests/SWMLVerbHandler.test.ts +0 -523
  519. package/tests/SchemaUtils.test.ts +0 -106
  520. package/tests/SchemaUtils.verb.test.ts +0 -206
  521. package/tests/SecurityUtils.test.ts +0 -192
  522. package/tests/ServerlessAdapter.test.ts +0 -222
  523. package/tests/SessionManager.test.ts +0 -257
  524. package/tests/SkillBaseFeatures.test.ts +0 -130
  525. package/tests/SkillMultiInstance.test.ts +0 -102
  526. package/tests/SkillParameterSchemas.test.ts +0 -134
  527. package/tests/SkillRegistrySchema.test.ts +0 -84
  528. package/tests/SslConfig.test.ts +0 -97
  529. package/tests/SwmlBuilder.test.ts +0 -400
  530. package/tests/TypeInference.test.ts +0 -165
  531. package/tests/VerbHandlerRegistry.test.ts +0 -128
  532. package/tests/cli/mock-data.test.ts +0 -113
  533. package/tests/cli/swaig-test.test.ts +0 -108
  534. package/tests/examples.test.ts +0 -194
  535. package/tests/fixtures/scrape-parity/README.md +0 -53
  536. package/tests/fixtures/scrape-parity/expected/01_simple_article.json +0 -5
  537. package/tests/fixtures/scrape-parity/expected/02_class_based_noise.json +0 -5
  538. package/tests/fixtures/scrape-parity/expected/03_nested_containers.json +0 -5
  539. package/tests/fixtures/scrape-parity/expected/04_bare_body.json +0 -5
  540. package/tests/fixtures/scrape-parity/expected/05_malformed.json +0 -5
  541. package/tests/fixtures/scrape-parity/expected/06_multi_class.json +0 -5
  542. package/tests/fixtures/scrape-parity/expected/07_anchor_pattern.json +0 -5
  543. package/tests/fixtures/scrape-parity/expected/08_inline_script.json +0 -5
  544. package/tests/fixtures/scrape-parity/expected/09_whitespace_nbsp.json +0 -5
  545. package/tests/fixtures/scrape-parity/expected/10_entity_unicode.json +0 -5
  546. package/tests/fixtures/scrape-parity/expected/11_cdata_comments.json +0 -5
  547. package/tests/fixtures/scrape-parity/expected/12_deep_nested_removals.json +0 -5
  548. package/tests/fixtures/scrape-parity/html/01_simple_article.html +0 -18
  549. package/tests/fixtures/scrape-parity/html/02_class_based_noise.html +0 -18
  550. package/tests/fixtures/scrape-parity/html/03_nested_containers.html +0 -13
  551. package/tests/fixtures/scrape-parity/html/04_bare_body.html +0 -9
  552. package/tests/fixtures/scrape-parity/html/05_malformed.html +0 -11
  553. package/tests/fixtures/scrape-parity/html/06_multi_class.html +0 -18
  554. package/tests/fixtures/scrape-parity/html/07_anchor_pattern.html +0 -12
  555. package/tests/fixtures/scrape-parity/html/08_inline_script.html +0 -17
  556. package/tests/fixtures/scrape-parity/html/09_whitespace_nbsp.html +0 -21
  557. package/tests/fixtures/scrape-parity/html/10_entity_unicode.html +0 -10
  558. package/tests/fixtures/scrape-parity/html/11_cdata_comments.html +0 -13
  559. package/tests/fixtures/scrape-parity/html/12_deep_nested_removals.html +0 -24
  560. package/tests/fixtures/scrape-parity/python_extract.py +0 -109
  561. package/tests/livewire/livewire.test.ts +0 -780
  562. package/tests/mcp.test.ts +0 -221
  563. package/tests/prefabs/prefabs.test.ts +0 -1093
  564. package/tests/relay/Action.test.ts +0 -392
  565. package/tests/relay/Call.test.ts +0 -535
  566. package/tests/relay/Deferred.test.ts +0 -71
  567. package/tests/relay/Message.test.ts +0 -164
  568. package/tests/relay/RelayClient.test.ts +0 -779
  569. package/tests/relay/RelayEvent.test.ts +0 -463
  570. package/tests/relay/helpers.ts +0 -79
  571. package/tests/rest/HttpClient.test.ts +0 -274
  572. package/tests/rest/RestError.test.ts +0 -53
  573. package/tests/rest/calling.test.ts +0 -156
  574. package/tests/rest/client.test.ts +0 -197
  575. package/tests/rest/compat.test.ts +0 -335
  576. package/tests/rest/datasphere.test.ts +0 -71
  577. package/tests/rest/fabric.test.ts +0 -186
  578. package/tests/rest/helpers.ts +0 -95
  579. package/tests/rest/logs.test.ts +0 -68
  580. package/tests/rest/pagination.test.ts +0 -133
  581. package/tests/rest/registry.test.ts +0 -94
  582. package/tests/rest/relay-rest.test.ts +0 -290
  583. package/tests/rest/video.test.ts +0 -173
  584. package/tests/setup.ts +0 -6
  585. package/tests/skills/SkillBase.test.ts +0 -108
  586. package/tests/skills/SkillManager.test.ts +0 -268
  587. package/tests/skills/SkillRegistry.test.ts +0 -176
  588. package/tests/skills/builtin.test.ts +0 -1472
  589. package/tests/skills/claude-skills.test.ts +0 -54
  590. package/tests/skills/custom-skills.test.ts +0 -53
  591. package/tests/skills/datasphere-serverless.test.ts +0 -70
  592. package/tests/skills/datasphere.test.ts +0 -107
  593. package/tests/skills/datetime.test.ts +0 -101
  594. package/tests/skills/google-maps.test.ts +0 -78
  595. package/tests/skills/info-gatherer.test.ts +0 -411
  596. package/tests/skills/joke.test.ts +0 -81
  597. package/tests/skills/math.test.ts +0 -68
  598. package/tests/skills/mcp-gateway.test.ts +0 -101
  599. package/tests/skills/play-background.test.ts +0 -54
  600. package/tests/skills/spider.test.ts +0 -108
  601. package/tests/skills/swml-transfer.test.ts +0 -178
  602. package/tests/skills/trivia.test.ts +0 -54
  603. package/tests/skills/vector-search.test.ts +0 -135
  604. package/tests/skills/weather-api.test.ts +0 -77
  605. package/tests/skills/web-search-parity.test.ts +0 -59
  606. package/tests/skills/web-search.test.ts +0 -103
  607. package/tests/skills/wikipedia.test.ts +0 -63
  608. package/tsconfig.json +0 -18
  609. package/vitest.config.ts +0 -9
  610. /package/{src → dist}/schema.json +0 -0
@@ -1,301 +0,0 @@
1
- # Skills System Reference
2
-
3
- Architectural reference for the Skills system in the SignalWire AI Agents TypeScript SDK.
4
-
5
- > **See also:** [skills-guide.md](skills-guide.md) for usage patterns and built-in skill details.
6
-
7
- ---
8
-
9
- ## Table of Contents
10
-
11
- 1. [Architecture](#architecture)
12
- 2. [SkillBase](#skillbase)
13
- 3. [SkillManager](#skillmanager)
14
- 4. [SkillRegistry](#skillregistry)
15
- 5. [Tool Registration Flow](#tool-registration-flow)
16
- 6. [Creating a Custom Skill](#creating-a-custom-skill)
17
- 7. [Multi-Instance Skills](#multi-instance-skills)
18
- 8. [Environment Validation](#environment-validation)
19
- 9. [Parameter Schema Discovery](#parameter-schema-discovery)
20
- 10. [Lifecycle Hooks](#lifecycle-hooks)
21
-
22
- ---
23
-
24
- ## Architecture
25
-
26
- The skills system consists of three cooperating components:
27
-
28
- ```
29
- SkillRegistry (singleton)
30
- |
31
- +-- registers skill factories by name
32
- |
33
- +-- SkillBase subclasses
34
- |
35
- +-- provide tools, prompts, hints, global data
36
- |
37
- +-- managed by SkillManager (per-agent)
38
- ```
39
-
40
- | Component | Responsibility |
41
- |---|---|
42
- | **SkillBase** | Abstract base class every skill extends. Declares tools, prompts, hints, and config schema. |
43
- | **SkillManager** | Attached to each `AgentBase`. Loads, validates, and wires skills into the agent. |
44
- | **SkillRegistry** | Global singleton. Maps skill names to factory functions for `agent.addSkill()` lookups. |
45
-
46
- ---
47
-
48
- ## SkillBase
49
-
50
- All skills extend `SkillBase`. The base class defines the contract:
51
-
52
- ```typescript
53
- import { SkillBase, SkillManifest, SkillToolRegistration } from '@signalwire/sdk';
54
-
55
- class MySkill extends SkillBase {
56
- static manifest: SkillManifest = {
57
- name: 'my_skill',
58
- version: '1.0.0',
59
- description: 'Does something useful',
60
- requiredEnvVars: ['MY_API_KEY'],
61
- supportsMultipleInstances: false,
62
- };
63
-
64
- registerTools(): SkillToolRegistration[] {
65
- return [
66
- {
67
- name: 'my_tool',
68
- description: 'Performs the action',
69
- parameters: { query: { type: 'string', description: 'Input' } },
70
- handler: (args) => {
71
- return new FunctionResult(`Result for ${args.query}`);
72
- },
73
- },
74
- ];
75
- }
76
-
77
- getHints(): string[] {
78
- return ['my skill', 'useful action'];
79
- }
80
-
81
- getPromptSections(): Array<{ title: string; body: string; bullets?: string[] }> {
82
- return [
83
- {
84
- title: 'My Skill',
85
- body: 'You have access to my_tool for performing useful actions.',
86
- },
87
- ];
88
- }
89
-
90
- getGlobalData(): Record<string, unknown> {
91
- return { my_skill_enabled: true };
92
- }
93
- }
94
- ```
95
-
96
- ### Key Methods
97
-
98
- | Method | Returns | Purpose |
99
- |---|---|---|
100
- | `registerTools()` | `SkillToolRegistration[]` | Define the SWAIG tools this skill provides |
101
- | `getHints()` | `string[]` | Speech recognition hints for ASR accuracy |
102
- | `getPromptSections()` | Section array | Prompt text injected into the agent's system prompt |
103
- | `getGlobalData()` | `Record<string, unknown>` | Key-value pairs merged into agent global data |
104
- | `setup()` | `Promise<void>` | Async initialization (API connections, file loading) |
105
- | `teardown()` | `Promise<void>` | Cleanup on agent shutdown |
106
-
107
- ---
108
-
109
- ## SkillManager
110
-
111
- Each `AgentBase` has an internal `SkillManager`. When you call `agent.addSkill()`, the manager:
112
-
113
- 1. Validates required environment variables from the skill manifest.
114
- 2. Calls `skill.setup()` for async initialization.
115
- 3. Registers all tools from `skill.registerTools()` with the agent.
116
- 4. Merges hints from `skill.getHints()` into the agent's hint list.
117
- 5. Adds prompt sections from `skill.getPromptSections()` to the POM.
118
- 6. Merges global data from `skill.getGlobalData()`.
119
-
120
- ```typescript
121
- // SkillManager is used internally by AgentBase
122
- const skills = agent.listSkills(); // Returns loaded skill metadata
123
- ```
124
-
125
- ---
126
-
127
- ## SkillRegistry
128
-
129
- The global registry allows skills to be discovered by name:
130
-
131
- ```typescript
132
- import { SkillRegistry } from '@signalwire/sdk';
133
-
134
- // List all registered skills
135
- const available = SkillRegistry.listSkills();
136
- // => [{ name: 'datetime', description: '...', version: '1.0.0' }, ...]
137
-
138
- // Get a skill's parameter schema
139
- const schema = SkillRegistry.getParameterSchema('web_search');
140
- ```
141
-
142
- Built-in skills register themselves automatically when imported. Custom skills must call `SkillRegistry.register()`:
143
-
144
- ```typescript
145
- SkillRegistry.register('my_skill', (config) => new MySkill(config));
146
- ```
147
-
148
- ---
149
-
150
- ## Tool Registration Flow
151
-
152
- ```
153
- agent.addSkill(new WebSearchSkill({ max_results: 5 }))
154
- |
155
- v
156
- SkillManager.loadSkill(skill)
157
- |
158
- +-- validate env vars (GOOGLE_SEARCH_API_KEY, etc.)
159
- +-- skill.setup() // async init
160
- +-- skill.registerTools() // get tool definitions
161
- | |
162
- | v
163
- +-- agent.defineTool(...) // register each tool on the agent
164
- +-- agent.addHints(...) // merge hints
165
- +-- agent.promptAddSection(...) // add prompt text
166
- +-- agent.updateGlobalData(...) // merge global data
167
- ```
168
-
169
- ---
170
-
171
- ## Creating a Custom Skill
172
-
173
- 1. **Extend `SkillBase`** and declare a static `manifest`:
174
-
175
- ```typescript
176
- import { SkillBase, FunctionResult } from '@signalwire/sdk';
177
-
178
- export class StockPriceSkill extends SkillBase {
179
- static manifest = {
180
- name: 'stock_price',
181
- version: '1.0.0',
182
- description: 'Look up current stock prices',
183
- requiredEnvVars: ['STOCK_API_KEY'],
184
- supportsMultipleInstances: false,
185
- };
186
-
187
- private apiKey: string;
188
-
189
- constructor(config: Record<string, unknown> = {}) {
190
- super(config);
191
- this.apiKey = process.env['STOCK_API_KEY'] ?? '';
192
- }
193
-
194
- registerTools() {
195
- return [
196
- {
197
- name: 'get_stock_price',
198
- description: 'Get the current price of a stock by ticker symbol',
199
- parameters: {
200
- ticker: { type: 'string', description: 'Stock ticker symbol (e.g. AAPL)' },
201
- },
202
- handler: async (args: Record<string, unknown>) => {
203
- const ticker = String(args.ticker).toUpperCase();
204
- // In production, call a real stock API here
205
- return new FunctionResult(`${ticker} is currently trading at $150.25`);
206
- },
207
- },
208
- ];
209
- }
210
-
211
- getHints() {
212
- return ['stock', 'ticker', 'price', 'market', 'shares'];
213
- }
214
-
215
- getPromptSections() {
216
- return [
217
- {
218
- title: 'Stock Price Lookup',
219
- body: 'You can look up current stock prices using the get_stock_price tool. ' +
220
- 'Ask the user for a ticker symbol if they want a price quote.',
221
- },
222
- ];
223
- }
224
- }
225
- ```
226
-
227
- 2. **Register** the skill (optional, for name-based discovery):
228
-
229
- ```typescript
230
- import { SkillRegistry } from '@signalwire/sdk';
231
- SkillRegistry.register('stock_price', (config) => new StockPriceSkill(config));
232
- ```
233
-
234
- 3. **Use** the skill:
235
-
236
- ```typescript
237
- await agent.addSkill(new StockPriceSkill());
238
- ```
239
-
240
- ---
241
-
242
- ## Multi-Instance Skills
243
-
244
- Some skills support multiple instances with different configurations. Set `supportsMultipleInstances: true` in the manifest and accept a `tool_name` config parameter:
245
-
246
- ```typescript
247
- // Two DataSphere instances with different knowledge bases
248
- await agent.addSkill(new DataSphereSkill({
249
- document_id: 'drinks-doc',
250
- tool_name: 'search_drinks',
251
- }));
252
-
253
- await agent.addSkill(new DataSphereSkill({
254
- document_id: 'food-doc',
255
- tool_name: 'search_food',
256
- }));
257
- ```
258
-
259
- Each instance registers its tools under the configured `tool_name`, avoiding collisions.
260
-
261
- ---
262
-
263
- ## Environment Validation
264
-
265
- Skills declare required environment variables in their manifest. The `SkillManager` checks these before calling `setup()`:
266
-
267
- ```typescript
268
- static manifest = {
269
- // ...
270
- requiredEnvVars: ['GOOGLE_SEARCH_API_KEY', 'GOOGLE_SEARCH_CX'],
271
- };
272
- ```
273
-
274
- If any required variable is missing, `addSkill()` throws with a descriptive error message listing the missing variables.
275
-
276
- ---
277
-
278
- ## Parameter Schema Discovery
279
-
280
- Skills can expose their configuration schema for tooling and documentation:
281
-
282
- ```typescript
283
- // Get the parameter schema for a skill class
284
- const schema = WebSearchSkill.getParameterSchema();
285
- // => { max_results: { type: 'number', default: 5 }, safe_search: { type: 'string', ... } }
286
- ```
287
-
288
- This allows external tools to generate configuration UIs or validate config objects before passing them to the skill constructor.
289
-
290
- ---
291
-
292
- ## Lifecycle Hooks
293
-
294
- | Hook | When | Use Case |
295
- |---|---|---|
296
- | `constructor(config)` | Instantiation | Store config, set defaults |
297
- | `setup()` | During `addSkill()` | Async init: connect to APIs, load data |
298
- | `registerTools()` | During `addSkill()` | Return tool definitions |
299
- | `teardown()` | Agent shutdown | Close connections, flush buffers |
300
-
301
- All hooks are called by the `SkillManager` in the order shown above.
@@ -1,392 +0,0 @@
1
- # Skills Parameter Schema System
2
-
3
- This guide explains the parameter schema system for SignalWire AI Agents SDK skills, which enables GUI configuration tools and programmatic skill discovery.
4
-
5
- ## Overview
6
-
7
- The parameter schema system allows skills to declare their configurable parameters with metadata including types, descriptions, default values, and security hints. This enables:
8
-
9
- - **GUI Configuration Tools** - Automatically generate configuration forms
10
- - **API Documentation** - Document all available parameters
11
- - **Validation** - Type checking and constraint validation
12
- - **Security** - Mark sensitive parameters as hidden
13
- - **Environment Variables** - Indicate which parameters can be sourced from environment
14
-
15
- ## Using the Schema System
16
-
17
- ### Getting All Skills Schema
18
-
19
- Use the `list_skills_with_params()` function to get a complete schema of all available skills:
20
-
21
- ```python
22
- from signalwire_agents import list_skills_with_params
23
-
24
- # Get complete schema for all skills
25
- schema = list_skills_with_params()
26
-
27
- # Example output structure:
28
- {
29
- "web_search": {
30
- "name": "web_search",
31
- "description": "Search the web for information using Google Custom Search API",
32
- "version": "1.0.0",
33
- "supports_multiple_instances": True,
34
- "required_packages": ["bs4", "requests"],
35
- "required_env_vars": [],
36
- "parameters": {
37
- "api_key": {
38
- "type": "string",
39
- "description": "Google Custom Search API key",
40
- "required": True,
41
- "hidden": True,
42
- "env_var": "GOOGLE_SEARCH_API_KEY"
43
- },
44
- "search_engine_id": {
45
- "type": "string",
46
- "description": "Google Custom Search Engine ID",
47
- "required": True,
48
- "hidden": True,
49
- "env_var": "GOOGLE_SEARCH_ENGINE_ID"
50
- },
51
- "num_results": {
52
- "type": "integer",
53
- "description": "Default number of search results to return",
54
- "default": 1,
55
- "required": False,
56
- "min": 1,
57
- "max": 10
58
- },
59
- ...
60
- }
61
- },
62
- "datetime": {
63
- "name": "datetime",
64
- "description": "Get current date, time, and timezone information",
65
- "version": "1.0.0",
66
- "supports_multiple_instances": False,
67
- "required_packages": ["pytz"],
68
- "required_env_vars": [],
69
- "parameters": {
70
- "swaig_fields": {
71
- "type": "object",
72
- "description": "Additional SWAIG function metadata to merge into tool definitions",
73
- "default": {},
74
- "required": False
75
- }
76
- }
77
- },
78
- ...
79
- }
80
- ```
81
-
82
- ### Using Schema for GUI Configuration
83
-
84
- Here's an example of how to use the schema to generate a configuration form:
85
-
86
- ```python
87
- import json
88
- from signalwire_agents import list_skills_with_params, AgentBase
89
-
90
- # Get skills schema
91
- schema = list_skills_with_params()
92
-
93
- # Example: Generate HTML form for web_search skill
94
- web_search_schema = schema['web_search']
95
-
96
- def generate_form_field(param_name, param_info):
97
- """Generate HTML form field based on parameter schema"""
98
- field_html = f'<div class="form-group">\n'
99
- field_html += f' <label for="{param_name}">{param_info["description"]}</label>\n'
100
-
101
- # Mark required fields
102
- required = "required" if param_info.get("required", False) else ""
103
-
104
- # Hide sensitive fields
105
- input_type = "password" if param_info.get("hidden", False) else "text"
106
-
107
- # Handle different types
108
- if param_info["type"] == "string":
109
- default = param_info.get("default", "")
110
- field_html += f' <input type="{input_type}" id="{param_name}" name="{param_name}" '
111
- field_html += f'value="{default}" {required}>\n'
112
-
113
- elif param_info["type"] == "integer":
114
- default = param_info.get("default", 0)
115
- min_val = f'min="{param_info["min"]}"' if "min" in param_info else ""
116
- max_val = f'max="{param_info["max"]}"' if "max" in param_info else ""
117
- field_html += f' <input type="number" id="{param_name}" name="{param_name}" '
118
- field_html += f'value="{default}" {min_val} {max_val} {required}>\n'
119
-
120
- elif param_info["type"] == "boolean":
121
- default = param_info.get("default", False)
122
- checked = "checked" if default else ""
123
- field_html += f' <input type="checkbox" id="{param_name}" name="{param_name}" {checked}>\n'
124
-
125
- # Show environment variable hint
126
- if "env_var" in param_info:
127
- field_html += f' <small>Can also be set via {param_info["env_var"]} environment variable</small>\n'
128
-
129
- field_html += '</div>\n'
130
- return field_html
131
-
132
- # Generate form fields for web_search skill
133
- print("<form>")
134
- for param_name, param_info in web_search_schema["parameters"].items():
135
- print(generate_form_field(param_name, param_info))
136
- print("</form>")
137
- ```
138
-
139
- ### Programmatic Skill Configuration
140
-
141
- Use the schema to validate and configure skills programmatically:
142
-
143
- ```python
144
- from signalwire_agents import AgentBase, list_skills_with_params
145
-
146
- class MyAgent(AgentBase):
147
- def __init__(self):
148
- super().__init__(name="my-agent")
149
-
150
- # Get schema to validate configuration
151
- schema = list_skills_with_params()
152
-
153
- # Configure web_search skill with validation
154
- web_search_params = {
155
- "api_key": "your-api-key",
156
- "search_engine_id": "your-engine-id",
157
- "num_results": 3,
158
- "max_content_length": 3000
159
- }
160
-
161
- # Validate required parameters
162
- web_search_schema = schema["web_search"]["parameters"]
163
- for param, info in web_search_schema.items():
164
- if info.get("required", False) and param not in web_search_params:
165
- raise ValueError(f"Missing required parameter: {param}")
166
-
167
- # Add skill with validated parameters
168
- self.add_skill("web_search", web_search_params)
169
- ```
170
-
171
- ## Parameter Schema Reference
172
-
173
- Each parameter in the schema can have the following properties:
174
-
175
- | Property | Type | Description |
176
- |----------|------|-------------|
177
- | `type` | string | Parameter type: "string", "integer", "number", "boolean", "object", "array" |
178
- | `description` | string | Human-readable description of the parameter |
179
- | `default` | any | Default value if not provided |
180
- | `required` | boolean | Whether the parameter is required (default: false) |
181
- | `hidden` | boolean | Whether to hide this field in UIs (for secrets/API keys) |
182
- | `env_var` | string | Environment variable that can provide this value |
183
- | `enum` | array | List of allowed values (for string types) |
184
- | `min` | number | Minimum value (for numeric types) |
185
- | `max` | number | Maximum value (for numeric types) |
186
-
187
- ## Implementing Parameter Schema in Skills
188
-
189
- To add parameter schema support to a skill, override the `get_parameter_schema()` class method:
190
-
191
- ```python
192
- from signalwire_agents.core.skill_base import SkillBase
193
- from typing import Dict, Any
194
-
195
- class MyCustomSkill(SkillBase):
196
- SKILL_NAME = "my_custom_skill"
197
- SKILL_DESCRIPTION = "My custom skill"
198
- SKILL_VERSION = "1.0.0"
199
- REQUIRED_PACKAGES = []
200
- REQUIRED_ENV_VARS = []
201
-
202
- @classmethod
203
- def get_parameter_schema(cls) -> Dict[str, Dict[str, Any]]:
204
- """Get parameter schema for this skill"""
205
- # Get base schema from parent (includes common parameters)
206
- schema = super().get_parameter_schema()
207
-
208
- # Add skill-specific parameters
209
- schema.update({
210
- "api_endpoint": {
211
- "type": "string",
212
- "description": "API endpoint URL",
213
- "required": True,
214
- "default": "https://api.example.com"
215
- },
216
- "api_key": {
217
- "type": "string",
218
- "description": "API authentication key",
219
- "required": True,
220
- "hidden": True, # Mark as sensitive
221
- "env_var": "MY_API_KEY" # Can be set via environment
222
- },
223
- "timeout": {
224
- "type": "integer",
225
- "description": "Request timeout in seconds",
226
- "default": 30,
227
- "required": False,
228
- "min": 1,
229
- "max": 300
230
- },
231
- "retry_count": {
232
- "type": "integer",
233
- "description": "Number of retries on failure",
234
- "default": 3,
235
- "required": False,
236
- "min": 0,
237
- "max": 10
238
- },
239
- "output_format": {
240
- "type": "string",
241
- "description": "Output format for results",
242
- "default": "json",
243
- "required": False,
244
- "enum": ["json", "xml", "text"] # Allowed values
245
- },
246
- "enable_cache": {
247
- "type": "boolean",
248
- "description": "Enable response caching",
249
- "default": True,
250
- "required": False
251
- }
252
- })
253
-
254
- return schema
255
-
256
- def setup(self) -> bool:
257
- """Setup the skill using parameters"""
258
- # Access parameters via self.params
259
- self.api_endpoint = self.params.get('api_endpoint')
260
- self.api_key = self.params.get('api_key')
261
- self.timeout = self.params.get('timeout', 30)
262
- # ... etc
263
- return True
264
- ```
265
-
266
- ## Common Parameter Patterns
267
-
268
- ### API Keys and Secrets
269
-
270
- Always mark sensitive parameters as `hidden` and provide an `env_var` option:
271
-
272
- ```python
273
- "api_key": {
274
- "type": "string",
275
- "description": "API key for authentication",
276
- "required": True,
277
- "hidden": True,
278
- "env_var": "SERVICE_API_KEY"
279
- }
280
- ```
281
-
282
- ### Numeric Parameters with Constraints
283
-
284
- Use `min` and `max` to enforce valid ranges:
285
-
286
- ```python
287
- "port": {
288
- "type": "integer",
289
- "description": "Server port number",
290
- "default": 8080,
291
- "required": False,
292
- "min": 1,
293
- "max": 65535
294
- }
295
- ```
296
-
297
- ### Enumerated Values
298
-
299
- Use `enum` to restrict to specific values:
300
-
301
- ```python
302
- "log_level": {
303
- "type": "string",
304
- "description": "Logging level",
305
- "default": "info",
306
- "required": False,
307
- "enum": ["debug", "info", "warning", "error"]
308
- }
309
- ```
310
-
311
- ### Optional Features
312
-
313
- Use boolean parameters for optional features:
314
-
315
- ```python
316
- "enable_analytics": {
317
- "type": "boolean",
318
- "description": "Enable analytics tracking",
319
- "default": False,
320
- "required": False
321
- }
322
- ```
323
-
324
- ## Base Parameters
325
-
326
- All skills automatically inherit these base parameters from `SkillBase`:
327
-
328
- - **`swaig_fields`** (object) - Additional SWAIG function metadata to merge into tool definitions
329
- - **`tool_name`** (string) - Custom name for skill instances (only for skills with `SUPPORTS_MULTIPLE_INSTANCES = True`)
330
-
331
- ## Examples
332
-
333
- ### Simple Skill (No Parameters)
334
-
335
- Skills like `datetime` and `math` that don't need configuration:
336
-
337
- ```python
338
- @classmethod
339
- def get_parameter_schema(cls) -> Dict[str, Dict[str, Any]]:
340
- # Just return base schema
341
- return super().get_parameter_schema()
342
- ```
343
-
344
- ### Complex Skill (Many Parameters)
345
-
346
- Skills like `web_search` with multiple configuration options:
347
-
348
- ```python
349
- @classmethod
350
- def get_parameter_schema(cls) -> Dict[str, Dict[str, Any]]:
351
- schema = super().get_parameter_schema()
352
-
353
- schema.update({
354
- # API credentials (hidden)
355
- "api_key": {...},
356
- "api_secret": {...},
357
-
358
- # Configuration options
359
- "timeout": {...},
360
- "retry_count": {...},
361
-
362
- # Feature flags
363
- "enable_cache": {...},
364
- "debug_mode": {...},
365
-
366
- # Customization
367
- "response_template": {...},
368
- "error_messages": {...}
369
- })
370
-
371
- return schema
372
- ```
373
-
374
- ## Best Practices
375
-
376
- 1. **Always provide descriptions** - Make parameters self-documenting
377
- 2. **Set sensible defaults** - Allow skills to work with minimal configuration
378
- 3. **Mark secrets as hidden** - Protect sensitive information in UIs
379
- 4. **Use appropriate types** - Enable proper validation and UI controls
380
- 5. **Document environment variables** - Show alternative configuration methods
381
- 6. **Validate in setup()** - Ensure all required parameters are present
382
- 7. **Support backward compatibility** - Handle deprecated parameters gracefully
383
-
384
- ## Future Enhancements
385
-
386
- The parameter schema system is designed to be extensible. Future enhancements may include:
387
-
388
- - **Conditional parameters** - Show/hide based on other parameter values
389
- - **Complex validation** - Cross-parameter validation rules
390
- - **Nested schemas** - Support for complex object parameters
391
- - **Internationalization** - Localized descriptions and error messages
392
- - **Runtime parameter updates** - Modify configuration without restart