zef-dev / convoworks-gpt

Convoworks GPT is a comprehensive components package designed to integrate OpenAI GPT API into WordPress websites. This powerful package offers a range of components that allow users to seamlessly incorporate the advanced natural language processing capabilities of OpenAI GPT into their WordPress website.

Convoworks GPT WordPress Plugin

Convoworks GPT is an extension package for Convoworks framework. It is in the form of a WordPress plugin so you can use it with the Convoworks WP.

This is a development version and it is yet decided will this package be part of the Convoworks core or will it stay as a separate plugin.

Building the Plugin

You can use the prebuilt plugin version (in the ./build folder) or you can build it by yourself.

When using it for the first time, you have to install the node packages. Navigate to the project root and enter the following command:

npm install

To build the deployment package, run this command, which will create the plugin zip. The version is taken from the package.json file:

node build.js

Installation & Quick Start

• Download and activate Convoworks WP through your plugin installer (available on WordPress.org). No additional configuration is required.
• Upload the convoworks-gpt plugin zip file through your WordPress plugin installer and activate it.
• In your WP admin panel, navigate to Convoworks WP, click on Create new, enter the desired name, select the GPT Example Chat template, and press Submit.
• In your newly created service, navigate to the Variables view and enter your OpenAI key into the GPT_API_KEY variable.
• Navigate to the Test view to try it out.

Displaying Chat on Public Pages

• Navigate to the Configuration view and enable the Convo Chat platform (no additional settings are needed).
• Use the shortcode to display it on the front end: [convo_chat service_id="gpt-example-chat" title="Example Chat"]

Functions

Convoworks GPT WordPress Plugin provides predefined functions that can be utilized within workflows to extend the capabilities and provide more dynamic interactions.

tokenize_string

Description:
The tokenize_string function processes an input string by removing all HTML tags, converting it to lowercase, stripping punctuation, and then tokenizing it by spaces. The resulting tokens are further refined by removing common stop words, producing a meaningful representation suitable for use with the embeddings API.

Parameters:

• $text - The input string to be tokenized.
• $stopWords (optional) - An array of words to be considered as stop words and removed from the tokenized output. If not provided, a default list of common English stop words will be used.

Usage:
To tokenize a raw string:

${tokenize_string(your_raw_text)}

To tokenize a raw string with custom stop words:

${tokenize_string(your_raw_text, ["custom", "stop", "words"])}

Default Stop Words:
The default stop words list includes common English words like "a", "about", "above", and so forth. These words are typically removed to produce a cleaner, more meaningful representation of the input.

Components

GPT Chat Completion API Element

This is an OpenAI API wrapper element, which allows you to make calls and get the chat completion API response.

Parameters:

• System message - The initial system message in the conversation.
• Messages - An array of conversation messages, including the assistant and user roles.
• Result Variable Name - Defaults to status, this is the variable name that stores the complete API response. Access the completion text with: ${status.choices[0]["message"]["content"]}
• API key - Your OpenAI API key.
• API options - Options for the OpenAI Chat Completion API.

Flows:

• OK flow - Executes elements after completion. Access completion results through the result_var variable.

GPT Chat Completion API v2

This advanced component enables you to perform chat completion API calls with more dynamic capabilities and additional contexts.

Parameters:

• Result Variable Name - Default status. The variable that stores the API completion response. Defaults to status, this is the variable name that stores response information. (response : full API response, messages: array of messages for current conversation, last_message: the last message (returned from GPT) as associative array)
• API key - Your OpenAI API key.
• API options - Configuration options for the chat completion API, such as the model used, temperature, and token limit.

Flows:

• Messages - Defines a sub-flow that provides messages or context for the chat completion API. This allows you to prepend agent definitions, add external data, or use conditional logic to determine context.
• Function - Allows dynamic registration of available functions that the agent can use during the conversation.
• OK flow - This flow is executed once the API call is finished and the result variable is ready for further actions.

GPT Embeddings Element

This element serves as a wrapper for the OpenAI Embeddings API, enabling the retrieval of vector representations for a given input.

Parameters:

• Input - The string to be embedded. Recommended preprocessing using tokenize_string(): ${ tokenize_string( your_raw_text)}.
• Status Variable - The variable that contains the complete API response. Access the embedding value with: ${status.data[0].embedding}.
• API key - Your OpenAI API key.
• API options - Options for the Embeddings API.

