feat: audio support (#189)

Author: chr-hertel

README.md

@@ -73,7 +73,7 @@ The core feature of LLM Chain is to interact with language models via messages.
 a **MessageBag** to a **Chain**, which takes care of LLM invocation and response handling.
 
 Messages can be of different types, most importantly `UserMessage`, `SystemMessage`, or `AssistantMessage`, and can also
-have different content types, like `Text` or `Image`.
+have different content types, like `Text`, `Image` or `Audio`.
 
 #### Example Chain call with messages
 
@@ -453,13 +453,13 @@ use PhpLlm\LlmChain\Model\Message\Content\Image;
 use PhpLlm\LlmChain\Model\Message\Message;
 use PhpLlm\LlmChain\Model\Message\MessageBag;
 
-// Initialize Platoform, LLM & Chain
+// Initialize Platform, LLM & Chain
 
 $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.png'), // Path to an image file
+        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
     ),
@@ -472,6 +472,30 @@ $response = $chain->call($messages);
 1. **Image Description**: [image-describer-binary.php](examples/image-describer-binary.php) (with binary file)
 1. **Image Description**: [image-describer-url.php](examples/image-describer-url.php) (with URL)
 
+### Audio Processing
+
+Similar to images, some LLMs also support audio as input, which is just another `Content` type within the `UserMessage`:
+
+```php
+use PhpLlm\LlmChain\Model\Message\Content\Audio;
+use PhpLlm\LlmChain\Model\Message\Message;
+use PhpLlm\LlmChain\Model\Message\MessageBag;
+
+// Initialize Platform, LLM & Chain
+
+$messages = new MessageBag(
+    Message::ofUser(
+        'What is this recording about?',
+        new Audio(dirname(__DIR__).'/tests/Fixture/audio.mp3'), // Path to an audio file
+    ),
+);
+$response = $chain->call($messages);
+```
+
+#### Code Examples
+
+1. **Audio Description**: [audio-describer.php](examples/audio-describer.php)
+
 ### Embeddings
 
 Creating embeddings of word, sentences or paragraphs is a typical use case around the interaction with LLMs and
