feat(OpenAI): Add 'tool_search' functionality.

src/Actions/Responses/CustomToolInputObjects.php

@@ -0,0 +1,29 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenAI\Actions\Responses;
+
+use OpenAI\Responses\Responses\Tool\CustomToolInputs\GrammarInput;
+use OpenAI\Responses\Responses\Tool\CustomToolInputs\TextInput;
+
+/**
+ * @phpstan-import-type TextInputType from TextInput
+ * @phpstan-import-type GrammarInputType from GrammarInput
+ *
+ * @phpstan-type CustomToolInputTypes TextInputType|GrammarInputType
+ * @phpstan-type CustomToolInputReturnType TextInput|GrammarInput
+ */
+final class CustomToolInputObjects
+{
+    /**
+     * @param  CustomToolInputTypes  $attributes
+     */
+    public static function parse(array $attributes): TextInput|GrammarInput
+    {
+        return match ($attributes['type']) {
+            'text' => TextInput::from($attributes),
+            'grammar' => GrammarInput::from($attributes),
+        };
+    }
+}

src/Actions/Responses/NamespaceToolObjects.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenAI\Actions\Responses;
+
+use OpenAI\Responses\Responses\Tool\NamespaceTools\CustomTool;
+use OpenAI\Responses\Responses\Tool\NamespaceTools\FunctionTool;
+
+/**
+ * @phpstan-import-type FunctionToolType from FunctionTool
+ * @phpstan-import-type CustomToolType from CustomTool
+ *
+ * @phpstan-type ResponseNamespaceToolObjectTypes array<int, FunctionToolType|CustomToolType>
+ * @phpstan-type ResponseNamespaceToolObjectReturnType array<int, FunctionTool|CustomTool>
+ */
+final class NamespaceToolObjects
+{
+    /**
+     * @param  ResponseNamespaceToolObjectTypes  $toolItems
+     * @return ResponseNamespaceToolObjectReturnType
+     */
+    public static function parse(array $toolItems): array
+    {
+        return array_map(
+            fn (array $tool): FunctionTool|CustomTool => match ($tool['type']) {
+                'function' => FunctionTool::from($tool),
+                'custom' => CustomTool::from($tool),
+            },
+            $toolItems,
+        );
+    }
+}

src/Actions/Responses/OutputObjects.php

@@ -16,6 +16,8 @@
 use OpenAI\Responses\Responses\Output\OutputMcpListTools;
 use OpenAI\Responses\Responses\Output\OutputMessage;
 use OpenAI\Responses\Responses\Output\OutputReasoning;
