API & Filters

Server-Side API (PHP)

I would like to make AI Engine extremely customizable so that you can achieve really everything you want with it. Here are the current available filters in the plugin.

Filters

Interactions with AI

  • mwai_ai_query( $query ) => Modify a query before it’s made
  • mwai_ai_allowed( $allowed, $query, $limits ) => Allow a query to be made or not
  • mwai_ai_reply( $reply, $query ) => Modify the answer before it’s sent (or do something at that time)
  • mwai_ai_exception( $message ) => Modify the error message
  • mwai_estimate_tokens( $tokens, $text ) => Modify the estimated number of tokens for the given text (you can modify the default algorithm) used to calculate the tokens usage estimation.

Chatbot

  • mwai_chatbot_params( $params ) => Modify the final params just before the query is made
  • mwai_chatbot_takeover( $takeoverText, $query, $params )
  • mwai_contentaware_content( $content ) => Handle extra use cases, like looking for content in specific fields, or handling page builders, etc
  • mwai_chatbot_reply( $rawText, $query, $params, $extra ) => Modify the answer before it’s sent.

Embeddings

  • mwai_pre_post_content( $content, $postId ): Get the raw content from the post. You can modify it to add your custom field, etc. AI Engine will clean that content further, and make sure it’s not too large for the AI model.
  • mwai_post_content( $content, $postId ): The final content that will be used. You can also modify this.
  • mwai_context_search( $query, $embeddingIndex = null ): Returns the embedding the most related to the query.

Forms

  • mwai_form_params( $params ) => Modify the final params
  • mwai_form_reply( $rawText ) => Modify the answer before it’s sent

Limits

  • mwai_stats_credits( $credits, $userId ) => Modify the number of credits (that allows you to create your own system)
  • mwai_stats_coins( $price, $stats, $atts ) => Modify the coins (that allows you to convert the price you personally pay to OpenAI to your own system of coins that you share with your users)

Others

  • mwai_languages( $languages ) => Modify the list of languages
  • mwai_allow_setup( $hasAccess ) => Allow access to the Settings of AI Engine in the Admin
  • mwai_allow_usage( $hasAccess ) => Allow access to the various screens of AI Engine in the Admin

PHP Functions

If you would like to access AI features easily through AI Engine, simply use the mwai global. There will be more and more functions available to use. The API uses the whole AI Engine system, so you’ll get the statistics and limitations features as well.

simpleTextQuery( $prompt, $options )

You can use this function to simply run a query against the default model (turbo, currently). It’s as simple as that! 

add_filter( 'the_content', function ( $content ) {
  global $mwai;
  $extra = $mwai->simpleTextQuery( "Write an one-liner about a cat introducing itself." );
  return $extra . $content;
} );

simpleChatbotQuery( $botId, $prompt, $chatId )

You can use this to discuss with one of your chatbots. The chatId is optional, but allows you to create a conversation. All the messages exchanged under the same chatId will be stored as a conversation. For this to work, you will need the Discussions to be enabled in the Settings.

moderationCheck( $text )

Simply return true if the message has been flagged as unsafe to use.

PHP Classes

Meow_MWAI_Query_Text

You will find this usually named as $query and this class is used mainly for completion and chat. By default, it uses the turbo model, and relatively safe parameters. But of course, you can override everything you like. Here is an example on how to use it manually:

$query = new Meow_MWAI_Query_Text( "Translate 'Hello World' into French.", 512 );
$query->setModel( 'text-davinci-003' ); // Override the model (turbo by default)
// AI Engine will take care of this for you.
global $mwai_core;
$reply = $mwai_core->ai->run( $query );
// And finally, let's output the result.
echo $reply->getResult();

