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=
 

examples/huggingface-text-classification.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__).'/vendor/autoload.php';
+(new Dotenv())->loadEnv(dirname(__DIR__).'/.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('ProsusAI/finbert');
+
+$response = $platform->request($model, 'I like you. I love you.', [
+    'task' => Task::TEXT_CLASSIFICATION,
+]);
+
+dump($response->getContent());

src/Bridge/HuggingFace/Model.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpLlm\LlmChain\Bridge\HuggingFace;
+
+use PhpLlm\LlmChain\Model\Model as BaseModel;
+
+final readonly class Model implements BaseModel
+{
+    /**
+     * @param string               $name    the name of the model is optional with HuggingFace
+     * @param array<string, mixed> $options
+     */
+    public function __construct(
+        private ?string $name = null,
+        private array $options = [],
+    ) {
+    }
+
+    public function getName(): string
+    {
+        return $this->name ?? '';
+    }
+
+    public function getOptions(): array
+    {
+        return $this->options;
+    }
+}

src/Bridge/HuggingFace/ModelClient.php

@@ -0,0 +1,62 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpLlm\LlmChain\Bridge\HuggingFace;
+
+use PhpLlm\LlmChain\Model\Model as BaseModel;
+use PhpLlm\LlmChain\Platform\ModelClient as PlatformModelClient;
+use Symfony\Component\HttpClient\EventSourceHttpClient;
+use Symfony\Contracts\HttpClient\HttpClientInterface;
+use Symfony\Contracts\HttpClient\ResponseInterface;
+use Webmozart\Assert\Assert;
+
+final readonly class ModelClient implements PlatformModelClient
+{
+    private EventSourceHttpClient $httpClient;
+
+    public function __construct(
+        HttpClientInterface $httpClient,
+        private string $provider,
+        #[\SensitiveParameter]
+        private string $apiKey,
+    ) {
+        $this->httpClient = $httpClient instanceof EventSourceHttpClient ? $httpClient : new EventSourceHttpClient($httpClient);
+    }
+
+    public function supports(BaseModel $model, object|array|string $input): bool
+    {
+        return $model instanceof Model;
+    }
+
+    public function request(BaseModel $model, object|array|string $input, array $options = []): ResponseInterface
+    {
+        Assert::isInstanceOf($model, Model::class);
+        $url = sprintf('https://router.huggingface.co/%s/models/%s', $this->provider, $model->getName());
+
+        return $this->httpClient->request('POST', $url, [
+            'auth_bearer' => $this->apiKey,
+            'headers' => ['Content-Type' => 'application/json'],
+            'json' => $this->getPayload($input, $options),
+        ]);
+    }
+
+    /**
+     * @param array<mixed>|string|object $input
+     * @param array<string, mixed>       $options
+     *
+     * @return array<string, mixed>
+     */
+    public function getPayload(object|array|string $input, array $options = []): array
+    {
+        $task = $options['task'] ?? null;
+
+        if (Task::TEXT_CLASSIFICATION === $task) {
+            return [
+                'inputs' => $input,
+            ];
+        }
+
+        throw new \InvalidArgumentException('Unsupported task: '.$task);
+    }
+}

src/Bridge/HuggingFace/Output/Classification.php

@@ -0,0 +1,14 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpLlm\LlmChain\Bridge\HuggingFace\Output;
+
+final readonly class Classification
+{
+    public function __construct(
+        public string $label,
+        public float $score,
+    ) {
+    }
+}

src/Bridge/HuggingFace/Output/ClassificationResult.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpLlm\LlmChain\Bridge\HuggingFace\Output;
+
+final class ClassificationResult
+{
+    /**
+     * @param Classification[] $classifications
+     */
+    public function __construct(
+        public array $classifications,
+    ) {
+    }
+
+    /**
+     * @param array<array{label: string, score: float}> $data
+     */
+    public static function collectionFromArray(array $data): self
+    {
+        return new self(array_map(
+            fn (array $item) => new Classification($item['label'], $item['score']),
+            $data,
+        ));
+    }
+}

src/Bridge/HuggingFace/PlatformFactory.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpLlm\LlmChain\Bridge\HuggingFace;
+
+use PhpLlm\LlmChain\Platform;
+use Symfony\Component\HttpClient\EventSourceHttpClient;
+use Symfony\Contracts\HttpClient\HttpClientInterface;
+
+final readonly class PlatformFactory
+{
+    public static function create(
+        #[\SensitiveParameter]
+        string $apiKey,
+        string $provider = Provider::HF_INFERENCE,
+        ?HttpClientInterface $httpClient = null,
+    ): Platform {
+        $httpClient = $httpClient instanceof EventSourceHttpClient ? $httpClient : new EventSourceHttpClient($httpClient);
+
+        return new Platform([new ModelClient($httpClient, $provider, $apiKey)], [new ResponseConverter()]);
+    }
+}

src/Bridge/HuggingFace/Provider.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpLlm\LlmChain\Bridge\HuggingFace;
+
+interface Provider
+{
+    public const CEREBRAS = 'cerebras';
+    public const FAL_AI = 'fal-ai';
+    public const FIREWORKS = 'fireworks-ai';
+    public const HYPERBOLIC = 'hyperbolic';
+    public const HF_INFERENCE = 'hf-inference';
+    public const NEBIUS = 'nebius';
+    public const NOVITA = 'novita';
+    public const REPLICATE = 'replicate';
+    public const SAMBA_NOVA = 'sambanova';
+    public const TOGETHER = 'together';
+}

src/Bridge/HuggingFace/ResponseConverter.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpLlm\LlmChain\Bridge\HuggingFace;
+
+use PhpLlm\LlmChain\Bridge\HuggingFace\Output\ClassificationResult;
+use PhpLlm\LlmChain\Model\Model as BaseModel;
+use PhpLlm\LlmChain\Model\Response\ResponseInterface as LlmResponse;
+use PhpLlm\LlmChain\Model\Response\StructuredResponse;
+use PhpLlm\LlmChain\Platform\ResponseConverter as PlatformResponseConverter;
+use Symfony\Contracts\HttpClient\ResponseInterface;
+
+final readonly class ResponseConverter implements PlatformResponseConverter
+{
+    public function supports(BaseModel $model, array|string|object $input): bool
+    {
+        return $model instanceof Model;
+    }
+
+    public function convert(ResponseInterface $response, array $options = []): LlmResponse
+    {
+        $data = $response->toArray();
+        $task = $options['task'] ?? null;
+
+        if (Task::TEXT_CLASSIFICATION === $task) {
+            return new StructuredResponse(ClassificationResult::collectionFromArray(reset($data) ?? []));
+        }
+
+        throw new \RuntimeException(sprintf('Unsupported task: %s', $task));
+    }
+}

src/Bridge/HuggingFace/Task.php

@@ -0,0 +1,37 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpLlm\LlmChain\Bridge\HuggingFace;
+
+interface Task
+{
+    public const AUDIO_CLASSIFICATION = 'audio-classification';
+    public const AUDIO_TO_AUDIO = 'audio-to-audio';
+    public const AUTOMATIC_SPEECH_RECOGNITION = 'automatic-speech-recognition';
+    public const CHAT_COMPLETION = 'chat-completion';
+    public const DOCUMENT_QUESTION_ANSWERING = 'document-question-answering';
+    public const FEATURE_EXTRACTION = 'feature-extraction';
+    public const FILL_MASK = 'fill-mask';
+    public const IMAGE_CLASSIFICATION = 'image-classification';
+    public const IMAGE_SEGMENTATION = 'image-segmentation';
+    public const IMAGE_TO_IMAGE = 'image-to-image';
+    public const IMAGE_TO_TEXT = 'image-to-text';
+    public const OBJECT_DETECTION = 'object-detection';
+    public const QUESTION_ANSWERING = 'question-answering';
+    public const SENTENCE_SIMILARITY = 'sentence-similarity';
+    public const SUMMARIZATION = 'summarization';
+    public const TABLE_QUESTION_ANSWERING = 'table-question-answering';
+    public const TABULAR_CLASSIFICATION = 'tabular-classification';
+    public const TABULAR_REGRESSION = 'tabular-regression';
+    public const TEXT_CLASSIFICATION = 'text-classification';
+    public const TEXT_GENERATION = 'text-generation';
+    public const TEXT_TO_IMAGE = 'text-to-image';
+    public const TEXT_TO_VIDEO = 'text-to-video';
+    public const TEXT_TO_SPEECH = 'text-to-speech';
+    public const TOKEN_CLASSIFICATION = 'token-classification';
+    public const TRANSLATION = 'translation';
+    public const VISUAL_QUESTION_ANSWERING = 'visual-question-answering';
+    public const ZERO_SHOT_CLASSIFICATION = 'zero-shot-classification';
+    public const ZERO_SHOT_IMAGE_CLASSIFICATION = 'zero-shot-image-classification';
+}