refactor: message content file handling [BC BREAK]

README.md

@@ -552,9 +552,9 @@ $messages = new MessageBag(
     Message::forSystem('You are an image analyzer bot that helps identify the content of images.'),
     Message::ofUser(
         'Describe the image as a comedian would do it.',
-        new Image(dirname(__DIR__).'/tests/Fixture/image.jpg'), // Path to an image file
-        new Image('https://foo.com/bar.png'), // URL to an image
-        new Image('data:image/png;base64,...'), // Data URL of an image
+        Image::fromFile(dirname(__DIR__).'/tests/Fixture/image.jpg'), // Path to an image file
+        Image::fromDataUrl('data:image/png;base64,...'), // Data URL of an image
+        new ImageUrl('https://foo.com/bar.png'), // URL to an image
     ),
 );
 $response = $chain->call($messages);
@@ -579,7 +579,7 @@ use PhpLlm\LlmChain\Model\Message\MessageBag;
 $messages = new MessageBag(
     Message::ofUser(
         'What is this recording about?',
-        Audio:fromFile(dirname(__DIR__).'/tests/Fixture/audio.mp3'), // Path to an audio file
+        Audio::fromFile(dirname(__DIR__).'/tests/Fixture/audio.mp3'), // Path to an audio file
     ),
 );
 $response = $chain->call($messages);

composer.json

@@ -15,6 +15,7 @@
     ],
     "require": {
         "php": ">=8.2",
+        "ext-fileinfo": "*",
         "oskarstark/enum-helper": "^1.5",
         "phpdocumentor/reflection-docblock": "^5.4",
         "phpstan/phpdoc-parser": "^2.1",

examples/audio-transcript-whisper.php

@@ -2,7 +2,7 @@
 
 use PhpLlm\LlmChain\Bridge\OpenAI\PlatformFactory;
 use PhpLlm\LlmChain\Bridge\OpenAI\Whisper;
-use PhpLlm\LlmChain\Bridge\OpenAI\Whisper\File;
+use PhpLlm\LlmChain\Model\Message\Content\Audio;
 use Symfony\Component\Dotenv\Dotenv;
 
 require_once dirname(__DIR__).'/vendor/autoload.php';
@@ -15,7 +15,7 @@
 
 $platform = PlatformFactory::create($_ENV['OPENAI_API_KEY']);
 $model = new Whisper();
-$file = new File(dirname(__DIR__).'/tests/Fixture/audio.mp3');
+$file = Audio::fromFile(dirname(__DIR__).'/tests/Fixture/audio.mp3');
 
 $response = $platform->request($model, $file);
 

examples/image-describer-binary-gemini.php

@@ -24,7 +24,7 @@
     Message::forSystem('You are an image analyzer bot that helps identify the content of images.'),
     Message::ofUser(
         'Describe the image as a comedian would do it.',
-        new Image(dirname(__DIR__).'/tests/Fixture/image.jpg'),
+        Image::fromFile(dirname(__DIR__).'/tests/Fixture/image.jpg'),
     ),
 );
 $response = $chain->call($messages);

examples/image-describer-binary.php

@@ -24,7 +24,7 @@
     Message::forSystem('You are an image analyzer bot that helps identify the content of images.'),
     Message::ofUser(
         'Describe the image as a comedian would do it.',
-        new Image(dirname(__DIR__).'/tests/Fixture/image.jpg'),
+        Image::fromFile(dirname(__DIR__).'/tests/Fixture/image.jpg'),
     ),
 );
 $response = $chain->call($messages);

examples/image-describer-url.php

@@ -3,7 +3,7 @@
 use PhpLlm\LlmChain\Bridge\OpenAI\GPT;
 use PhpLlm\LlmChain\Bridge\OpenAI\PlatformFactory;
 use PhpLlm\LlmChain\Chain;
-use PhpLlm\LlmChain\Model\Message\Content\Image;
+use PhpLlm\LlmChain\Model\Message\Content\ImageUrl;
 use PhpLlm\LlmChain\Model\Message\Message;
 use PhpLlm\LlmChain\Model\Message\MessageBag;
 use Symfony\Component\Dotenv\Dotenv;
@@ -24,7 +24,7 @@
     Message::forSystem('You are an image analyzer bot that helps identify the content of images.'),
     Message::ofUser(
         'Describe the image as a comedian would do it.',
-        new Image('https://upload.wikimedia.org/wikipedia/commons/thumb/3/31/Webysther_20160423_-_Elephpant.svg/350px-Webysther_20160423_-_Elephpant.svg.png'),
+        new ImageUrl('https://upload.wikimedia.org/wikipedia/commons/thumb/3/31/Webysther_20160423_-_Elephpant.svg/350px-Webysther_20160423_-_Elephpant.svg.png'),
     ),
 );
 $response = $chain->call($messages);

