@sprucelabs/sprucebot-llm 15.1.8 → 15.1.9

package/README.md

@@ -16,6 +16,7 @@ A TypeScript library for leveraging large language models to do... anything!
 * Unlimited use cases
     * Skill architecture for extensibility
     * Leverage Skills to get your bot to complete any task!
+    * [Swap skills mid-conversation](#swapping-skills) to chain multi-step flows
 * Multiple adapter support
     * [OpenAI](#openai-adapter-configuration) - GPT-4o, o1, and other OpenAI models
     * [Anthropic](#anthropic-adapter) - Claude models with prompt caching support
@@ -467,6 +468,127 @@ const bookingBot = bots.Bot({
 
 If you are using reasoning models that accept `reasoning_effort`, you can set it via `OPENAI_REASONING_EFFORT` or `adapter.setReasoningEffort(...)`.
 
+## Swapping Skills
+
+You can replace the active skill on a bot at any time — even mid-conversation — by calling `bot.setSkill(newSkill)`. This is useful for multi-step flows where each phase of the conversation has a different job, state schema, or set of callbacks.
+
+```ts
+const greetingSkill = bots.Skill({
+    yourJobIfYouChooseToAcceptItIs: 'to greet the user and ask for their name',
+    weAreDoneWhen: 'you have collected the user\'s name',
+    stateSchema: buildSchema({
+        id: 'greeting',
+        fields: {
+            firstName: { type: 'text', label: 'First name' },
+        },
+    }),
+})
+
+const bookingSkill = bots.Skill({
+    yourJobIfYouChooseToAcceptItIs: 'to book an appointment for the user',
+    weAreDoneWhen: 'the appointment is booked',
+    callbacks: {
+        book: {
+            cb: async (options) => {
+                await bookAppointment(options)
+                return 'Appointment booked!'
+            },
+            useThisWhenever: 'you are ready to book the appointment',
+        },
+    },
+})
+
+const bot = bots.Bot({
+    youAre: 'a helpful scheduling assistant',
+    skill: greetingSkill,
+})
+
+// Listen for the greeting phase to complete, then swap to booking
+await greetingSkill.on('did-update-state', async () => {
+    if (greetingSkill.getState()?.firstName) {
+        bot.setSkill(bookingSkill)
+    }
+})
+```
+
+### Pre-populating state before swapping
+
+Skills manage their own state independently of the bot. You can create a skill, set its initial state, and then hand it to the bot — useful when you already know some context going into the next phase:
+
+```ts
+const bookingSkill = bots.Skill({
+    yourJobIfYouChooseToAcceptItIs: 'to book an appointment',
+    weAreDoneWhen: 'the appointment is booked',
+    stateSchema: buildSchema({
+        id: 'booking',
+        fields: {
+            guestName: { type: 'text', label: 'Guest name' },
+            time: { type: 'text', label: 'Appointment time' },
+        },
+    }),
+})
+
+// Pre-load state from the previous phase before the bot ever uses this skill
+await bookingSkill.updateState({
+    guestName: greetingSkill.getState()?.firstName,
+})
+
+// Now swap — the LLM will already know guestName when it starts
+bot.setSkill(bookingSkill)
+```
+
+You can also read and update a skill's state at any point, regardless of whether it's active:
+
+```ts
+// Check what the skill has collected so far
+console.log(bookingSkill.getState())
+// { guestName: 'Taylor', time: undefined }
+
+// Inject external data directly (e.g. from your own API)
+await bookingSkill.updateState({ time: '10am' })
+```
+
+`updateState` merges — it only overwrites the fields you pass, leaving others intact. And since skills are plain objects, you can maintain references to them alongside the bot and keep them in sync independently.
+
+### Key behaviors when swapping skills
+
+**`getIsDone()` resets to `false`** — swapping in a new skill always marks the bot as not done, so the conversation continues even if the previous skill had completed:
+
+```ts
+bot.markAsDone()
+console.log(bot.getIsDone()) // true
+
+bot.setSkill(bookingSkill)
+console.log(bot.getIsDone()) // false — ready for the next phase
+```
+
+**Message history is preserved** — the full conversation history carries over. Only the active skill (its instructions, state schema, callbacks, and model) changes:
+
+```ts
+// Before swap: greeting skill active
+await bot.sendMessage('Hi there!')
+
+// Swap to a new skill mid-conversation
+bot.setSkill(bookingSkill)
+
+// After swap: booking skill active, but previous messages still in history
+await bot.sendMessage('I\'d like to book for Tuesday')
+```
+
+**The new skill's state replaces the old one** — after a swap, `bot.serialize().skill` reflects the new skill's full configuration:
+
+```ts
+const skill2 = bots.Skill({
+    stateSchema: carSchema,
+    yourJobIfYouChooseToAcceptItIs: 'to help the user pick a car',
+})
+
+bot.setSkill(skill2)
+
+// bot.serialize().skill now reflects skill2's schema and state
+console.log(bot.serialize().skill)
+```
+
 ## Serialization and Persistence
 
 You can snapshot a bot's full state — including message history, skill configuration, and any accumulated state — and later restore it. This is useful for persisting conversations across process restarts, saving/loading sessions, or transferring bot state.

package/build/esm/parsingResponses/ResponseParserV2.js

@@ -100,9 +100,31 @@ export default class ResponseParserV2 {
         return `@results ${JSON.stringify(callbackOptions)}\n`;
     }
     getStateUpdateInstructions() {
-        return 'Updating state works similar to all function calls. Use the following syntax:\n@updateState { "updates": "here" }\n. Make sure to json encode only the fields you want to change. You can update state once and do it at the end of any messages you send. IMPORTANT: JSON must be on a single line. Do NOT use multi-line or formatted JSON.';
+        return `Updating state works similar to all function calls. Use the following syntax:
+@updateState { "field1": "value1", "field2": "value2" }
+Make sure to json encode only the fields you want to change. You can update state once and do it at the end of any messages you send. IMPORTANT: JSON must be on a single line. Do NOT use multi-line or formatted JSON.
+Good example:
+@updateState { "favoriteColor": "blue", "firstName": "Taylor" }
+Bad examples:
+@updateState
+{ "favoriteColor": "blue" }
+@updateState {
+  "favoriteColor": "blue"
+}
+@updateState { favoriteColor: "blue" }`;
     }
     getFunctionCallInstructions() {
-        return `A function call is done using the following syntax:\n@callback { "name": "callbackName", "options": {} }\nMake sure to json encode the options and include the name of the callback you want to call. You can call as many callbacks as you want in a single response by including multiple @callback lines. IMPORTANT: JSON must be on a single line. Do NOT use multi-line or formatted JSON. Also, do NOT call something like @myCallback. You would call it like this: @callback { "name": "myCallback", "options": {} }`;
+        return `A function call is done using the following syntax:
+@callback { "name": "callbackName", "options": {} }
+Make sure to json encode the options and include the name of the callback you want to call. You can call as many callbacks as you want in a single response by including multiple @callback lines. IMPORTANT: JSON must be on a single line. Do NOT use multi-line or formatted JSON. Also, do NOT call something like @myCallback. You would call it like this: @callback { "name": "myCallback", "options": {} }
+Good example:
+@callback { "name": "lookupWeather", "options": { "zip": "80524" } }
+Bad examples:
+@lookupWeather { "zip": "80524" }
+@callback
+{ "name": "lookupWeather", "options": { "zip": "80524" } }
+@callback { "name": "lookupWeather", "options": {
+  "zip": "80524"
+} }`;
     }
 }

package/build/parsingResponses/ResponseParserV2.js

@@ -92,10 +92,32 @@ class ResponseParserV2 {
         return `@results ${JSON.stringify(callbackOptions)}\n`;
     }
     getStateUpdateInstructions() {
-        return 'Updating state works similar to all function calls. Use the following syntax:\n@updateState { "updates": "here" }\n. Make sure to json encode only the fields you want to change. You can update state once and do it at the end of any messages you send. IMPORTANT: JSON must be on a single line. Do NOT use multi-line or formatted JSON.';
+        return `Updating state works similar to all function calls. Use the following syntax:
+@updateState { "field1": "value1", "field2": "value2" }
+Make sure to json encode only the fields you want to change. You can update state once and do it at the end of any messages you send. IMPORTANT: JSON must be on a single line. Do NOT use multi-line or formatted JSON.
+Good example:
+@updateState { "favoriteColor": "blue", "firstName": "Taylor" }
+Bad examples:
+@updateState
+{ "favoriteColor": "blue" }
+@updateState {
+  "favoriteColor": "blue"
+}
+@updateState { favoriteColor: "blue" }`;
     }
     getFunctionCallInstructions() {
-        return `A function call is done using the following syntax:\n@callback { "name": "callbackName", "options": {} }\nMake sure to json encode the options and include the name of the callback you want to call. You can call as many callbacks as you want in a single response by including multiple @callback lines. IMPORTANT: JSON must be on a single line. Do NOT use multi-line or formatted JSON. Also, do NOT call something like @myCallback. You would call it like this: @callback { "name": "myCallback", "options": {} }`;
+        return `A function call is done using the following syntax:
+@callback { "name": "callbackName", "options": {} }
+Make sure to json encode the options and include the name of the callback you want to call. You can call as many callbacks as you want in a single response by including multiple @callback lines. IMPORTANT: JSON must be on a single line. Do NOT use multi-line or formatted JSON. Also, do NOT call something like @myCallback. You would call it like this: @callback { "name": "myCallback", "options": {} }
+Good example:
+@callback { "name": "lookupWeather", "options": { "zip": "80524" } }
+Bad examples:
+@lookupWeather { "zip": "80524" }
+@callback
+{ "name": "lookupWeather", "options": { "zip": "80524" } }
+@callback { "name": "lookupWeather", "options": {
+  "zip": "80524"
+} }`;
     }
 }
 exports.default = ResponseParserV2;

package/package.json

@@ -8,7 +8,7 @@
       "eta"
     ]
   },
-  "version": "15.1.8",
+  "version": "15.1.9",
   "files": [
     "build"
   ],