There are the main functions:

  • $query->replace( $search, $replace ): Replace a string by another string (in will affect only the prompt)
  • $query->setApiKey( $apiKey ): Override the default API Key set in the settings.
  • $query->setPrompt( $prompt ): Add or set the prompt. This function will evolve.
  • $query->getPrompt( $prompt ): Get the prompt. If chat mode (from 3.5 models), it will automatically compile the messages into a properly formatter prompt. This function will evolve.
  • $query->setMessages( $messages ): Add or override the previous messages. This function will evolve.
  • $query->setNewMessage( $message ): Add or override the new message (from the user). This function will evolve.
  • $query->getLastMessage(): Get the latest message (typically, that would be the new question from the user).
  • $query->setContext( $context ): Set or override the context.
  • $query->setModel( $model ): Override the model (gpt-3.5-turbo by default).
  • $query->setTemperature( $temperature ): Override the temperature (0.8 by default).
  • $query->setMaxTokens( $maxTokens ): Override the max tokens (1024 by default). It will be automatically be reduced by AI Engine if it’s too high.
  • $query->setMaxResults( $maxResults ): Specific the number of results (1 by default).
  • $query->injectContext( $context ): Add an additional context that will only affect this query (this works only with the chat mode with turbo).
  • $reply->estimateTokens( $text ): Give an estimation of the number of tokens for this text. Very approximate, don’t make your life depend on it.

Meow_MWAI_Reply

You will find it usually named as $reply. Here are the main functions:

  • $reply->getResults(): Return an array with all the results.
  • $reply->getResult(): Return simply the first (or the only) result.
  • $reply->replace( $search, $replace ): Replace a string by another string (in will affect all the results)
  • $reply->getUsage(): Return an array with the number of prompts_tokens, completion_tokens, and total_tokens. But I think I’ll modify this, to show the costs directly instead with more interesting statistics (like what the plugin does normally, in the Statistics module).

Function Calling

Using the Function Calling feature of OpenAI is quite straightforward. Here is an example. Please note that you’ll need the latest version of Turbo (gpt-3.5-turbo-0613 or more) or GPT 4 (gpt-4-0613 or more); so be careful if you are using Azure with deployments of models that might not be the latest ones.

add_filter( 'mwai_ai_query', function ( $query ) {

  // This function will be returned by the AI if it's the right fit, with the right parameters.
  // You can use addFunction, setFunctions and getFunctions.
  $query->addFunction( new Meow_MWAI_Query_Function( 
    'send_email',
    'Send an email to the owner of this website',
    [
      new Meow_MWAI_Query_Parameter( 'subject', 'The subject of the email', 'string', true ),
      new Meow_MWAI_Query_Parameter( 'message', 'The message of the email', 'string', true )
    ]
  ) );

  return $query;
}, 999, 1 );

add_filter( 'mwai_ai_reply', function ( $reply, $query ) {
  
  // Make sure the query is of type Text (and not Image, Embedding, etc)
  if ( !( $query instanceof Meow_MWAI_Query_Text ) ) { return $reply; }

  // If we have a function call, we can handle it here.
  if ( $reply->functionCall ) {
    $functionCall = $reply->functionCall;
    if ( $functionCall['name'] === 'send_email' ) {
      $subject = $functionCall['arguments']['subject'];
      $message = $functionCall['arguments']['message'];
      mail( "[email protected]", $subject, $message );

      // Since function call doesn't return anything, better to set a reply to the user
      $reply->setReply( "An email was sent to the owner of the website. You'll get a reply soon!" );
    }
  }

  return $reply;
}, 10, 2 );

In the chatbot, you would then be able to interact with the AI this way, and the email would be actually sent to the administrator:

Public REST API