Flows:

• OK flow - Executes when the operation completes and the result variable is available.

For more information on available API options, refer to the Embeddings API Reference - OpenAI API.

GPT Moderation API

This element allows you to validate input with the OpenAI Moderation API. The Moderation API is a powerful tool for content moderation, helping you ensure that the generated content aligns with your guidelines and policies.

Parameters:

• Input - Text for moderation.
• Result Variable Name - Variable storing the moderation API response.
• API key - Your OpenAI API key.
• API options - Options for the OpenAI Moderation API.

Flows:

• OK flow - Executes once the moderation operation completes and the result variable is available.

For more information on the OpenAI Moderation API and its capabilities, refer to the OpenAI Moderation API documentation.

GPT Query Generator

The GPT Query Generator element allows you to create context-rich questions from a given conversation. These questions can be utilized to query a knowledge database, enhancing GPT chat completion-based interactions by providing additional context and insights.

In your system message, you can use the ${conversation} expression, which contains a serialized conversation summary. If omitted, the serialized conversation will be attached as a separate system prompt.

Parameters:

• System Message - Sets initial context and format for the conversation.
• Messages - Array of messages representing the GPT chat completion, acting as the primary context for question generation.
• Messages Count - Number of recent conversation messages to be considered.
• Result Variable Name - Variable storing the generated questions.
• API key - Your OpenAI API key.
• API Options - Parameters for the GPT chat completion API.

Flows:

• OK Flow - Executes after successful question generation.

System Message

The System Message element defines a system-generated message within the chat context. These messages are primarily used in conjunction with the GPT Chat Completion API v2 to prepend system-level information or context to a conversation. This can be useful for providing agents with a consistent introduction or setting the tone for the conversation.

Parameters:

• Message Content - Text content of the system message, which can be static or dynamically generated.

For use cases and more details on how system messages can be integrated with the Chat Completion API v2, refer to the associated component documentation.

Conversation Messages

The Conversation Messages element plays a pivotal role in handling conversations with the GPT Chat Completion API v2. It manages the storage and provision of the entire conversation that needs to be sent to the API. This ensures that the context and flow of the conversation remain intact during API interactions.

Parameters:

• Messages - Expression evaluating to an array of conversation messages. These chronologically ordered messages ensure contextual continuity.

For more details on how to properly set up and manage conversation messages with the GPT Chat Completion API v2, refer to the associated component documentation.

GPT Messages Limiter

Limits the size of messages by summarizing the oldest ones.

Parameters:

• System message - The main system prompt.
• Max messages to keep - Maximum message count before older messages get summarized.
• Truncate to this number of messages - Message count after truncation.
• API key - Your OpenAI API key.
• API options - Options for summarizing the conversation.
• Messages - Provides the conversation messages.

Chat Function

Function definition that can be used with Completion API based elements.

Parameters:

• Function name - Unique function name.
• Description - Function description.
• Function parameters - Defines required function parameters. For more details on how to define parameter check JSON Schema documentation
• Defaults - Default values for function parameters.
• Required - List of mandatory function fields.
• Request data variable - Variable for passing function arguments.
• Function result - Expression to determine the function result.

Flows:

• OK flow - Workflow executed when an action is requested through this function.

Deprecated components

The following components are associated with the now-deprecated OpenAI endpoints. While these components remain in the package to ensure your existing services continue to function, they are no longer visible in the toolbox.

GPT Completion API Element

This is an OpenAI API wrapper element, which allows you to make calls and get the completion API response.

Parameters:

• prompt - The actual prompt sent for completion
• result_var - Default status, the name of the variable that contains the complete API response. You can access the completion text itself like this: ${status.choices[0]["message"]["content"]}
• api_key - Your OpenAI API key
• apiOptions - OpenAI Completion API endpoint options

Flows:

• ok - Elements to execute after completion. The completion result is accessible via the variable defined with result_var

Autonomous Chat Element

This specialized conversational element enables the building of bots that are capable of interacting with your system (WordPress). This variant is built using the GPT-3 completion API.

