@signalwire/sdk 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (325) hide show
  1. package/.github/workflows/publish.yml +27 -0
  2. package/.github/workflows/test.yml +17 -0
  3. package/CLAUDE.md +112 -0
  4. package/README.md +254 -0
  5. package/docs/MIGRATION-2.0.md +81 -0
  6. package/docs/agent-guide.md +869 -0
  7. package/docs/agent_guide.md +1026 -0
  8. package/docs/api-reference.md +2420 -0
  9. package/docs/api_reference.md +1301 -0
  10. package/docs/architecture.md +843 -0
  11. package/docs/cli-guide.md +579 -0
  12. package/docs/cli_guide.md +448 -0
  13. package/docs/cloud_functions_guide.md +474 -0
  14. package/docs/configuration.md +422 -0
  15. package/docs/contexts-guide.md +787 -0
  16. package/docs/contexts_guide.md +511 -0
  17. package/docs/datamap-guide.md +1141 -0
  18. package/docs/datamap_guide.md +595 -0
  19. package/docs/llm_parameters.md +239 -0
  20. package/docs/mcp_gateway_reference.md +648 -0
  21. package/docs/mcp_integration.md +108 -0
  22. package/docs/prefabs-guide.md +800 -0
  23. package/docs/sdk_features.md +477 -0
  24. package/docs/security.md +436 -0
  25. package/docs/serverless-guide.md +513 -0
  26. package/docs/skills-guide.md +857 -0
  27. package/docs/skills-system.md +301 -0
  28. package/docs/skills_parameter_schema.md +392 -0
  29. package/docs/skills_system.md +467 -0
  30. package/docs/swaig-reference.md +1627 -0
  31. package/docs/swaig_reference.md +910 -0
  32. package/docs/swml_service_guide.md +600 -0
  33. package/docs/third_party_skills.md +533 -0
  34. package/docs/web_service.md +677 -0
  35. package/examples/README.md +131 -0
  36. package/examples/advanced-datamap.ts +100 -0
  37. package/examples/advanced-dynamic-config.ts +70 -0
  38. package/examples/auto-vivified.ts +94 -0
  39. package/examples/call-flow.ts +63 -0
  40. package/examples/comprehensive-dynamic.ts +125 -0
  41. package/examples/contexts-steps.ts +65 -0
  42. package/examples/custom-path.ts +45 -0
  43. package/examples/datamap-tools.ts +55 -0
  44. package/examples/datasphere-multi-instance.ts +63 -0
  45. package/examples/datasphere-serverless-env.ts +68 -0
  46. package/examples/datasphere-webhook-env.ts +66 -0
  47. package/examples/datasphere.ts +37 -0
  48. package/examples/declarative.ts +100 -0
  49. package/examples/dynamic-config.ts +54 -0
  50. package/examples/dynamic-info-gatherer.ts +69 -0
  51. package/examples/dynamic-swml-service.ts +67 -0
  52. package/examples/gather-info.ts +71 -0
  53. package/examples/gather-per-question-functions-demo.ts +140 -0
  54. package/examples/joke-agent.ts +34 -0
  55. package/examples/kubernetes-agent.ts +45 -0
  56. package/examples/llm-params.ts +69 -0
  57. package/examples/mcp-agent.ts +84 -0
  58. package/examples/mcp-gateway.ts +35 -0
  59. package/examples/multi-agent.ts +73 -0
  60. package/examples/multi-endpoint.ts +79 -0
  61. package/examples/pom-prompt.ts +71 -0
  62. package/examples/prefab-concierge.ts +47 -0
  63. package/examples/prefab-faq.ts +54 -0
  64. package/examples/prefab-info-gatherer.ts +33 -0
  65. package/examples/prefab-receptionist.ts +36 -0
  66. package/examples/prefab-survey.ts +68 -0
  67. package/examples/record-call.ts +67 -0
  68. package/examples/relay-demo.ts +33 -0
  69. package/examples/room-and-sip.ts +94 -0
  70. package/examples/serverless-lambda.ts +35 -0
  71. package/examples/session-state.ts +83 -0
  72. package/examples/simple-agent.ts +36 -0
  73. package/examples/simple-static.ts +29 -0
  74. package/examples/skills-demo.ts +38 -0
  75. package/examples/step-function-inheritance-demo.ts +124 -0
  76. package/examples/swaig-features.ts +187 -0
  77. package/examples/swml-service-routing.ts +66 -0
  78. package/examples/swml-service.ts +38 -0
  79. package/examples/tap.ts +68 -0
  80. package/examples/verb-methods.ts +45 -0
  81. package/examples/web-search-multi-instance.ts +72 -0
  82. package/examples/web-search.ts +38 -0
  83. package/examples/wikipedia.ts +36 -0
  84. package/livewire/README.md +140 -0
  85. package/livewire/docs/migration-guide.md +228 -0
  86. package/livewire/examples/livewire-basic-agent.ts +74 -0
  87. package/livewire/examples/livewire-handoff.ts +197 -0
  88. package/livewire/examples/livewire-multi-tool.ts +117 -0
  89. package/package.json +38 -0
  90. package/relay/README.md +70 -0
  91. package/relay/RELAY_IMPLEMENTATION_GUIDE.md +1257 -0
  92. package/relay/docs/call-methods.md +474 -0
  93. package/relay/docs/client-reference.md +142 -0
  94. package/relay/docs/events.md +134 -0
  95. package/relay/docs/getting-started.md +134 -0
  96. package/relay/docs/guide.md +306 -0
  97. package/relay/docs/messaging.md +182 -0
  98. package/relay/examples/relay-inbound.ts +66 -0
  99. package/relay/examples/relay-messaging.ts +71 -0
  100. package/relay/examples/relay-outbound.ts +76 -0
  101. package/rest/README.md +95 -0
  102. package/rest/docs/calling.md +273 -0
  103. package/rest/docs/client-reference.md +107 -0
  104. package/rest/docs/compat.md +204 -0
  105. package/rest/docs/fabric.md +183 -0
  106. package/rest/docs/getting-started.md +110 -0
  107. package/rest/docs/guide.md +351 -0
  108. package/rest/docs/namespaces.md +285 -0
  109. package/rest/examples/rest-10dlc-registration.ts +161 -0
  110. package/rest/examples/rest-calling-ivr-and-ai.ts +102 -0
  111. package/rest/examples/rest-calling-play-and-record.ts +91 -0
  112. package/rest/examples/rest-client.ts +65 -0
  113. package/rest/examples/rest-compat-laml.ts +210 -0
  114. package/rest/examples/rest-datasphere-search.ts +82 -0
  115. package/rest/examples/rest-fabric-conferences-and-routing.ts +144 -0
  116. package/rest/examples/rest-fabric-subscribers-and-sip.ts +108 -0
  117. package/rest/examples/rest-fabric-swml-and-callflows.ts +99 -0
  118. package/rest/examples/rest-manage-resources.ts +65 -0
  119. package/rest/examples/rest-phone-number-management.ts +197 -0
  120. package/rest/examples/rest-queues-mfa-and-recordings.ts +143 -0
  121. package/rest/examples/rest-video-rooms.ts +186 -0
  122. package/src/AgentBase.ts +2489 -0
  123. package/src/AgentServer.ts +415 -0
  124. package/src/AuthHandler.ts +256 -0
  125. package/src/ConfigLoader.ts +447 -0
  126. package/src/ContextBuilder.ts +1150 -0
  127. package/src/DataMap.ts +449 -0
  128. package/src/FunctionResult.ts +866 -0
  129. package/src/Logger.ts +337 -0
  130. package/src/PomBuilder.ts +439 -0
  131. package/src/PromptManager.ts +133 -0
  132. package/src/SWMLHandler.ts +298 -0
  133. package/src/SWMLService.ts +717 -0
  134. package/src/SchemaUtils.ts +361 -0
  135. package/src/SecurityUtils.ts +153 -0
  136. package/src/ServerlessAdapter.ts +221 -0
  137. package/src/SessionManager.ts +311 -0
  138. package/src/SslConfig.ts +118 -0
  139. package/src/SwaigFunction.ts +276 -0
  140. package/src/SwmlBuilder.ts +258 -0
  141. package/src/SwmlVerbMethods.generated.ts +234 -0
  142. package/src/TypeInference.ts +181 -0
  143. package/src/WebService.ts +619 -0
  144. package/src/cli/agent-loader.ts +166 -0
  145. package/src/cli/mock-data.ts +111 -0
  146. package/src/cli/swaig-test.ts +452 -0
  147. package/src/generateVerbTypes.ts +322 -0
  148. package/src/index.ts +167 -0
  149. package/src/livewire/index.ts +950 -0
  150. package/src/prefabs/ConciergeAgent.ts +287 -0
  151. package/src/prefabs/FAQBotAgent.ts +384 -0
  152. package/src/prefabs/InfoGathererAgent.ts +339 -0
  153. package/src/prefabs/ReceptionistAgent.ts +366 -0
  154. package/src/prefabs/SurveyAgent.ts +646 -0
  155. package/src/prefabs/index.ts +27 -0
  156. package/src/relay/Action.ts +314 -0
  157. package/src/relay/Call.ts +854 -0
  158. package/src/relay/Deferred.ts +71 -0
  159. package/src/relay/Message.ts +148 -0
  160. package/src/relay/RelayClient.ts +1036 -0
  161. package/src/relay/RelayError.ts +14 -0
  162. package/src/relay/RelayEvent.ts +892 -0
  163. package/src/relay/constants.ts +132 -0
  164. package/src/relay/index.ts +123 -0
  165. package/src/relay/types.ts +149 -0
  166. package/src/rest/HttpClient.ts +103 -0
  167. package/src/rest/RestError.ts +31 -0
  168. package/src/rest/base/BaseResource.ts +19 -0
  169. package/src/rest/base/CrudResource.ts +51 -0
  170. package/src/rest/base/CrudWithAddresses.ts +26 -0
  171. package/src/rest/index.ts +200 -0
  172. package/src/rest/namespaces/addresses.ts +32 -0
  173. package/src/rest/namespaces/calling.ts +187 -0
  174. package/src/rest/namespaces/chat.ts +20 -0
  175. package/src/rest/namespaces/compat.ts +352 -0
  176. package/src/rest/namespaces/datasphere.ts +45 -0
  177. package/src/rest/namespaces/fabric.ts +222 -0
  178. package/src/rest/namespaces/imported-numbers.ts +20 -0
  179. package/src/rest/namespaces/logs.ts +84 -0
  180. package/src/rest/namespaces/lookup.ts +21 -0
  181. package/src/rest/namespaces/mfa.ts +30 -0
  182. package/src/rest/namespaces/number-groups.ts +38 -0
  183. package/src/rest/namespaces/phone-numbers.ts +44 -0
  184. package/src/rest/namespaces/project.ts +36 -0
  185. package/src/rest/namespaces/pubsub.ts +20 -0
  186. package/src/rest/namespaces/queues.ts +33 -0
  187. package/src/rest/namespaces/recordings.ts +28 -0
  188. package/src/rest/namespaces/registry.ts +101 -0
  189. package/src/rest/namespaces/short-codes.ts +28 -0
  190. package/src/rest/namespaces/sip-profile.ts +25 -0
  191. package/src/rest/namespaces/verified-callers.ts +27 -0
  192. package/src/rest/namespaces/video.ts +165 -0
  193. package/src/rest/pagination.ts +84 -0
  194. package/src/rest/types.ts +61 -0
  195. package/src/schema.json +12250 -0
  196. package/src/skills/SkillBase.ts +547 -0
  197. package/src/skills/SkillManager.ts +415 -0
  198. package/src/skills/SkillRegistry.ts +367 -0
  199. package/src/skills/builtin/api_ninjas_trivia.ts +280 -0
  200. package/src/skills/builtin/ask_claude.ts +241 -0
  201. package/src/skills/builtin/claude_skills.ts +978 -0
  202. package/src/skills/builtin/custom_skills.ts +312 -0
  203. package/src/skills/builtin/datasphere.ts +438 -0
  204. package/src/skills/builtin/datasphere_serverless.ts +339 -0
  205. package/src/skills/builtin/datetime.ts +130 -0
  206. package/src/skills/builtin/google_maps.ts +651 -0
  207. package/src/skills/builtin/index.ts +88 -0
  208. package/src/skills/builtin/info_gatherer.ts +405 -0
  209. package/src/skills/builtin/joke.ts +191 -0
  210. package/src/skills/builtin/math.ts +142 -0
  211. package/src/skills/builtin/mcp_gateway.ts +677 -0
  212. package/src/skills/builtin/native_vector_search.ts +901 -0
  213. package/src/skills/builtin/play_background_file.ts +358 -0
  214. package/src/skills/builtin/spider.ts +869 -0
  215. package/src/skills/builtin/swml_transfer.ts +635 -0
  216. package/src/skills/builtin/weather_api.ts +248 -0
  217. package/src/skills/builtin/web_search.ts +1074 -0
  218. package/src/skills/builtin/wikipedia_search.ts +299 -0
  219. package/src/skills/index.ts +12 -0
  220. package/src/types.ts +132 -0
  221. package/tests/AgentBase.test.ts +1093 -0
  222. package/tests/AgentServer.test.ts +126 -0
  223. package/tests/AuthHandler.test.ts +133 -0
  224. package/tests/ConfigLoader.test.ts +151 -0
  225. package/tests/ContextBuilder.test.ts +108 -0
  226. package/tests/DataMap.test.ts +367 -0
  227. package/tests/EphemeralSkillCopy.test.ts +107 -0
  228. package/tests/FunctionResult.test.ts +298 -0
  229. package/tests/GracefulShutdown.test.ts +46 -0
  230. package/tests/Logger.test.ts +420 -0
  231. package/tests/PomBuilder.test.ts +228 -0
  232. package/tests/ProxyDetection.test.ts +228 -0
  233. package/tests/SWMLService.test.ts +320 -0
  234. package/tests/SWMLVerbHandler.test.ts +523 -0
  235. package/tests/SchemaUtils.test.ts +106 -0
  236. package/tests/SchemaUtils.verb.test.ts +206 -0
  237. package/tests/SecurityUtils.test.ts +192 -0
  238. package/tests/ServerlessAdapter.test.ts +222 -0
  239. package/tests/SessionManager.test.ts +257 -0
  240. package/tests/SkillBaseFeatures.test.ts +130 -0
  241. package/tests/SkillMultiInstance.test.ts +102 -0
  242. package/tests/SkillParameterSchemas.test.ts +134 -0
  243. package/tests/SkillRegistrySchema.test.ts +84 -0
  244. package/tests/SslConfig.test.ts +97 -0
  245. package/tests/SwmlBuilder.test.ts +400 -0
  246. package/tests/TypeInference.test.ts +165 -0
  247. package/tests/VerbHandlerRegistry.test.ts +128 -0
  248. package/tests/cli/mock-data.test.ts +113 -0
  249. package/tests/cli/swaig-test.test.ts +108 -0
  250. package/tests/examples.test.ts +194 -0
  251. package/tests/fixtures/scrape-parity/README.md +53 -0
  252. package/tests/fixtures/scrape-parity/expected/01_simple_article.json +5 -0
  253. package/tests/fixtures/scrape-parity/expected/02_class_based_noise.json +5 -0
  254. package/tests/fixtures/scrape-parity/expected/03_nested_containers.json +5 -0
  255. package/tests/fixtures/scrape-parity/expected/04_bare_body.json +5 -0
  256. package/tests/fixtures/scrape-parity/expected/05_malformed.json +5 -0
  257. package/tests/fixtures/scrape-parity/expected/06_multi_class.json +5 -0
  258. package/tests/fixtures/scrape-parity/expected/07_anchor_pattern.json +5 -0
  259. package/tests/fixtures/scrape-parity/expected/08_inline_script.json +5 -0
  260. package/tests/fixtures/scrape-parity/expected/09_whitespace_nbsp.json +5 -0
  261. package/tests/fixtures/scrape-parity/expected/10_entity_unicode.json +5 -0
  262. package/tests/fixtures/scrape-parity/expected/11_cdata_comments.json +5 -0
  263. package/tests/fixtures/scrape-parity/expected/12_deep_nested_removals.json +5 -0
  264. package/tests/fixtures/scrape-parity/html/01_simple_article.html +18 -0
  265. package/tests/fixtures/scrape-parity/html/02_class_based_noise.html +18 -0
  266. package/tests/fixtures/scrape-parity/html/03_nested_containers.html +13 -0
  267. package/tests/fixtures/scrape-parity/html/04_bare_body.html +9 -0
  268. package/tests/fixtures/scrape-parity/html/05_malformed.html +11 -0
  269. package/tests/fixtures/scrape-parity/html/06_multi_class.html +18 -0
  270. package/tests/fixtures/scrape-parity/html/07_anchor_pattern.html +12 -0
  271. package/tests/fixtures/scrape-parity/html/08_inline_script.html +17 -0
  272. package/tests/fixtures/scrape-parity/html/09_whitespace_nbsp.html +21 -0
  273. package/tests/fixtures/scrape-parity/html/10_entity_unicode.html +10 -0
  274. package/tests/fixtures/scrape-parity/html/11_cdata_comments.html +13 -0
  275. package/tests/fixtures/scrape-parity/html/12_deep_nested_removals.html +24 -0
  276. package/tests/fixtures/scrape-parity/python_extract.py +109 -0
  277. package/tests/livewire/livewire.test.ts +780 -0
  278. package/tests/mcp.test.ts +221 -0
  279. package/tests/prefabs/prefabs.test.ts +1093 -0
  280. package/tests/relay/Action.test.ts +392 -0
  281. package/tests/relay/Call.test.ts +535 -0
  282. package/tests/relay/Deferred.test.ts +71 -0
  283. package/tests/relay/Message.test.ts +164 -0
  284. package/tests/relay/RelayClient.test.ts +779 -0
  285. package/tests/relay/RelayEvent.test.ts +463 -0
  286. package/tests/relay/helpers.ts +79 -0
  287. package/tests/rest/HttpClient.test.ts +274 -0
  288. package/tests/rest/RestError.test.ts +53 -0
  289. package/tests/rest/calling.test.ts +156 -0
  290. package/tests/rest/client.test.ts +197 -0
  291. package/tests/rest/compat.test.ts +335 -0
  292. package/tests/rest/datasphere.test.ts +71 -0
  293. package/tests/rest/fabric.test.ts +186 -0
  294. package/tests/rest/helpers.ts +95 -0
  295. package/tests/rest/logs.test.ts +68 -0
  296. package/tests/rest/pagination.test.ts +133 -0
  297. package/tests/rest/registry.test.ts +94 -0
  298. package/tests/rest/relay-rest.test.ts +290 -0
  299. package/tests/rest/video.test.ts +173 -0
  300. package/tests/setup.ts +6 -0
  301. package/tests/skills/SkillBase.test.ts +108 -0
  302. package/tests/skills/SkillManager.test.ts +268 -0
  303. package/tests/skills/SkillRegistry.test.ts +176 -0
  304. package/tests/skills/builtin.test.ts +1472 -0
  305. package/tests/skills/claude-skills.test.ts +54 -0
  306. package/tests/skills/custom-skills.test.ts +53 -0
  307. package/tests/skills/datasphere-serverless.test.ts +70 -0
  308. package/tests/skills/datasphere.test.ts +107 -0
  309. package/tests/skills/datetime.test.ts +101 -0
  310. package/tests/skills/google-maps.test.ts +78 -0
  311. package/tests/skills/info-gatherer.test.ts +411 -0
  312. package/tests/skills/joke.test.ts +81 -0
  313. package/tests/skills/math.test.ts +68 -0
  314. package/tests/skills/mcp-gateway.test.ts +101 -0
  315. package/tests/skills/play-background.test.ts +54 -0
  316. package/tests/skills/spider.test.ts +108 -0
  317. package/tests/skills/swml-transfer.test.ts +178 -0
  318. package/tests/skills/trivia.test.ts +54 -0
  319. package/tests/skills/vector-search.test.ts +135 -0
  320. package/tests/skills/weather-api.test.ts +77 -0
  321. package/tests/skills/web-search-parity.test.ts +59 -0
  322. package/tests/skills/web-search.test.ts +103 -0
  323. package/tests/skills/wikipedia.test.ts +63 -0
  324. package/tsconfig.json +18 -0
  325. package/vitest.config.ts +9 -0