src/Bridge/Azure/OpenAI/WhisperModelClient.php

@@ -5,7 +5,7 @@
 namespace PhpLlm\LlmChain\Bridge\Azure\OpenAI;
 
 use PhpLlm\LlmChain\Bridge\OpenAI\Whisper;
-use PhpLlm\LlmChain\Bridge\OpenAI\Whisper\File;
+use PhpLlm\LlmChain\Model\Message\Content\Audio;
 use PhpLlm\LlmChain\Model\Model;
 use PhpLlm\LlmChain\Platform\ModelClient;
 use Symfony\Component\HttpClient\EventSourceHttpClient;
@@ -34,12 +34,12 @@ public function __construct(
 
     public function supports(Model $model, object|array|string $input): bool
     {
-        return $model instanceof Whisper && $input instanceof File;
+        return $model instanceof Whisper && $input instanceof Audio;
     }
 
     public function request(Model $model, object|array|string $input, array $options = []): ResponseInterface
     {
-        assert($input instanceof File);
+        assert($input instanceof Audio);
 
         $url = sprintf('https://%s/openai/deployments/%s/audio/translations', $this->baseUrl, $this->deployment);
 
@@ -51,7 +51,7 @@ public function request(Model $model, object|array|string $input, array $options
             'query' => ['api-version' => $this->apiVersion],
             'body' => array_merge($options, $model->getOptions(), [
                 'model' => $model->getName(),
-                'file' => fopen($input->path, 'r'),
+                'file' => $input->asResource(),
             ]),
         ]);
     }

src/Bridge/Google/GooglePromptConverter.php

@@ -12,8 +12,6 @@
 use PhpLlm\LlmChain\Model\Message\Role;
 use PhpLlm\LlmChain\Model\Message\UserMessage;
 
-use function Symfony\Component\String\u;
-
 final class GooglePromptConverter
 {
     /**
@@ -63,8 +61,8 @@ private function convertMessage(MessageInterface $message): array
                 }
                 if ($content instanceof Image) {
                     $parts[] = ['inline_data' => [
-                        'mime_type' => u($content->url)->after('data:')->before(';')->toString(),
-                        'data' => u($content->url)->after('base64,')->toString(),
+                        'mime_type' => $content->getFormat(),
+                        'data' => $content->asBase64(),
                     ]];
                 }
             }

src/Bridge/Meta/LlamaPromptConverter.php

@@ -6,7 +6,7 @@
 
 use PhpLlm\LlmChain\Exception\RuntimeException;
 use PhpLlm\LlmChain\Model\Message\AssistantMessage;
-use PhpLlm\LlmChain\Model\Message\Content\Image;
+use PhpLlm\LlmChain\Model\Message\Content\ImageUrl;
 use PhpLlm\LlmChain\Model\Message\Content\Text;
 use PhpLlm\LlmChain\Model\Message\MessageBagInterface;
 use PhpLlm\LlmChain\Model\Message\SystemMessage;
@@ -60,7 +60,7 @@ public function convertMessage(UserMessage|SystemMessage|AssistantMessage $messa
                     $contentParts[] = $value->text;
                 }
 
-                if ($value instanceof Image) {
+                if ($value instanceof ImageUrl) {
                     $contentParts[] = $value->url;
                 }
             }
@@ -70,7 +70,7 @@ public function convertMessage(UserMessage|SystemMessage|AssistantMessage $messa
                 $contentParts[] = $value->text;
             }
 
-            if ($value instanceof Image) {
+            if ($value instanceof ImageUrl) {
                 $contentParts[] = $value->url;
             }
         } else {

src/Bridge/OpenAI/Whisper/ModelClient.php

@@ -5,6 +5,7 @@
 namespace PhpLlm\LlmChain\Bridge\OpenAI\Whisper;
 
 use PhpLlm\LlmChain\Bridge\OpenAI\Whisper;
+use PhpLlm\LlmChain\Model\Message\Content\Audio;
 use PhpLlm\LlmChain\Model\Model;
 use PhpLlm\LlmChain\Platform\ModelClient as BaseModelClient;
 use Symfony\Contracts\HttpClient\HttpClientInterface;
@@ -23,19 +24,19 @@ public function __construct(
 
     public function supports(Model $model, object|array|string $input): bool
     {
-        return $model instanceof Whisper && $input instanceof File;
+        return $model instanceof Whisper && $input instanceof Audio;
     }
 
     public function request(Model $model, object|array|string $input, array $options = []): ResponseInterface
     {
-        assert($input instanceof File);
+        assert($input instanceof Audio);
 
         return $this->httpClient->request('POST', 'https://api.openai.com/v1/audio/transcriptions', [
             'auth_bearer' => $this->apiKey,
             'headers' => ['Content-Type' => 'multipart/form-data'],
             'body' => array_merge($options, $model->getOptions(), [
                 'model' => $model->getName(),
-                'file' => fopen($input->path, 'r'),
+                'file' => $input->asResource(),
             ]),
         ]);
     }

src/Bridge/OpenAI/Whisper/ResponseConverter.php

@@ -5,6 +5,7 @@
 namespace PhpLlm\LlmChain\Bridge\OpenAI\Whisper;
 
 use PhpLlm\LlmChain\Bridge\OpenAI\Whisper;
+use PhpLlm\LlmChain\Model\Message\Content\Audio;
 use PhpLlm\LlmChain\Model\Model;
 use PhpLlm\LlmChain\Model\Response\ResponseInterface as LlmResponse;
 use PhpLlm\LlmChain\Model\Response\TextResponse;
@@ -15,7 +16,7 @@ final class ResponseConverter implements BaseResponseConverter
 {
     public function supports(Model $model, object|array|string $input): bool
     {
-        return $model instanceof Whisper && $input instanceof File;
+        return $model instanceof Whisper && $input instanceof Audio;
     }
 
     public function convert(HttpResponse $response, array $options = []): LlmResponse

src/Model/Message/Content/Audio.php

@@ -4,42 +4,8 @@
 
 namespace PhpLlm\LlmChain\Model\Message\Content;
 
-use PhpLlm\LlmChain\Exception\InvalidArgumentException;
-
-use function Symfony\Component\String\u;
-
-final readonly class Audio implements Content
+final readonly class Audio extends File implements Content
 {
-    public function __construct(
-        public string $data,
-        public string $format,
-    ) {
-    }
-
-    public static function fromDataUrl(string $dataUrl): self
-    {
-        if (!str_starts_with($dataUrl, 'data:audio/')) {
-            throw new InvalidArgumentException('Invalid audio data URL format.');
-        }
-
-        return new self(
-            u($dataUrl)->after('base64,')->toString(),
-            u($dataUrl)->after('data:audio/')->before(';base64,')->toString(),
-        );
-    }
-
-    public static function fromFile(string $filePath): self
-    {
-        if (!is_readable($filePath) || false === $audioData = file_get_contents($filePath)) {
-            throw new InvalidArgumentException(sprintf('The file "%s" does not exist or is not readable.', $filePath));
-        }
-
-        return new self(
-            base64_encode($audioData),
-            pathinfo($filePath, PATHINFO_EXTENSION)
-        );
-    }
-
     /**
      * @return array{type: 'input_audio', input_audio: array{data: string, format: string}}
      */
@@ -48,8 +14,12 @@ public function jsonSerialize(): array
         return [
             'type' => 'input_audio',
             'input_audio' => [
-                'data' => $this->data,
-                'format' => $this->format,
+                'data' => $this->asBase64(),
+                'format' => match ($this->getFormat()) {
+                    'audio/mpeg' => 'mp3',
+                    'audio/wav' => 'wav',
+                    default => $this->getFormat(),
+                },
             ],
         ];
     }

