feat: add support for hugging face inference api

Author: chr-hertel

.env

@@ -25,6 +25,9 @@ AZURE_OPENAI_KEY=
 AZURE_LLAMA_BASEURL=
 AZURE_LLAMA_KEY=
 
+# Hugging Face Access Token
+HUGGINGFACE_KEY=
+
 # For using OpenRouter
 OPENROUTER_KEY=
 

Makefile

@@ -23,6 +23,10 @@ coverage:
 
 run-examples:
 	./example
+	./huggingface
+
+make huggingface-models:
+	php examples/huggingface/_model-listing.php
 
 ci: ci-stable
 

README.md

@@ -1,9 +1,9 @@
 # LLM Chain
 
-PHP library for building LLM-based features and applications.
+PHP library for building LLM-based and AI-based features and applications.
 
-This library is not a stable yet, but still rather experimental. Feel free to try it out, give feedback, ask questions, contribute or share your use cases.
-Abstractions, concepts and interfaces are not final and potentially subject of change.
+This library is not a stable yet, but still rather experimental. Feel free to try it out, give feedback, ask questions,
+contribute or share your use cases. Abstractions, concepts and interfaces are not final and potentially subject of change.
 
 ## Requirements
 
@@ -25,15 +25,16 @@ See [examples](examples) folder to run example implementations using this librar
 Depending on the example you need to export different environment variables
 for API keys or deployment configurations or create a `.env.local` based on `.env` file.
 
