@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,248 @@
1
+ /**
2
+ * Weather API Skill - Fetches current weather data from OpenWeatherMap.
3
+ *
4
+ * Tier 2 built-in skill: requires WEATHER_API_KEY environment variable.
5
+ * Uses the OpenWeatherMap API to retrieve current weather conditions
6
+ * for a specified location.
7
+ */
8
+
9
+ import { SkillBase } from '../SkillBase.js';
10
+ import type {
11
+ SkillToolDefinition,
12
+ SkillPromptSection,
13
+ SkillConfig,
14
+ ParameterSchemaEntry,
15
+ } from '../SkillBase.js';
16
+ import { FunctionResult } from '../../FunctionResult.js';
17
+ import { MAX_SKILL_INPUT_LENGTH } from '../../SecurityUtils.js';
18
+ import { getLogger } from '../../Logger.js';
19
+
20
+ const log = getLogger('WeatherApiSkill');
21
+
22
+ /** Response shape from the OpenWeatherMap current weather endpoint. */
23
+ interface WeatherApiResponse {
24
+ name: string;
25
+ sys: { country: string };
26
+ main: {
27
+ temp: number;
28
+ feels_like: number;
29
+ humidity: number;
30
+ pressure: number;
31
+ temp_min: number;
32
+ temp_max: number;
33
+ };
34
+ weather: Array<{ main: string; description: string }>;
35
+ wind: { speed: number; deg: number };
36
+ visibility?: number;
37
+ clouds?: { all: number };
38
+ cod: number;
39
+ message?: string;
40
+ }
41
+
42
+ /**
43
+ * Fetches current weather data from OpenWeatherMap for any location worldwide.
44
+ *
45
+ * Tier 2 built-in skill. Requires the `WEATHER_API_KEY` environment variable
46
+ * containing a valid OpenWeatherMap API key (obtainable at openweathermap.org).
47
+ * Supports metric, imperial, and standard temperature units via the `units`
48
+ * config option. The `api_key` config value takes precedence over the
49
+ * environment variable when both are set.
50
+ *
51
+ * **Provider note:** The Python reference SDK uses WeatherAPI.com
52
+ * (`api.weatherapi.com/v1/current.json`). This TypeScript skill uses
53
+ * OpenWeatherMap (`api.openweathermap.org/data/2.5/weather`). These providers
54
+ * use different API key formats — a WeatherAPI.com key will NOT work here.
55
+ * Obtain an OpenWeatherMap key at https://openweathermap.org/api.
56
+ *
57
+ * **Unit aliases:** For migration compatibility with the Python SDK the `units`
58
+ * config also accepts `"fahrenheit"` (normalized to `"imperial"`) and
59
+ * `"celsius"` (normalized to `"metric"`).
60
+ */
61
+ export class WeatherApiSkill extends SkillBase {
62
+ // Python ground truth: skills/weather_api/skill.py
63
+ // TS declares env var as required historically; Python declares [] explicitly.
64
+ // Preserving TS behavior — full Python parity is out-of-scope for this PR.
65
+ static override SKILL_NAME = 'weather_api';
66
+ static override SKILL_DESCRIPTION = 'Get current weather information from WeatherAPI.com';
67
+ static override REQUIRED_ENV_VARS: readonly string[] = ['WEATHER_API_KEY'];
68
+ static override SUPPORTS_MULTIPLE_INSTANCES = false;
69
+
70
+ /**
71
+ * Validates that an API key is available either via inline config or the
72
+ * `WEATHER_API_KEY` environment variable. Fails fast (returns `false`) when
73
+ * neither source provides a key — matching Python SDK behaviour where
74
+ * `_validate_config()` raises on construction when `api_key` is absent.
75
+ * @returns `true` if a key is present, `false` otherwise.
76
+ */
77
+ override async setup(): Promise<boolean> {
78
+ const key = this.getConfig<string>('api_key') ?? process.env['WEATHER_API_KEY'];
79
+ if (!key) {
80
+ log.error('WeatherApiSkill: api_key is required. Set the WEATHER_API_KEY environment variable or pass api_key in skill config.');
81
+ return false;
82
+ }
83
+ return true;
84
+ }
85
+
86
+ static override getParameterSchema(): Record<string, ParameterSchemaEntry> {
87
+ return {
88
+ ...super.getParameterSchema(),
89
+ api_key: {
90
+ type: 'string',
91
+ description: 'OpenWeatherMap API key.',
92
+ hidden: true,
93
+ env_var: 'WEATHER_API_KEY',
94
+ required: true,
95
+ },
96
+ tool_name: {
97
+ type: 'string',
98
+ description: 'Custom name for the generated weather tool.',
99
+ default: 'get_weather',
100
+ },
101
+ units: {
102
+ type: 'string',
103
+ description:
104
+ 'Temperature units. Preferred values: "metric" (Celsius), "imperial" (Fahrenheit), "standard" (Kelvin). ' +
105
+ 'Python SDK aliases also accepted: "celsius" → "metric", "fahrenheit" → "imperial". ' +
106
+ 'Default matches Python (`temperature_unit: "fahrenheit"` → `"imperial"`).',
107
+ default: 'fahrenheit',
108
+ enum: ['metric', 'imperial', 'standard', 'celsius', 'fahrenheit'],
109
+ },
110
+ };
111
+ }
112
+
113
+ /** @returns A single weather tool (configurable name) that fetches current weather for a location. */
114
+ getTools(): SkillToolDefinition[] {
115
+ // Normalize Python SDK unit aliases to OpenWeatherMap unit names.
116
+ const rawUnits = this.getConfig<string>('units', 'metric');
117
+ const units =
118
+ rawUnits === 'fahrenheit' ? 'imperial' :
119
+ rawUnits === 'celsius' ? 'metric' :
120
+ rawUnits;
121
+ const toolName = this.getConfig<string>('tool_name', 'get_weather');
122
+
123
+ return [
124
+ {
125
+ name: toolName,
126
+ description:
127
+ 'Get the current weather conditions for a specified location. Returns temperature, humidity, wind speed, and weather description.',
128
+ parameters: {
129
+ location: {
130
+ type: 'string',
131
+ description:
132
+ 'The city name, optionally with country code (e.g., "London", "Paris,FR", "New York,US").',
133
+ },
134
+ },
135
+ required: ['location'],
136
+ handler: async (args: Record<string, unknown>) => {
137
+ const location = args.location as string | undefined;
138
+
139
+ if (!location || typeof location !== 'string' || location.trim().length === 0) {
140
+ return new FunctionResult(
141
+ 'Please provide a location to get the weather for.',
142
+ );
143
+ }
144
+
145
+ if (location.length > MAX_SKILL_INPUT_LENGTH) {
146
+ return new FunctionResult('Input is too long.');
147
+ }
148
+
149
+ const apiKey = this.getConfig<string>('api_key') ?? process.env['WEATHER_API_KEY'];
150
+ if (!apiKey) {
151
+ return new FunctionResult(
152
+ 'Service is not configured. Please contact your administrator.',
153
+ );
154
+ }
155
+
156
+ try {
157
+ const encodedLocation = encodeURIComponent(location.trim());
158
+ const url = `https://api.openweathermap.org/data/2.5/weather?q=${encodedLocation}&appid=${apiKey}&units=${units}`;
159
+
160
+ const controller = new AbortController();
161
+ const timeout = setTimeout(() => controller.abort(), 30_000);
162
+ let response: Response;
163
+ try {
164
+ response = await fetch(url, { signal: controller.signal });
165
+ } finally {
166
+ clearTimeout(timeout);
167
+ }
168
+ const data = (await response.json()) as WeatherApiResponse;
169
+
170
+ if (!response.ok || data.cod !== 200) {
171
+ log.error('weather_api_error', { status: response.status });
172
+ return new FunctionResult(
173
+ `Could not retrieve weather for "${location}". Please check the location name and try again.`,
174
+ );
175
+ }
176
+
177
+ const unitLabel = units === 'imperial' ? 'F' : units === 'standard' ? 'K' : 'C';
178
+ const speedUnit = units === 'imperial' ? 'mph' : 'm/s';
179
+
180
+ const weatherDesc =
181
+ data.weather.length > 0
182
+ ? data.weather.map((w) => w.description).join(', ')
183
+ : 'unknown';
184
+
185
+ const parts: string[] = [
186
+ `Weather for ${data.name}, ${data.sys.country}:`,
187
+ `Conditions: ${weatherDesc}.`,
188
+ `Temperature: ${data.main.temp}\u00B0${unitLabel} (feels like ${data.main.feels_like}\u00B0${unitLabel}).`,
189
+ `High: ${data.main.temp_max}\u00B0${unitLabel}, Low: ${data.main.temp_min}\u00B0${unitLabel}.`,
190
+ `Humidity: ${data.main.humidity}%.`,
191
+ `Wind: ${data.wind.speed} ${speedUnit}.`,
192
+ `Pressure: ${data.main.pressure} hPa.`,
193
+ ];
194
+
195
+ if (data.visibility !== undefined) {
196
+ const visKm = (data.visibility / 1000).toFixed(1);
197
+ parts.push(`Visibility: ${visKm} km.`);
198
+ }
199
+
200
+ if (data.clouds?.all !== undefined) {
201
+ parts.push(`Cloud cover: ${data.clouds.all}%.`);
202
+ }
203
+
204
+ return new FunctionResult(parts.join(' '));
205
+ } catch (err) {
206
+ log.error('get_weather_failed', { error: err instanceof Error ? err.message : String(err) });
207
+ return new FunctionResult(
208
+ 'The request could not be completed. Please try again.',
209
+ );
210
+ }
211
+ },
212
+ },
213
+ ];
214
+ }
215
+
216
+ protected override _getPromptSections(): SkillPromptSection[] {
217
+ const units = this.getConfig<string>('units', 'metric');
218
+ const unitDesc =
219
+ units === 'imperial'
220
+ ? 'Fahrenheit'
221
+ : units === 'standard'
222
+ ? 'Kelvin'
223
+ : 'Celsius';
224
+
225
+ return [
226
+ {
227
+ title: 'Weather Information',
228
+ body: 'You can look up current weather conditions for any location worldwide.',
229
+ bullets: [
230
+ 'Use the get_weather tool when a user asks about current weather conditions.',
231
+ 'You can specify a city name, optionally with a country code (e.g., "London", "Paris,FR").',
232
+ `Temperature is reported in ${unitDesc}.`,
233
+ 'The weather data includes temperature, humidity, wind speed, pressure, and general conditions.',
234
+ 'If the user asks about a forecast or future weather, let them know you can only provide current conditions.',
235
+ ],
236
+ },
237
+ ];
238
+ }
239
+ }
240
+
241
+ /**
242
+ * Factory function for creating WeatherApiSkill instances.
243
+ * @param config - Optional skill configuration.
244
+ * @returns A new WeatherApiSkill instance.
245
+ */
246
+ export function createSkill(config?: SkillConfig): WeatherApiSkill {
247
+ return new WeatherApiSkill(config);
248
+ }