@@ -617,3 +641,10 @@ Contributions are always welcome, so feel free to join the development of this l
 [![LLM Chain Contributors](https://contrib.rocks/image?repo=php-llm/llm-chain 'LLM Chain Contributors')](https://github.com/php-llm/llm-chain/graphs/contributors)
 
 Made with [contrib.rocks](https://contrib.rocks).
+
+### Fixture Licenses
+
+For testing multi-modal features, the repository contains binary media content, with the following owners and licenses:
+
+* `tests/Fixture/image.jpg`: Chris F., Creative Commons, see [pexels.com](https://www.pexels.com/photo/blauer-und-gruner-elefant-mit-licht-1680755/)
+* `tests/Fixture/audio.mp3`: davidbain, Creative Commons, see [freesound.org](https://freesound.org/people/davidbain/sounds/136777/)

examples/audio-describer.php

@@ -0,0 +1,31 @@
+<?php
+
+use PhpLlm\LlmChain\Bridge\OpenAI\GPT;
+use PhpLlm\LlmChain\Bridge\OpenAI\PlatformFactory;
+use PhpLlm\LlmChain\Chain;
+use PhpLlm\LlmChain\Model\Message\Content\Audio;
+use PhpLlm\LlmChain\Model\Message\Message;
+use PhpLlm\LlmChain\Model\Message\MessageBag;
+use Symfony\Component\Dotenv\Dotenv;
+
+require_once dirname(__DIR__).'/vendor/autoload.php';
+(new Dotenv())->loadEnv(dirname(__DIR__).'/.env');
+
+if (empty($_ENV['OPENAI_API_KEY'])) {
+    echo 'Please set the OPENAI_API_KEY environment variable.'.PHP_EOL;
+    exit(1);
+}
+
+$platform = PlatformFactory::create($_ENV['OPENAI_API_KEY']);
+$llm = new GPT(GPT::GPT_4O_AUDIO);
+
+$chain = new Chain($platform, $llm);
+$messages = new MessageBag(
+    Message::ofUser(
+        'What is this recording about?',
+        new Audio(dirname(__DIR__).'/tests/Fixture/audio.mp3'),
+    ),
+);
+$response = $chain->call($messages);
+
+echo $response->getContent().PHP_EOL;

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.png'),
+        new Image(dirname(__DIR__).'/tests/Fixture/image.jpg'),
     ),
 );
 $response = $chain->call($messages);

src/Bridge/Anthropic/Claude.php

@@ -32,6 +32,11 @@ public function getOptions(): array
         return $this->options;
     }
 
+    public function supportsAudioInput(): bool
+    {
+        return false;
+    }
+
     public function supportsImageInput(): bool
     {
         return false; // it does, but implementation here is still open.

src/Bridge/Meta/Llama.php

@@ -42,6 +42,11 @@ public function getOptions(): array
         return $this->options;
     }
 
+    public function supportsAudioInput(): bool
+    {
+        return false;
+    }
+
     public function supportsImageInput(): bool
     {
         return false; // it does, but implementation here is still open.

src/Bridge/OpenAI/GPT.php

@@ -14,6 +14,7 @@ final class GPT implements LanguageModel
     public const GPT_4_TURBO = 'gpt-4-turbo';
     public const GPT_4O = 'gpt-4o';
     public const GPT_4O_MINI = 'gpt-4o-mini';
+    public const GPT_4O_AUDIO = 'gpt-4o-audio-preview';
     public const O1_MINI = 'o1-mini';
     public const O1_PREVIEW = 'o1-preview';
 
@@ -23,9 +24,14 @@ final class GPT implements LanguageModel
     public function __construct(
         private readonly string $version = self::GPT_4O,
         private readonly array $options = ['temperature' => 1.0],
+        private bool $supportsAudioInput = false,
         private bool $supportsImageInput = false,
         private bool $supportsStructuredOutput = false,
     ) {
+        if (false === $this->supportsAudioInput) {
+            $this->supportsAudioInput = self::GPT_4O_AUDIO === $this->version;
+        }
+
         if (false === $this->supportsImageInput) {
             $this->supportsImageInput = in_array($this->version, [self::GPT_4_TURBO, self::GPT_4O, self::GPT_4O_MINI, self::O1_MINI, self::O1_PREVIEW], true);
         }
@@ -45,6 +51,11 @@ public function getOptions(): array
         return $this->options;
     }
 
+    public function supportsAudioInput(): bool
+    {
+        return $this->supportsImageInput;
+    }
+
     public function supportsImageInput(): bool
     {
         return $this->supportsImageInput;

src/Chain.php

@@ -60,6 +60,10 @@ public function call(MessageBagInterface $messages, array $options = []): Respon
         $messages = $input->messages;
         $options = $input->getOptions();
 
+        if ($messages->containsAudio() && !$llm->supportsAudioInput()) {
+            throw MissingModelSupport::forAudioInput($llm::class);
+        }
+
         if ($messages->containsImage() && !$llm->supportsImageInput()) {
             throw MissingModelSupport::forImageInput($llm::class);
         }

src/Exception/MissingModelSupport.php

@@ -16,6 +16,11 @@ public static function forToolCalling(string $model): self
         return new self($model, 'tool calling');
     }
 
+    public static function forAudioInput(string $model): self
+    {
+        return new self($model, 'audio input');
+    }
+
     public static function forImageInput(string $model): self
     {
         return new self($model, 'image input');

src/Model/LanguageModel.php

@@ -6,6 +6,8 @@
 
 interface LanguageModel extends Model
 {
+    public function supportsAudioInput(): bool;
+
     public function supportsImageInput(): bool;
 
     public function supportsStreaming(): bool;

src/Model/Message/Content/Audio.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpLlm\LlmChain\Model\Message\Content;
+
+use PhpLlm\LlmChain\Exception\InvalidArgumentException;
+
+final readonly class Audio implements Content
+{
+    public function __construct(
+        public string $path,
+    ) {
+        if (!is_readable($path) || false === file_get_contents($path)) {
+            throw new InvalidArgumentException(sprintf('The file "%s" does not exist or is not readable.', $path));
+        }
+    }
+
+    /**
+     * @return array{type: 'input_audio', input_audio: array{data: string, format: string}}
+     */
+    public function jsonSerialize(): array
+    {
+        $data = file_get_contents($this->path);
+        $format = pathinfo($this->path, PATHINFO_EXTENSION);
+
+        return [
+            'type' => 'input_audio',
+            'input_audio' => [
+                'data' => base64_encode($data),
+                'format' => $format,
+            ],
+        ];
+    }
+}