@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,239 @@
1
+ # LLM Parameters Guide
2
+
3
+ This guide explains how to customize Language Model (LLM) parameters in SignalWire AI Agents to fine-tune the AI's behavior for your specific use case.
4
+
5
+ ## Overview
6
+
7
+ SignalWire AI Agents SDK provides methods to customize LLM parameters for both the main prompt and post-prompt, allowing precise control over the AI's response characteristics.
8
+
9
+ **Important:** The SDK passes parameters through to the SignalWire server without validation. Model-specific parameters are validated and handled by the server based on the target model's capabilities and requirements. Invalid parameters for the selected model will be handled or ignored by the server.
10
+
11
+ ## Available Methods
12
+
13
+ ### set_prompt_llm_params(**params)
14
+
15
+ Sets LLM parameters for the main agent prompt. Accepts any parameters that will be passed to the server.
16
+
17
+ ```python
18
+ agent.set_prompt_llm_params(
19
+ temperature=0.7,
20
+ top_p=0.9,
21
+ barge_confidence=0.6,
22
+ presence_penalty=0.0,
23
+ frequency_penalty=0.0
24
+ )
25
+ ```
26
+
27
+ ### set_post_prompt_llm_params(**params)
28
+
29
+ Sets LLM parameters for the post-prompt (conversation summary). Accepts any parameters that will be passed to the server.
30
+
31
+ ```python
32
+ agent.set_post_prompt_llm_params(
33
+ temperature=0.3,
34
+ top_p=0.95,
35
+ presence_penalty=0.0,
36
+ frequency_penalty=0.0
37
+ )
38
+ ```
39
+
40
+ Note: barge_confidence is not applicable to post-prompt as interruption doesn't apply to summaries.
41
+
42
+ ## Common Parameter Descriptions
43
+
44
+ These are commonly used parameters, but any parameter accepted by your model can be used. The actual ranges and defaults are model-specific and handled by the server.
45
+
46
+ ### temperature
47
+ Controls the randomness of the AI's responses.
48
+ - **Lower values (e.g., 0.0-0.3)**: More deterministic, focused, and consistent responses
49
+ - **Medium values (e.g., 0.4-0.7)**: Balanced creativity and consistency
50
+ - **Higher values (e.g., 0.8+)**: More creative, diverse, and unpredictable responses
51
+
52
+ ### top_p
53
+ Nucleus sampling parameter that controls the cumulative probability of token selection.
54
+ - **Lower values (e.g., 0.1-0.5)**: Only considers the most likely tokens
55
+ - **Medium values (e.g., 0.6-0.9)**: Balanced token selection
56
+ - **Higher values (e.g., 0.95-1.0)**: Considers a wider range of tokens
57
+
58
+ ### barge_confidence
59
+ ASR (Automatic Speech Recognition) confidence threshold to interrupt the AI while it's speaking (main prompt only).
60
+ - **Lower values (e.g., 0.0-0.4)**: Easier to interrupt, more sensitive to user speech
61
+ - **Medium values (e.g., 0.5-0.7)**: Balanced interruption sensitivity
62
+ - **Higher values (e.g., 0.8-1.0)**: Harder to interrupt, requires clear user speech
63
+
64
+ ### presence_penalty
65
+ Topic diversity control. Penalizes tokens based on whether they appear in the conversation so far.
66
+ - **Negative values**: Encourages repetition of topics
67
+ - **Zero**: No penalty
68
+ - **Positive values**: Discourages repetition, encourages new topics
69
+
70
+ ### frequency_penalty
71
+ Repetition control. Penalizes tokens based on their frequency in the conversation.
72
+ - **Negative values**: Encourages repetition of specific words
73
+ - **Zero**: No penalty
74
+ - **Positive values**: Discourages word repetition, encourages vocabulary variety
75
+
76
+ **Note:** No default values are sent unless explicitly set using the methods above. The server will apply model-appropriate defaults if parameters are not specified.
77
+
78
+ ## Use Case Examples
79
+
80
+ ### Customer Service Agent
81
+ ```python
82
+ class CustomerServiceAgent(AgentBase):
83
+ def __init__(self):
84
+ super().__init__(name="customer-service", route="/support")
85
+
86
+ self.prompt_add_section("Role", "You are a professional customer service representative.")
87
+
88
+ # Consistent, helpful responses
89
+ self.set_prompt_llm_params(
90
+ temperature=0.3, # Low randomness for consistency
91
+ top_p=0.9, # Focused token selection
92
+ barge_confidence=0.6, # Moderate interruption threshold (default 0.0 is too easy)
93
+ presence_penalty=0.1, # Slight penalty to avoid repetition
94
+ frequency_penalty=0.1 # Encourage varied language
95
+ )
96
+ ```
97
+
98
+ ### Creative Writing Assistant
99
+ ```python
100
+ class CreativeWritingAgent(AgentBase):
101
+ def __init__(self):
102
+ super().__init__(name="creative-writer", route="/writer")
103
+
104
+ self.prompt_add_section("Role", "You are a creative writing assistant.")
105
+
106
+ # Creative, diverse responses
107
+ self.set_prompt_llm_params(
108
+ temperature=0.8, # High randomness for creativity
109
+ top_p=0.95, # Wide token selection
110
+ barge_confidence=0.3, # Easy to interrupt for collaboration (but not default 0.0)
111
+ presence_penalty=-0.1, # Allow topic revisiting
112
+ frequency_penalty=0.3 # Encourage vocabulary diversity
113
+ )
114
+ ```
115
+
116
+ ### Technical Documentation Bot
117
+ ```python
118
+ class TechnicalDocsAgent(AgentBase):
119
+ def __init__(self):
120
+ super().__init__(name="tech-docs", route="/docs")
121
+
122
+ self.prompt_add_section("Role", "You are a technical documentation assistant.")
123
+
124
+ # Precise, accurate responses
125
+ self.set_prompt_llm_params(
126
+ temperature=0.2, # Very low randomness
127
+ top_p=0.8, # More focused token selection
128
+ barge_confidence=0.8, # Hard to interrupt - let it finish
129
+ presence_penalty=0.0, # Neutral on repetition
130
+ frequency_penalty=0.2 # Some vocabulary variety
131
+ )
132
+
133
+ # Even more focused for summaries
134
+ self.set_post_prompt_llm_params(
135
+ temperature=0.1 # Extremely consistent
136
+ )
137
+ ```
138
+
139
+ ### Legal Advisor Bot
140
+ ```python
141
+ class LegalAdvisorAgent(AgentBase):
142
+ def __init__(self):
143
+ super().__init__(name="legal-advisor", route="/legal")
144
+
145
+ self.prompt_add_section("Role", "You are a legal information assistant.")
146
+ self.prompt_add_section("Disclaimer", "Always remind users to consult a real attorney.")
147
+
148
+ # Cautious, precise responses
149
+ self.set_prompt_llm_params(
150
+ temperature=0.2, # Very consistent
151
+ top_p=0.85, # Focused selection
152
+ barge_confidence=0.9, # Very hard to interrupt - legal accuracy important
153
+ presence_penalty=0.0, # Allow legal term repetition
154
+ frequency_penalty=0.0 # Legal language often repeats
155
+ )
156
+ ```
157
+
158
+ ## Best Practices
159
+
160
+ ### 1. Start with Defaults
161
+ Begin with the default values and adjust based on observed behavior.
162
+
163
+ ### 2. Test Incrementally
164
+ Make small adjustments and test thoroughly to understand the impact.
165
+
166
+ ### 3. Consider the Use Case
167
+ - **Customer Service**: Low temperature (0.2-0.4), moderate barge_confidence (0.6-0.7)
168
+ - **Creative Tasks**: Higher temperature (0.7-0.9), low barge_confidence (0.4-0.6)
169
+ - **Technical/Legal**: Very low temperature (0.1-0.3), high barge_confidence (0.8-0.9)
170
+ - **General Assistant**: Medium temperature (0.5-0.7), medium barge_confidence (0.6-0.7)
171
+
172
+ ### 4. Match Post-Prompt Parameters
173
+ Post-prompt parameters should typically be lower temperature than main prompt for consistent summaries.
174
+
175
+ ### 5. Monitor Barge Confidence Levels
176
+ - Too high: Users have difficulty interrupting the AI
177
+ - Too low: AI gets interrupted too easily by background noise
178
+
179
+ ## Parameter Interactions
180
+
181
+ ### Temperature + Top-p
182
+ These parameters work together to control randomness:
183
+ - Low temperature + Low top_p = Very focused responses
184
+ - High temperature + High top_p = Maximum creativity
185
+ - Low temperature + High top_p = Consistent but with fallback options
186
+ - High temperature + Low top_p = Creative within constraints
187
+
188
+ ### Penalty Parameters
189
+ Presence and frequency penalties can be used together:
190
+ - Both positive: Strong encouragement for variety
191
+ - Both negative: Strong encouragement for repetition
192
+ - Mixed: Fine-tuned control over specific repetition patterns
193
+
194
+ ## Troubleshooting
195
+
196
+ ### AI is too repetitive
197
+ - Increase `presence_penalty` (try 0.3-0.6)
198
+ - Increase `frequency_penalty` (try 0.3-0.6)
199
+ - Slightly increase `temperature`
200
+
201
+ ### AI is too random/inconsistent
202
+ - Decrease `temperature` (try 0.2-0.4)
203
+ - Decrease `top_p` (try 0.7-0.85)
204
+
205
+ ### AI gets interrupted too easily
206
+ - Increase `barge_confidence` threshold
207
+ - Check for background noise in the environment
208
+ - Consider the user's speaking clarity
209
+
210
+ ### Users can't interrupt the AI
211
+ - Decrease `barge_confidence` threshold
212
+ - Train users to speak more clearly when interrupting
213
+ - Consider the use case (e.g., legal/medical may need higher thresholds)
214
+
215
+ ## Parameter Behavior
216
+
217
+ **No Default Values:** The SDK does not send any LLM parameters unless explicitly set using `set_prompt_llm_params()` or `set_post_prompt_llm_params()`. When parameters are not specified, the SignalWire server will apply appropriate defaults based on the model being used.
218
+
219
+ **Server-Side Validation:** All parameter validation is handled by the SignalWire server. The SDK accepts any parameters and passes them through without modification. This allows:
220
+ - Use of model-specific parameters without SDK updates
221
+ - Forward compatibility with new models and parameters
222
+ - Server-side optimization based on model capabilities
223
+
224
+ **Partial Configuration:** You can set only the parameters you want to customize. For example:
225
+ ```python
226
+ # Only set temperature, let server handle other parameters
227
+ agent.set_prompt_llm_params(temperature=0.7)
228
+
229
+ # Or set multiple specific parameters
230
+ agent.set_prompt_llm_params(
231
+ temperature=0.5,
232
+ barge_confidence=0.6
233
+ )
234
+ ```
235
+
236
+ ## Examples
237
+
238
+ - `examples/llm_params_demo.py` - Three agent personas (customer service, creative, technical) demonstrating different LLM parameter configurations
239
+ - `examples/simple_agent.py` - Basic LLM parameter tuning with `set_prompt_llm_params()`