@@ -0,0 +1,646 @@
1
+ /**
2
+ * SurveyAgent - A prefab agent that conducts surveys with branching logic,
3
+ * scoring, and conditional question flow.
4
+ *
5
+ * Ported from the Python SDK `signalwire.prefabs.survey.SurveyAgent`. Keeps
6
+ * TS-specific enhancements (per-call session state, branching via
7
+ * `nextQuestion`, answer scoring via `points`) alongside the Python surface.
8
+ */
9
+
10
+ import { AgentBase } from '../AgentBase.js';
11
+ import { FunctionResult } from '../FunctionResult.js';
12
+ import type { AgentOptions } from '../types.js';
13
+
14
+ // ── Config types ────────────────────────────────────────────────────────────
15
+
16
+ export interface SurveyQuestion {
17
+ /** Unique question identifier. */
18
+ id: string;
19
+ /** The question text to ask the caller. */
20
+ text: string;
21
+ /** Question type determines validation and display. */
22
+ type: 'multiple_choice' | 'open_ended' | 'rating' | 'yes_no';
23
+ /** Options for multiple_choice questions. */
24
+ options?: string[];
25
+ /**
26
+ * For `rating` questions, the upper bound of the scale (1..scale).
27
+ * Defaults to 5 (matching the Python prefab) when unspecified.
28
+ */
29
+ scale?: number;
30
+ /**
31
+ * Whether the question requires an answer. Defaults to `true`.
32
+ * Mirrors the Python `required` flag on each question dict.
33
+ */
34
+ required?: boolean;
35
+ /**
36
+ * Next question ID after this one.
37
+ * - string: always go to that question
38
+ * - Record<string, string>: map from answer value to next question ID
39
+ * - undefined: proceed to next question in array order
40
+ */
41
+ nextQuestion?: string | Record<string, string>;
42
+ /**
43
+ * Points awarded for answers.
44
+ * - number: fixed points for any answer
45
+ * - Record<string, number>: points per specific answer value
46
+ */
47
+ points?: number | Record<string, number>;
48
+ }
49
+
50
+ export interface SurveyConfig {
51
+ /** Human-readable survey name, used in prompts and global data. */
52
+ surveyName: string;
53
+ /** Ordered list of survey questions. */
54
+ questions: SurveyQuestion[];
55
+ /** Opening message before the first question (matches Python `introduction`). */
56
+ introduction?: string;
57
+ /** Message after the survey is complete (matches Python `conclusion`). */
58
+ conclusion?: string;
59
+ /** Brand or company name the agent represents (matches Python `brand_name`). */
60
+ brandName?: string;
61
+ /** Maximum number of times to retry invalid answers. Defaults to 2. */
62
+ maxRetries?: number;
63
+ /** Agent display name (defaults to `"survey"`). */
64
+ name?: string;
65
+ /** HTTP route for this agent (defaults to `"/survey"`). */
66
+ route?: string;
67
+ /** Callback fired when the survey is finished. */
68
+ onComplete?: (responses: Record<string, unknown>, score: number) => void | Promise<void>;
69
+ /** Additional AgentBase options forwarded to super(). */
70
+ agentOptions?: Partial<AgentOptions>;
71
+ }
72
+
73
+ // ── Per-call session state ──────────────────────────────────────────────────
74
+
75
+ interface SurveySession {
76
+ currentQuestionIndex: number;
77
+ currentQuestionId: string;
78
+ responses: Record<string, unknown>;
79
+ score: number;
80
+ completed: boolean;
81
+ }
82
+
83
+ // ── Agent ───────────────────────────────────────────────────────────────────
84
+
85
+ /** Prefab agent that conducts surveys with branching logic, answer scoring, and conditional question flow. */
86
+ export class SurveyAgent extends AgentBase {
87
+ /** Human-readable survey name. */
88
+ public surveyName: string;
89
+ /** The configured survey questions (public, matching Python). */
90
+ public questions: SurveyQuestion[];
91
+ /** Brand/company name used in prompts. */
92
+ public brandName: string;
93
+ /** Maximum number of times to retry invalid answers. */
94
+ public maxRetries: number;
95
+ /** Opening message before the first question. */
96
+ public introduction: string;
97
+ /** Closing message shown when the survey completes. */
98
+ public conclusion: string;
99
+
100
+ private questionMap: Map<string, SurveyQuestion>;
101
+ private onCompleteCallback?: (responses: Record<string, unknown>, score: number) => void | Promise<void>;
102
+ private sessions: Map<string, SurveySession> = new Map();
103
+
104
+ /**
105
+ * Create a SurveyAgent with the specified questions and callbacks.
106
+ * @param config - Configuration including questions, messages, and completion callback.
107
+ */
108
+ constructor(config: SurveyConfig) {
109
+ const agentName = config.name ?? 'survey';
110
+ super({
111
+ name: agentName,
112
+ route: config.route ?? '/survey',
113
+ usePom: true,
114
+ ...config.agentOptions,
115
+ });
116
+
117
+ // Store configuration (matches Python __init__)
118
+ this.surveyName = config.surveyName;
119
+ this.questions = config.questions;
120
+ this.brandName = config.brandName ?? 'Our Company';
121
+ this.maxRetries = config.maxRetries ?? 2;
122
+ this.introduction =
123
+ config.introduction ?? `Welcome to our ${config.surveyName}. We appreciate your participation.`;
124
+ this.conclusion =
125
+ config.conclusion ?? 'Thank you for completing our survey. Your feedback is valuable to us.';
126
+ this.onCompleteCallback = config.onComplete;
127
+
128
+ // Validate and default questions (mirrors Python _validate_questions)
129
+ this.validateQuestions();
130
+
131
+ this.questionMap = new Map(this.questions.map((q) => [q.id, q]));
132
+
133
+ this.setupSurveyAgent();
134
+
135
+ // Register tools after all fields are initialized
136
+ this.defineTools();
137
+ }
138
+
139
+ // ── Question validation (mirrors Python _validate_questions) ──────────
140
+
141
+ private validateQuestions(): void {
142
+ const validTypes = new Set(['rating', 'multiple_choice', 'yes_no', 'open_ended']);
143
+
144
+ for (let i = 0; i < this.questions.length; i++) {
145
+ const q = this.questions[i];
146
+ if (!q.id) q.id = `question_${i + 1}`;
147
+ if (!q.text) throw new Error(`Question ${i + 1} is missing the 'text' field`);
148
+ if (!q.type || !validTypes.has(q.type)) {
149
+ throw new Error(
150
+ `Question ${i + 1} has an invalid type. Must be one of: ${Array.from(validTypes).join(', ')}`,
151
+ );
152
+ }
153
+ if (q.required === undefined) q.required = true;
154
+ if (q.type === 'multiple_choice' && (!q.options || q.options.length === 0)) {
155
+ throw new Error(`Multiple choice question '${q.id}' must have options`);
156
+ }
157
+ if (q.type === 'rating' && q.scale === undefined) q.scale = 5;
158
+ }
159
+ }
160
+
161
+ // ── Prompt + settings (mirrors Python _setup_survey_agent) ────────────
162
+
163
+ private setupSurveyAgent(): void {
164
+ // Personality
165
+ this.promptAddSection('Personality', {
166
+ body: `You are a friendly and professional survey agent representing ${this.brandName}.`,
167
+ });
168
+
169
+ // Goal
170
+ this.promptAddSection('Goal', {
171
+ body: `Conduct the '${this.surveyName}' survey by asking questions and collecting responses.`,
172
+ });
173
+
174
+ // Instructions
175
+ const instructions = [
176
+ 'Guide the user through each survey question in sequence.',
177
+ 'Ask only one question at a time and wait for a response.',
178
+ 'For rating questions, explain the scale (e.g., 1-5, where 5 is best).',
179
+ 'For multiple choice questions, list all the options.',
180
+ `If a response is invalid, explain and retry up to ${this.maxRetries} times.`,
181
+ 'Be conversational but stay focused on collecting the survey data.',
182
+ 'After all questions are answered, thank the user for their participation.',
183
+ ];
184
+ this.promptAddSection('Instructions', { bullets: instructions });
185
+
186
+ // Introduction
187
+ this.promptAddSection('Introduction', {
188
+ body: `Begin with this introduction: ${this.introduction}`,
189
+ });
190
+
191
+ // Questions subsection
192
+ const questionsSubsections = this.questions.map((q) => {
193
+ let description = `ID: ${q.id}\nType: ${q.type}\nRequired: ${q.required}`;
194
+ if (q.type === 'rating') description += `\nScale: 1-${q.scale}`;
195
+ if (q.type === 'multiple_choice' && q.options) {
196
+ description += `\nOptions: ${q.options.join(', ')}`;
197
+ }
198
+ return { title: q.text, body: description };
199
+ });
200
+ this.promptAddSection('Survey Questions', {
201
+ body: 'Ask these questions in order:',
202
+ subsections: questionsSubsections,
203
+ });
204
+
205
+ // Conclusion
206
+ this.promptAddSection('Conclusion', {
207
+ body: `End with this conclusion: ${this.conclusion}`,
208
+ });
209
+
210
+ // Post-prompt summary template
211
+ this.setPostPrompt(`
212
+ Return a JSON summary of the survey responses:
213
+ {
214
+ "survey_name": "SURVEY_NAME",
215
+ "responses": {
216
+ "QUESTION_ID_1": "RESPONSE_1",
217
+ "QUESTION_ID_2": "RESPONSE_2",
218
+ ...
219
+ },
220
+ "completion_status": "complete/incomplete",
221
+ "timestamp": "CURRENT_TIMESTAMP"
222
+ }
223
+ `);
224
+
225
+ // Hints: rating numbers, MC options, yes/no, plus the names
226
+ const typeTerms: string[] = [];
227
+ for (const q of this.questions) {
228
+ if (q.type === 'rating') {
229
+ const scale = q.scale ?? 5;
230
+ for (let i = 1; i <= scale; i++) typeTerms.push(String(i));
231
+ } else if (q.type === 'multiple_choice' && q.options) {
232
+ typeTerms.push(...q.options);
233
+ } else if (q.type === 'yes_no') {
234
+ typeTerms.push('yes', 'no');
235
+ }
236
+ }
237
+ this.addHints([this.surveyName, this.brandName, ...typeTerms]);
238
+
239
+ // AI behavior parameters (includes non-bargeable static greeting = introduction)
240
+ this.setParams({
241
+ wait_for_user: false,
242
+ end_of_speech_timeout: 1500,
243
+ ai_volume: 5,
244
+ static_greeting: this.introduction,
245
+ static_greeting_no_barge: true,
246
+ });
247
+
248
+ // Global data
249
+ this.setGlobalData({
250
+ survey_name: this.surveyName,
251
+ brand_name: this.brandName,
252
+ questions: this.questions,
253
+ max_retries: this.maxRetries,
254
+ });
255
+
256
+ // Native functions
257
+ this.setNativeFunctions(['check_time']);
258
+ }
259
+
260
+ // ── Session helpers ───────────────────────────────────────────────────
261
+
262
+ private getSession(rawData: Record<string, unknown>): SurveySession {
263
+ const callId = (rawData['call_id'] as string) ?? 'default';
264
+ let session = this.sessions.get(callId);
265
+ if (!session) {
266
+ const firstQuestion = this.questions[0];
267
+ session = {
268
+ currentQuestionIndex: 0,
269
+ currentQuestionId: firstQuestion ? firstQuestion.id : '',
270
+ responses: {},
271
+ score: 0,
272
+ completed: false,
273
+ };
274
+ this.sessions.set(callId, session);
275
+ }
276
+ return session;
277
+ }
278
+
279
+ private resolveNextQuestion(question: SurveyQuestion, answer: string): string | null {
280
+ if (!question.nextQuestion) {
281
+ const idx = this.questions.findIndex((q) => q.id === question.id);
282
+ if (idx >= 0 && idx < this.questions.length - 1) {
283
+ return this.questions[idx + 1].id;
284
+ }
285
+ return null;
286
+ }
287
+
288
+ if (typeof question.nextQuestion === 'string') {
289
+ return question.nextQuestion;
290
+ }
291
+
292
+ const normalizedAnswer = answer.toLowerCase().trim();
293
+ for (const [key, nextId] of Object.entries(question.nextQuestion)) {
294
+ if (key.toLowerCase().trim() === normalizedAnswer) {
295
+ return nextId;
296
+ }
297
+ }
298
+
299
+ if ('_default' in question.nextQuestion) {
300
+ return question.nextQuestion['_default'];
301
+ }
302
+
303
+ const idx = this.questions.findIndex((q) => q.id === question.id);
304
+ if (idx >= 0 && idx < this.questions.length - 1) {
305
+ return this.questions[idx + 1].id;
306
+ }
307
+ return null;
308
+ }
309
+
310
+ private calculatePoints(question: SurveyQuestion, answer: string): number {
311
+ if (question.points === undefined) return 0;
312
+ if (typeof question.points === 'number') return question.points;
313
+
314
+ const normalizedAnswer = answer.toLowerCase().trim();
315
+ for (const [key, pts] of Object.entries(question.points)) {
316
+ if (key.toLowerCase().trim() === normalizedAnswer) {
317
+ return pts;
318
+ }
319
+ }
320
+ return 0;
321
+ }
322
+
323
+ /**
324
+ * Validate an answer against the question's type and constraints.
325
+ * Mirrors the Python `validate_response` tool body.
326
+ * @returns error message string if invalid, or `null` if valid.
327
+ */
328
+ private validateAnswer(question: SurveyQuestion, answer: string): string | null {
329
+ switch (question.type) {
330
+ case 'multiple_choice': {
331
+ if (!question.options || question.options.length === 0) return null;
332
+ const normalized = answer.toLowerCase().trim();
333
+ const match = question.options.find((o) => o.toLowerCase().trim() === normalized);
334
+ if (!match) {
335
+ return `Invalid choice. Please select one of: ${question.options.join(', ')}.`;
336
+ }
337
+ return null;
338
+ }
339
+ case 'rating': {
340
+ const scale = question.scale ?? 5;
341
+ const trimmed = answer.trim();
342
+ const num = parseInt(trimmed, 10);
343
+ if (!/^-?\d+$/.test(trimmed) || isNaN(num) || num < 1 || num > scale) {
344
+ return `Invalid rating. Please provide a number between 1 and ${scale}.`;
345
+ }
346
+ return null;
347
+ }
348
+ case 'yes_no': {
349
+ const normalized = answer.toLowerCase().trim();
350
+ // Python reference accepts only 'yes', 'no', 'y', 'n' (survey.py:260).
351
+ if (!['yes', 'y', 'no', 'n'].includes(normalized)) {
352
+ return "Please answer with 'yes' or 'no'.";
353
+ }
354
+ return null;
355
+ }
356
+ case 'open_ended': {
357
+ // Python: required open_ended with empty response is invalid.
358
+ if (!answer.trim() && question.required !== false) {
359
+ return 'A response is required for this question.';
360
+ }
361
+ return null;
362
+ }
363
+ default:
364
+ return null;
365
+ }
366
+ }
367
+
368
+ private normalizeAnswer(question: SurveyQuestion, answer: string): string {
369
+ if (question.type === 'yes_no') {
370
+ const normalized = answer.toLowerCase().trim();
371
+ // Mirrors validateAnswer's accepted set (Python: 'yes','y','no','n').
372
+ return ['yes', 'y'].includes(normalized) ? 'yes' : 'no';
373
+ }
374
+ return answer;
375
+ }
376
+
377
+ // ── Tool registration ─────────────────────────────────────────────────
378
+
379
+ /**
380
+ * Register SWAIG tools:
381
+ * - Python-parity tools: `validate_response`, `log_response`
382
+ * - TS-specific session tools: `answer_question`, `get_current_question`, `get_survey_progress`
383
+ */
384
+ protected override defineTools(): void {
385
+ // Tool: validate_response (Python parity)
386
+ this.defineTool({
387
+ name: 'validate_response',
388
+ description: 'Validate if a response meets the requirements for a specific question',
389
+ parameters: {
390
+ type: 'object',
391
+ properties: {
392
+ question_id: {
393
+ type: 'string',
394
+ description: 'The ID of the question',
395
+ },
396
+ response: {
397
+ type: 'string',
398
+ description: "The user's response to validate",
399
+ },
400
+ },
401
+ },
402
+ handler: (args: Record<string, unknown>) => {
403
+ const questionId = (args['question_id'] as string) ?? '';
404
+ const response = (args['response'] as string) ?? '';
405
+
406
+ const question = this.questionMap.get(questionId);
407
+ if (!question) {
408
+ return new FunctionResult(`Error: Question with ID '${questionId}' not found.`);
409
+ }
410
+
411
+ const error = this.validateAnswer(question, response);
412
+ if (error) return new FunctionResult(error);
413
+ return new FunctionResult(`Response to '${questionId}' is valid.`);
414
+ },
415
+ });
416
+
417
+ // Tool: log_response (Python parity — acknowledge recording)
418
+ this.defineTool({
419
+ name: 'log_response',
420
+ description: 'Log a validated response to a survey question',
421
+ parameters: {
422
+ type: 'object',
423
+ properties: {
424
+ question_id: {
425
+ type: 'string',
426
+ description: 'The ID of the question',
427
+ },
428
+ response: {
429
+ type: 'string',
430
+ description: "The user's validated response",
431
+ },
432
+ },
433
+ },
434
+ handler: (args: Record<string, unknown>, rawData: Record<string, unknown>) => {
435
+ const questionId = (args['question_id'] as string) ?? '';
436
+ const response = (args['response'] as string) ?? '';
437
+
438
+ const question = this.questionMap.get(questionId);
439
+ const questionText = question ? question.text : '';
440
+
441
+ // Record on the per-call session for observability.
442
+ const session = this.getSession(rawData);
443
+ if (question) {
444
+ session.responses[questionId] = this.normalizeAnswer(question, response);
445
+ }
446
+
447
+ return new FunctionResult(
448
+ `Response to '${questionText}' has been recorded.`,
449
+ );
450
+ },
451
+ });
452
+
453
+ // Tool: answer_question (TS-specific atomic validate+record+advance)
454
+ this.defineTool({
455
+ name: 'answer_question',
456
+ description: "Record the caller's answer to the current survey question. Validates the answer based on question type and advances to the next question.",
457
+ parameters: {
458
+ type: 'object',
459
+ properties: {
460
+ question_id: {
461
+ type: 'string',
462
+ description: 'The ID of the question being answered.',
463
+ },
464
+ answer: {
465
+ type: 'string',
466
+ description: "The caller's answer to the question.",
467
+ },
468
+ },
469
+ required: ['question_id', 'answer'],
470
+ },
471
+ handler: async (args: Record<string, unknown>, rawData: Record<string, unknown>) => {
472
+ const questionId = args['question_id'] as string;
473
+ const answer = args['answer'] as string;
474
+
475
+ if (!questionId || !answer) {
476
+ return new FunctionResult('Both question_id and answer are required.');
477
+ }
478
+
479
+ const question = this.questionMap.get(questionId);
480
+ if (!question) {
481
+ return new FunctionResult(`Unknown question ID "${questionId}".`);
482
+ }
483
+
484
+ const session = this.getSession(rawData);
485
+
486
+ if (session.completed) {
487
+ return new FunctionResult('The survey has already been completed.');
488
+ }
489
+
490
+ const validationError = this.validateAnswer(question, answer);
491
+ if (validationError) {
492
+ return new FunctionResult(validationError);
493
+ }
494
+
495
+ const normalizedAnswer = this.normalizeAnswer(question, answer);
496
+ session.responses[questionId] = normalizedAnswer;
497
+
498
+ const points = this.calculatePoints(question, normalizedAnswer);
499
+ session.score += points;
500
+
501
+ const nextId = this.resolveNextQuestion(question, normalizedAnswer);
502
+
503
+ if (!nextId || !this.questionMap.has(nextId)) {
504
+ session.completed = true;
505
+ if (this.onCompleteCallback) {
506
+ try {
507
+ await this.onCompleteCallback({ ...session.responses }, session.score);
508
+ } catch (err) {
509
+ this.log.error(`onComplete callback error: ${err}`);
510
+ }
511
+ }
512
+ const answeredCount = Object.keys(session.responses).length;
513
+ return new FunctionResult(
514
+ `Answer recorded. The survey is now complete! ${answeredCount} questions answered, total score: ${session.score}. ${this.conclusion}`,
515
+ );
516
+ }
517
+
518
+ session.currentQuestionId = nextId;
519
+ const nextQ = this.questionMap.get(nextId)!;
520
+ const nextIdx = this.questions.findIndex((q) => q.id === nextId);
521
+ if (nextIdx >= 0) session.currentQuestionIndex = nextIdx;
522
+
523
+ let nextInfo = `Answer recorded. Next question [${nextQ.id}]: "${nextQ.text}"`;
524
+ if (nextQ.type === 'multiple_choice' && nextQ.options) {
525
+ nextInfo += ` (Options: ${nextQ.options.join(', ')})`;
526
+ } else if (nextQ.type === 'rating') {
527
+ nextInfo += ` (Rating: 1-${nextQ.scale ?? 5})`;
528
+ } else if (nextQ.type === 'yes_no') {
529
+ nextInfo += ' (Yes/No)';
530
+ }
531
+
532
+ return new FunctionResult(nextInfo);
533
+ },
534
+ });
535
+
536
+ // Tool: get_current_question
537
+ this.defineTool({
538
+ name: 'get_current_question',
539
+ description: 'Get the current question that should be asked to the caller.',
540
+ parameters: {
541
+ type: 'object',
542
+ properties: {},
543
+ },
544
+ handler: (_args: Record<string, unknown>, rawData: Record<string, unknown>) => {
545
+ const session = this.getSession(rawData);
546
+
547
+ if (session.completed) {
548
+ return new FunctionResult('The survey has been completed. No more questions.');
549
+ }
550
+
551
+ const question = this.questionMap.get(session.currentQuestionId);
552
+ if (!question) {
553
+ return new FunctionResult('No current question available.');
554
+ }
555
+
556
+ let info = `Current question [${question.id}] (${question.type}): "${question.text}"`;
557
+ if (question.type === 'multiple_choice' && question.options) {
558
+ info += ` Options: ${question.options.join(', ')}`;
559
+ } else if (question.type === 'rating') {
560
+ info += ` (Caller should provide a rating from 1 to ${question.scale ?? 5})`;
561
+ } else if (question.type === 'yes_no') {
562
+ info += ' (Caller should answer yes or no)';
563
+ }
564
+
565
+ return new FunctionResult(info);
566
+ },
567
+ });
568
+
569
+ // Tool: get_survey_progress
570
+ this.defineTool({
571
+ name: 'get_survey_progress',
572
+ description: 'Get the current progress of the survey, including how many questions have been answered and the current score.',
573
+ parameters: {
574
+ type: 'object',
575
+ properties: {},
576
+ },
577
+ handler: (_args: Record<string, unknown>, rawData: Record<string, unknown>) => {
578
+ const session = this.getSession(rawData);
579
+ const answeredCount = Object.keys(session.responses).length;
580
+ const totalCount = this.questions.length;
581
+ const percentage = totalCount > 0 ? Math.round((answeredCount / totalCount) * 100) : 0;
582
+
583
+ let progress = `Survey progress: ${answeredCount}/${totalCount} questions answered (${percentage}%). Current score: ${session.score}.`;
584
+
585
+ if (session.completed) {
586
+ progress += ' Survey is COMPLETE.';
587
+ } else {
588
+ progress += ` Current question: ${session.currentQuestionId}.`;
589
+ }
590
+
591
+ if (answeredCount > 0) {
592
+ const answered = Object.entries(session.responses)
593
+ .map(([qId, ans]) => `${qId}: ${ans}`)
594
+ .join('; ');
595
+ progress += ` Answers so far: ${answered}`;
596
+ }
597
+
598
+ return new FunctionResult(progress);
599
+ },
600
+ });
601
+ }
602
+
603
+ // ── Lifecycle hooks ───────────────────────────────────────────────────
604
+
605
+ /**
606
+ * Process the survey results summary returned at the end of a call.
607
+ * Mirrors Python `on_summary`: structured (dict-like) summaries are logged
608
+ * as JSON; unstructured summaries are logged verbatim.
609
+ *
610
+ * The parameter type widens the base `AgentBase.onSummary` signature to
611
+ * accept string payloads as well, matching Python's `isinstance(summary, dict)`
612
+ * branch even though the current framework only surfaces object summaries.
613
+ */
614
+ override onSummary(
615
+ summary: Record<string, unknown> | string | null,
616
+ _rawData: Record<string, unknown>,
617
+ ): void | Promise<void> {
618
+ if (summary) {
619
+ try {
620
+ if (typeof summary === 'string') {
621
+ // eslint-disable-next-line no-console
622
+ console.log(`Survey summary (unstructured): ${summary}`);
623
+ } else {
624
+ // eslint-disable-next-line no-console
625
+ console.log(`Survey completed: ${JSON.stringify(summary, null, 2)}`);
626
+ }
627
+ } catch (err) {
628
+ // eslint-disable-next-line no-console
629
+ console.log(`Error processing survey summary: ${String(err)}`);
630
+ }
631
+ }
632
+ }
633
+ }
634
+
635
+ // ── Factory function ────────────────────────────────────────────────────────
636
+
637
+ /**
638
+ * Factory function that creates and returns a new SurveyAgent.
639
+ * @param config - Configuration for the survey agent.
640
+ * @returns A configured SurveyAgent instance.
641
+ */
642
+ export function createSurveyAgent(config: SurveyConfig): SurveyAgent {
643
+ return new SurveyAgent(config);
644
+ }
645
+
646
+ export default SurveyAgent;
@@ -0,0 +1,27 @@
1
+ /**
2
+ * Prefab agents - Ready-to-use agent implementations built on AgentBase.
3
+ */
4
+
5
+ // InfoGathererAgent
6
+ export { InfoGathererAgent, createInfoGathererAgent } from './InfoGathererAgent.js';
7
+ export type {
8
+ InfoGathererConfig,
9
+ InfoGathererQuestion,
10
+ InfoGathererQuestionCallback,
11
+ } from './InfoGathererAgent.js';
12
+
13
+ // SurveyAgent
14
+ export { SurveyAgent, createSurveyAgent } from './SurveyAgent.js';
15
+ export type { SurveyConfig, SurveyQuestion } from './SurveyAgent.js';
16
+
17
+ // FAQBotAgent
18
+ export { FAQBotAgent, createFAQBotAgent } from './FAQBotAgent.js';
19
+ export type { FAQBotConfig, FAQEntry } from './FAQBotAgent.js';
20
+
21
+ // ConciergeAgent
22
+ export { ConciergeAgent, createConciergeAgent } from './ConciergeAgent.js';
23
+ export type { ConciergeConfig } from './ConciergeAgent.js';
24
+
25
+ // ReceptionistAgent
26
+ export { ReceptionistAgent, createReceptionistAgent } from './ReceptionistAgent.js';
27
+ export type { ReceptionistConfig, ReceptionistDepartment } from './ReceptionistAgent.js';