@cpwc/node-red-contrib-ai-intent 3.1.0-alpha

package/register-intent/index.html

@@ -0,0 +1,195 @@
+<script type="text/javascript">
+    RED.nodes.registerType("Register Intent", {
+        category: 'AI Intent',
+        color: '#1abc9c',
+        icon:"register-icon.svg",
+        defaults: {
+            name: { value: "", required: true, validate: RED.validators.regex(/^[a-zA-Z0-9_-]{1,64}$/) },
+            description: { value: "", required: true},
+            advanceMode: {value: "false"},
+            excludeFromOpenAi: { value: false },
+            code: {
+                value: "",
+                validate: function(code){
+                    if(this.advanceMode === "true"){
+                        try{
+                            return code.trim() && !!JSON.parse(code)
+                        }catch(e){
+                            return false
+                        }
+                    }
+                    return true
+                }
+            }
+        },
+        inputs: 0,
+        outputs: 1,
+        label: function () {
+            return this.name || "Register Intent";
+        },
+        oneditprepare: function(){
+            this.editor = RED.editor.createEditor({
+                id: 'node-code',
+                mode: 'ace/mode/json',
+                value: this.code
+            });
+
+            $("#node-input-advanceMode").typedInput({
+                type:"bool",
+                types:["bool"],
+                typeField: "#node-input-advanceMode-type"
+            }).on("change",function () {
+                this.advanceMode = $(this).val()
+                if ($(this).val() === "true") {
+                    $("#code").slideDown()
+                } else {
+                    $("#code").slideUp();
+                }
+            })
+        },
+        oneditsave: function() {
+            this.code = this.editor.getValue();
+            this.editor.destroy();
+            delete this.editor;
+        },
+        oneditcancel: function() {
+            this.editor.destroy();
+            delete this.editor;
+        }
+
+    });
+
+
+</script>
+
+<script type="text/html" data-template-name="Register Intent">
+
+    <div style="display: flex; justify-content: center; margin-bottom: 25px;">
+        <a href="https://youtu.be/FvP04OToeLQ" target="_blank" referrerpolicy="no-referrer"
+            style="color: #f53b57"><i class="fa fa-youtube"></i><span style="padding-left: 10px;">Watch
+            Register Intent Node Tutorial</span></a>
+    </div>
+    
+    <div>
+        
+        <div class="form-row">
+            <label for="node-input-name">Name</label>
+            <input type="text" id="node-input-name" placeholder="Name">
+        </div>
+        <div class="form-tips"><b>Tip:</b> Name should be alphanumeric including underscores and hyphens (no spaces).</div>
+    </div>
+    
+
+    <div class="form-row">
+        <label for="node-input-description">Intent Description</label>
+        <input type="text" id="node-input-description" placeholder="Description">
+    </div>
+
+    <div class="form-row">
+        <label for="node-input-advanceMode">Advance Mode</label>
+        <input type="text" id="node-input-advanceMode">
+        <input type="hidden" id="node-input-advanceMode-type">
+    </div>
+
+    <div class="form-row" id="code">
+        <label for="node-code"><i class="fa fa-code"></i>Tool Schema (parameters)</label>
+        <div style="height: 250px; min-height:150px;" class="node-text-editor" id="node-code"></div>
+    </div>
+
+
+    <div style="display: flex; justify-content: space-around;">
+
+        <label for="node-input-excludeFromOpenAi" style="display: flex;">
+            <i class="fa fa-tag"></i>
+            <span style="margin-left: 5px;">Exclude from OpenAI (Deprecated)</span>
+            <input style="display: inline-block;margin-left: 1rem;" type="checkbox" id="node-input-excludeFromOpenAi"
+                name="enable conversation"></label>
+    </div>
+  
+</script>
+
+<script type="text/html" data-help-name="Register Intent">
+    <p>Registers an intent for use with the <code>Call Intent</code> node.  This allows you to define custom actions that can be triggered by other flows or, optionally, by an AI assistant like OpenAI.</p>
+
+    <h3>Inputs</h3>
+    <dl class="message-properties">
+        <dt>Name <span class="property-type">string</span></dt>
+        <dd>A unique name for this intent.  This name is used to identify the intent when calling it from other nodes.  It should be alphanumeric and can include underscores and hyphens (no spaces).  Maximum length is 64 characters.</dd>
+
+        <dt>Description <span class="property-type">string</span></dt>
+        <dd>A clear and concise description of the intent's purpose.  This description is used by AI assistants (if enabled) to understand when the intent should be triggered.  A good description helps the AI choose the appropriate function to call.</dd>
+
+        <dt>Advanced Mode <span class="property-type">boolean</span></dt>
+        <dd>Enables/Disables advanced configuration of the intent. If checked, the Tool Schema field will be displayed and required.</dd>
+
+        <dt>Tool Schema <span class="property-type">JSON (when Advanced Mode is enabled)</span></dt>
+        <dd>A JSON object defining the schema of the tool, enabling more structured interactions with AI assistants. This schema describes the parameters the tool expects, allowing the AI to provide the correct inputs.  Must be valid JSON.</dd>
+
+        <dt>Exclude from OpenAI (Deprecated) <span class="property-type">boolean</span></dt>
+        <dd><em>Deprecated: This option is no longer used.</em>  Previously, this option controlled whether the intent was exposed to OpenAI as a callable function. This is now handled automatically based on your flow configuration.
+        </dd>
+    </dl>
+
+    <h3>Details</h3>
+    <p>Place this node at the beginning of a flow to register an intent.  The registered intent can then be called by a <code>Call Intent</code> node.  This mechanism allows you to create modular and reusable flows that can be triggered by various events or AI assistants.</p>
+
+    <p>When integrating with AI assistants, the <strong>Description</strong> field is crucial.  It provides the AI with the context needed to determine when to call this intent.  Therefore, write descriptive and concise descriptions that clearly explain the intent's functionality.</p>
+
+    <p>The <strong>Advanced Mode</strong> and <strong>Tool Schema</strong> fields allow you to define a structured interface for AI interactions.  The schema describes the input parameters expected by the intent, ensuring that the AI provides valid data when calling the associated flow.</p>
+
+    <p><strong>Example:</strong>  Imagine you have a flow that controls your living room lights.  You could create a "Living Room Lights" intent with a description like "Controls the living room lights. Accepts 'on', 'off', and 'dim' commands."  Then, in your AI assistant, you could configure it to call this intent when the user says something like "Turn on the living room lights."</p>
+
+    <h3>Important</h3>
+    <p>The JSON provide will vary greatly based on the LLM platform. Some Schema features in OpenAI is not support in Gemini while many models in Ollama are not supported at all.
+    Please consult the various function calling documentation for your specified platform</p>
+
+    <h4>Example</h4>
+    The following is an example of a OpenAI function definition.
+    You only need to provide the `parameters` property of the schema.
+    A typical full function schema looks like this:
+    <pre>
+        {
+            type: "function",
+            function:{
+                name: "",
+                description: "",
+                parameters: {
+                    type: "object"
+                    properties: {...}
+                }
+        }
+    </pre>
+
+   <p> You only need to provide the `parameters` property for your schema</p>
+    <pre>
+    {
+        "type": "object",
+        "properties": {
+            "eventName": {
+                "type": "string",
+                "description": "A unique name for the event. Used to identify the event in the schedule."
+            },
+            "eventTime": {
+                "type": "string",
+                "format": "date-time",
+                "description": "The time for the one-off event in ISO8601 format (e.g., 2025-01-26T18:30:00)."
+            },
+            "eventPayload": {
+                "type": "string",
+                "description": "Command to give the smart home when the timer finishes"
+            }
+        },
+        "required": [
+            "eventName",
+            "eventTime"
+        ],
+        "additionalProperties": false
+    }
+    </pre>
+    <p>Check the function calling documentation for your platform of choice</p>
+    <ul>
+        <li><a href="https://platform.openai.com/docs/guides/function-calling">OpenAI</a></li>
+        <li><a href="https://ai.google.dev/gemini-api/docs/function-calling">Gemini</a></li>
+        <li><a href="https://ollama.com/blog/tool-support">Ollama</a></li>
+    </ul>
+</script>

package/register-intent/index.js

@@ -0,0 +1,72 @@
+const PubSub = require("pubsub-js");
+const { getErrorMessagesForConfig } = require("./utils");
+const { end, ContextDatabase } = require("../globalUtils");
+const {validateOpenAISchema} = require("../utilities/validateSchema")
+
+module.exports = function (RED) {
+  function RegisterIntentHandlerNode(config) {
+    RED.nodes.createNode(this, config);
+
+    const errorMessage = getErrorMessagesForConfig(config);
+    const node = this;
+    try{
+      if(config.advanceMode === "true"){
+        const schema = JSON.parse(config.code)
+        const result = validateOpenAISchema(schema)
+        if(!result.isValid){
+          node.status({fill:"red",shape:"dot",text:`${result.errorMsg}`});
+          node.error(result.errorMsg)
+          console.log(`RESULT: ${config.name} - `,result.errorMsg)
+        }else{
+          node.status({fill:"blue",shape:"dot",text:"Ready (Advanced)"});
+        }
+      }else{
+        node.status({fill:"blue",shape:"dot",text:"Ready (Simple)"});
+      }
+    }catch(e){
+      node.status({fill:"red",shape:"dot",text:"Advance mode json invalid"});
+      node.error(e)
+
+    }
+
+    const nodeDB = new ContextDatabase(RED);
+    if (errorMessage) {
+      // There was an error. Stop.
+      node.status({fill:"red",shape:"dot",text:"Error"});
+      return this.error(errorMessage);
+    }
+    else {
+      // create a new entry in global context for the given node id
+      nodeDB.saveIntent({
+        nodeId: node.id,
+        ...config,
+      });
+    }
+
+    // When Call Intent node publishes an event,
+    // this node will only listen for its own intent
+    const token = PubSub.subscribe(config.id, function (msg, data) {
+      const nodeStore = nodeDB.getNodeStore();
+      const { name, description, excludeFromOpenAi, code } = nodeStore[node.id];
+      node.status({fill:"green",shape:"dot",text:`Received data ${new Date()}`});
+      node.send([
+        { ...data, _config: { name, description, excludeFromOpenAi, code } },
+      ]);
+    });
+
+    // We need to clean up on close otherwise
+    // more than one message is sent when a call is published
+    this.on("close", function (removed, done) {
+      if (removed) {
+        nodeDB.removeIntent(config);
+        PubSub.unsubscribe(token);
+        end(done);
+      } else {
+        PubSub.unsubscribe(token);
+        end(done);
+      }
+    });
+  }
+
+  RED.nodes.registerType("Register Intent", RegisterIntentHandlerNode);
+};

package/register-intent/utils.js

@@ -0,0 +1,10 @@
+const getErrorMessagesForConfig = (config) => {
+  const { name, description } = config;
+  if (!name) {
+    return "Name is required";
+  } else if (!description) {
+    return "Description is required";
+  }
+};
+
+module.exports = { getErrorMessagesForConfig };

package/utilities/chat-controller.js

@@ -0,0 +1,249 @@
+const { TYPES, TOOL_CHOICE } = require("../constants");
+const { ContextDatabase } = require("../globalUtils");
+const { ChatLedger } = require("./chat-ledger");
+
+class ChatController {
+  constructor(node, config, msg, RED) {
+    this.msg = msg;
+    this.node = node;
+    this.config = config;
+    this.apiProperties = getChatCompletionProps(msg, config, node);
+
+    const registeredIntentFunctions = this.getRegisteredIntentFunctions(RED);
+    const rawIntents = this.getRawIntents(RED);
+
+    this.tools = [
+      ...this.apiProperties.tools,
+      ...registeredIntentFunctions,
+    ].filter(Boolean);
+    const toolProperties = determineToolProperties(
+      rawIntents,
+      this.tools,
+      this.apiProperties.tool_choice
+    );
+
+    this.toolProperties = validateToolProperties(toolProperties, node);
+  }
+
+  mergeResponseWithMessage = (response, request) => {
+    const { user, system, tools, ...rest } = this.msg;
+    const ledger = new ChatLedger(this.config.conversation_id, this.node);
+    const fullConversation = ledger.addResponseToConversationAndSave(
+      request,
+      response,
+      this.node.type
+    );
+
+    return {
+      ...rest,
+      payload: response,
+      _debug: {
+        ...request,
+        type: this.node.type,
+        fullConversation,
+        conversation_id: this.config.conversation_id,
+      },
+    };
+  };
+
+  /**
+   * Converts the raw intents into functions that the LLM can use.
+   * @param {*} node
+   * @returns
+   */
+  getRegisteredIntentFunctions = (RED) => {
+    const intents = this.getRawIntents(RED);
+    return createFunctionsFromContext(intents);
+  };
+
+  /**
+   * This will return all stored Registered Intents throughout the entire system
+   * and Tool Nodes that are attached directly to this flow
+   * This will return:
+   *  type RawIntent = {
+   *    [node_id]: node // could be Registered Intent or Tool node
+   *  }
+   */
+  getRawIntents = (RED) => {
+    const context = new ContextDatabase(RED);
+    return context.getNodeStore() || {};
+  };
+}
+
+/**
+ * If no tools exist, then remove tools and toolChoice from the payload
+ */
+const validateToolProperties = (toolProperties, node) => {
+  if (!toolProperties.tools?.length) {
+    const { tools, toolChoice, ...rest } = toolProperties;
+
+    if (toolChoice && toolChoice !== TOOL_CHOICE.None) {
+      node.warn(
+        "Removing tools from payload since no tools are available. Flow will continue."
+      );
+    }
+
+    return rest;
+  }
+  return toolProperties;
+};
+
+/**
+ * combines various properties from `msg` and `config` to return all the properties needed for OpenAI API request
+ * @param {Record<string,any>} msg
+ * @param {Record<string, any>} config
+ * @returns
+ */
+const getChatCompletionProps = (msg, config, node) => {
+  const model = msg.payload?.model || config.model;
+  const temperature = Number(msg.payload?.temperature || config.temperature);
+  const max_tokens = Number(msg.payload?.max_tokens || config.max_tokens);
+  const top_p = Number(msg.payload?.top_p || config.top_p);
+  const frequency_penalty = Number(
+    msg.payload?.frequency_penalty || config.frequency_penalty
+  );
+  const presence_penalty = Number(
+    msg.payload?.presence_penalty || config.presence_penalty
+  );
+  const _format = { format: msg.payload?.json || config.json };
+  const tools = msg?.tools || [];
+  const tool_choice =
+    msg.payload?.tool_choice || config?.tool_choice || TOOL_CHOICE.Auto;
+  const ledger = new ChatLedger(config.conversation_id, node);
+  const messages = ledger.combineExistingMessages(msg.user, msg.system);
+
+  if (!_format.format) {
+    delete _format.format;
+  } else {
+    _format.format = "json";
+  }
+
+  return {
+    model,
+    temperature,
+    max_tokens,
+    top_p,
+    frequency_penalty,
+    presence_penalty,
+    messages,
+    tool_choice,
+    tools,
+    ..._format,
+  };
+};
+
+/**
+ * converts the registered intents stored in the context into functions that can be used by the LLM.
+ * The registered intent will be ignored if excludeFromOpenAi is set to true.
+ * rawIntents may have tool nodes included so the values need to be filtered by the node type.
+ * rawIntents have the following shape:
+ *
+ * type RawIntents = {
+ *  [node_id]: node // node could be Registered Intent or Tool node
+ * }
+ */
+const createFunctionsFromContext = (rawIntents = {}) => {
+  return (
+    Object.values(rawIntents)
+      .filter((payload) => {
+        return payload.type === "Register Intent";
+      })
+      .map((payload) => {
+        if (payload.excludeFromOpenAi) {
+          return undefined;
+        }
+
+        return {
+          type: "function",
+          function: {
+            name: payload.name,
+            description: payload.description,
+            parameters: {
+              type: "object",
+              properties: {
+                isRegisteredIntent: { type:"boolean", const: true },
+                response: {
+                  type: "string",
+                  description: "A friendly response to the given command",
+                },
+              },
+              required: ["isRegisteredIntent", "response"],
+            },
+          },
+        };
+      })
+      .filter(Boolean) || []
+  );
+};
+
+/**
+ * Based on the tool_choice the tool properties will be created. This is based off
+ * https://cookbook.openai.com/examples/how_to_call_functions_with_chat_models
+ *
+ * @param {Object} context - contains all the saved nodes that represents functions
+ * @param {*} tools - All the tools to be sent as functions
+ * @param {*} toolChoice - Specifies which tools to use
+ * @returns
+ */
+const determineToolProperties = (
+  context = {},
+  tools = [],
+  toolChoice = TOOL_CHOICE.Auto
+) => {
+  const props = {
+    tools,
+    tool_choice: toolChoice,
+  };
+  if (toolChoice === TOOL_CHOICE.None || tools.length === 0) {
+    // No tools chosen
+    return {};
+  } else if (toolChoice === TOOL_CHOICE.Auto) {
+    // set the choice to auto
+    return props;
+  } else if (context[toolChoice]?.type === TYPES.OpenAITool) {
+    // User chose a specific tool from the dropdown list
+    const tool = JSON.parse(context[toolChoice].tool);
+    props.tool_choice = {
+      type: tool.type,
+      function: { name: tool.function.name },
+    };
+
+    const doesExist = tools.some((_tool) => {
+      return _tool.function.name === tool.function.name;
+    });
+
+    if (!doesExist) {
+      throw new Error(
+        `The OpenAI Tool node "${context[toolChoice].name}" is missing from the flow.`
+      );
+    }
+
+    return props;
+  } else if (context[toolChoice]?.name) {
+    // ???
+    props.tool_choice = {
+      type: "function",
+      function: { name: context[toolChoice].name },
+    };
+
+    return props;
+  }
+  // Something funky happened so we will use auto instead
+  return {
+    tools,
+    tool_choice: TOOL_CHOICE.Auto,
+  };
+};
+
+const createChatEndpoint = (baseURL = "") => {
+  return stripTrailingSlash(baseURL) + "/api/chat";
+};
+
+const stripTrailingSlash = (str) => {
+  return str.endsWith("/") ? str.slice(0, -1) : str;
+};
+
+module.exports = {
+  ChatController,
+  createChatEndpoint,
+};

package/utilities/chat-ledger.js

@@ -0,0 +1,122 @@
+const { CONVERSATION_CONTEXT, TYPES } = require("../constants");
+const { GlobalContext } = require("./global-context");
+
+class ChatLedger {
+  constructor(id = "", node) {
+    this.id = id;
+    this.node = node;
+  }
+
+  addResponseToConversationAndSave = (
+    request,
+    response,
+    type = TYPES.OpenAIChat
+  ) => {
+    const conversation = [];
+
+    request.messages.forEach((message) => {
+      conversation.push(message);
+    });
+
+    if (type === TYPES.OpenAIChat) {
+      response.choices.forEach(({ message }) => {
+        const { role, content = "", tool_calls } = message;
+
+        if (content) {
+          conversation.push({ role, content });
+        } else if (tool_calls) {
+          const toolMessage = tool_calls.reduce((message, tool) => {
+            return `${message} ${JSON.stringify(
+              tool.function.arguments,
+              null,
+              2
+            )}`;
+          }, "");
+          conversation.push({ role, content: toolMessage });
+        }
+      });
+    } else {
+      const { role, content = "" } = response.message;
+      conversation.push({ role, content });
+    }
+
+    return this.saveConversation(conversation);
+  };
+
+  combineExistingMessages = (userOrAssistant, system) => {
+    const existingConversation = this.getConversation();
+    let combined = [...existingConversation, userOrAssistant];
+
+    if (existingConversation[0]?.role === "system" && system) {
+      //Replace the existing system with the new system
+      combined[0] = system;
+    } else if (system) {
+      // Add the system to the beginning of the array
+      combined = [system, ...combined];
+    }
+
+    // Remove entries with empty content. API breaks if content is empty
+    return combined
+      .map((conversation) => {
+        if (conversation.content) {
+          return conversation;
+        }
+      })
+      .filter(Boolean);
+  };
+
+  clearConversation = () => {
+    const { id, node } = this;
+    if (!id) {
+      this.node.warn(
+        `No conversation id is present on the . Cannot clear conversation`
+      );
+      return [];
+    }
+    const globalContext = new GlobalContext(node);
+    const conversations =
+      globalContext.getValueFromGlobalContext(CONVERSATION_CONTEXT) || {};
+
+    conversations[id] = [];
+
+    globalContext.setValueToGlobalContext(conversations, CONVERSATION_CONTEXT);
+
+    return conversations[id];
+  };
+
+  getConversation = () => {
+    const { id = "", node } = this;
+
+    if (!id) {
+      return [];
+    }
+
+    const globalContext = new GlobalContext(node);
+    const conversations =
+      globalContext.getValueFromGlobalContext(CONVERSATION_CONTEXT) || {};
+
+    return conversations[id] || [];
+  };
+
+  saveConversation = (conversation = []) => {
+    const { id, node } = this;
+
+    if (!id) {
+      return conversation;
+    }
+
+    const globalContext = new GlobalContext(node);
+    const conversations =
+      globalContext.getValueFromGlobalContext(CONVERSATION_CONTEXT) || {};
+
+    conversations[id] = conversation;
+
+    globalContext.setValueToGlobalContext(conversations, CONVERSATION_CONTEXT);
+
+    return conversation;
+  };
+}
+
+module.exports = {
+  ChatLedger,
+};