+use OpenAI\Responses\Responses\Output\OutputToolSearchCall;
+use OpenAI\Responses\Responses\Output\OutputToolSearchOutput;
 use OpenAI\Responses\Responses\Output\OutputWebSearchToolCall;
 
 /**
@@ -32,9 +34,11 @@
  * @phpstan-import-type OutputCodeInterpreterToolCallType from OutputCodeInterpreterToolCall
  * @phpstan-import-type OutputLocalShellCallType from OutputLocalShellCall
  * @phpstan-import-type OutputCustomToolCallType from OutputCustomToolCall
+ * @phpstan-import-type OutputToolSearchCallType from OutputToolSearchCall
+ * @phpstan-import-type OutputToolSearchOutputType from OutputToolSearchOutput
  *
- * @phpstan-type ResponseOutputObjectTypes array<int, OutputComputerToolCallType|OutputFileSearchToolCallType|OutputFunctionToolCallType|OutputMessageType|OutputReasoningType|OutputWebSearchToolCallType|OutputMcpListToolsType|OutputMcpApprovalRequestType|OutputMcpCallType|OutputImageGenerationToolCallType|OutputCodeInterpreterToolCallType|OutputLocalShellCallType|OutputCustomToolCallType>
- * @phpstan-type ResponseOutputObjectReturnType array<int, OutputMessage|OutputComputerToolCall|OutputFileSearchToolCall|OutputWebSearchToolCall|OutputFunctionToolCall|OutputReasoning|OutputMcpListTools|OutputMcpApprovalRequest|OutputMcpCall|OutputImageGenerationToolCall|OutputCodeInterpreterToolCall|OutputLocalShellCall|OutputCustomToolCall>
+ * @phpstan-type ResponseOutputObjectTypes array<int, OutputComputerToolCallType|OutputFileSearchToolCallType|OutputFunctionToolCallType|OutputMessageType|OutputReasoningType|OutputWebSearchToolCallType|OutputMcpListToolsType|OutputMcpApprovalRequestType|OutputMcpCallType|OutputImageGenerationToolCallType|OutputCodeInterpreterToolCallType|OutputLocalShellCallType|OutputCustomToolCallType|OutputToolSearchCallType|OutputToolSearchOutputType>
+ * @phpstan-type ResponseOutputObjectReturnType array<int, OutputMessage|OutputComputerToolCall|OutputFileSearchToolCall|OutputWebSearchToolCall|OutputFunctionToolCall|OutputReasoning|OutputMcpListTools|OutputMcpApprovalRequest|OutputMcpCall|OutputImageGenerationToolCall|OutputCodeInterpreterToolCall|OutputLocalShellCall|OutputCustomToolCall|OutputToolSearchCall|OutputToolSearchOutput>
  */
 final class OutputObjects
 {
@@ -45,7 +49,7 @@ final class OutputObjects
     public static function parse(array $outputItems): array
     {
         return array_map(
-            fn (array $item): OutputMessage|OutputComputerToolCall|OutputFileSearchToolCall|OutputWebSearchToolCall|OutputFunctionToolCall|OutputReasoning|OutputMcpListTools|OutputMcpApprovalRequest|OutputMcpCall|OutputImageGenerationToolCall|OutputCodeInterpreterToolCall|OutputLocalShellCall|OutputCustomToolCall => match ($item['type']) {
+            fn (array $item): OutputMessage|OutputComputerToolCall|OutputFileSearchToolCall|OutputWebSearchToolCall|OutputFunctionToolCall|OutputReasoning|OutputMcpListTools|OutputMcpApprovalRequest|OutputMcpCall|OutputImageGenerationToolCall|OutputCodeInterpreterToolCall|OutputLocalShellCall|OutputCustomToolCall|OutputToolSearchCall|OutputToolSearchOutput => match ($item['type']) {
                 'message' => OutputMessage::from($item),
                 'file_search_call' => OutputFileSearchToolCall::from($item),
                 'function_call' => OutputFunctionToolCall::from($item),
@@ -59,6 +63,9 @@ public static function parse(array $outputItems): array
                 'code_interpreter_call' => OutputCodeInterpreterToolCall::from($item),
                 'local_shell_call' => OutputLocalShellCall::from($item),
                 'custom_tool_call' => OutputCustomToolCall::from($item),
+                'tool_search_call' => OutputToolSearchCall::from($item),
+                'tool_search_output' => OutputToolSearchOutput::from($item),
+                default => throw new \UnexpectedValueException('Uh oh! We do not recognize this type. Please submit a bug to openai-php/client on GitHub!'),
             },
             $outputItems,
         );

src/Actions/Responses/ToolObjects.php

@@ -6,23 +6,29 @@
 
 use OpenAI\Responses\Responses\Tool\CodeInterpreterTool;
 use OpenAI\Responses\Responses\Tool\ComputerUseTool;
+use OpenAI\Responses\Responses\Tool\CustomTool;
 use OpenAI\Responses\Responses\Tool\FileSearchTool;
 use OpenAI\Responses\Responses\Tool\FunctionTool;
 use OpenAI\Responses\Responses\Tool\ImageGenerationTool;
+use OpenAI\Responses\Responses\Tool\NamespaceTool;
 use OpenAI\Responses\Responses\Tool\RemoteMcpTool;
+use OpenAI\Responses\Responses\Tool\ToolSearchTool;
 use OpenAI\Responses\Responses\Tool\WebSearchTool;
 
 /**
+ * @phpstan-import-type CodeInterpreterToolType from CodeInterpreterTool
  * @phpstan-import-type ComputerUseToolType from ComputerUseTool
+ * @phpstan-import-type CustomToolType from CustomTool
  * @phpstan-import-type FileSearchToolType from FileSearchTool
+ * @phpstan-import-type FunctionToolType from FunctionTool
  * @phpstan-import-type ImageGenerationToolType from ImageGenerationTool
+ * @phpstan-import-type NamespaceToolType from NamespaceTool
  * @phpstan-import-type RemoteMcpToolType from RemoteMcpTool
- * @phpstan-import-type FunctionToolType from FunctionTool
+ * @phpstan-import-type ToolSearchToolType from ToolSearchTool
  * @phpstan-import-type WebSearchToolType from WebSearchTool
- * @phpstan-import-type CodeInterpreterToolType from CodeInterpreterTool
  *
- * @phpstan-type ResponseToolObjectTypes array<int, ComputerUseToolType|FileSearchToolType|FunctionToolType|WebSearchToolType|ImageGenerationToolType|RemoteMcpToolType|CodeInterpreterToolType>
- * @phpstan-type ResponseToolObjectReturnType array<int, ComputerUseTool|FileSearchTool|FunctionTool|WebSearchTool|ImageGenerationTool|RemoteMcpTool|CodeInterpreterTool>
+ * @phpstan-type ResponseToolObjectTypes array<int, CodeInterpreterToolType|ComputerUseToolType|CustomToolType|FileSearchToolType|FunctionToolType|ImageGenerationToolType|NamespaceToolType|RemoteMcpToolType|ToolSearchToolType|WebSearchToolType>
+ * @phpstan-type ResponseToolObjectReturnType array<int, CodeInterpreterTool|ComputerUseTool|CustomTool|FileSearchTool|FunctionTool|ImageGenerationTool|NamespaceTool|RemoteMcpTool|ToolSearchTool|WebSearchTool>
  */
 final class ToolObjects
 {
@@ -33,14 +39,17 @@ final class ToolObjects
     public static function parse(array $toolItems): array
     {
         return array_map(
-            fn (array $tool): ComputerUseTool|FileSearchTool|FunctionTool|WebSearchTool|ImageGenerationTool|RemoteMcpTool|CodeInterpreterTool => match ($tool['type']) {
+            fn (array $tool): CodeInterpreterTool|ComputerUseTool|CustomTool|FileSearchTool|FunctionTool|ImageGenerationTool|NamespaceTool|RemoteMcpTool|ToolSearchTool|WebSearchTool => match ($tool['type']) {
                 'file_search' => FileSearchTool::from($tool),
                 'web_search', 'web_search_preview', 'web_search_preview_2025_03_11' => WebSearchTool::from($tool),
                 'function' => FunctionTool::from($tool),
                 'computer_use_preview' => ComputerUseTool::from($tool),
                 'image_generation' => ImageGenerationTool::from($tool),
                 'mcp' => RemoteMcpTool::from($tool),
                 'code_interpreter' => CodeInterpreterTool::from($tool),
+                'tool_search' => ToolSearchTool::from($tool),
+                'namespace' => NamespaceTool::from($tool),
+                'custom' => CustomTool::from($tool),
             },
             $toolItems,
         );

src/Responses/Responses/CreateResponse.php

@@ -25,13 +25,18 @@
 use OpenAI\Responses\Responses\Output\OutputMcpListTools;
 use OpenAI\Responses\Responses\Output\OutputMessage;
 use OpenAI\Responses\Responses\Output\OutputReasoning;
+use OpenAI\Responses\Responses\Output\OutputToolSearchCall;
+use OpenAI\Responses\Responses\Output\OutputToolSearchOutput;
 use OpenAI\Responses\Responses\Output\OutputWebSearchToolCall;
 use OpenAI\Responses\Responses\Tool\CodeInterpreterTool;
 use OpenAI\Responses\Responses\Tool\ComputerUseTool;
+use OpenAI\Responses\Responses\Tool\CustomTool;
 use OpenAI\Responses\Responses\Tool\FileSearchTool;
 use OpenAI\Responses\Responses\Tool\FunctionTool;
 use OpenAI\Responses\Responses\Tool\ImageGenerationTool;
+use OpenAI\Responses\Responses\Tool\NamespaceTool;
 use OpenAI\Responses\Responses\Tool\RemoteMcpTool;
+use OpenAI\Responses\Responses\Tool\ToolSearchTool;
 use OpenAI\Responses\Responses\Tool\WebSearchTool;
 use OpenAI\Responses\Responses\ToolChoice\FunctionToolChoice;
 use OpenAI\Responses\Responses\ToolChoice\HostedToolChoice;
@@ -47,6 +52,9 @@
  * @phpstan-import-type ResponseOutputObjectTypes from OutputObjects
  * @phpstan-import-type ResponseToolChoiceTypes from ToolChoiceObjects
  * @phpstan-import-type ResponseToolObjectTypes from ToolObjects
+ * @phpstan-import-type ResponseOutputObjectReturnType from OutputObjects
+ * @phpstan-import-type ResponseToolChoiceReturnType from ToolChoiceObjects
+ * @phpstan-import-type ResponseToolObjectReturnType from ToolObjects
  *
  * @phpstan-type InstructionsType array<int, mixed>|string|null
  * @phpstan-type CreateResponseType array{id: string, background?: bool|null, object: 'response', created_at: int, status: 'completed'|'failed'|'in_progress'|'incomplete', error: ErrorType|null, incomplete_details?: IncompleteDetailsType|null, instructions: InstructionsType, max_output_tokens?: int|null, max_tool_calls?: int|null, model: string, output: ResponseOutputObjectTypes, output_text: string|null, parallel_tool_calls: bool, previous_response_id?: string|null, prompt: ReferencePromptObjectType|null, prompt_cache_key?: string|null, reasoning?: ReasoningType|null, safety_identifier?: string|null, service_tier?: string|null, store?: bool|null, temperature?: float|null, text?: ResponseFormatType|null, tool_choice: ResponseToolChoiceTypes, tools: ResponseToolObjectTypes, top_logprobs?: int|null, top_p?: float|null, truncation?: 'auto'|'disabled'|null, usage?: UsageType|null, user?: string|null, verbosity?: string|null, metadata?: array<string, string>|null}
@@ -67,8 +75,8 @@ final class CreateResponse implements ResponseContract, ResponseHasMetaInformati
      * @param  'response'  $object
      * @param  'completed'|'failed'|'in_progress'|'incomplete'  $status
      * @param  array<int, mixed>|string|null  $instructions
-     * @param  array<int, OutputMessage|OutputComputerToolCall|OutputFileSearchToolCall|OutputWebSearchToolCall|OutputFunctionToolCall|OutputReasoning|OutputMcpListTools|OutputMcpApprovalRequest|OutputMcpCall|OutputImageGenerationToolCall|OutputCodeInterpreterToolCall|OutputLocalShellCall|OutputCustomToolCall>  $output
-     * @param  array<int, ComputerUseTool|FileSearchTool|FunctionTool|WebSearchTool|ImageGenerationTool|RemoteMcpTool|ImageGenerationTool|CodeInterpreterTool>  $tools
+     * @param  ResponseOutputObjectReturnType  $output
+     * @param  ResponseToolObjectReturnType  $tools
      * @param  'auto'|'disabled'|null  $truncation
      * @param  array<string, string>  $metadata
      */
@@ -187,7 +195,7 @@ public function toArray(): array
             'metadata' => $this->metadata ?? [],
             'model' => $this->model,
             'output' => array_map(
-                fn (OutputMessage|OutputComputerToolCall|OutputFileSearchToolCall|OutputWebSearchToolCall|OutputFunctionToolCall|OutputReasoning|OutputMcpListTools|OutputMcpApprovalRequest|OutputMcpCall|OutputImageGenerationToolCall|OutputCodeInterpreterToolCall|OutputLocalShellCall|OutputCustomToolCall $output): array => $output->toArray(),
+                fn (OutputMessage|OutputComputerToolCall|OutputFileSearchToolCall|OutputWebSearchToolCall|OutputFunctionToolCall|OutputReasoning|OutputMcpListTools|OutputMcpApprovalRequest|OutputMcpCall|OutputImageGenerationToolCall|OutputCodeInterpreterToolCall|OutputLocalShellCall|OutputCustomToolCall|OutputToolSearchCall|OutputToolSearchOutput $output): array => $output->toArray(),
                 $this->output
             ),
             'parallel_tool_calls' => $this->parallelToolCalls,
@@ -204,7 +212,7 @@ public function toArray(): array
                 ? $this->toolChoice
                 : $this->toolChoice->toArray(),
             'tools' => array_map(
-                fn (ComputerUseTool|FileSearchTool|FunctionTool|WebSearchTool|ImageGenerationTool|RemoteMcpTool|CodeInterpreterTool $tool): array => $tool->toArray(),
+                fn (ComputerUseTool|FileSearchTool|FunctionTool|WebSearchTool|ImageGenerationTool|RemoteMcpTool|CodeInterpreterTool|ToolSearchTool|NamespaceTool|CustomTool $tool): array => $tool->toArray(),
                 $this->tools
             ),
             'top_logprobs' => $this->topLogProbs,

src/Responses/Responses/Output/OutputToolSearchCall.php

@@ -0,0 +1,71 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenAI\Responses\Responses\Output;
+
+use OpenAI\Contracts\ResponseContract;
+use OpenAI\Responses\Concerns\ArrayAccessible;
+use OpenAI\Testing\Responses\Concerns\Fakeable;
+
+/**
+ * @phpstan-type OutputToolSearchCallType array{id: string, arguments: mixed, call_id: ?string, execution: 'server'|'client', status: 'in_progress'|'completed'|'incomplete', type: 'tool_search_call', created_by?: ?string}
+ *
+ * @implements ResponseContract<OutputToolSearchCallType>
+ */
+final class OutputToolSearchCall implements ResponseContract
+{
+    /**
+     * @use ArrayAccessible<OutputToolSearchCallType>
+     */
+    use ArrayAccessible;
+
+    use Fakeable;
+
+    /**
+     * @param  'server'|'client'  $execution
+     * @param  'in_progress'|'completed'|'incomplete'  $status
+     * @param  'tool_search_call'  $type
+     */
+    private function __construct(
+        public readonly string $id,
+        public readonly mixed $arguments,
+        public readonly ?string $callId,
+        public readonly string $execution,
+        public readonly string $status,
+        public readonly string $type,
+        public readonly ?string $createdBy,
+    ) {}
+
+    /**
+     * @param  OutputToolSearchCallType  $attributes
+     */
+    public static function from(array $attributes): self
+    {
+        return new self(
+            id: $attributes['id'],
+            arguments: $attributes['arguments'],
+            callId: $attributes['call_id'] ?? null,
+            execution: $attributes['execution'],
+            status: $attributes['status'],
+            type: $attributes['type'],
+            createdBy: $attributes['created_by'] ?? null,
+        );
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function toArray(): array
+    {
+        return [
+            'id' => $this->id,
+            'arguments' => $this->arguments,
+            'call_id' => $this->callId,
+            'execution' => $this->execution,
+            'status' => $this->status,
+            'type' => $this->type,
+            'created_by' => $this->createdBy,
+        ];
+    }
+}

src/Responses/Responses/Output/OutputToolSearchOutput.php

@@ -0,0 +1,89 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenAI\Responses\Responses\Output;
+
+use OpenAI\Actions\Responses\ToolObjects;
+use OpenAI\Contracts\ResponseContract;
+use OpenAI\Responses\Concerns\ArrayAccessible;
+use OpenAI\Responses\Responses\Tool\CodeInterpreterTool;
+use OpenAI\Responses\Responses\Tool\ComputerUseTool;
+use OpenAI\Responses\Responses\Tool\CustomTool;
+use OpenAI\Responses\Responses\Tool\FileSearchTool;
+use OpenAI\Responses\Responses\Tool\FunctionTool;
+use OpenAI\Responses\Responses\Tool\ImageGenerationTool;
+use OpenAI\Responses\Responses\Tool\NamespaceTool;
+use OpenAI\Responses\Responses\Tool\RemoteMcpTool;
+use OpenAI\Responses\Responses\Tool\ToolSearchTool;
+use OpenAI\Responses\Responses\Tool\WebSearchTool;
+use OpenAI\Testing\Responses\Concerns\Fakeable;
+
+/**
+ * @phpstan-import-type ResponseToolObjectTypes from ToolObjects
+ * @phpstan-import-type ResponseToolObjectReturnType from ToolObjects
+ *
+ * @phpstan-type OutputToolSearchOutputType array{id: string, call_id: ?string, execution: 'server'|'client', status: 'in_progress'|'completed'|'incomplete', tools: ResponseToolObjectTypes, type: 'tool_search_output', created_by?: ?string}
+ *
+ * @implements ResponseContract<OutputToolSearchOutputType>
+ */
+final class OutputToolSearchOutput implements ResponseContract
+{
+    /**
+     * @use ArrayAccessible<OutputToolSearchOutputType>
+     */
+    use ArrayAccessible;
+
+    use Fakeable;
+
+    /**
+     * @param  'server'|'client'  $execution
+     * @param  'in_progress'|'completed'|'incomplete'  $status
+     * @param  ResponseToolObjectReturnType  $tools
+     * @param  'tool_search_output'  $type
+     */
+    private function __construct(
+        public readonly string $id,
+        public readonly ?string $callId,
+        public readonly string $execution,
+        public readonly string $status,
+        public readonly array $tools,
+        public readonly string $type,
+        public readonly ?string $createdBy,
+    ) {}
+
+    /**
+     * @param  OutputToolSearchOutputType  $attributes
+     */
+    public static function from(array $attributes): self
+    {
+        return new self(
+            id: $attributes['id'],
+            callId: $attributes['call_id'] ?? null,
+            execution: $attributes['execution'],
+            status: $attributes['status'],
+            tools: ToolObjects::parse($attributes['tools']),
+            type: $attributes['type'],
+            createdBy: $attributes['created_by'] ?? null,
+        );
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public function toArray(): array
+    {
+        return [
+            'id' => $this->id,
+            'call_id' => $this->callId,
+            'execution' => $this->execution,
+            'status' => $this->status,
+            'tools' => array_map(
+                fn (CodeInterpreterTool|ComputerUseTool|CustomTool|FileSearchTool|FunctionTool|ImageGenerationTool|NamespaceTool|RemoteMcpTool|ToolSearchTool|WebSearchTool $tool): array => $tool->toArray(),
+                $this->tools,
+            ),
+            'type' => $this->type,
+            'created_by' => $this->createdBy,
+        ];
+    }
+}