-To run all examples, use `make run-examples` or `php example`.
+To run all examples, use `make run-examples` or `php example` and `php huggingface` for all HuggingFace related examples.
 
 For a more sophisticated demo, see the [Symfony Demo Application](https://github.com/php-llm/symfony-demo).
 
 ## Basic Concepts & Usage
 
 ### Models & Platforms
 
-LLM Chain categorizes two main types of models: **Language Models** and **Embeddings Models**.
+LLM Chain categorizes two main types of models: **Language Models** and **Embeddings Models**. On top of that, there are
+other models, like text-to-speech, image generation or classification models that are also supported.
 
 Language Models, like GPT, Claude and Llama, as essential centerpiece of LLM applications
 and Embeddings Models as supporting models to provide vector representations of text.
@@ -71,6 +72,8 @@ $embeddings = new Embeddings();
 * Other Models
   * [OpenAI's Dall·E](https://platform.openai.com/docs/guides/image-generation) with [OpenAI](https://platform.openai.com/docs/overview) as Platform
   * [OpenAI's Whisper](https://platform.openai.com/docs/guides/speech-to-text) with [OpenAI](https://platform.openai.com/docs/overview) and [Azure](https://learn.microsoft.com/azure/ai-services/openai/concepts/models) as Platform
+  * All models provided by [HuggingFace](https://huggingface.co/) can be listed with `make huggingface-models`
+    And more filtered with `php examples/huggingface/_model-listing.php --provider=hf-inference --task=object-detection`
 
 See [issue #28](https://github.com/php-llm/llm-chain/issues/28) for planned support of other models and platforms.
 
@@ -725,6 +728,51 @@ final class MyProcessor implements OutputProcessor, ChainAwareProcessor
 }
 ```
 
+## HuggingFace
+
+LLM Chain comes out of the box with an integration for [HuggingFace](https://huggingface.co/)  which is a platform for
+hosting and sharing all kind of models, including LLMs, embeddings, image generation and classification models.
+
+You can just instantiate the Platform with the corresponding HuggingFace bridge and use it with the `task` option:
+```php
+use PhpLlm\LlmChain\Bridge\HuggingFace\Model;
+use PhpLlm\LlmChain\Bridge\HuggingFace\PlatformFactory;
+use PhpLlm\LlmChain\Bridge\HuggingFace\Task;
+use PhpLlm\LlmChain\Model\Message\Content\Image;
+
+$platform = PlatformFactory::create($apiKey);
+$model = new Model('facebook/detr-resnet-50');
+
+$image = Image::fromFile(dirname(__DIR__, 2).'/tests/Fixture/image.jpg');
+$response = $platform->request($model, $image, [
+    'task' => Task::OBJECT_DETECTION, // defining a task is mandatory for internal request & response handling
+]);
+
+dump($response->getContent());
+```
+
+#### Code Examples
+
+1. [Audio Classification](examples/huggingface/audio-classification.php)
+1. [Automatic Speech Recognition](examples/huggingface/automatic-speech-recognition.php)
+1. [Chat Completion](examples/huggingface/chat-completion.php)
+1. [Feature Extraction (Embeddings)](examples/huggingface/feature-extraction.php)
+1. [Fill Mask](examples/huggingface/fill-mask.php)
+1. [Image Classification](examples/huggingface/image-classification.php)
+1. [Image Segmentation.php](examples/huggingface/image-segmentation.php)
+1. [Image-to-Text](examples/huggingface/image-to-text.php)
+1. [Object Detection](examples/huggingface/object-detection.php)
+1. [Question Answering](examples/huggingface/question-answering.php)
+1. [Sentence Similarity](examples/huggingface/sentence-similarity.php)
+1. [Summarization](examples/huggingface/summarization.php)
+1. [Table Question Answering](examples/huggingface/table-question-answering.php)
+1. [Text Classification](examples/huggingface/text-classification.php)
+1. [Text Generation](examples/huggingface/text-generation.php)
+1. [Text-to-Image](examples/huggingface/text-to-image.php)
+1. [Token Classification](examples/huggingface/token-classification.php)
+1. [Translation](examples/huggingface/translation.php)
+1. [Zero-shot Classification](examples/huggingface/zero-shot-classification.php)
+
 ## Contributions
 
 Contributions are always welcome, so feel free to join the development of this library. To get started, please read the

examples/huggingface/_model-listing.php

@@ -0,0 +1,39 @@
+<?php
+
+use PhpLlm\LlmChain\Bridge\HuggingFace\ApiClient;
+use PhpLlm\LlmChain\Bridge\HuggingFace\Model;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Input\InputOption;
+use Symfony\Component\Console\Output\ConsoleOutput;
+use Symfony\Component\Console\SingleCommandApplication;
+use Symfony\Component\Console\Style\SymfonyStyle;
+
+require_once dirname(__DIR__, 2).'/vendor/autoload.php';
+
+$app = (new SingleCommandApplication('HuggingFace Model Listing'))
+    ->setDescription('Lists all available models on HuggingFace')
+    ->addOption('provider', 'p', InputOption::VALUE_REQUIRED, 'Name of the inference provider to filter models by')
+    ->addOption('task', 't', InputOption::VALUE_REQUIRED, 'Name of the task to filter models by')
+    ->setCode(function (InputInterface $input, ConsoleOutput $output) {
+        $io = new SymfonyStyle($input, $output);
+        $io->title('HuggingFace Model Listing');
+
+        $provider = $input->getOption('provider');
+        $task = $input->getOption('task');
+
+        $models = (new ApiClient())->models($provider, $task);
+
+        if (0 === count($models)) {
+            $io->error('No models found for the given provider and task.');
+
+            return Command::FAILURE;
+        }
+
+        $io->listing(
+            array_map(fn (Model $model) => $model->getName(), $models)
+        );
+
+        return Command::SUCCESS;
+    })
+    ->run();

examples/huggingface/audio-classification.php

@@ -0,0 +1,25 @@
+<?php
+
+use PhpLlm\LlmChain\Bridge\HuggingFace\Model;
+use PhpLlm\LlmChain\Bridge\HuggingFace\PlatformFactory;
+use PhpLlm\LlmChain\Bridge\HuggingFace\Task;
+use PhpLlm\LlmChain\Model\Message\Content\Audio;
+use Symfony\Component\Dotenv\Dotenv;
+
+require_once dirname(__DIR__, 2).'/vendor/autoload.php';
+(new Dotenv())->loadEnv(dirname(__DIR__, 2).'/.env');
+
+if (empty($_ENV['HUGGINGFACE_KEY'])) {
+    echo 'Please set the HUGGINGFACE_KEY environment variable.'.PHP_EOL;
+    exit(1);
+}
+
+$platform = PlatformFactory::create($_ENV['HUGGINGFACE_KEY']);
+$model = new Model('MIT/ast-finetuned-audioset-10-10-0.4593');
+$audio = Audio::fromFile(dirname(__DIR__, 2).'/tests/Fixture/audio.mp3');
+
+$response = $platform->request($model, $audio, [
+    'task' => Task::AUDIO_CLASSIFICATION,
+]);
+
+dump($response->getContent());

examples/huggingface/automatic-speech-recognition.php

@@ -0,0 +1,25 @@
+<?php
+
+use PhpLlm\LlmChain\Bridge\HuggingFace\Model;
+use PhpLlm\LlmChain\Bridge\HuggingFace\PlatformFactory;
+use PhpLlm\LlmChain\Bridge\HuggingFace\Task;
+use PhpLlm\LlmChain\Model\Message\Content\Audio;
+use Symfony\Component\Dotenv\Dotenv;
+
+require_once dirname(__DIR__, 2).'/vendor/autoload.php';
+(new Dotenv())->loadEnv(dirname(__DIR__, 2).'/.env');
+
+if (empty($_ENV['HUGGINGFACE_KEY'])) {
+    echo 'Please set the HUGGINGFACE_KEY environment variable.'.PHP_EOL;
+    exit(1);
+}
+
+$platform = PlatformFactory::create($_ENV['HUGGINGFACE_KEY']);
+$model = new Model('openai/whisper-large-v3');
+$audio = Audio::fromFile(dirname(__DIR__, 2).'/tests/Fixture/audio.mp3');
+
+$response = $platform->request($model, $audio, [
+    'task' => Task::AUTOMATIC_SPEECH_RECOGNITION,
+]);
+
+echo $response->getContent().PHP_EOL;

examples/huggingface/chat-completion.php

@@ -0,0 +1,26 @@
+<?php
+
+use PhpLlm\LlmChain\Bridge\HuggingFace\Model;
+use PhpLlm\LlmChain\Bridge\HuggingFace\PlatformFactory;
+use PhpLlm\LlmChain\Bridge\HuggingFace\Task;
+use PhpLlm\LlmChain\Model\Message\Message;
+use PhpLlm\LlmChain\Model\Message\MessageBag;
+use Symfony\Component\Dotenv\Dotenv;
+
+require_once dirname(__DIR__, 2).'/vendor/autoload.php';
+(new Dotenv())->loadEnv(dirname(__DIR__, 2).'/.env');
+
+if (empty($_ENV['HUGGINGFACE_KEY'])) {
+    echo 'Please set the HUGGINGFACE_KEY environment variable.'.PHP_EOL;
+    exit(1);
+}
+
+$platform = PlatformFactory::create($_ENV['HUGGINGFACE_KEY']);
+$model = new Model('HuggingFaceH4/zephyr-7b-beta');
+
+$messages = new MessageBag(Message::ofUser('Hello, how are you doing today?'));
+$response = $platform->request($model, $messages, [
+    'task' => Task::CHAT_COMPLETION,
+]);
+
+echo $response->getContent().PHP_EOL;

examples/huggingface/feature-extraction.php

@@ -0,0 +1,26 @@
+<?php
+
+use PhpLlm\LlmChain\Bridge\HuggingFace\Model;
+use PhpLlm\LlmChain\Bridge\HuggingFace\PlatformFactory;
+use PhpLlm\LlmChain\Bridge\HuggingFace\Task;
+use PhpLlm\LlmChain\Model\Response\VectorResponse;
+use Symfony\Component\Dotenv\Dotenv;
+
+require_once dirname(__DIR__, 2).'/vendor/autoload.php';
+(new Dotenv())->loadEnv(dirname(__DIR__, 2).'/.env');
+
+if (empty($_ENV['HUGGINGFACE_KEY'])) {
+    echo 'Please set the HUGGINGFACE_KEY environment variable.'.PHP_EOL;
+    exit(1);
+}
+
+$platform = PlatformFactory::create($_ENV['HUGGINGFACE_KEY']);
+$model = new Model('thenlper/gte-large');
+
+$response = $platform->request($model, 'Today is a sunny day and I will get some ice cream.', [
+    'task' => Task::FEATURE_EXTRACTION,
+]);
+
+assert($response instanceof VectorResponse);
+
+echo 'Dimensions: '.$response->getContent()[0]->getDimensions().PHP_EOL;

examples/huggingface/fill-mask.php

@@ -0,0 +1,23 @@
+<?php
+
+use PhpLlm\LlmChain\Bridge\HuggingFace\Model;
+use PhpLlm\LlmChain\Bridge\HuggingFace\PlatformFactory;
+use PhpLlm\LlmChain\Bridge\HuggingFace\Task;
+use Symfony\Component\Dotenv\Dotenv;
+
+require_once dirname(__DIR__, 2).'/vendor/autoload.php';
+(new Dotenv())->loadEnv(dirname(__DIR__, 2).'/.env');
+
+if (empty($_ENV['HUGGINGFACE_KEY'])) {
+    echo 'Please set the HUGGINGFACE_KEY environment variable.'.PHP_EOL;
+    exit(1);
+}
+
+$platform = PlatformFactory::create($_ENV['HUGGINGFACE_KEY']);
+$model = new Model('FacebookAI/xlm-roberta-base');
+
+$response = $platform->request($model, 'Hello I\'m a <mask> model.', [
+    'task' => Task::FILL_MASK,
+]);
+
+dump($response->getContent());

examples/huggingface/image-classification.php

@@ -0,0 +1,25 @@
+<?php
+
+use PhpLlm\LlmChain\Bridge\HuggingFace\Model;
+use PhpLlm\LlmChain\Bridge\HuggingFace\PlatformFactory;
+use PhpLlm\LlmChain\Bridge\HuggingFace\Task;
+use PhpLlm\LlmChain\Model\Message\Content\Image;
+use Symfony\Component\Dotenv\Dotenv;
+
+require_once dirname(__DIR__, 2).'/vendor/autoload.php';
+(new Dotenv())->loadEnv(dirname(__DIR__, 2).'/.env');
+
+if (empty($_ENV['HUGGINGFACE_KEY'])) {
+    echo 'Please set the HUGGINGFACE_KEY environment variable.'.PHP_EOL;
+    exit(1);
+}
+
+$platform = PlatformFactory::create($_ENV['HUGGINGFACE_KEY']);
+$model = new Model('google/vit-base-patch16-224');
+
+$image = Image::fromFile(dirname(__DIR__, 2).'/tests/Fixture/image.jpg');
+$response = $platform->request($model, $image, [
+    'task' => Task::IMAGE_CLASSIFICATION,
+]);
+
+dump($response->getContent());