README

Provider-agnostic contracts and DTOs for text embeddings in PHP.

Installation

composer require adachsoft/embedding-contracts

Contracts

DTOs

Enums

Collections

Exceptions

Exception hierarchy

EmbeddingException (extends RuntimeException)
├── InputTooLongException
├── UnsupportedModelException
├── UnsupportedEncodingFormatException
├── RateLimitException
└── EmbeddingFailedException

Usage examples

Implementing a provider

<?php declare(strict_types=1);

use AdachSoft\\EmbeddingContracts\\Collection\\EmbeddingEncodingFormatCollection;
use AdachSoft\\EmbeddingContracts\\Collection\\EmbeddingInputTypeCollection;
use AdachSoft\\EmbeddingContracts\\Contract\\EmbedderInterface;
use AdachSoft\\EmbeddingContracts\\Dto\\EmbedderCapabilitiesDto;
use AdachSoft\\EmbeddingContracts\\Dto\\EmbeddingRequestDto;
use AdachSoft\\EmbeddingContracts\\Dto\\EmbeddingResponseDto;
use AdachSoft\\EmbeddingContracts\\Enum\\EmbeddingEncodingFormatEnum;
use AdachSoft\\EmbeddingContracts\\Enum\\EmbeddingInputTypeEnum;
use AdachSoft\\EmbeddingContracts\\Exception\\EmbeddingException;
use AdachSoft\\EmbeddingContracts\\Exception\\EmbeddingFailedException;
use AdachSoft\\EmbeddingContracts\\Exception\\InputTooLongException;
use AdachSoft\\EmbeddingContracts\\Exception\\RateLimitException;
use AdachSoft\\EmbeddingContracts\\Exception\\UnsupportedEncodingFormatException;
use AdachSoft\\EmbeddingContracts\\Exception\\UnsupportedModelException;

final class OpenAiEmbedder implements EmbedderInterface
{
    public function embed(EmbeddingRequestDto $request): EmbeddingResponseDto
    {
        // Call the underlying OpenAI client here and map the response.
        // The implementation is out of scope for this package.
        throw new EmbeddingFailedException('Not implemented');
    }

    public function embedBatch(EmbeddingRequestDto ...$requests): \AdachSoft\\EmbeddingContracts\\Collection\\EmbeddingResponseCollection
    {
        // Implement batch embedding using provider-specific API.
        throw new EmbeddingFailedException('Not implemented');
    }

    public function getProviderName(): string
    {
        return 'openai';
    }

    public function getCapabilities(): EmbedderCapabilitiesDto
    {
        return new EmbedderCapabilitiesDto(
            maxInputTokens: 8192,
            vectorDimensions: 1536,
            maxBatchSize: 100,
            supportedEncodingFormats: new EmbeddingEncodingFormatCollection([
                EmbeddingEncodingFormatEnum::Float,
            ]),
            supportedInputTypes: new EmbeddingInputTypeCollection([
                EmbeddingInputTypeEnum::Query,
                EmbeddingInputTypeEnum::Document,
            ]),
            supportsDimensionTruncation: true,
        );
    }
}

Consuming the contracts from application code

<?php declare(strict_types=1);

use AdachSoft\\EmbeddingContracts\\Contract\\EmbedderInterface;
use AdachSoft\\EmbeddingContracts\\Dto\\EmbeddingRequestDto;
use AdachSoft\\EmbeddingContracts\\Enum\\EmbeddingEncodingFormatEnum;
use AdachSoft\\EmbeddingContracts\\Enum\\EmbeddingInputTypeEnum;
use AdachSoft\\EmbeddingContracts\\Exception\\EmbeddingException;

final class SemanticSearchService
{
    public function __construct(private readonly EmbedderInterface $embedder)
    {
    }

    /**
     * @return list<float>
     *
     * @throws EmbeddingException
     */
    public function embedQuery(string $query, string $model): array
    {
        $request = new EmbeddingRequestDto(
            input: $query,
            model: $model,
            inputType: EmbeddingInputTypeEnum::Query,
            encodingFormat: EmbeddingEncodingFormatEnum::Float,
        );

        $response = $this->embedder->embed($request);

        if (!is_array($response->vector)) {
            throw new \RuntimeException('Expected float vector for query embeddings.');
        }

        return $response->vector;
    }
}