Research normalize function calling in Chat operator

Draft merge request here: https://git.drupalcode.org/project/ai/-/merge_requests/277

I will set this as in review for now, but we will not merge it until we have at least 2-3 providers prepared for it.

This approach looks well thought out and aligns well with the Drupal way of abstracting things. I just want to clarify a few points to make sure my understanding is correct:

1. From what I gather, the approach involves creating plugins to expose functions that can be used in AI providers as function calls. These plugins essentially act as the lowest level of actions that can be executed as AI functions. I think this is a great opportunity to not only use them for AI providers but also extend them for other use cases, like agents, MCP tools, or even other integrations.
2. Using the ChatTrait’s getTools() setTools(), it seems all provider implementations will have these methods (as base class uses this trait). If a provider doesn’t implement function calling, this wouldn’t lead to any breaking changes - this is important to make sure that its not breaking.
3. Finally, it seems that AI providers themselves are responsible for implementing the actual function calling logic. So, if getTools() returns functions, the provider would handle their execution in its own way (load the plugin and then execute). So what they have to take care of is 1) register the functions and 2) if response has function calls, then call them right.

If all of the above is accurate, I think this is an excellent, drupal-friendly abstraction that provides flexibility. The only concern would be ensuring it doesn't introduce any breaking changes for providers that either don’t implement or don’t support function calling.

I think the general approach is good but have a few smaller suggestions before this gets merged. Some are definitely just suggestions and optional while others are things that probably need doing.

1. Use HEREDOC style strings for form values rather than lots of   and string concatenation?
2. createFromArray in ToolsFunctionInput and ToolsPropertyInput don't actually create. They should either be made static and create the objects (e.g. DateTimePlus) or be renamed to setFromArray or similar. Also, because they don't create a new object, they don't clear out old values if the key isn't set in the array passed in. If this is intentional then maybe addFromArray would be better but I suspect one of the other two options is the intent.
3. ToolsFunctionOutput::setArgument and ToolsFunctionOutput::setArguments - set* functions normally update a value or have a key to potentially update a value. These always add to the existing array which isn't consistent with the other functions.
4. If a property is required then the check is whether it is NULL. In PHP a required function parameter can be explicitly passed NULL (depending on types). Are we happy with this difference? If so then it should be documented
5. ToolsFunctionInputInterface - make it clearer that the name is a machine name so that translated names aren't passed in
6. The API used for the Weather tool is only free for non-commercial use so probably shouldn't be included in the generic AI module for everyone (or at the very least this should be made clear but I think it should probably be removed).

It might be worth taking inspiration from how the core Context API works for this. In particular, I think it makes sense:

1. Move the FunctionProperty definitions into the FunctionCall definition. This would give you visibility into the FunctionCall props prior to instantiating the plugin. An example context definition in another plugin:
   

   context_definitions: [
       'entity' => new ContextDefinition(
         data_type: 'entity',
         label: new TranslatableMarkup("Entity"),
         required: FALSE,
         description: new TranslatableMarkup("The contextual entity that can be used for token replacements.")
       ),
       'recipient' => new ContextDefinition(
         data_type: 'email',
         label: new TranslatableMarkup("Recipient"),
         description: new TranslatableMarkup("The email address to which the message should be sent.")
       ),
       'subject' => new ContextDefinition(
         data_type: 'string',
         label: new TranslatableMarkup("Subject"),
         description: new TranslatableMarkup("The subject of the message.")
       ),
       'message' => new ContextDefinition(
         data_type: 'string',
         label: new TranslatableMarkup("Message"),
         description: new TranslatableMarkup("The message that should be sent.")
       ),
     ]
   

2. Additionally we could tap into cores DataType API and 'Constraints', similarly to Contexts. This would make it easier to describe and reuse existing property types, and set more advanced rules like 'string' with max length 84. For example:
   

     constraints: [
       "ComplexData" => [
         "value" => [
           "Length" => ["max" => 84],
         ],
       ],
     ]
   

3. Consider interfacing/extending Drupal\Core\Executable\ExecutablePluginBase and/or Drupal\Core\Executable\ExecutableInterface, though ExecutablePluginBase does have an implied config layer that might not really align with properties

Looks like we might also want FunctionCall Attribute to extend the Drupal\Component\Plugin\Attribute\Plugin class, and then the FunctionProperty might more closely reflect the changes 📌 Convert ContextDefinition plugin discovery to attributes Closed: won't fix in regards to using constraints and what have you.

Thanks Mark!

1. Moved to an issue here: 📌 Use HEREDOC style string for AI API Explorer Active
2. Renamed.
3. Renamed.
4. It should just do a check if its available, so the check for value is gone.
5. Fixed the comments.
6. Moved both to the test module we have, that is hidden, so people can see the code for reference, but not use it.

Hey @michaellander - I've been checking this internally and also reading up on the Context/DataType API and this definitely makes sense as long as we can map everything correctly and just give some good warning nudges with what natural data_types you can use!

The thing I'm missing from the ContextDefinition that is important for (AI) context is example values and I'm trying to figure out how to get that in there, without creating some ugly solution of setting it as a custom constraint. Any idea?

Also, how would it work with something like a complex type like Entity? Should there be some abstraction to map these specific for function calling, since the providers only will give back natural types - like a string of node:1:en or something like and then upcasting it?

E-mail and others that are based on a primitive base would be simple to just map to its primitive - with some mapping like float and decimal to number, integer to int etc.

With this now merged into 1.1, I think we should close this issue and work off separate issues for bugs/features/etc.

Right you are @michaellander - This is merged into 1.1.x-dev!

Automatically closed - issue fixed for 2 weeks with no activity.