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