feat: add support for Hugging Face Inference API (#279)

* 1st Commit: Christopher
* 2nd Commit: Claude Desktop with Jetbrains MCP:
> I'm writing a PHP library that is similar to langchain but should also
cover the HuggingFace inference API - like their library.
You can access my terminal and my IDE via tools.
Please have a look at the different tasks that should be available in
src/Bridge/HuggingFace/Task.php and see the example implementation in
examples/huggingface/text-classification.php in combination with the
namespace PhpLlm\LlmChain\Bridge\HuggingFace.
Your task is to implement the response conversion, corresponding DTOs
and examples for all other tasks than text-classification.
* 3rd Commit: Claude Desktop with Jetbrains MCP:
> please have a look at the other examples in the examples/ folder using
audio, image or text input and refactor the ones you just created.
all new example files are located in
/home/christopher/Projects/PHP-LLM/llm-chain/examples/huggingface -
please verify they're working by executing them - and patch bugs if
there are any
* 4th Commit: Claude Desktop with Jetbrains MCP:
> please create an example runner for huggingface examples, based on the
/example file in root directory
* 5th Commit: Christopher making it work.

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());

examples/huggingface/image-segmentation.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('nvidia/segformer-b0-finetuned-ade-512-512');
+
+$image = Image::fromFile(dirname(__DIR__, 2).'/tests/Fixture/image.jpg');
+$response = $platform->request($model, $image, [
+    'task' => Task::IMAGE_SEGMENTATION,
+]);
+
+dump($response->getContent());

examples/huggingface/image-to-text.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('Salesforce/blip-image-captioning-base');
+
+$image = Image::fromFile(dirname(__DIR__, 2).'/tests/Fixture/image.jpg');
+$response = $platform->request($model, $image, [
+    'task' => Task::IMAGE_TO_TEXT,
+]);
+
+echo $response->getContent().PHP_EOL;

examples/huggingface/object-detection.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('facebook/detr-resnet-50');
+
+$image = Image::fromFile(dirname(__DIR__, 2).'/tests/Fixture/image.jpg');
+$response = $platform->request($model, $image, [
+    'task' => Task::OBJECT_DETECTION,
+]);
+
+dump($response->getContent());