feat:OpenAI responses api & Provider Tools

src/Chat/Messages/Message.php

@@ -96,6 +96,11 @@ public function addMetadata(string $key, string|array|null $value): Message
         return $this;
     }
 
+    public function getMetadata(string $key): mixed
+    {
+        return $this->meta[$key] ?? null;
+    }
+
     /**
      * @return array<string, mixed>
      */
@@ -106,7 +111,7 @@ public function jsonSerialize(): array
             'content' => $this->getContent()
         ];
 
-        if ($this->getUsage() instanceof \NeuronAI\Chat\Messages\Usage) {
+        if ($this->getUsage() instanceof Usage) {
             $data['usage'] = $this->getUsage()->jsonSerialize();
         }
 

src/HandleTools.php

@@ -12,6 +12,7 @@
 use NeuronAI\Observability\Events\ToolCalled;
 use NeuronAI\Observability\Events\ToolCalling;
 use NeuronAI\Observability\Events\ToolsBootstrapped;
+use NeuronAI\Tools\ProviderToolInterface;
 use NeuronAI\Tools\ToolInterface;
 use NeuronAI\Tools\Toolkits\ToolkitInterface;
 
@@ -29,6 +30,9 @@ trait HandleTools
      */
     protected array $toolsBootstrapCache = [];
 
+    /**
+     * Global max tries for all tools.
+     */
     protected int $tollMaxTries = 5;
 
     /**
@@ -43,17 +47,17 @@ public function toolMaxTries(int $tries): Agent
     }
 
     /**
-     * Get the list of tools.
+     * Override to provide tools to the agent.
      *
-     * @return ToolInterface[]|ToolkitInterface[]
+     * @return array<ToolInterface|ToolkitInterface|ProviderToolInterface>
      */
     protected function tools(): array
     {
         return [];
     }
 
     /**
-     * @return ToolInterface[]|ToolkitInterface[]
+     * @return array<ToolInterface|ToolkitInterface|ProviderToolInterface>
      */
     public function getTools(): array
     {
@@ -121,15 +125,16 @@ public function bootstrapTools(): array
     /**
      * Add tools.
      *
+     * @param  ToolInterface|ToolkitInterface|ProviderToolInterface|array<ToolInterface|ToolkitInterface|ProviderToolInterface>  $tools
      * @throws AgentException
      */
-    public function addTool(ToolInterface|ToolkitInterface|array $tools): AgentInterface
+    public function addTool(ToolInterface|ToolkitInterface|ProviderToolInterface|array $tools): AgentInterface
     {
         $tools = \is_array($tools) ? $tools : [$tools];
 
         foreach ($tools as $t) {
-            if (! $t instanceof ToolInterface && ! $t instanceof ToolkitInterface) {
-                throw new AgentException('Tools must be an instance of ToolInterface or ToolkitInterface');
+            if (! $t instanceof ToolInterface && ! $t instanceof ToolkitInterface && ! $t instanceof ProviderToolInterface) {
+                throw new AgentException('Tools must be an instance of ToolInterface, ToolkitInterface, or ProviderToolInterface');
             }
             $this->tools[] = $t;
         }

src/Observability/AgentMonitoring.php

@@ -12,6 +12,7 @@
 use NeuronAI\Chat\Messages\Message;
 use NeuronAI\Observability\Events\AgentError;
 use NeuronAI\RAG\RAG;
+use NeuronAI\Tools\ProviderToolInterface;
 use NeuronAI\Tools\ToolInterface;
 use NeuronAI\Tools\Toolkits\ToolkitInterface;
 use NeuronAI\Tools\ToolPropertyInterface;
@@ -225,12 +226,11 @@ protected function getContext(Agent $agent): array
                 'provider' => $agent->resolveProvider()::class,
                 'instructions' => $agent->resolveInstructions(),
             ],
-            'Tools' => \array_map(
-                fn (ToolInterface|ToolkitInterface $tool) => $tool instanceof ToolInterface
-                    ? $mapTool($tool)
-                    : [$tool::class => \array_map($mapTool, $tool->tools())],
-                $agent->getTools()
-            ),
+            'Tools' => \array_map(fn (ToolInterface|ToolkitInterface|ProviderToolInterface $tool) => match (true) {
+                $tool instanceof ToolInterface => $mapTool($tool),
+                $tool instanceof ToolkitInterface => [$tool::class => \array_map($mapTool, $tool->tools())],
+                default => $tool->jsonSerialize(),
+            }, $agent->getTools()),
             //'Messages' => $agent->resolveChatHistory()->getMessages(),
         ];
     }

src/Observability/HandleToolEvents.php

@@ -8,6 +8,7 @@
 use NeuronAI\Observability\Events\ToolCalled;
 use NeuronAI\Observability\Events\ToolCalling;
 use NeuronAI\Observability\Events\ToolsBootstrapped;
+use NeuronAI\Tools\ProviderToolInterface;
 use NeuronAI\Tools\ToolInterface;
 
 trait HandleToolEvents
@@ -30,8 +31,12 @@ public function toolsBootstrapped(AgentInterface $agent, string $event, ToolsBoo
     {
         if (\array_key_exists($agent::class.'_tools_bootstrap', $this->segments) && $data->tools !== []) {
             $segment = $this->segments[$agent::class.'_tools_bootstrap']->end();
-            $segment->addContext('Tools', \array_reduce($data->tools, function (array $carry, ToolInterface $tool): array {
-                $carry[$tool->getName()] = $tool->getDescription();
+            $segment->addContext('Tools', \array_reduce($data->tools, function (array $carry, ToolInterface|ProviderToolInterface $tool): array {
+                if ($tool instanceof ProviderToolInterface) {
+                    $carry[$tool->getType()] = $tool->getOptions();
+                } else {
+                    $carry[$tool->getName()] = $tool->getDescription();
+                }
                 return $carry;
             }, []));
             $segment->addContext('Guidelines', $data->guidelines);

src/Providers/AIProviderInterface.php

@@ -28,6 +28,11 @@ public function setTools(array $tools): AIProviderInterface;
      */
     public function messageMapper(): MessageMapperInterface;
 
+    /**
+     * The component responsible for mapping the NeuronAI Tools to the AI provider format.
+     */
+    public function toolPayloadMapper(): ToolPayloadMapperInterface;
+
     /**
      * Send a prompt to the AI agent.
      *

src/Providers/AWS/BedrockRuntime.php

@@ -10,8 +10,8 @@
 use NeuronAI\Providers\AIProviderInterface;
 use NeuronAI\Providers\HandleWithTools;
 use NeuronAI\Providers\MessageMapperInterface;
+use NeuronAI\Providers\ToolPayloadMapperInterface;
 use NeuronAI\Tools\ToolInterface;
-use NeuronAI\Tools\ToolPropertyInterface;
 
 class BedrockRuntime implements AIProviderInterface
 {
@@ -23,6 +23,7 @@ class BedrockRuntime implements AIProviderInterface
     protected ?string $system = null;
 
     protected MessageMapperInterface $messageMapper;
+    protected ToolPayloadMapperInterface $toolPayloadMapper;
 
     public function __construct(
         protected BedrockRuntimeClient $bedrockRuntimeClient,
@@ -34,7 +35,6 @@ public function __construct(
     public function systemPrompt(?string $prompt): AIProviderInterface
     {
         $this->system = $prompt;
-
         return $this;
     }
 
@@ -43,6 +43,11 @@ public function messageMapper(): MessageMapperInterface
         return $this->messageMapper ?? $this->messageMapper = new MessageMapper();
     }
 
+    public function toolPayloadMapper(): ToolPayloadMapperInterface
+    {
+        return $this->toolPayloadMapper ?? $this->toolPayloadMapper = new ToolPayloadMapper();
+    }
+
     protected function createPayLoad(array $messages): array
     {
         $payload = [
@@ -57,49 +62,15 @@ protected function createPayLoad(array $messages): array
             $payload['inferenceConfig'] = $this->inferenceConfig;
         }
 
-        $toolSpecs = $this->generateToolsPayload();
+        $tools = $this->toolPayloadMapper()->map($this->tools);
 
-        if (\count($toolSpecs) > 0) {
-            $payload['toolConfig']['tools'] = $toolSpecs;
+        if ($tools !== []) {
+            $payload['toolConfig']['tools'] = $tools;
         }
 
         return $payload;
     }
 
-    protected function generateToolsPayload(): array
-    {
-        return \array_map(function (ToolInterface $tool): array {
-            $payload = [
-                'toolSpec' => [
-                    'name' => $tool->getName(),
-                    'description' => $tool->getDescription(),
-                    'inputSchema' => [
-                        'json' => [
-                            'type' => 'object',
-                            'properties' => new \stdClass(),
-                            'required' => [],
-                        ]
-                    ],
-                ],
-            ];
-
-            $properties = \array_reduce($tool->getProperties(), function (array $carry, ToolPropertyInterface $property): array {
-                $carry[$property->getName()] = $property->getJsonSchema();
-                return $carry;
-            }, []);
-
-            if (!empty($properties)) {
-                $payload['toolSpec']['inputSchema']['json'] = [
-                    'type' => 'object',
-                    'properties' => $properties,
-                    'required' => $tool->getRequiredProperties(),
-                ];
-            }
-
-            return $payload;
-        }, $this->tools);
-    }
-
     /**
      * @throws ProviderException
      */

src/Providers/AWS/MessageMapper.php

@@ -11,24 +11,22 @@
 
 class MessageMapper implements MessageMapperInterface
 {
-    protected array $mapping = [];
-
     public function map(array $messages): array
     {
-        $this->mapping = [];
+        $mapping = [];
 
         foreach ($messages as $message) {
-            match ($message::class) {
+            $mapping[] = match ($message::class) {
                 ToolCallResultMessage::class => $this->mapToolCallResult($message),
                 ToolCallMessage::class => $this->mapToolCall($message),
                 default => $this->mapMessage($message),
             };
         }
 
-        return $this->mapping;
+        return $mapping;
     }
 
-    protected function mapToolCallResult(ToolCallResultMessage $message): void
+    protected function mapToolCallResult(ToolCallResultMessage $message): array
     {
         $toolContents = [];
         foreach ($message->getTools() as $tool) {
@@ -46,13 +44,13 @@ protected function mapToolCallResult(ToolCallResultMessage $message): void
             ];
         }
 
-        $this->mapping[] = [
+        return [
             'role' => $message->getRole(),
             'content' => $toolContents,
         ];
     }
 
-    protected function mapToolCall(ToolCallMessage $message): void
+    protected function mapToolCall(ToolCallMessage $message): array
     {
         $toolCallContents = [];
 
@@ -66,15 +64,15 @@ protected function mapToolCall(ToolCallMessage $message): void
             ];
         }
 
-        $this->mapping[] = [
+        return [
             'role' => $message->getRole(),
             'content' => $toolCallContents,
         ];
     }
 
-    protected function mapMessage(Message $message): void
+    protected function mapMessage(Message $message): array
     {
-        $this->mapping[] = [
+        return [
             'role' => $message->getRole(),
             'content' => [['text' => $message->getContent()]],
         ];

src/Providers/AWS/ToolPayloadMapper.php

@@ -0,0 +1,61 @@
+<?php
+
+declare(strict_types=1);
+
+namespace NeuronAI\Providers\AWS;
+
+use NeuronAI\Exceptions\ProviderException;
+use NeuronAI\Providers\ToolPayloadMapperInterface;
+use NeuronAI\Tools\ProviderToolInterface;
+use NeuronAI\Tools\ToolInterface;
+use NeuronAI\Tools\ToolPropertyInterface;
+
+class ToolPayloadMapper implements ToolPayloadMapperInterface
+{
+    public function map(array $tools): array
+    {
+        $mapping = [];
+
+        foreach ($tools as $tool) {
+            $mapping[] = match (true) {
+                $tool instanceof ToolInterface => $this->mapTool($tool),
+                $tool instanceof ProviderToolInterface => throw new ProviderException('Bedrock Runtime does not support Provider Tools'),
+                default => throw new ProviderException('Could not map tool type '.$tool::class),
+            };
+        }
+
+        return $mapping;
+    }
+
+    protected function mapTool(ToolInterface $tool): array
+    {
+        $payload = [
+            'toolSpec' => [
+                'name' => $tool->getName(),
+                'description' => $tool->getDescription(),
+                'inputSchema' => [
+                    'json' => [
+                        'type' => 'object',
+                        'properties' => new \stdClass(),
+                        'required' => [],
+                    ]
+                ],
+            ],
+        ];
+
+        $properties = \array_reduce($tool->getProperties(), function (array $carry, ToolPropertyInterface $property): array {
+            $carry[$property->getName()] = $property->getJsonSchema();
+            return $carry;
+        }, []);
+
+        if (!empty($properties)) {
+            $payload['toolSpec']['inputSchema']['json'] = [
+                'type' => 'object',
+                'properties' => $properties,
+                'required' => $tool->getRequiredProperties(),
+            ];
+        }
+
+        return $payload;
+    }
+}