adachsoft/embedding-contracts

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

v0.1.0 2026-03-23 08:59 UTC

Requires

• php: >=8.3
• adachsoft/collection: ^3.0

Requires (Dev)

• adachsoft/php-code-style: ^0.4
• friendsofphp/php-cs-fixer: ^3.94
• phpstan/phpstan: ^2.1
• phpunit/phpunit: ^13.0
• rector/rector: ^2.3

MIT

• collections
• dto
• nlp
• vector
• ai
• contracts
• embeddings

README

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

Installation

composer require adachsoft/embedding-contracts

Contracts

Element	Description
Contract\\EmbedderInterface	Main contract for embedding providers; exposes single and batch embed operations plus provider metadata.

DTOs

Class	Description
Dto\\EmbeddingRequestDto	Immutable request describing a single embedding operation (input, model, input type, encoding format, dimensions, user).
Dto\\EmbeddingResponseDto	Immutable response carrying a single embedding vector together with token count, encoding format, model and original input.
Dto\\EmbedderCapabilitiesDto	Describes provider capabilities such as maximum input tokens, vector dimensions, batch size and supported formats/input types.

Enums

Enum	Values	Description
Enum\\EmbeddingEncodingFormatEnum	Float, Base64	Encoding of the embedding vector (float list or base64 string).
Enum\\EmbeddingInputTypeEnum	Query, Document	Semantic role of the input text (search query vs indexed document).

Collections

Class	Description
Collection\\EmbeddingResponseCollection	Immutable collection of EmbeddingResponseDto with helper totalTokenCount() summing tokens of all items.
Collection\\EmbeddingEncodingFormatCollection	Immutable collection of EmbeddingEncodingFormatEnum with helper supports(EmbeddingEncodingFormatEnum): bool.
Collection\\EmbeddingInputTypeCollection	Immutable collection of EmbeddingInputTypeEnum with helper supports(EmbeddingInputTypeEnum): bool.

Exceptions

Class	Description
Exception\\EmbeddingException	Base class for all embedding-related domain exceptions.
Exception\\InputTooLongException	Thrown when input text exceeds maximum supported length.
Exception\\UnsupportedModelException	Thrown when a requested embedding model is not supported by the provider.
Exception\\UnsupportedEncodingFormatException	Thrown when a requested encoding format is not supported; message is built from the requested format.
Exception\\RateLimitException	Thrown when provider rate limits are exceeded.
Exception\\EmbeddingFailedException	Thrown when an embedding operation fails for a non-recoverable reason.

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;
    }
}