feat: user message additional attributes (#411)

Author: sixlive

docs/providers/openai.md

@@ -83,4 +83,17 @@ Prism::text()
     ->withPrompt('Solve the equation 3x + 10 = 14.')
     ->withProviderTools([new ProviderTool(type: 'code_interpreter', options: ['container' => ['type' => 'auto']])])
     ->asText();
-```
+```
+
+### Additional Message Attributes
+
+Adding optional parameters to a `UserMessage` like the `name` field can be done through the `additionalAttributes` parameter.
+
+```php
+Prism::text()
+    ->using('openai', 'gpt-4.1')
+    ->withMessages([
+        new UserMessage('Who are you?', additionalAttributes: ['name' => 'TJ']),
+    ])
+    ->asText()
+```

src/Providers/OpenAI/Maps/MessageMap.php

@@ -87,6 +87,7 @@ protected function mapUserMessage(UserMessage $message): void
                 ...self::mapDocumentParts($message->documents()),
                 ...self::mapFileParts($message->files()),
             ],
+            ...$message->additionalAttributes,
         ];
     }
 

src/ValueObjects/Messages/UserMessage.php

@@ -17,10 +17,12 @@ class UserMessage implements Message
 
     /**
      * @param  array<int, Text|Image|Document|OpenAIFile>  $additionalContent
+     * @param  array<string, mixed>  $additionalAttributes
      */
     public function __construct(
         public readonly string $content,
-        public array $additionalContent = []
+        public array $additionalContent = [],
+        public readonly array $additionalAttributes = [],
     ) {
         $this->additionalContent[] = new Text($content);
     }

tests/Providers/OpenAI/MessageMapTest.php

@@ -31,6 +31,23 @@
     ]]);
 });
 
+it('maps user messages with additional attributes', function (): void {
+    $messageMap = new MessageMap(
+        messages: [
+            new UserMessage('Who are you?', additionalAttributes: ['name' => 'TJ']),
+        ],
+        systemPrompts: []
+    );
+
+    expect($messageMap())->toBe([[
+        'role' => 'user',
+        'content' => [
+            ['type' => 'input_text', 'text' => 'Who are you?'],
+        ],
+        'name' => 'TJ',
+    ]]);
+});
+
 it('maps user messages with images from path', function (): void {
     $messageMap = new MessageMap(
         messages: [