Every function from the PHP Functions is accessible through the REST API (https://domains.com/wp-json/mwai/v1/function_name). Use the POST method, with the parameters passed as JSON in the body.

Simple Examples

If you would like to run a simple AI query, you can do this:

POST https://yoursite.com/wp-json/mwai/v1/simpleTextQuery
{
  "prompt": "Give me a few facts about Bordeaux. Concise answer."
}

You can also chat directly with one one your chatbots:

POST https://yoursite.com/wp-json/mwai/v1/simpleChatbotQuery
{
  "prompt": "Hi! Who are you, actually?",
  "botId": "default"
}

Access Control

By default, the Public REST API is disabled completely. If you enable it, only authentified API requests will actually go through, otherwise they will be rejected. You can override this behavior in many ways and we will see a few examples. The Public REST API is also limited by the Limits set in AI Engine (either as Users or Guests, and System).

Authentified API Request

With WordPress REST API, to authentify your requests (which means they will be ran under a specific user in WordPress), you need to use nonces. Basically, you create the nonce on the WordPress side, for the current user, this way: 

$my_nonce = wp_create_nonce( 'wp_rest' );

This nonce should be shared with the client (on the JS side, typically), then it can be used to make the requests, this way:

let nonce = "THE_NONCE_VALUE";
fetch('http://yoursite.com/wp-json/mwai/v1/simpleChatbotQuery', { 
  method: 'POST',
  headers: { 
    'Content-Type': 'application/json',
    'X-WP-Nonce': nonce
  },
  body: JSON.stringify({
    botId: 'default',
    prompt: 'Hello, who are you? What's up?'
  })
}).then(res => res.json()).then(console.log);

For more details about this, check the official documentation.

Full-Access to a Specific Feature

I don’t recommend it, but let’s say you would like to completely open the simpleTextQuery to everyone, or maybe for testing purposes. You can use the mwai_allow_public_api filter, which allows you to do this easily:

add_filter( 'mwai_allow_public_api', function ( $allow, $feature, $extra ) {
  if ( $feature === 'simpleTextQuery' ) {
    return true;
  }
  return $allow;
}, 10, 3 );

In this case, since the request is not authentified, the limits applied by AI Engine would be the ones related to the Guests. That said, you could also authentify them by force by calling the wp_set_current_user function. Be really careful when doing this.

add_filter( 'mwai_allow_public_api', function ( $allow, $feature, $extra ) {
  if ( $feature === 'simpleTextQuery' ) {
    wp_set_current_user(1);
    return true;
  }
  return $allow;
}, 10, 3 );

Custom Authentification

Let’s say you are building an external app for mobile, or maybe calling AI Engine from a different website or system; you will need to create your own authentification. For this, I recommend using a Bearer Token. Don’t worry, it’s easy! Use the mwai_allow_public_api filter to authorize the request. The $extra argument contains actually all the data about the incoming request. You can retrieve the token from it, and check if it’s the right one. You can secure it further by checking the IP address, etc.

add_filter( 'mwai_allow_public_api', function ( $allow, $feature, $extra ) {
  if ( !empty( $extra ) && !empty( $extra->get_header( 'Authorization' ) ) ) {    
    $token = $extra->get_header( 'Authorization' );
    $token = str_replace( 'Bearer ', '', $token );
    if ( $token === "123456" ) {
      // You don't need to absolutely do this, but it's better to link a Bearer Token to an User.
      wp_set_current_user(1);
      return true;
    }
  }
  return $allow;
}, 10, 3 );

For a quick test using the Chrome Developers Tools, you could try this in the Console:

fetch('http://ai.nekod.net/wp-json/mwai/v1/simpleChatbotQuery', { 
    method: 'POST', 
    headers: { 
        'Content-Type': 'application/json', 
        'Authorization': 'Bearer 123456'
    }, 
    body: JSON.stringify({ 
        prompt: 'Hello, who are you?', 
        botId: 'default',
    }) 
}).then(res => res.json()).then(console.log);

Client-Side API (JS)

You can interact with the chatbots and conversations directly through JS. Have a look at the MwaiAPI object that it is available directly in your JS console. If you only use one chatbot, you can get the instance by using MwaiAPI.getChatbot(). If you have many, you can mention its ID as the first argument. For example, you could do:

let chatbot = MwaiAPI.getChatbot(); // Get the chatbot; if there are more than one on the same page, you'll need to pass the ID of the chatbot in argument
chatbot.open(); // Opens the chatbot if it's minimized
chatbot.ask("How are you?", false); // Sends a request (if true, the request will be send immediately)

JS Filters

Modify the reply: ai.reply

MwaiAPI.addFilter('ai.reply', function (reply) {
  return reply + ' For more information, visit [Meow Apps](https://meowapps.com).';
});