@signalwire/sdk 2.0.0 → 2.0.2

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 (612) 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/dist/index.d.ts +146 -0
  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 +1019 -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/{src/rest/index.ts → dist/rest/index.d.ts} +53 -122
  149. package/dist/rest/index.js +195 -0
  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/dist/rest/pagination.d.ts +39 -0
  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 -2489
  416. package/src/AgentServer.ts +0 -415
  417. package/src/AuthHandler.ts +0 -256
  418. package/src/ConfigLoader.ts +0 -447
  419. package/src/ContextBuilder.ts +0 -1150
  420. package/src/DataMap.ts +0 -449
  421. package/src/FunctionResult.ts +0 -866
  422. package/src/Logger.ts +0 -337
  423. package/src/PomBuilder.ts +0 -439
  424. package/src/PromptManager.ts +0 -133
  425. package/src/SWMLHandler.ts +0 -298
  426. package/src/SWMLService.ts +0 -717
  427. package/src/SchemaUtils.ts +0 -361
  428. package/src/ServerlessAdapter.ts +0 -221
  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 -258
  433. package/src/SwmlVerbMethods.generated.ts +0 -234
  434. package/src/TypeInference.ts +0 -181
  435. package/src/WebService.ts +0 -619
  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/index.ts +0 -167
  441. package/src/livewire/index.ts +0 -950
  442. package/src/prefabs/ConciergeAgent.ts +0 -287
  443. package/src/prefabs/FAQBotAgent.ts +0 -384
  444. package/src/prefabs/InfoGathererAgent.ts +0 -339
  445. package/src/prefabs/ReceptionistAgent.ts +0 -366
  446. package/src/prefabs/SurveyAgent.ts +0 -646
  447. package/src/relay/Action.ts +0 -314
  448. package/src/relay/Call.ts +0 -854
  449. package/src/relay/Deferred.ts +0 -71
  450. package/src/relay/Message.ts +0 -148
  451. package/src/relay/RelayClient.ts +0 -1036
  452. package/src/relay/RelayError.ts +0 -14
  453. package/src/relay/RelayEvent.ts +0 -892
  454. package/src/relay/index.ts +0 -123
  455. package/src/relay/types.ts +0 -149
  456. package/src/rest/HttpClient.ts +0 -103
  457. package/src/rest/RestError.ts +0 -31
  458. package/src/rest/base/BaseResource.ts +0 -19
  459. package/src/rest/base/CrudResource.ts +0 -51
  460. package/src/rest/base/CrudWithAddresses.ts +0 -26
  461. package/src/rest/namespaces/addresses.ts +0 -32
  462. package/src/rest/namespaces/calling.ts +0 -187
  463. package/src/rest/namespaces/chat.ts +0 -20
  464. package/src/rest/namespaces/compat.ts +0 -352
  465. package/src/rest/namespaces/datasphere.ts +0 -45
  466. package/src/rest/namespaces/fabric.ts +0 -222
  467. package/src/rest/namespaces/imported-numbers.ts +0 -20
  468. package/src/rest/namespaces/logs.ts +0 -84
  469. package/src/rest/namespaces/lookup.ts +0 -21
  470. package/src/rest/namespaces/mfa.ts +0 -30
  471. package/src/rest/namespaces/number-groups.ts +0 -38
  472. package/src/rest/namespaces/phone-numbers.ts +0 -44
  473. package/src/rest/namespaces/project.ts +0 -36
  474. package/src/rest/namespaces/pubsub.ts +0 -20
  475. package/src/rest/namespaces/queues.ts +0 -33
  476. package/src/rest/namespaces/recordings.ts +0 -28
  477. package/src/rest/namespaces/registry.ts +0 -101
  478. package/src/rest/namespaces/short-codes.ts +0 -28
  479. package/src/rest/namespaces/sip-profile.ts +0 -25
  480. package/src/rest/namespaces/verified-callers.ts +0 -27
  481. package/src/rest/namespaces/video.ts +0 -165
  482. package/src/rest/pagination.ts +0 -84
  483. package/src/rest/types.ts +0 -61
  484. package/src/skills/SkillBase.ts +0 -547
  485. package/src/skills/SkillManager.ts +0 -415
  486. package/src/skills/SkillRegistry.ts +0 -367
  487. package/src/skills/builtin/api_ninjas_trivia.ts +0 -280
  488. package/src/skills/builtin/ask_claude.ts +0 -241
  489. package/src/skills/builtin/claude_skills.ts +0 -978
  490. package/src/skills/builtin/custom_skills.ts +0 -312
  491. package/src/skills/builtin/datasphere.ts +0 -438
  492. package/src/skills/builtin/datasphere_serverless.ts +0 -339
  493. package/src/skills/builtin/datetime.ts +0 -130
  494. package/src/skills/builtin/google_maps.ts +0 -651
  495. package/src/skills/builtin/info_gatherer.ts +0 -405
  496. package/src/skills/builtin/joke.ts +0 -191
  497. package/src/skills/builtin/math.ts +0 -142
  498. package/src/skills/builtin/mcp_gateway.ts +0 -677
  499. package/src/skills/builtin/native_vector_search.ts +0 -901
  500. package/src/skills/builtin/play_background_file.ts +0 -358
  501. package/src/skills/builtin/spider.ts +0 -869
  502. package/src/skills/builtin/swml_transfer.ts +0 -635
  503. package/src/skills/builtin/weather_api.ts +0 -248
  504. package/src/skills/builtin/web_search.ts +0 -1074
  505. package/src/skills/builtin/wikipedia_search.ts +0 -299
  506. package/src/types.ts +0 -132
  507. package/tests/AgentBase.test.ts +0 -1093
  508. package/tests/AgentServer.test.ts +0 -126
  509. package/tests/AuthHandler.test.ts +0 -133
  510. package/tests/ConfigLoader.test.ts +0 -151
  511. package/tests/ContextBuilder.test.ts +0 -108
  512. package/tests/DataMap.test.ts +0 -367
  513. package/tests/EphemeralSkillCopy.test.ts +0 -107
  514. package/tests/FunctionResult.test.ts +0 -298
  515. package/tests/GracefulShutdown.test.ts +0 -46
  516. package/tests/Logger.test.ts +0 -420
  517. package/tests/PomBuilder.test.ts +0 -228
  518. package/tests/ProxyDetection.test.ts +0 -228
  519. package/tests/SWMLService.test.ts +0 -320
  520. package/tests/SWMLVerbHandler.test.ts +0 -523
  521. package/tests/SchemaUtils.test.ts +0 -106
  522. package/tests/SchemaUtils.verb.test.ts +0 -206
  523. package/tests/SecurityUtils.test.ts +0 -192
  524. package/tests/ServerlessAdapter.test.ts +0 -222
  525. package/tests/SessionManager.test.ts +0 -257
  526. package/tests/SkillBaseFeatures.test.ts +0 -130
  527. package/tests/SkillMultiInstance.test.ts +0 -102
  528. package/tests/SkillParameterSchemas.test.ts +0 -134
  529. package/tests/SkillRegistrySchema.test.ts +0 -84
  530. package/tests/SslConfig.test.ts +0 -97
  531. package/tests/SwmlBuilder.test.ts +0 -400
  532. package/tests/TypeInference.test.ts +0 -165
  533. package/tests/VerbHandlerRegistry.test.ts +0 -128
  534. package/tests/cli/mock-data.test.ts +0 -113
  535. package/tests/cli/swaig-test.test.ts +0 -108
  536. package/tests/examples.test.ts +0 -194
  537. package/tests/fixtures/scrape-parity/README.md +0 -53
  538. package/tests/fixtures/scrape-parity/expected/01_simple_article.json +0 -5
  539. package/tests/fixtures/scrape-parity/expected/02_class_based_noise.json +0 -5
  540. package/tests/fixtures/scrape-parity/expected/03_nested_containers.json +0 -5
  541. package/tests/fixtures/scrape-parity/expected/04_bare_body.json +0 -5
  542. package/tests/fixtures/scrape-parity/expected/05_malformed.json +0 -5
  543. package/tests/fixtures/scrape-parity/expected/06_multi_class.json +0 -5
  544. package/tests/fixtures/scrape-parity/expected/07_anchor_pattern.json +0 -5
  545. package/tests/fixtures/scrape-parity/expected/08_inline_script.json +0 -5
  546. package/tests/fixtures/scrape-parity/expected/09_whitespace_nbsp.json +0 -5
  547. package/tests/fixtures/scrape-parity/expected/10_entity_unicode.json +0 -5
  548. package/tests/fixtures/scrape-parity/expected/11_cdata_comments.json +0 -5
  549. package/tests/fixtures/scrape-parity/expected/12_deep_nested_removals.json +0 -5
  550. package/tests/fixtures/scrape-parity/html/01_simple_article.html +0 -18
  551. package/tests/fixtures/scrape-parity/html/02_class_based_noise.html +0 -18
  552. package/tests/fixtures/scrape-parity/html/03_nested_containers.html +0 -13
  553. package/tests/fixtures/scrape-parity/html/04_bare_body.html +0 -9
  554. package/tests/fixtures/scrape-parity/html/05_malformed.html +0 -11
  555. package/tests/fixtures/scrape-parity/html/06_multi_class.html +0 -18
  556. package/tests/fixtures/scrape-parity/html/07_anchor_pattern.html +0 -12
  557. package/tests/fixtures/scrape-parity/html/08_inline_script.html +0 -17
  558. package/tests/fixtures/scrape-parity/html/09_whitespace_nbsp.html +0 -21
  559. package/tests/fixtures/scrape-parity/html/10_entity_unicode.html +0 -10
  560. package/tests/fixtures/scrape-parity/html/11_cdata_comments.html +0 -13
  561. package/tests/fixtures/scrape-parity/html/12_deep_nested_removals.html +0 -24
  562. package/tests/fixtures/scrape-parity/python_extract.py +0 -109
  563. package/tests/livewire/livewire.test.ts +0 -780
  564. package/tests/mcp.test.ts +0 -221
  565. package/tests/prefabs/prefabs.test.ts +0 -1093
  566. package/tests/relay/Action.test.ts +0 -392
  567. package/tests/relay/Call.test.ts +0 -535
  568. package/tests/relay/Deferred.test.ts +0 -71
  569. package/tests/relay/Message.test.ts +0 -164
  570. package/tests/relay/RelayClient.test.ts +0 -779
  571. package/tests/relay/RelayEvent.test.ts +0 -463
  572. package/tests/relay/helpers.ts +0 -79
  573. package/tests/rest/HttpClient.test.ts +0 -274
  574. package/tests/rest/RestError.test.ts +0 -53
  575. package/tests/rest/calling.test.ts +0 -156
  576. package/tests/rest/client.test.ts +0 -197
  577. package/tests/rest/compat.test.ts +0 -335
  578. package/tests/rest/datasphere.test.ts +0 -71
  579. package/tests/rest/fabric.test.ts +0 -186
  580. package/tests/rest/helpers.ts +0 -95
  581. package/tests/rest/logs.test.ts +0 -68
  582. package/tests/rest/pagination.test.ts +0 -133
  583. package/tests/rest/registry.test.ts +0 -94
  584. package/tests/rest/relay-rest.test.ts +0 -290
  585. package/tests/rest/video.test.ts +0 -173
  586. package/tests/setup.ts +0 -6
  587. package/tests/skills/SkillBase.test.ts +0 -108
  588. package/tests/skills/SkillManager.test.ts +0 -268
  589. package/tests/skills/SkillRegistry.test.ts +0 -176
  590. package/tests/skills/builtin.test.ts +0 -1472
  591. package/tests/skills/claude-skills.test.ts +0 -54
  592. package/tests/skills/custom-skills.test.ts +0 -53
  593. package/tests/skills/datasphere-serverless.test.ts +0 -70
  594. package/tests/skills/datasphere.test.ts +0 -107
  595. package/tests/skills/datetime.test.ts +0 -101
  596. package/tests/skills/google-maps.test.ts +0 -78
  597. package/tests/skills/info-gatherer.test.ts +0 -411
  598. package/tests/skills/joke.test.ts +0 -81
  599. package/tests/skills/math.test.ts +0 -68
  600. package/tests/skills/mcp-gateway.test.ts +0 -101
  601. package/tests/skills/play-background.test.ts +0 -54
  602. package/tests/skills/spider.test.ts +0 -108
  603. package/tests/skills/swml-transfer.test.ts +0 -178
  604. package/tests/skills/trivia.test.ts +0 -54
  605. package/tests/skills/vector-search.test.ts +0 -135
  606. package/tests/skills/weather-api.test.ts +0 -77
  607. package/tests/skills/web-search-parity.test.ts +0 -59
  608. package/tests/skills/web-search.test.ts +0 -103
  609. package/tests/skills/wikipedia.test.ts +0 -63
  610. package/tsconfig.json +0 -18
  611. package/vitest.config.ts +0 -9
  612. /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