@signalwire/sdk 2.0.5 → 3.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (659) hide show
  1. package/CHANGELOG.md +821 -0
  2. package/LICENSE +21 -0
  3. package/README.md +163 -68
  4. package/dist/AGENTS.md +13 -0
  5. package/dist/AgentBase.d.ts +510 -126
  6. package/dist/AgentBase.js +1581 -455
  7. package/dist/AgentBase.js.map +1 -1
  8. package/dist/AgentServer.d.ts +21 -0
  9. package/dist/AgentServer.js +154 -47
  10. package/dist/AgentServer.js.map +1 -1
  11. package/dist/AuthHandler.d.ts +14 -2
  12. package/dist/AuthHandler.js +7 -2
  13. package/dist/AuthHandler.js.map +1 -1
  14. package/dist/ConfigLoader.d.ts +5 -13
  15. package/dist/ConfigLoader.js +15 -29
  16. package/dist/ConfigLoader.js.map +1 -1
  17. package/dist/ContextBuilder.d.ts +202 -9
  18. package/dist/ContextBuilder.js +219 -36
  19. package/dist/ContextBuilder.js.map +1 -1
  20. package/dist/DataMap.d.ts +186 -45
  21. package/dist/DataMap.js +210 -52
  22. package/dist/DataMap.js.map +1 -1
  23. package/dist/FunctionResult.d.ts +309 -83
  24. package/dist/FunctionResult.js +483 -116
  25. package/dist/FunctionResult.js.map +1 -1
  26. package/dist/Logger.d.ts +30 -5
  27. package/dist/Logger.js +77 -19
  28. package/dist/Logger.js.map +1 -1
  29. package/dist/POM/PromptObjectModel.d.ts +12 -1
  30. package/dist/POM/PromptObjectModel.js +25 -9
  31. package/dist/POM/PromptObjectModel.js.map +1 -1
  32. package/dist/ParameterSchema.d.ts +306 -0
  33. package/dist/ParameterSchema.js +251 -0
  34. package/dist/ParameterSchema.js.map +1 -0
  35. package/dist/PlatformContracts.d.ts +21 -0
  36. package/dist/PlatformContracts.generated.d.ts +109 -0
  37. package/dist/PlatformContracts.generated.js +8 -0
  38. package/dist/PlatformContracts.generated.js.map +1 -0
  39. package/dist/PlatformContracts.js +2 -0
  40. package/dist/PlatformContracts.js.map +1 -0
  41. package/dist/PomBuilder.d.ts +18 -0
  42. package/dist/PomBuilder.js +53 -3
  43. package/dist/PomBuilder.js.map +1 -1
  44. package/dist/PostPrompt.d.ts +110 -0
  45. package/dist/PostPrompt.js +204 -0
  46. package/dist/PostPrompt.js.map +1 -0
  47. package/dist/PromptManager.d.ts +22 -1
  48. package/dist/PromptManager.js +28 -1
  49. package/dist/PromptManager.js.map +1 -1
  50. package/dist/PublicFetch.d.ts +132 -0
  51. package/dist/PublicFetch.js +311 -0
  52. package/dist/PublicFetch.js.map +1 -0
  53. package/dist/RobotsTxt.d.ts +41 -0
  54. package/dist/RobotsTxt.js +152 -0
  55. package/dist/RobotsTxt.js.map +1 -0
  56. package/dist/SWMLHandler.js.map +1 -1
  57. package/dist/SWMLService.d.ts +169 -59
  58. package/dist/SWMLService.js +456 -129
  59. package/dist/SWMLService.js.map +1 -1
  60. package/dist/SchemaUtils.d.ts +115 -2
  61. package/dist/SchemaUtils.js +444 -12
  62. package/dist/SchemaUtils.js.map +1 -1
  63. package/dist/SecurityUtils.d.ts +49 -9
  64. package/dist/SecurityUtils.js +153 -51
  65. package/dist/SecurityUtils.js.map +1 -1
  66. package/dist/SemanticGate.d.ts +183 -0
  67. package/dist/SemanticGate.js +533 -0
  68. package/dist/SemanticGate.js.map +1 -0
  69. package/dist/ServerlessAdapter.d.ts +156 -7
  70. package/dist/ServerlessAdapter.js +399 -42
  71. package/dist/ServerlessAdapter.js.map +1 -1
  72. package/dist/SessionManager.d.ts +11 -2
  73. package/dist/SessionManager.js +50 -18
  74. package/dist/SessionManager.js.map +1 -1
  75. package/dist/SslConfig.d.ts +2 -1
  76. package/dist/SslConfig.js +4 -1
  77. package/dist/SslConfig.js.map +1 -1
  78. package/dist/SwaigActions.generated.d.ts +23 -0
  79. package/dist/SwaigActions.generated.js +8 -0
  80. package/dist/SwaigActions.generated.js.map +1 -0
  81. package/dist/SwaigContracts.d.ts +15 -0
  82. package/dist/SwaigContracts.generated.d.ts +264 -0
  83. package/dist/SwaigContracts.generated.js +12 -0
  84. package/dist/SwaigContracts.generated.js.map +1 -0
  85. package/dist/SwaigContracts.js +2 -0
  86. package/dist/SwaigContracts.js.map +1 -0
  87. package/dist/SwaigFunction.d.ts +139 -7
  88. package/dist/SwaigFunction.js +170 -22
  89. package/dist/SwaigFunction.js.map +1 -1
  90. package/dist/SwmlBuilder.d.ts +68 -19
  91. package/dist/SwmlBuilder.js +74 -38
  92. package/dist/SwmlBuilder.js.map +1 -1
  93. package/dist/SwmlVerbMethods.generated.d.ts +41 -4
  94. package/dist/SwmlVerbMethods.generated.js +1 -1
  95. package/dist/TypeInference.d.ts +39 -3
  96. package/dist/TypeInference.js +256 -16
  97. package/dist/TypeInference.js.map +1 -1
  98. package/dist/WebService.d.ts +79 -11
  99. package/dist/WebService.js +320 -109
  100. package/dist/WebService.js.map +1 -1
  101. package/dist/WebhookMiddleware.d.ts +119 -0
  102. package/dist/WebhookMiddleware.js +271 -0
  103. package/dist/WebhookMiddleware.js.map +1 -0
  104. package/dist/WebhookValidator.d.ts +92 -0
  105. package/dist/WebhookValidator.js +409 -0
  106. package/dist/WebhookValidator.js.map +1 -0
  107. package/dist/agents/BedrockAgent.d.ts +162 -0
  108. package/dist/agents/BedrockAgent.js +323 -0
  109. package/dist/agents/BedrockAgent.js.map +1 -0
  110. package/dist/ai-chat/AIChatClient.d.ts +316 -0
  111. package/dist/ai-chat/AIChatClient.js +535 -0
  112. package/dist/ai-chat/AIChatClient.js.map +1 -0
  113. package/dist/ai-chat/ChatGateway.d.ts +408 -0
  114. package/dist/ai-chat/ChatGateway.js +747 -0
  115. package/dist/ai-chat/ChatGateway.js.map +1 -0
  116. package/dist/ai-chat/HandoffRouter.d.ts +282 -0
  117. package/dist/ai-chat/HandoffRouter.js +518 -0
  118. package/dist/ai-chat/HandoffRouter.js.map +1 -0
  119. package/dist/ai-chat/index.d.ts +12 -0
  120. package/dist/ai-chat/index.js +10 -0
  121. package/dist/ai-chat/index.js.map +1 -0
  122. package/dist/capabilities.d.ts +64 -0
  123. package/dist/capabilities.js +95 -0
  124. package/dist/capabilities.js.map +1 -0
  125. package/dist/cli/agent-loader.d.ts +32 -6
  126. package/dist/cli/agent-loader.js +92 -33
  127. package/dist/cli/agent-loader.js.map +1 -1
  128. package/dist/cli/datamap-exec.d.ts +175 -0
  129. package/dist/cli/datamap-exec.js +1284 -0
  130. package/dist/cli/datamap-exec.js.map +1 -0
  131. package/dist/cli/function-args.d.ts +40 -0
  132. package/dist/cli/function-args.js +146 -0
  133. package/dist/cli/function-args.js.map +1 -0
  134. package/dist/cli/simulation.d.ts +99 -0
  135. package/dist/cli/simulation.js +490 -0
  136. package/dist/cli/simulation.js.map +1 -0
  137. package/dist/cli/swaig-test.d.ts +12 -25
  138. package/dist/cli/swaig-test.js +935 -371
  139. package/dist/cli/swaig-test.js.map +1 -1
  140. package/dist/cli/tsdocs/agentsNote.d.ts +30 -0
  141. package/dist/cli/tsdocs/agentsNote.js +92 -0
  142. package/dist/cli/tsdocs/agentsNote.js.map +1 -0
  143. package/dist/cli/tsdocs/api-index.json +1 -0
  144. package/dist/cli/tsdocs/api.d.ts +91 -0
  145. package/dist/cli/tsdocs/api.js +372 -0
  146. package/dist/cli/tsdocs/api.js.map +1 -0
  147. package/dist/cli/tsdocs/apiTypes.d.ts +64 -0
  148. package/dist/cli/tsdocs/apiTypes.js +7 -0
  149. package/dist/cli/tsdocs/apiTypes.js.map +1 -0
  150. package/dist/cli/tsdocs/bin.d.ts +6 -0
  151. package/dist/cli/tsdocs/bin.js +23 -0
  152. package/dist/cli/tsdocs/bin.js.map +1 -0
  153. package/dist/cli/tsdocs/files.d.ts +108 -0
  154. package/dist/cli/tsdocs/files.js +287 -0
  155. package/dist/cli/tsdocs/files.js.map +1 -0
  156. package/dist/cli/tsdocs/index.d.ts +28 -0
  157. package/dist/cli/tsdocs/index.js +307 -0
  158. package/dist/cli/tsdocs/index.js.map +1 -0
  159. package/dist/cli/tsdocs/live.d.ts +41 -0
  160. package/dist/cli/tsdocs/live.js +202 -0
  161. package/dist/cli/tsdocs/live.js.map +1 -0
  162. package/dist/cli/tsdocs/locate.d.ts +51 -0
  163. package/dist/cli/tsdocs/locate.js +75 -0
  164. package/dist/cli/tsdocs/locate.js.map +1 -0
  165. package/dist/cli/tsdocs/render.d.ts +75 -0
  166. package/dist/cli/tsdocs/render.js +323 -0
  167. package/dist/cli/tsdocs/render.js.map +1 -0
  168. package/dist/cli/tsdocs/topics.d.ts +43 -0
  169. package/dist/cli/tsdocs/topics.js +920 -0
  170. package/dist/cli/tsdocs/topics.js.map +1 -0
  171. package/dist/index.d.ts +49 -68
  172. package/dist/index.js +45 -73
  173. package/dist/index.js.map +1 -1
  174. package/dist/livewire/index.d.ts +229 -155
  175. package/dist/livewire/index.js +298 -195
  176. package/dist/livewire/index.js.map +1 -1
  177. package/dist/llms.txt +65 -0
  178. package/dist/prefabs/CallSessionStore.d.ts +52 -0
  179. package/dist/prefabs/CallSessionStore.js +72 -0
  180. package/dist/prefabs/CallSessionStore.js.map +1 -0
  181. package/dist/prefabs/ConciergeAgent.d.ts +13 -1
  182. package/dist/prefabs/ConciergeAgent.js +36 -31
  183. package/dist/prefabs/ConciergeAgent.js.map +1 -1
  184. package/dist/prefabs/FAQBotAgent.d.ts +9 -1
  185. package/dist/prefabs/FAQBotAgent.js +113 -47
  186. package/dist/prefabs/FAQBotAgent.js.map +1 -1
  187. package/dist/prefabs/InfoGathererAgent.d.ts +22 -3
  188. package/dist/prefabs/InfoGathererAgent.js +67 -58
  189. package/dist/prefabs/InfoGathererAgent.js.map +1 -1
  190. package/dist/prefabs/ReceptionistAgent.d.ts +16 -5
  191. package/dist/prefabs/ReceptionistAgent.js +39 -31
  192. package/dist/prefabs/ReceptionistAgent.js.map +1 -1
  193. package/dist/prefabs/SurveyAgent.d.ts +22 -4
  194. package/dist/prefabs/SurveyAgent.js +84 -68
  195. package/dist/prefabs/SurveyAgent.js.map +1 -1
  196. package/dist/relay/Action.d.ts +44 -21
  197. package/dist/relay/Action.js +75 -17
  198. package/dist/relay/Action.js.map +1 -1
  199. package/dist/relay/Call.d.ts +312 -47
  200. package/dist/relay/Call.js +369 -18
  201. package/dist/relay/Call.js.map +1 -1
  202. package/dist/relay/Deferred.js.map +1 -1
  203. package/dist/relay/Message.d.ts +26 -5
  204. package/dist/relay/Message.js +36 -6
  205. package/dist/relay/Message.js.map +1 -1
  206. package/dist/relay/RelayClient.d.ts +44 -17
  207. package/dist/relay/RelayClient.js +175 -65
  208. package/dist/relay/RelayClient.js.map +1 -1
  209. package/dist/relay/RelayError.d.ts +14 -0
  210. package/dist/relay/RelayError.js +15 -0
  211. package/dist/relay/RelayError.js.map +1 -1
  212. package/dist/relay/RelayEvent.d.ts +96 -65
  213. package/dist/relay/RelayEvent.js +85 -56
  214. package/dist/relay/RelayEvent.js.map +1 -1
  215. package/dist/relay/closedSets.d.ts +111 -0
  216. package/dist/relay/closedSets.js +83 -0
  217. package/dist/relay/closedSets.js.map +1 -0
  218. package/dist/relay/index.d.ts +3 -1
  219. package/dist/relay/index.js +1 -0
  220. package/dist/relay/index.js.map +1 -1
  221. package/dist/relay/normalize.js.map +1 -1
  222. package/dist/relay/protocol.types.generated.d.ts +1195 -0
  223. package/dist/relay/protocol.types.generated.js +8 -0
  224. package/dist/relay/protocol.types.generated.js.map +1 -0
  225. package/dist/relay/types.d.ts +73 -42
  226. package/dist/rest/HttpClient.d.ts +36 -8
  227. package/dist/rest/HttpClient.js +233 -40
  228. package/dist/rest/HttpClient.js.map +1 -1
  229. package/dist/rest/RequestOptions.d.ts +110 -0
  230. package/dist/rest/RequestOptions.js +113 -0
  231. package/dist/rest/RequestOptions.js.map +1 -0
  232. package/dist/rest/RestError.d.ts +52 -6
  233. package/dist/rest/RestError.js +89 -5
  234. package/dist/rest/RestError.js.map +1 -1
  235. package/dist/rest/base/CrudResource.d.ts +16 -26
  236. package/dist/rest/base/CrudResource.js +19 -33
  237. package/dist/rest/base/CrudResource.js.map +1 -1
  238. package/dist/rest/base/CrudWithAddresses.d.ts +3 -2
  239. package/dist/rest/base/CrudWithAddresses.js +2 -2
  240. package/dist/rest/base/CrudWithAddresses.js.map +1 -1
  241. package/dist/rest/base/FabricResource.d.ts +15 -0
  242. package/dist/rest/base/FabricResource.js +16 -0
  243. package/dist/rest/base/FabricResource.js.map +1 -0
  244. package/dist/rest/base/ReadResource.d.ts +62 -0
  245. package/dist/rest/base/ReadResource.js +69 -0
  246. package/dist/rest/base/ReadResource.js.map +1 -0
  247. package/dist/rest/callHandler.d.ts +5 -2
  248. package/dist/rest/callHandler.js +4 -1
  249. package/dist/rest/callHandler.js.map +1 -1
  250. package/dist/rest/index.d.ts +18 -77
  251. package/dist/rest/index.js +47 -120
  252. package/dist/rest/index.js.map +1 -1
  253. package/dist/rest/namespaces/_client_tree_generated.d.ts +103 -0
  254. package/dist/rest/namespaces/_client_tree_generated.js +171 -0
  255. package/dist/rest/namespaces/_client_tree_generated.js.map +1 -0
  256. package/dist/rest/namespaces/addresses.d.ts +3 -42
  257. package/dist/rest/namespaces/addresses.js +3 -50
  258. package/dist/rest/namespaces/addresses.js.map +1 -1
  259. package/dist/rest/namespaces/calling.d.ts +6 -378
  260. package/dist/rest/namespaces/calling.js +6 -473
  261. package/dist/rest/namespaces/calling.js.map +1 -1
  262. package/dist/rest/namespaces/calling.resources.generated.d.ts +165 -0
  263. package/dist/rest/namespaces/calling.resources.generated.js +477 -0
  264. package/dist/rest/namespaces/calling.resources.generated.js.map +1 -0
  265. package/dist/rest/namespaces/calling.types.generated.d.ts +2917 -0
  266. package/dist/rest/namespaces/calling.types.generated.js +8 -0
  267. package/dist/rest/namespaces/calling.types.generated.js.map +1 -0
  268. package/dist/rest/namespaces/chat.d.ts +4 -18
  269. package/dist/rest/namespaces/chat.js +4 -21
  270. package/dist/rest/namespaces/chat.js.map +1 -1
  271. package/dist/rest/namespaces/chat.resources.generated.d.ts +12 -0
  272. package/dist/rest/namespaces/chat.resources.generated.js +29 -0
  273. package/dist/rest/namespaces/chat.resources.generated.js.map +1 -0
  274. package/dist/rest/namespaces/chat.types.generated.d.ts +56 -0
  275. package/dist/rest/namespaces/chat.types.generated.js +8 -0
  276. package/dist/rest/namespaces/chat.types.generated.js.map +1 -0
  277. package/dist/rest/namespaces/datasphere.d.ts +6 -62
  278. package/dist/rest/namespaces/datasphere.js +6 -72
  279. package/dist/rest/namespaces/datasphere.js.map +1 -1
  280. package/dist/rest/namespaces/datasphere.resources.generated.d.ts +25 -0
  281. package/dist/rest/namespaces/datasphere.resources.generated.js +50 -0
  282. package/dist/rest/namespaces/datasphere.resources.generated.js.map +1 -0
  283. package/dist/rest/namespaces/datasphere.types.generated.d.ts +180 -0
  284. package/dist/rest/namespaces/datasphere.types.generated.js +8 -0
  285. package/dist/rest/namespaces/datasphere.types.generated.js.map +1 -0
  286. package/dist/rest/namespaces/fabric.d.ts +11 -327
  287. package/dist/rest/namespaces/fabric.js +14 -439
  288. package/dist/rest/namespaces/fabric.js.map +1 -1
  289. package/dist/rest/namespaces/fabric.resources.generated.d.ts +195 -0
  290. package/dist/rest/namespaces/fabric.resources.generated.js +399 -0
  291. package/dist/rest/namespaces/fabric.resources.generated.js.map +1 -0
  292. package/dist/rest/namespaces/fabric.types.generated.d.ts +4557 -0
  293. package/dist/rest/namespaces/fabric.types.generated.js +8 -0
  294. package/dist/rest/namespaces/fabric.types.generated.js.map +1 -0
  295. package/dist/rest/namespaces/fax.resources.generated.d.ts +6 -0
  296. package/dist/rest/namespaces/fax.resources.generated.js +14 -0
  297. package/dist/rest/namespaces/fax.resources.generated.js.map +1 -0
  298. package/dist/rest/namespaces/fax.types.generated.d.ts +131 -0
  299. package/dist/rest/namespaces/fax.types.generated.js +8 -0
  300. package/dist/rest/namespaces/fax.types.generated.js.map +1 -0
  301. package/dist/rest/namespaces/imported-numbers.d.ts +3 -18
  302. package/dist/rest/namespaces/imported-numbers.js +3 -21
  303. package/dist/rest/namespaces/imported-numbers.js.map +1 -1
  304. package/dist/rest/namespaces/logs.d.ts +10 -101
  305. package/dist/rest/namespaces/logs.js +10 -128
  306. package/dist/rest/namespaces/logs.js.map +1 -1
  307. package/dist/rest/namespaces/logs.resources.generated.d.ts +9 -0
  308. package/dist/rest/namespaces/logs.resources.generated.js +17 -0
  309. package/dist/rest/namespaces/logs.resources.generated.js.map +1 -0
  310. package/dist/rest/namespaces/logs.types.generated.d.ts +131 -0
  311. package/dist/rest/namespaces/logs.types.generated.js +8 -0
  312. package/dist/rest/namespaces/logs.types.generated.js.map +1 -0
  313. package/dist/rest/namespaces/lookup.d.ts +3 -25
  314. package/dist/rest/namespaces/lookup.js +3 -27
  315. package/dist/rest/namespaces/lookup.js.map +1 -1
  316. package/dist/rest/namespaces/message.resources.generated.d.ts +6 -0
  317. package/dist/rest/namespaces/message.resources.generated.js +14 -0
  318. package/dist/rest/namespaces/message.resources.generated.js.map +1 -0
  319. package/dist/rest/namespaces/message.types.generated.d.ts +122 -0
  320. package/dist/rest/namespaces/message.types.generated.js +8 -0
  321. package/dist/rest/namespaces/message.types.generated.js.map +1 -0
  322. package/dist/rest/namespaces/messages.resources.generated.d.ts +18 -0
  323. package/dist/rest/namespaces/messages.resources.generated.js +44 -0
  324. package/dist/rest/namespaces/messages.resources.generated.js.map +1 -0
  325. package/dist/rest/namespaces/messages.types.generated.d.ts +99 -0
  326. package/dist/rest/namespaces/messages.types.generated.js +8 -0
  327. package/dist/rest/namespaces/messages.types.generated.js.map +1 -0
  328. package/dist/rest/namespaces/mfa.d.ts +3 -42
  329. package/dist/rest/namespaces/mfa.js +3 -49
  330. package/dist/rest/namespaces/mfa.js.map +1 -1
  331. package/dist/rest/namespaces/number-groups.d.ts +3 -45
  332. package/dist/rest/namespaces/number-groups.js +3 -53
  333. package/dist/rest/namespaces/number-groups.js.map +1 -1
  334. package/dist/rest/namespaces/phone-numbers.d.ts +8 -196
  335. package/dist/rest/namespaces/phone-numbers.js +8 -230
  336. package/dist/rest/namespaces/phone-numbers.js.map +1 -1
  337. package/dist/rest/namespaces/project.d.ts +6 -42
  338. package/dist/rest/namespaces/project.js +6 -51
  339. package/dist/rest/namespaces/project.js.map +1 -1
  340. package/dist/rest/namespaces/project.resources.generated.d.ts +17 -0
  341. package/dist/rest/namespaces/project.resources.generated.js +44 -0
  342. package/dist/rest/namespaces/project.resources.generated.js.map +1 -0
  343. package/dist/rest/namespaces/project.types.generated.d.ts +58 -0
  344. package/dist/rest/namespaces/project.types.generated.js +8 -0
  345. package/dist/rest/namespaces/project.types.generated.js.map +1 -0
  346. package/dist/rest/namespaces/projects.resources.generated.d.ts +12 -0
  347. package/dist/rest/namespaces/projects.resources.generated.js +25 -0
  348. package/dist/rest/namespaces/projects.resources.generated.js.map +1 -0
  349. package/dist/rest/namespaces/projects.types.generated.d.ts +77 -0
  350. package/dist/rest/namespaces/projects.types.generated.js +8 -0
  351. package/dist/rest/namespaces/projects.types.generated.js.map +1 -0
  352. package/dist/rest/namespaces/pubsub.d.ts +4 -18
  353. package/dist/rest/namespaces/pubsub.js +4 -21
  354. package/dist/rest/namespaces/pubsub.js.map +1 -1
  355. package/dist/rest/namespaces/pubsub.resources.generated.d.ts +12 -0
  356. package/dist/rest/namespaces/pubsub.resources.generated.js +29 -0
  357. package/dist/rest/namespaces/pubsub.resources.generated.js.map +1 -0
  358. package/dist/rest/namespaces/pubsub.types.generated.d.ts +60 -0
  359. package/dist/rest/namespaces/pubsub.types.generated.js +8 -0
  360. package/dist/rest/namespaces/pubsub.types.generated.js.map +1 -0
  361. package/dist/rest/namespaces/queues.d.ts +3 -38
  362. package/dist/rest/namespaces/queues.js +3 -44
  363. package/dist/rest/namespaces/queues.js.map +1 -1
  364. package/dist/rest/namespaces/recordings.d.ts +3 -34
  365. package/dist/rest/namespaces/recordings.js +3 -40
  366. package/dist/rest/namespaces/recordings.js.map +1 -1
  367. package/dist/rest/namespaces/registry.d.ts +6 -137
  368. package/dist/rest/namespaces/registry.js +6 -173
  369. package/dist/rest/namespaces/registry.js.map +1 -1
  370. package/dist/rest/namespaces/relay-rest.resources.generated.d.ts +168 -0
  371. package/dist/rest/namespaces/relay-rest.resources.generated.js +430 -0
  372. package/dist/rest/namespaces/relay-rest.resources.generated.js.map +1 -0
  373. package/dist/rest/namespaces/relay-rest.types.generated.d.ts +1906 -0
  374. package/dist/rest/namespaces/relay-rest.types.generated.js +8 -0
  375. package/dist/rest/namespaces/relay-rest.types.generated.js.map +1 -0
  376. package/dist/rest/namespaces/short-codes.d.ts +3 -35
  377. package/dist/rest/namespaces/short-codes.js +3 -41
  378. package/dist/rest/namespaces/short-codes.js.map +1 -1
  379. package/dist/rest/namespaces/sip-profile.d.ts +3 -24
  380. package/dist/rest/namespaces/sip-profile.js +3 -29
  381. package/dist/rest/namespaces/sip-profile.js.map +1 -1
  382. package/dist/rest/namespaces/verified-callers.d.ts +3 -29
  383. package/dist/rest/namespaces/verified-callers.js +3 -34
  384. package/dist/rest/namespaces/verified-callers.js.map +1 -1
  385. package/dist/rest/namespaces/video.d.ts +10 -227
  386. package/dist/rest/namespaces/video.js +10 -288
  387. package/dist/rest/namespaces/video.js.map +1 -1
  388. package/dist/rest/namespaces/video.resources.generated.d.ts +81 -0
  389. package/dist/rest/namespaces/video.resources.generated.js +171 -0
  390. package/dist/rest/namespaces/video.resources.generated.js.map +1 -0
  391. package/dist/rest/namespaces/video.types.generated.d.ts +771 -0
  392. package/dist/rest/namespaces/video.types.generated.js +8 -0
  393. package/dist/rest/namespaces/video.types.generated.js.map +1 -0
  394. package/dist/rest/namespaces/voice.resources.generated.d.ts +9 -0
  395. package/dist/rest/namespaces/voice.resources.generated.js +17 -0
  396. package/dist/rest/namespaces/voice.resources.generated.js.map +1 -0
  397. package/dist/rest/namespaces/voice.types.generated.d.ts +214 -0
  398. package/dist/rest/namespaces/voice.types.generated.js +8 -0
  399. package/dist/rest/namespaces/voice.types.generated.js.map +1 -0
  400. package/dist/rest/pagination.d.ts +5 -1
  401. package/dist/rest/pagination.js +40 -20
  402. package/dist/rest/pagination.js.map +1 -1
  403. package/dist/rest/types.d.ts +21 -3
  404. package/dist/schema.json +299 -98
  405. package/dist/skills/SkillBase.d.ts +111 -21
  406. package/dist/skills/SkillBase.js +100 -17
  407. package/dist/skills/SkillBase.js.map +1 -1
  408. package/dist/skills/SkillManager.d.ts +66 -13
  409. package/dist/skills/SkillManager.js +101 -20
  410. package/dist/skills/SkillManager.js.map +1 -1
  411. package/dist/skills/SkillName.d.ts +44 -0
  412. package/dist/skills/SkillName.js +2 -0
  413. package/dist/skills/SkillName.js.map +1 -0
  414. package/dist/skills/SkillRegistry.d.ts +22 -11
  415. package/dist/skills/SkillRegistry.js +47 -17
  416. package/dist/skills/SkillRegistry.js.map +1 -1
  417. package/dist/skills/builtin/api_ninjas_trivia.d.ts +3 -1
  418. package/dist/skills/builtin/api_ninjas_trivia.js +18 -6
  419. package/dist/skills/builtin/api_ninjas_trivia.js.map +1 -1
  420. package/dist/skills/builtin/ask_claude.d.ts +14 -4
  421. package/dist/skills/builtin/ask_claude.js +36 -14
  422. package/dist/skills/builtin/ask_claude.js.map +1 -1
  423. package/dist/skills/builtin/claude_skills.d.ts +3 -1
  424. package/dist/skills/builtin/claude_skills.js +19 -15
  425. package/dist/skills/builtin/claude_skills.js.map +1 -1
  426. package/dist/skills/builtin/custom_skills.d.ts +10 -3
  427. package/dist/skills/builtin/custom_skills.js +26 -9
  428. package/dist/skills/builtin/custom_skills.js.map +1 -1
  429. package/dist/skills/builtin/datasphere.d.ts +5 -3
  430. package/dist/skills/builtin/datasphere.js +21 -22
  431. package/dist/skills/builtin/datasphere.js.map +1 -1
  432. package/dist/skills/builtin/datasphere_serverless.d.ts +12 -1
  433. package/dist/skills/builtin/datasphere_serverless.js +17 -6
  434. package/dist/skills/builtin/datasphere_serverless.js.map +1 -1
  435. package/dist/skills/builtin/datetime.d.ts +3 -1
  436. package/dist/skills/builtin/datetime.js +11 -7
  437. package/dist/skills/builtin/datetime.js.map +1 -1
  438. package/dist/skills/builtin/google_maps.d.ts +29 -14
  439. package/dist/skills/builtin/google_maps.js +89 -269
  440. package/dist/skills/builtin/google_maps.js.map +1 -1
  441. package/dist/skills/builtin/index.d.ts +8 -6
  442. package/dist/skills/builtin/index.js +8 -6
  443. package/dist/skills/builtin/index.js.map +1 -1
  444. package/dist/skills/builtin/info_gatherer.d.ts +4 -2
  445. package/dist/skills/builtin/info_gatherer.js +20 -12
  446. package/dist/skills/builtin/info_gatherer.js.map +1 -1
  447. package/dist/skills/builtin/joke.d.ts +16 -6
  448. package/dist/skills/builtin/joke.js +54 -37
  449. package/dist/skills/builtin/joke.js.map +1 -1
  450. package/dist/skills/builtin/math.d.ts +3 -1
  451. package/dist/skills/builtin/math.js +14 -9
  452. package/dist/skills/builtin/math.js.map +1 -1
  453. package/dist/skills/builtin/mcp_gateway.d.ts +34 -5
  454. package/dist/skills/builtin/mcp_gateway.js +77 -46
  455. package/dist/skills/builtin/mcp_gateway.js.map +1 -1
  456. package/dist/skills/builtin/native_vector_search.d.ts +19 -5
  457. package/dist/skills/builtin/native_vector_search.js +179 -61
  458. package/dist/skills/builtin/native_vector_search.js.map +1 -1
  459. package/dist/skills/builtin/play_background_file.d.ts +21 -15
  460. package/dist/skills/builtin/play_background_file.js +43 -122
  461. package/dist/skills/builtin/play_background_file.js.map +1 -1
  462. package/dist/skills/builtin/spider.d.ts +42 -4
  463. package/dist/skills/builtin/spider.js +277 -104
  464. package/dist/skills/builtin/spider.js.map +1 -1
  465. package/dist/skills/builtin/swml_transfer.d.ts +14 -3
  466. package/dist/skills/builtin/swml_transfer.js +45 -24
  467. package/dist/skills/builtin/swml_transfer.js.map +1 -1
  468. package/dist/skills/builtin/weather_api.d.ts +24 -13
  469. package/dist/skills/builtin/weather_api.js +38 -30
  470. package/dist/skills/builtin/weather_api.js.map +1 -1
  471. package/dist/skills/builtin/web_search.d.ts +48 -10
  472. package/dist/skills/builtin/web_search.js +294 -100
  473. package/dist/skills/builtin/web_search.js.map +1 -1
  474. package/dist/skills/builtin/wikipedia_search.d.ts +4 -2
  475. package/dist/skills/builtin/wikipedia_search.js +14 -13
  476. package/dist/skills/builtin/wikipedia_search.js.map +1 -1
  477. package/dist/skills/index.d.ts +3 -2
  478. package/dist/skills/index.js +1 -1
  479. package/dist/skills/index.js.map +1 -1
  480. package/dist/swml_verbs_generated.d.ts +2824 -0
  481. package/dist/swml_verbs_generated.js +12 -0
  482. package/dist/swml_verbs_generated.js.map +1 -0
  483. package/dist/types.d.ts +59 -6
  484. package/dist/web.d.ts +27 -0
  485. package/dist/web.js +20 -0
  486. package/dist/web.js.map +1 -0
  487. package/docs/agent-guide.md +1034 -0
  488. package/docs/ai_chat.md +560 -0
  489. package/docs/api-reference.md +3641 -0
  490. package/docs/architecture.md +846 -0
  491. package/docs/bedrock_agent.md +411 -0
  492. package/docs/cli-guide.md +403 -0
  493. package/docs/cloud_functions_guide.md +399 -0
  494. package/docs/configuration.md +548 -0
  495. package/docs/contexts-guide.md +884 -0
  496. package/docs/datamap-guide.md +1207 -0
  497. package/docs/developer_pain_points.md +548 -0
  498. package/docs/llm_parameters.md +298 -0
  499. package/docs/mcp_gateway_reference.md +354 -0
  500. package/docs/mcp_integration.md +162 -0
  501. package/docs/pgi_agent_guide.md +1820 -0
  502. package/docs/prefabs-guide.md +815 -0
  503. package/docs/programmatically_governed_inference.md +301 -0
  504. package/docs/sdk_features.md +501 -0
  505. package/docs/security.md +559 -0
  506. package/docs/serverless-guide.md +520 -0
  507. package/docs/skills-guide.md +1223 -0
  508. package/docs/skills-system.md +405 -0
  509. package/docs/skills_parameter_schema.md +417 -0
  510. package/docs/swaig-reference.md +1986 -0
  511. package/docs/swml_service_guide.md +573 -0
  512. package/docs/third_party_skills.md +410 -0
  513. package/docs/web_service.md +666 -0
  514. package/examples/README.md +202 -0
  515. package/examples/advanced-datamap.ts +108 -0
  516. package/examples/advanced-dynamic-config.ts +70 -0
  517. package/examples/auto-vivified.ts +95 -0
  518. package/examples/call-flow.ts +65 -0
  519. package/examples/comprehensive-dynamic.ts +125 -0
  520. package/examples/contexts-steps.ts +65 -0
  521. package/examples/custom-path.ts +45 -0
  522. package/examples/datamap-tools.ts +51 -0
  523. package/examples/datasphere-multi-instance.ts +66 -0
  524. package/examples/datasphere-serverless-env.ts +87 -0
  525. package/examples/datasphere-webhook-env.ts +65 -0
  526. package/examples/datasphere.ts +56 -0
  527. package/examples/declarative.ts +100 -0
  528. package/examples/dynamic-config.ts +54 -0
  529. package/examples/dynamic-info-gatherer.ts +69 -0
  530. package/examples/dynamic-swml-service.ts +67 -0
  531. package/examples/gather-info.ts +95 -0
  532. package/examples/gather-per-question-functions-demo.ts +139 -0
  533. package/examples/joke-agent.ts +34 -0
  534. package/examples/kubernetes-agent.ts +45 -0
  535. package/examples/llm-params.ts +75 -0
  536. package/examples/mcp-agent.ts +89 -0
  537. package/examples/mcp-gateway.ts +81 -0
  538. package/examples/multi-agent.ts +80 -0
  539. package/examples/multi-endpoint.ts +79 -0
  540. package/examples/pgi/case-domain.ts +114 -0
  541. package/examples/pgi/serve.ts +16 -0
  542. package/examples/pgi/support-agent.ts +265 -0
  543. package/examples/pom-prompt.ts +70 -0
  544. package/examples/prefab-concierge.ts +42 -0
  545. package/examples/prefab-faq.ts +58 -0
  546. package/examples/prefab-info-gatherer.ts +33 -0
  547. package/examples/prefab-receptionist.ts +36 -0
  548. package/examples/prefab-survey.ts +69 -0
  549. package/examples/quickstart-agent.ts +29 -0
  550. package/examples/quickstart-relay.ts +25 -0
  551. package/examples/quickstart-rest.ts +25 -0
  552. package/examples/record-call.ts +65 -0
  553. package/examples/relay-demo.ts +33 -0
  554. package/examples/room-and-sip.ts +93 -0
  555. package/examples/serverless-lambda.ts +43 -0
  556. package/examples/session-state.ts +83 -0
  557. package/examples/simple-agent.ts +36 -0
  558. package/examples/simple-static.ts +29 -0
  559. package/examples/skills-demo.ts +41 -0
  560. package/examples/step-function-inheritance-demo.ts +124 -0
  561. package/examples/swaig-features.ts +193 -0
  562. package/examples/swml-service-routing.ts +66 -0
  563. package/examples/swml-service.ts +38 -0
  564. package/examples/swmlservice_ai_sidecar.ts +104 -0
  565. package/examples/swmlservice_swaig_standalone.ts +79 -0
  566. package/examples/tap.ts +67 -0
  567. package/examples/typed-tools.ts +68 -0
  568. package/examples/verb-methods.ts +45 -0
  569. package/examples/web-search-multi-instance.ts +75 -0
  570. package/examples/web-search.ts +38 -0
  571. package/examples/wikipedia.ts +36 -0
  572. package/livewire/README.md +164 -0
  573. package/livewire/docs/migration-guide.md +251 -0
  574. package/livewire/examples/livewire-basic-agent.ts +74 -0
  575. package/livewire/examples/livewire-handoff.ts +196 -0
  576. package/livewire/examples/livewire-multi-tool.ts +121 -0
  577. package/package.json +85 -13
  578. package/relay/README.md +101 -0
  579. package/relay/docs/call-methods.md +622 -0
  580. package/relay/docs/client-reference.md +281 -0
  581. package/relay/docs/events.md +193 -0
  582. package/relay/docs/getting-started.md +221 -0
  583. package/relay/docs/guide.md +386 -0
  584. package/relay/docs/messaging.md +246 -0
  585. package/relay/examples/relay-inbound.ts +66 -0
  586. package/relay/examples/relay-messaging.ts +74 -0
  587. package/relay/examples/relay-outbound.ts +76 -0
  588. package/rest/README.md +141 -0
  589. package/rest/docs/calling.md +313 -0
  590. package/rest/docs/client-reference.md +149 -0
  591. package/rest/docs/fabric.md +192 -0
  592. package/rest/docs/getting-started.md +138 -0
  593. package/rest/docs/guide.md +421 -0
  594. package/rest/docs/namespaces.md +367 -0
  595. package/rest/docs/phone-binding.md +116 -0
  596. package/rest/examples/rest-10dlc-registration.ts +177 -0
  597. package/rest/examples/rest-bind-phone-to-swml-webhook.ts +66 -0
  598. package/rest/examples/rest-calling-ivr-and-ai.ts +136 -0
  599. package/rest/examples/rest-calling-play-and-record.ts +98 -0
  600. package/rest/examples/rest-client.ts +59 -0
  601. package/rest/examples/rest-datasphere-search.ts +81 -0
  602. package/rest/examples/rest-fabric-conferences-and-routing.ts +147 -0
  603. package/rest/examples/rest-fabric-subscribers-and-sip.ts +106 -0
  604. package/rest/examples/rest-fabric-swml-and-callflows.ts +101 -0
  605. package/rest/examples/rest-manage-resources.ts +64 -0
  606. package/rest/examples/rest-phone-number-management.ts +200 -0
  607. package/rest/examples/rest-queues-mfa-and-recordings.ts +143 -0
  608. package/rest/examples/rest-video-rooms.ts +186 -0
  609. package/tutorial/fred/fred.ts +218 -0
  610. package/tutorial/fred/tutorial/01-introduction.md +141 -0
  611. package/tutorial/fred/tutorial/02-setup.md +304 -0
  612. package/tutorial/fred/tutorial/03-basic-agent.md +284 -0
  613. package/tutorial/fred/tutorial/04-wikipedia-skill.md +298 -0
  614. package/tutorial/fred/tutorial/05-custom-functions.md +347 -0
  615. package/tutorial/fred/tutorial/06-running-testing.md +642 -0
  616. package/tutorial/fred/tutorial/README.md +56 -0
  617. package/tutorial/fred/tutorial/appendix-complete-code.md +632 -0
  618. package/tutorial/fred/tutorial/appendix-docker-deployment.md +504 -0
  619. package/tutorial/full-guardrails-agent/handlers.ts +436 -0
  620. package/tutorial/full-guardrails-agent/penny.ts +305 -0
  621. package/tutorial/full-guardrails-agent/reservations.ts +1109 -0
  622. package/tutorial/full-guardrails-agent/tutorial/01-why-guardrails.md +149 -0
  623. package/tutorial/full-guardrails-agent/tutorial/02-design-first.md +139 -0
  624. package/tutorial/full-guardrails-agent/tutorial/03-rules-first.md +422 -0
  625. package/tutorial/full-guardrails-agent/tutorial/04-the-shell.md +238 -0
  626. package/tutorial/full-guardrails-agent/tutorial/05-steps-and-scoping.md +247 -0
  627. package/tutorial/full-guardrails-agent/tutorial/06-tools-that-decide.md +467 -0
  628. package/tutorial/full-guardrails-agent/tutorial/07-gather-and-projection.md +160 -0
  629. package/tutorial/full-guardrails-agent/tutorial/08-the-verification-gate.md +333 -0
  630. package/tutorial/full-guardrails-agent/tutorial/09-people-and-endings.md +313 -0
  631. package/tutorial/full-guardrails-agent/tutorial/10-testing-and-running.md +387 -0
  632. package/tutorial/full-guardrails-agent/tutorial/README.md +106 -0
  633. package/tutorial/full-guardrails-agent/tutorial/appendix-complete-code.md +2207 -0
  634. package/tutorial/full-guardrails-agent/tutorial/appendix-deployment.md +191 -0
  635. package/tutorial/full-guardrails-agent/tutorial/appendix-technique-map.md +117 -0
  636. package/tutorial/full-guardrails-agent/workflow.ts +219 -0
  637. package/tutorial/multi_agents/README.md +175 -0
  638. package/tutorial/multi_agents/advanced_agent.ts +395 -0
  639. package/tutorial/multi_agents/extending_agents.ts +641 -0
  640. package/tutorial/multi_agents/knowledge.ts +59 -0
  641. package/tutorial/multi_agents/lesson1_first_agent.md +368 -0
  642. package/tutorial/multi_agents/lesson2_knowledge_bases.md +404 -0
  643. package/tutorial/multi_agents/lesson3_multi_agent_systems.md +621 -0
  644. package/tutorial/multi_agents/lesson4_advanced_features.md +805 -0
  645. package/tutorial/multi_agents/lesson5_extending_agents.md +856 -0
  646. package/tutorial/multi_agents/pc_builder.ts +529 -0
  647. package/tutorial/multi_agents/sales_agent.ts +88 -0
  648. package/tutorial/multi_agents/sales_agent_with_search.ts +116 -0
  649. package/tutorial/multi_agents/sales_knowledge.md +139 -0
  650. package/tutorial/multi_agents/support_knowledge.md +256 -0
  651. package/dist/cli/mock-data.d.ts +0 -37
  652. package/dist/cli/mock-data.js +0 -80
  653. package/dist/cli/mock-data.js.map +0 -1
  654. package/dist/generateVerbTypes.d.ts +0 -11
  655. package/dist/generateVerbTypes.js +0 -265
  656. package/dist/generateVerbTypes.js.map +0 -1
  657. package/dist/rest/namespaces/compat.d.ts +0 -585
  658. package/dist/rest/namespaces/compat.js +0 -735
  659. package/dist/rest/namespaces/compat.js.map +0 -1