src/Model/Message/Content/File.php

@@ -0,0 +1,76 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpLlm\LlmChain\Model\Message\Content;
+
+use PhpLlm\LlmChain\Exception\InvalidArgumentException;
+
+use function Symfony\Component\String\u;
+
+readonly class File
+{
+    final public function __construct(
+        private string|\Closure $data,
+        private string $format,
+        private ?string $path = null,
+    ) {
+    }
+
+    public static function fromDataUrl(string $dataUrl): static
+    {
+        if (!str_starts_with($dataUrl, 'data:')) {
+            throw new InvalidArgumentException('Invalid audio data URL format.');
+        }
+
+        return new static(
+            base64_decode(u($dataUrl)->after('base64,')->toString()),
+            u($dataUrl)->after('data:')->before(';base64,')->toString(),
+        );
+    }
+
+    public static function fromFile(string $path): static
+    {
+        if (!is_readable($path)) {
+            throw new \InvalidArgumentException(sprintf('The file "%s" does not exist or is not readable.', $path));
+        }
+
+        return new static(
+            fn () => file_get_contents($path),
+            mime_content_type($path),
+            $path,
+        );
+    }
+
+    public function getFormat(): string
+    {
+        return $this->format;
+    }
+
+    public function asBinary(): string
+    {
+        return $this->data instanceof \Closure ? ($this->data)() : $this->data;
+    }
+
+    public function asBase64(): string
+    {
+        return base64_encode($this->asBinary());
+    }
+
+    public function asDataUrl(): string
+    {
+        return sprintf('data:%s;base64,%s', $this->format, $this->asBase64());
+    }
+
+    /**
+     * @return resource|false
+     */
+    public function asResource()
+    {
+        if (null === $this->path) {
+            throw new \RuntimeException('You can only get a resource after creating fromFile.');
+        }
+
+        return fopen($this->path, 'r');
+    }
+}