AI: How to use it or integrate it in contrib modules

Are you building an AI integration via an open source contribution module or maybe even a private integration - good, you have come to the right place. This documentation covers why you should integrate the AI API abstraction layer and how to integrate the AI API abstraction layer into your own module.

How to integrate a provider is available in another section soon.

Integrating the module

Here comes some examples of different type of levels you might want to integrate the module at. In these examples the code is loaded as a static, for best practice use Dependency Injection.

Call one operation, that should NOT be reusable between service providers.

This is when you want one simple provider, like OpenAI, to just do one simple operation, like Chat. And you know that you will only ever use OpenAI in this case and you want to input the messages and get the output as the openai-php/client provides them.

This can be done in one line of code if you know then service providers data name, in this case openai and using the operations type chat.

$messages = [
  ['role' => 'user', 'content' => 'Hello!'],
];
$response =  \Drupal::service('ai.provider')->createInstance('openai')->chat($messages, 'gpt-4o')->getRaw();
// Response would be an array of a full OpenAI response in this case.

Lets go through what is happening here and what each of these parameters means.

1. The service ai.provider is the service that takes care of loading all providers.
2. The provider we want in this case is OpenAI with an id of openai. You can list the available models with "\Drupal::service('ai.provider')->getDefinitions();"
3. The function we use on the provider depends on the type of operation you want to do. In this case its chat.
4. The first input is always the main input required and in this case it is the array of message OpenAI expects.
5. The second input is the model we are using.
6. There is a third input where you can tag your request for logging purposes.
7. We use the getRaw method to get the raw output from the API.

Call one operation, that should be reusable between service providers.

This is when you want one simple like OpenAI, to just do one operation, like Chat, but you might want to swap it out to use some other provider like Anthropic in the future, so the input and the output will have to be normalized.

We will do the same call as above, but in a way where not just the logic is abstracted away, but also the data.

use Drupal\ai\OperationType\Chat\ChatInput;
use Drupal\ai\OperationType\Chat\ChatMessage;

$messages = new ChatInput([
  new ChatMessage('user', 'Hello!'),
]);
$response =  \Drupal::service('ai.provider')->createInstance('openai')->chat($messages, 'gpt-4o')->getNormalized();
// Response would be a ChatMessage in this case.

Lets go through what is happening here and what each of these parameters means.

1. We use the ChatInput and ChatMessage namespaces since they are needed to construct a normalized input. If you check the input of any operation type, you will notice that they allow mixed, but also a specific interface. For normalized you always use the interface.
2. We construct the ChatInput with the ChatMessage inside of it, following the interfaces.
3. We use the getNormalized method in this case and get a ChatMessage back, instead of a raw output.

Why should I require/integrate the AI module instead of my own solution?

Here are some reasons why you should use our way to integrate your API call via the AI module instead of doing your own solution:

• The AI core module makes sure that the user only needs to input one Authentication/API key per service in a known and secure pattern.
• The AI core module enable you to hotswap one service to another. So if you realize that you want to move from OpenAI TTS to ElevenLabs for speech, its one line of code change.
• The AI core module makes sure that you do not need to understand any specific API of any AI integrator. You just need to understand the AI modules basic interfaces.
• The AI core module makes sure that you can use the end-users default API service at any time without having to provide configuration forms.
• But at the same time it also enables you to have a flexible form where the end-user can switch services with the click of a button if you want it.
• The AI core module takes care of exposing events and exceptions for you, meaning that your module will work with any type of integrator like prompt security modules, cost analysis modules etc.
• The AI core module takes care of logging any or every prompt or API call for the user of your module if they choose to.
• The AI core module also comes with API explorers, so you the end-user can replay a prompt/call for debugging or prompt engineering.
• The AI core is opinionated and makes sure that your implementation uses best practices for security like pre-moderation requests, so the end-users API access is not revoked. You can still opt-out from this for your specific implementation.
• Even in the edge cases where your AI service want to do something that the abstraction layer does not support, you can use it for authentication and get the raw client or even extend the providers to do what you want.