adachsoft/embedding-contracts

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

Maintainers

Package info

gitlab.com/a.adach/embedding-contracts

Issues

pkg:composer/adachsoft/embedding-contracts

Statistics

Installs: 1

Dependents: 1

Suggesters: 0

Stars: 0

Security

Advisories: 0

Aikido package health analysis

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

Requires

Requires (Dev)

MIT 6276b0653495caad76faf7ca3048b7e4c25eeccb

collectionsdtonlpvectoraicontractsembeddings

This package is not auto-updated.

Last update: 2026-03-24 06:37:27 UTC

README

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

Installation

composer require adachsoft/embedding-contracts

Contracts

ElementDescription
Contract\\EmbedderInterfaceMain contract for embedding providers; exposes single and batch embed operations plus provider metadata.

DTOs

ClassDescription
Dto\\EmbeddingRequestDtoImmutable request describing a single embedding operation (input, model, input type, encoding format, dimensions, user).
Dto\\EmbeddingResponseDtoImmutable response carrying a single embedding vector together with token count, encoding format, model and original input.
Dto\\EmbedderCapabilitiesDtoDescribes provider capabilities such as maximum input tokens, vector dimensions, batch size and supported formats/input types.

Enums

EnumValuesDescription
Enum\\EmbeddingEncodingFormatEnumFloat, Base64Encoding of the embedding vector (float list or base64 string).
Enum\\EmbeddingInputTypeEnumQuery, DocumentSemantic role of the input text (search query vs indexed document).

Collections

ClassDescription
Collection\\EmbeddingResponseCollectionImmutable collection of EmbeddingResponseDto with helper totalTokenCount() summing tokens of all items.
Collection\\EmbeddingEncodingFormatCollectionImmutable collection of EmbeddingEncodingFormatEnum with helper supports(EmbeddingEncodingFormatEnum): bool.
Collection\\EmbeddingInputTypeCollectionImmutable collection of EmbeddingInputTypeEnum with helper supports(EmbeddingInputTypeEnum): bool.

Exceptions

ClassDescription
Exception\\EmbeddingExceptionBase class for all embedding-related domain exceptions.
Exception\\InputTooLongExceptionThrown when input text exceeds maximum supported length.
Exception\\UnsupportedModelExceptionThrown when a requested embedding model is not supported by the provider.
Exception\\UnsupportedEncodingFormatExceptionThrown when a requested encoding format is not supported; message is built from the requested format.
Exception\\RateLimitExceptionThrown when provider rate limits are exceeded.
Exception\\EmbeddingFailedExceptionThrown 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;
    }
}