@@ -0,0 +1,218 @@
1
+ // region: fred
2
+ /**
3
+ * Fred: a Wikipedia knowledge bot
4
+ *
5
+ * An agent that searches Wikipedia and shares facts about Wikipedia itself,
6
+ * with a friendly, curious persona.
7
+ *
8
+ * Run: npx tsx fred.ts
9
+ */
10
+
11
+ // region: imports
12
+ import { pathToFileURL } from 'node:url';
13
+
14
+ import { AgentBase, FunctionResult, WikipediaSearchSkill } from '@signalwire/sdk';
15
+ // endregion: imports
16
+
17
+ // region: facts
18
+ /** Facts about Wikipedia, by category, for the share_fun_fact tool. */
19
+ const FACTS = {
20
+ statistics: [
21
+ 'Wikipedia has over 6 million articles in English alone!',
22
+ 'Wikipedia is available in more than 300 languages!',
23
+ 'Wikipedia receives over 18 billion page views per month!',
24
+ 'There are over 100,000 active Wikipedia contributors!',
25
+ ],
26
+ history: [
27
+ 'Wikipedia was launched on January 15, 2001!',
28
+ 'Wikipedia started as a side project of Nupedia, an encyclopedia written by experts!',
29
+ "Wikipedia's name comes from 'wiki' (Hawaiian for 'quick') and 'encyclopedia'!",
30
+ 'Jimmy Wales and Larry Sanger founded Wikipedia!',
31
+ ],
32
+ records: [
33
+ "English Wikipedia's one billionth edit was made on January 13, 2021!",
34
+ 'Steven Pruitt has made more edits to English Wikipedia than anyone else, over three million!',
35
+ 'Wikipedia is one of the most visited websites in the world!',
36
+ ],
37
+ };
38
+ // endregion: facts
39
+
40
+ /** Fred, a Wikipedia assistant with a friendly persona. */
41
+ export class FredTheWikiBot extends AgentBase {
42
+ constructor() {
43
+ super({ name: 'Fred', route: '/fred' });
44
+
45
+ // region: personality
46
+ // Set up Fred's personality with the Prompt Object Model
47
+ this.promptAddSection('Personality', {
48
+ body:
49
+ 'You are Fred, a friendly and knowledgeable assistant who loves learning and ' +
50
+ "sharing information from Wikipedia. You're enthusiastic about facts and always " +
51
+ 'eager to help people discover new things.',
52
+ });
53
+ // endregion: personality
54
+
55
+ // region: goal
56
+ this.promptAddSection('Goal', {
57
+ body:
58
+ 'Help users find reliable factual information by searching Wikipedia. ' +
59
+ 'Make learning fun and engaging.',
60
+ });
61
+
62
+ this.promptAddSection('Instructions', {
63
+ bullets: [
64
+ 'Introduce yourself as Fred when greeting users',
65
+ 'Use the search_wiki function whenever users ask about factual topics',
66
+ 'Be enthusiastic about sharing knowledge',
67
+ 'Search before you say Wikipedia has nothing on a topic, even one that sounds made up',
68
+ "If Wikipedia doesn't have information, suggest alternative search terms",
69
+ 'Make learning conversational and enjoyable',
70
+ 'Add interesting context or follow-up questions to engage users',
71
+ ],
72
+ });
73
+ // endregion: goal
74
+
75
+ // region: voice
76
+ // Configure Fred's voice
77
+ this.addLanguage({
78
+ name: 'English',
79
+ code: 'en-US',
80
+ voice: 'rime.bolt', // A friendly, energetic voice for Fred
81
+ speechFillers: [
82
+ 'Hmm, let me think...',
83
+ "Oh, that's interesting...",
84
+ 'Great question!',
85
+ 'Let me see...',
86
+ ],
87
+ });
88
+ // endregion: voice
89
+
90
+ // region: hints
91
+ // Add hints for better speech recognition
92
+ this.addHints([
93
+ 'Wikipedia',
94
+ 'Fred',
95
+ 'tell me about',
96
+ 'what is',
97
+ 'who is',
98
+ 'search for',
99
+ 'look up',
100
+ ]);
101
+ // endregion: hints
102
+
103
+ // region: params
104
+ // Set conversation parameters
105
+ this.setParams({
106
+ ai_model: 'gpt-4.1-nano', // The model that runs the conversation
107
+ wait_for_user: true, // The caller speaks first
108
+ end_of_speech_timeout: 1000, // Milliseconds of silence that end the caller's turn
109
+ ai_volume: 7, // Voice volume adjustment (-50 to 50, default 0)
110
+ local_tz: 'America/New_York', // Time zone for time-related functions
111
+ });
112
+ // endregion: params
113
+
114
+ // region: global-data
115
+ // Add some context about Fred
116
+ this.setGlobalData({
117
+ assistant_name: 'Fred',
118
+ specialty: 'Wikipedia knowledge',
119
+ personality_traits: ['friendly', 'curious', 'enthusiastic', 'helpful'],
120
+ });
121
+ // endregion: global-data
122
+ }
123
+
124
+ // region: fun-fact
125
+ /** Register Fred's own tool. The SDK calls this once, the first time it needs the tools. */
126
+ protected override defineTools(): void {
127
+ this.defineTool({
128
+ name: 'share_fun_fact',
129
+ description: 'Share an interesting fact about Wikipedia itself',
130
+ parameters: {
131
+ category: {
132
+ type: 'string',
133
+ description: 'Type of fact to share',
134
+ enum: ['statistics', 'history', 'records', 'random'],
135
+ },
136
+ },
137
+ handler: (args) => {
138
+ // The model may leave the category out, so default to random
139
+ const category = args.category ?? 'random';
140
+
141
+ // The enum guides the model but doesn't bind it: random, or any
142
+ // category Fred doesn't have, draws from every fact
143
+ const known = category !== 'random' && Object.hasOwn(FACTS, category);
144
+ const factList = known ? FACTS[category] : Object.values(FACTS).flat();
145
+ const fact = factList[Math.floor(Math.random() * factList.length)];
146
+
147
+ // Say what kind of fact it is, so the model can introduce it
148
+ if (known) {
149
+ return new FunctionResult(`Here's a ${category} fact about Wikipedia: ${fact}`);
150
+ }
151
+ return new FunctionResult(`Here's a fun Wikipedia fact: ${fact}`);
152
+ },
153
+ });
154
+ }
155
+ // endregion: fun-fact
156
+ }
157
+
158
+ // region: create
159
+ /** Build Fred, then add the Wikipedia search skill, which loads asynchronously. */
160
+ export async function createFred(): Promise<FredTheWikiBot> {
161
+ const fred = new FredTheWikiBot();
162
+
163
+ // Add the Wikipedia search skill with custom configuration
164
+ await fred.addSkill(
165
+ new WikipediaSearchSkill({
166
+ num_results: 2, // Get up to 2 articles for broader coverage
167
+ no_results_message:
168
+ "Oh, I couldn't find anything about '{query}' on Wikipedia. " +
169
+ 'Maybe try different keywords or let me know if you meant something else!',
170
+ swaig_fields: {
171
+ fillers: {
172
+ 'en-US': [
173
+ 'Let me look that up on Wikipedia for you...',
174
+ 'Searching Wikipedia for that information...',
175
+ 'One moment, checking Wikipedia...',
176
+ 'Let me find that in the encyclopedia...',
177
+ ],
178
+ },
179
+ },
180
+ }),
181
+ );
182
+
183
+ return fred;
184
+ }
185
+ // endregion: create
186
+
187
+ // region: main
188
+ // swaig-test imports this file, and finds Fred through this export
189
+ export const fred = await createFred();
190
+
191
+ // Print the banner and start the server only when this file is the program
192
+ // that runs, not when another program imports it
193
+ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
194
+ const [username, password] = fred.getBasicAuthCredentials();
195
+
196
+ console.log('='.repeat(60));
197
+ console.log('Fred: a Wikipedia knowledge bot');
198
+ console.log('='.repeat(60));
199
+ console.log();
200
+ console.log('Fred searches Wikipedia and shares facts about Wikipedia itself.');
201
+ console.log();
202
+ console.log('Questions to try:');
203
+ console.log(' - Tell me about Albert Einstein');
204
+ console.log(' - What is quantum physics?');
205
+ console.log(' - Who was Marie Curie?');
206
+ console.log(' - Search for information about the solar system');
207
+ console.log(' - Can you share a fun fact?');
208
+ console.log();
209
+ console.log(`Fred is available at: http://localhost:${fred.port}/fred`);
210
+ console.log(`Basic Auth: ${username}:${password}`);
211
+ console.log();
212
+ console.log('Starting Fred. Press Ctrl+C to stop.');
213
+ console.log('='.repeat(60));
214
+
215
+ await fred.run();
216
+ }
217
+ // endregion: main
218
+ // endregion: fred
@@ -0,0 +1,141 @@
1
+ # Lesson 1: Introduction to SignalWire Agents
2
+
3
+ Before writing Fred, it helps to know what a SignalWire agent is and how a call reaches it. This lesson covers the platform, the SDK's building blocks, and the concepts the rest of the tutorial uses.
4
+
5
+ ## Table of Contents
6
+
7
+ 1. [What Is SignalWire?](#what-is-signalwire)
8
+ 2. [Understanding AI Agents](#understanding-ai-agents)
9
+ 3. [The SDK Architecture](#the-sdk-architecture)
10
+ 4. [What You're Building](#what-youre-building)
11
+ 5. [Key Concepts](#key-concepts)
12
+ 6. [Why This Architecture?](#why-this-architecture)
13
+
14
+ ---
15
+
16
+ ## What Is SignalWire?
17
+
18
+ SignalWire is a communications platform for building voice, video and messaging applications. It carries the phone call and runs the AI conversation, and your agent tells it what to do. The platform provides:
19
+
20
+ - Voice calling
21
+ - Real-time communication
22
+ - AI integration
23
+ - Scalable infrastructure
24
+
25
+ ## Understanding AI Agents
26
+
27
+ In the SignalWire SDK, an AI agent is a Node.js web application that does four things:
28
+
29
+ 1. **Answers HTTP requests** from SignalWire when a call arrives
30
+ 2. **Returns a SWML document** (SignalWire Markup Language) that describes the agent's behavior
31
+ 3. **Lets the platform run the conversation**, turning speech into text and the model's replies into speech
32
+ 4. **Runs functions** when the model asks for them during the call
33
+
34
+ The request flow looks like this:
35
+
36
+ ```text
37
+ Caller -> SignalWire platform -> Your agent -> SWML response -> AI conversation
38
+ ```
39
+
40
+ ## The SDK Architecture
41
+
42
+ An agent is an instance of `AgentBase`. Fred is a class that extends it, so its whole configuration lives in one place:
43
+
44
+ ```typescript
45
+ import { AgentBase } from '@signalwire/sdk';
46
+
47
+ class MyAgent extends AgentBase {
48
+ constructor() {
49
+ super({ name: 'My Agent', route: '/agent' });
50
+ }
51
+ }
52
+ ```
53
+
54
+ The SDK has four core components:
55
+
56
+ 1. **`AgentBase`**: the class every agent is built from
57
+ 2. **Skills**: ready-made capabilities you add with one call
58
+ 3. **SWAIG functions**: tools the model can call during a conversation
59
+ 4. **Prompt Object Model (POM)**: a structured way to write the agent's prompt
60
+
61
+ ## What You're Building
62
+
63
+ Fred is a voice assistant that answers questions from Wikipedia. Building it covers four techniques:
64
+
65
+ - **Persona design**: giving the agent a consistent voice and manner
66
+ - **Skill integration**: adding the Wikipedia search skill
67
+ - **Custom functions**: writing a tool of your own
68
+ - **Voice configuration**: choosing a voice and speech settings
69
+
70
+ By the end of the tutorial, Fred can:
71
+
72
+ 1. **Search Wikipedia** for a topic
73
+ 2. **Share facts** about Wikipedia itself
74
+ 3. **Hold a conversation** about what it finds
75
+ 4. **Answer voice calls** through SignalWire
76
+
77
+ ## Key Concepts
78
+
79
+ The rest of the tutorial relies on five concepts.
80
+
81
+ ### 1. SWML (SignalWire Markup Language)
82
+
83
+ SWML is a JSON document that tells SignalWire how your agent behaves. It includes:
84
+
85
+ - The prompt: the agent's persona and instructions
86
+ - The functions the model can call
87
+ - Voice and language settings
88
+ - Conversation parameters
89
+
90
+ ### 2. SWAIG (SignalWire AI Gateway)
91
+
92
+ SWAIG lets your agent run functions during a conversation. When a caller asks Fred about a topic, the model calls Fred's search function through SWAIG, and your code returns the result.
93
+
94
+ ### 3. Skills
95
+
96
+ Skills are ready-made modules that add a capability to an agent. Instead of writing Wikipedia search yourself, you add the existing skill. `addSkill()` returns a promise, because a skill can do setup work before it's ready:
97
+
98
+ <!-- snippet: no-compile fragment: `agent` stands for any AgentBase instance, and Lesson 4 adds the skill to Fred -->
99
+ ```typescript
100
+ await agent.addSkill(new WikipediaSearchSkill());
101
+ ```
102
+
103
+ ### 4. HTTP Endpoints
104
+
105
+ Your agent exposes HTTP endpoints that SignalWire calls:
106
+
107
+ - `/agent` returns the SWML document. SignalWire requests it with a `POST`, and you can fetch it with `GET` to inspect it.
108
+ - `POST /agent/swaig` runs a function
109
+
110
+ ### 5. Authentication
111
+
112
+ Agents protect their endpoints with HTTP Basic authentication. The SDK takes the credentials from environment variables, or generates a random password at startup.
113
+
114
+ ## Why This Architecture?
115
+
116
+ Keeping the call on the platform and the logic in your code has four benefits:
117
+
118
+ 1. **Separation of concerns**: your code handles logic, and the platform handles telephony
119
+ 2. **Scalability**: the platform runs many calls at once against the same agent
120
+ 3. **Flexibility**: a new capability is a skill or a function, not a rewrite
121
+ 4. **Testing**: you can test an agent locally, without a phone line
122
+
123
+ ## Review Questions
124
+
125
+ 1. What is the purpose of SWML?
126
+ 2. How do skills extend an agent?
127
+ 3. Which two HTTP endpoints does an agent expose for a call?
128
+
129
+ **Answers:**
130
+
131
+ 1. SWML tells SignalWire how the agent behaves during a call: its prompt, functions and voice settings.
132
+ 2. Skills add ready-made, tested capabilities with one call to `addSkill()`.
133
+ 3. The agent's route, which returns SWML, and its `/swaig` path, which runs functions.
134
+
135
+ ## Next Steps
136
+
137
+ With the concepts in place, the next step is installing the SDK. Continue with [Lesson 2: Setting Up Your Environment](02-setup.md).
138
+
139
+ ---
140
+
141
+ [Overview](README.md) | [Next: Environment Setup](02-setup.md)
@@ -0,0 +1,304 @@
1
+ # Lesson 2: Setting Up Your Environment
2
+
3
+ Fred needs Node.js and the SignalWire SDK. This lesson creates the project directory the rest of the tutorial uses, installs the SDK and the TypeScript tools in it, and checks that they work.
4
+
5
+ ## Table of Contents
6
+
7
+ 1. [Prerequisites Check](#prerequisites-check)
8
+ 2. [Creating the Project](#creating-the-project)
9
+ 3. [Installing the SDK](#installing-the-sdk)
10
+ 4. [Verifying Installation](#verifying-installation)
11
+ 5. [Understanding Dependencies](#understanding-dependencies)
12
+ 6. [Project Structure](#project-structure)
13
+ 7. [Environment Variables](#environment-variables)
14
+ 8. [Common Installation Issues](#common-installation-issues)
15
+
16
+ ---
17
+
18
+ ## Prerequisites Check
19
+
20
+ The SDK needs Node.js 22.18 or later, and npm to install it. From 22.18, Node.js can load a TypeScript file itself, and the SDK's `swaig-test` tool relies on that in [Lesson 6](06-running-testing.md).
21
+
22
+ ### Required Software
23
+
24
+ Check your Node.js version:
25
+
26
+ ```bash
27
+ node --version
28
+ ```
29
+
30
+ The output should show version 22.18 or later:
31
+
32
+ ```text
33
+ v24.18.0
34
+ ```
35
+
36
+ Check that npm is installed:
37
+
38
+ ```bash
39
+ npm --version
40
+ ```
41
+
42
+ ## Creating the Project
43
+
44
+ Fred's files live in one directory, which is also an npm project. Create it:
45
+
46
+ ```bash
47
+ mkdir fred-bot
48
+ cd fred-bot
49
+ npm init -y
50
+ npm pkg set type=module
51
+ ```
52
+
53
+ `npm init -y` writes a `package.json` with default values. `npm pkg set type=module` makes Node.js treat the project's files as ES modules. Fred needs that for `import`, and for `await` at the top level of a file.
54
+
55
+ ## Installing the SDK
56
+
57
+ With the project created, install the SDK from npm.
58
+
59
+ ### Basic Installation
60
+
61
+ One command installs the SDK:
62
+
63
+ ```bash
64
+ npm install @signalwire/sdk
65
+ ```
66
+
67
+ ### TypeScript Tools
68
+
69
+ Three development packages run and check TypeScript. Install them as development dependencies:
70
+
71
+ ```bash
72
+ npm install --save-dev tsx typescript @types/node
73
+ ```
74
+
75
+ Each package has a role:
76
+
77
+ - `tsx`: runs a TypeScript file without a build step, as in `npx tsx fred.ts`
78
+ - `typescript`: the `tsc` compiler, which checks types and compiles Fred to JavaScript for [Appendix B](appendix-docker-deployment.md)
79
+ - `@types/node`: type definitions for Node.js itself
80
+
81
+ ### The tsconfig.json File
82
+
83
+ `tsc` reads its settings from `tsconfig.json`. Create it in the project directory with these settings:
84
+
85
+ <!-- copy of: tutorial/fred/tsconfig.json -->
86
+ ```json
87
+ {
88
+ "compilerOptions": {
89
+ "target": "ES2022",
90
+ "module": "NodeNext",
91
+ "moduleResolution": "NodeNext",
92
+ "strict": true,
93
+ "skipLibCheck": true,
94
+ "types": ["node"],
95
+ "outDir": "dist"
96
+ },
97
+ "files": ["fred.ts"]
98
+ }
99
+ ```
100
+
101
+ `strict` turns on TypeScript's full type checks. `outDir` is where `tsc` writes the compiled `fred.js`, and `files` names the one file to compile. `fred.ts` doesn't exist yet, so `tsc` has nothing to check until [Lesson 3](03-basic-agent.md).
102
+
103
+ ## Verifying Installation
104
+
105
+ A short script confirms that the SDK imports and can create an agent. Create a file called `check-setup.ts`:
106
+
107
+ ```typescript
108
+ // Check that this machine is ready to build Fred
109
+ import { versions } from 'node:process';
110
+
111
+ const [major = 0, minor = 0] = versions.node.split('.').map(Number);
112
+ if (major > 22 || (major === 22 && minor >= 18)) {
113
+ console.log(`OK Node.js ${versions.node}`);
114
+ } else {
115
+ console.log(`MISSING Node.js ${versions.node} (need 22.18 or later)`);
116
+ process.exitCode = 1;
117
+ }
118
+
119
+ try {
120
+ // Import the SDK and create an agent. Nothing starts a server.
121
+ const { AgentBase } = await import('@signalwire/sdk');
122
+ const agent = new AgentBase({ name: 'Test Agent', route: '/test' });
123
+ console.log(`OK SignalWire SDK (created '${agent.getName()}' at ${agent.route})`);
124
+ } catch (err) {
125
+ console.log(`MISSING SignalWire SDK: ${err instanceof Error ? err.message : String(err)}`);
126
+ console.log(' Run: npm install @signalwire/sdk');
127
+ process.exitCode = 1;
128
+ }
129
+ ```
130
+
131
+ Run the script with `SIGNALWIRE_LOG_MODE=off`, which keeps the SDK's startup warnings out of the output. [Lesson 6](06-running-testing.md#important-information) explains those warnings.
132
+
133
+ ```bash
134
+ SIGNALWIRE_LOG_MODE=off npx tsx check-setup.ts
135
+ ```
136
+
137
+ The output confirms both parts:
138
+
139
+ ```text
140
+ OK Node.js 24.18.0
141
+ OK SignalWire SDK (created 'Test Agent' at /test)
142
+ ```
143
+
144
+ `npm ls` shows the installed version of the SDK:
145
+
146
+ ```bash
147
+ npm ls @signalwire/sdk
148
+ ```
149
+
150
+ The output names the project and the version:
151
+
152
+ ```text
153
+ fred-bot@1.0.0 /home/you/fred-bot
154
+ └── @signalwire/sdk@3.5.0
155
+ ```
156
+
157
+ You can delete `check-setup.ts` once it passes.
158
+
159
+ ## Understanding Dependencies
160
+
161
+ The SDK installs a small set of packages with it:
162
+
163
+ - `hono`: the web framework behind the agent's HTTP endpoints
164
+ - `@hono/node-server`: runs a Hono app on Node.js's HTTP server
165
+ - `ajv`: checks SWML and function arguments against their JSON schemas
166
+ - `js-yaml`: reads and writes prompts as YAML
167
+ - `ws`: the WebSocket client behind the SDK's RELAY client
168
+
169
+ Fetching from Wikipedia uses the `fetch` function built into Node.js, so the Wikipedia skill needs no extra package. A few other skills do. The `web_search` and `spider` skills need `cheerio`, for example. Fred doesn't use them.
170
+
171
+ ## Project Structure
172
+
173
+ By the end of the tutorial, the directory holds these files:
174
+
175
+ ```text
176
+ fred-bot/
177
+ ├── fred.ts # The agent
178
+ ├── fred.sh # Management script (Lesson 6)
179
+ ├── package.json # The project and its dependencies
180
+ ├── package-lock.json # The exact versions npm installed
181
+ ├── tsconfig.json # TypeScript settings
182
+ └── node_modules/ # The installed packages
183
+ ```
184
+
185
+ ### The package.json File
186
+
187
+ After the installs, `package.json` lists the SDK and the three tools. Replace the defaults `npm init` wrote with this version, which adds a description, the Node.js version Fred needs, and three scripts:
188
+
189
+ <!-- copy of: tutorial/fred/package.json -->
190
+ ```json
191
+ {
192
+ "name": "fred-bot",
193
+ "version": "1.0.0",
194
+ "private": true,
195
+ "description": "Fred, a voice agent that answers questions from Wikipedia",
196
+ "type": "module",
197
+ "scripts": {
198
+ "start": "tsx fred.ts",
199
+ "build": "tsc",
200
+ "typecheck": "tsc --noEmit"
201
+ },
202
+ "engines": {
203
+ "node": ">=22.18.0"
204
+ },
205
+ "dependencies": {
206
+ "@signalwire/sdk": "^3.5.0"
207
+ },
208
+ "devDependencies": {
209
+ "@types/node": "^22.20.4",
210
+ "tsx": "^4.23.15",
211
+ "typescript": "^7.0.2"
212
+ }
213
+ }
214
+ ```
215
+
216
+ The scripts are shortcuts. `npm start` runs Fred with `tsx`, and `npm run build` compiles it into `dist/`. `npm run typecheck` checks its types without writing any files. Commit `package-lock.json` with the rest of the project, so that `npm ci` installs the same versions everywhere, including in the Docker images in [Appendix B](appendix-docker-deployment.md).
217
+
218
+ ## Environment Variables
219
+
220
+ The SDK reads a few optional environment variables.
221
+
222
+ ### Authentication
223
+
224
+ Without these, the SDK generates a random password each time the agent starts, and uses the agent's name, `Fred`, as the username:
225
+
226
+ ```bash
227
+ export SWML_BASIC_AUTH_USER="fred"
228
+ export SWML_BASIC_AUTH_PASSWORD="a-long-random-password"
229
+ ```
230
+
231
+ ### Port
232
+
233
+ Fred listens on port 3000 by default. If something else uses that port, choose another:
234
+
235
+ ```bash
236
+ export PORT=3001
237
+ ```
238
+
239
+ ### Proxy Configuration
240
+
241
+ When Fred runs behind a proxy or a tunnel such as ngrok, tell the SDK its public address:
242
+
243
+ ```bash
244
+ export SWML_PROXY_URL_BASE="https://your-domain.com"
245
+ ```
246
+
247
+ ## Common Installation Issues
248
+
249
+ Most installation problems have one of three causes.
250
+
251
+ ### Issue: Node.js Is Too Old
252
+
253
+ Before version 22.18, Node.js can't load a TypeScript file itself, so `swaig-test` fails on `fred.ts`:
254
+
255
+ ```text
256
+ Error: Failed to import agent file: /home/you/fred-bot/fred.ts
257
+ TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".ts" for /home/you/fred-bot/fred.ts
258
+ ```
259
+
260
+ Install a current release from [nodejs.org](https://nodejs.org/), or with a version manager such as nvm:
261
+
262
+ ```bash
263
+ nvm install 24
264
+ nvm use 24
265
+ ```
266
+
267
+ ### Issue: Top-Level Await Isn't Supported
268
+
269
+ If `package.json` has no `"type": "module"`, `tsx` compiles `fred.ts` as CommonJS, and the `await` at the top of the file fails:
270
+
271
+ ```text
272
+ ERROR: Top-level await is currently not supported with the "cjs" output format
273
+ ```
274
+
275
+ Set the module type, then run Fred again:
276
+
277
+ ```bash
278
+ npm pkg set type=module
279
+ ```
280
+
281
+ ### Issue: Cannot Find the Package
282
+
283
+ Node.js can't find the SDK when it isn't installed in the project that runs the file:
284
+
285
+ ```text
286
+ Cannot find package '@signalwire/sdk' imported from /home/you/fred-bot/check-setup.ts
287
+ ```
288
+
289
+ Run `npm install` from the project directory, the one that holds `package.json`, and run Fred from there too.
290
+
291
+ ## Next Steps
292
+
293
+ Before you continue, check that:
294
+
295
+ - Node.js 22.18 or later is installed
296
+ - The project directory has `package.json` with `"type": "module"`, and `tsconfig.json`
297
+ - The SDK and the TypeScript tools are installed
298
+ - `check-setup.ts` passes
299
+
300
+ Next, create Fred's agent class. Continue with [Lesson 3: Creating Fred's Basic Structure](03-basic-agent.md).
301
+
302
+ ---
303
+
304
+ [Previous: Introduction](01-introduction.md) | [Overview](README.md) | [Next: Basic Agent](03-basic-agent.md)