The conversation is between the user, the bot, and the website. As usual, the user talks to the bot, and when necessary, the bot issues action commands to the website, which returns action results. When speaking (responding) to the user request, the bot speaks in plain English. When the bot wants the website to perform some action, it responds with a JSON message.

Here is an example conversation:

Bot: Hi, how can I help you?
User: I would like to book a demo.
Bot: Great, when would you like to book it?
User: Friday at 4 pm.
Bot: {"action":"check_appointment_slot", "date":"2023-03-31", "time":"16:00"}
Website: {"available":true}
Bot: Great! That time is available. Please tell me your name and email.
User: I'm John Smith, [email protected]
Bot: {"action":"create_appointment", "date":"2023-03-31", "time":"16:00", "name":"John Smith", "email":"[email protected]"}
Website: {"appointment_id":"abc344bh43"}
Bot: Thanks. Your appointment is created. Can I help you with something else?

In order to enable this kind of behavior, this element delegates prompt building and actions to specialized components, configured in the Convoworks workflow. Prompt and action components can be used inside other elements (e.g. IF/ELSE, INCLUDE, FOR), allowing you to dynamically change the system behavior.

Parameters:

• system_message - The main prompt to generate completions for. It will be appended with eventual child Prompt elements.
• user_message - The new user message to append to the conversation.
• messages - An array containing all messages in the current conversation
• result_var - Default status, the name of the variable that contains additional information. It contains these fields: messages array of all conversation messages (including the last bot response), bot_response the last bot response (safe to display to the user), last_prompt the full last prompt which is sent to the API call. Useful for debugging.
• api_key - Your OpenAI API key
• apiOptions - OpenAI Completion API endpoint options
• skipChildPrompts - When enabled, only this component prompt will be used. This can be useful when testing and tuning your prompts.

Flows:

• prompts - Prompt and Action definition components (IChatPrompt and IChatAction interfaces) which will participate in the prompt building.
• ok - Elements to execute after completion. The completion result is accessible via the variable defined with result_var

Turbo Chat Element

This component is quite similar to the previous one, with a difference that it is using GPT-3.5-urbo & chat completion API. As chat and completion API have different interfaces, there are slight differences in the element's parameters too.

Parameters:

• system_message - The main prompt to generate completions for (prepended as role = system message).
• messages - An array containing all messages in the current conversation including the latest user request. These messages are following the chat API defined structure: {"role":"msg_role", "content" : "Message content"}
• result_var - Default status, the name of the variable that contains additional information. It contains these fields: messages array of all conversation messages (including the last bot response), bot_response the last bot response (also as a complex object. Use it to display a response to the user).
• api_key - Your OpenAI API key
• apiOptions - OpenAI Chat Completion API endpoint options
• skipChildPrompts - When enabled, only this component prompt will be used. This can be useful when testing and tuning your prompts.

Flows:

• prompts - Prompt and Action definition components (IChatPrompt and IChatAction interfaces) which will participate in the prompt building.
• ok - Elements to execute after completion. The completion result is accessible via the variable defined with result_var

Simple Prompt Element

This element allows you to split complex prompts into several, manageable sections. Use this element inside the prompts flow.

Parameters:

• title - The title for the prompt section.
• content - The content of the prompt section.

Prompt Section Element

Addition to the Simple Prompt which allows prompts grouping into sections.

Parameters:

• title - The title for the prompt section.
• content - The content of the prompt section.

Flows:

• prompts - Child Prompt and Action definition components which will participate in the prompt building.

Simple Chat Action Element

This element allows you to define an action, with its ID and prompt definition, and to define a workflow which will be executed when the action is invoked. Use this element inside the actions flow.

Parameters:

• action_id - A unique action identifier.
• title - The title for the prompt section.
• content - The content of the prompt section.
• action_var - A variable containing action data which is available in the OK flow.
• result - A variable which evaluates to a result of the executed action. This (evaluated) value will be appended to the conversation as a website response.
• autoActivate - When enabled, it will call this action automatically and prepend the call to the conversation. Applicable for getting current user information or any other action which does not require input parameters.

Flows:

• ok - Elements to execute when the action is requested.

Validation Error Element

Stops the execution and signals the Chat App that the action request is not valid.

Parameters:

• message - Error message describing why the validation failed.

---

Written with StackEdit.