Overview

Embeddings are numerical representations of text that capture semantic meaning in a high-dimensional vector space. They are a foundational building block for many LLM-powered applications, enabling machines to understand relationships between words, phrases, and documents.

Polyglot’s Embeddings class provides a unified interface for generating vector embeddings across multiple providers. You write your code once, and switch between OpenAI, Cohere, Gemini, Jina, Mistral, or any other supported provider by changing a single preset name.

Understanding Embeddings

Before diving into the API, it helps to understand the core concepts:

• Vectors — Embeddings represent text as arrays of floating-point numbers in a high-dimensional space (typically 256 to 3072 dimensions).
• Semantic similarity — Texts with similar meaning produce vectors that are closer together, measurable through cosine similarity, Euclidean distance, or dot product.
• Provider models — Different providers offer models with varying dimension counts, language support, and performance characteristics.

Common use cases for embeddings include:

• Semantic search — Find documents similar to a query based on meaning, not just keywords.
• Clustering — Group related documents together automatically.
• Classification — Assign categories to text based on content.
• Recommendations — Suggest related items based on vector proximity.
• RAG (Retrieval-Augmented Generation) — Retrieve relevant context for LLM prompts.

The Embeddings Class

The Embeddings class is a facade that combines provider configuration, request building, and result handling into a fluent, immutable API. Every method that modifies state returns a new instance, making the class safe to reuse and compose.

Architecture Overview

The class is built from several focused components:

Component	Responsibility
Embeddings	Facade with fluent API and static factory methods
EmbeddingsRuntime	Orchestrates driver creation, HTTP clients, and event dispatching
EmbeddingsProvider	Resolves configuration and optional explicit drivers
PendingEmbeddings	Executes the request with retry logic and returns the response
EmbeddingsDriverRegistry	Maps driver names to concrete driver implementations

Entry Points

You can create an Embeddings instance in several ways, depending on how much control you need:

<?php

use Cognesy\Polyglot\Embeddings\Embeddings;
use Cognesy\Polyglot\Embeddings\Config\EmbeddingsConfig;

// From a named preset (most common)
$embeddings = Embeddings::using('openai');

// From a configuration object
$config = new EmbeddingsConfig(
    apiUrl: 'https://api.openai.com/v1',
    apiKey: getenv('OPENAI_API_KEY'),
    endpoint: '/embeddings',
    model: 'text-embedding-3-small',
    driver: 'openai',
);
$embeddings = Embeddings::fromConfig($config);

// From a provider instance (for advanced composition)
$embeddings = Embeddings::fromProvider($provider);

// From a custom runtime (full control over driver and events)
$embeddings = Embeddings::fromRuntime($runtime);
// @doctest id="6f8f"

EmbeddingsConfig owns connection and route selection. Model facts such as default dimensions, input limits, token limits, and pricing live in the optional Embeddings\Models\ModelCatalog. Inject it into EmbeddingsRuntime when an application wants metadata or known input-count preflight.

Request Methods

Configure what to embed before executing the request:

Method	Description
withInputs(string|array $input)	Set one or more texts to embed
withModel(string $model)	Override the model from the preset
withOptions(array $options)	Pass provider-specific options
withRetryPolicy(EmbeddingsRetryPolicy $policy)	Configure retry behavior
withRequest(EmbeddingsRequest $request)	Replace the entire request object
with($input, $options, $model)	Shorthand combining inputs, options, and model

Execution Methods

Three convenience methods execute the request and return results at different levels of detail:

Method	Returns	Description
get()	EmbeddingsResponse	Full response with vectors, usage, and metadata
vectors()	Vector[]	Array of all embedding vectors
first()	?Vector	The first vector, or null if empty

For advanced use cases, create() returns a PendingEmbeddings instance that you can inspect or execute manually.

Supported Providers

Polyglot ships with presets for the following providers:

Preset	Driver	Default Model	Dimensions
openai	OpenAI	text-embedding-3-small	1536
azure	Azure OpenAI	(configured per deployment)	(varies)
cohere	Cohere	embed-multilingual-v3.0	1024
gemini	Gemini	(configured per preset)	(varies)
jina	Jina	(configured per preset)	(varies)
mistral	OpenAI-compatible	(configured per preset)	(varies)
ollama	OpenAI-compatible	(configured per preset)	(varies)
perplexity	Perplexity	pplx-embed-v1-0.6b	1024
perplexity-context	Perplexity	pplx-embed-context-v1-0.6b	1024

Note: Mistral and Ollama use the OpenAI-compatible driver, since their APIs follow the same format.

Perplexity

The perplexity driver reads PERPLEXITY_API_KEY and supports pplx-embed-v1-0.6b, pplx-embed-v1-4b, and the contextualized pplx-embed-context-v1-0.6b and pplx-embed-context-v1-4b models.

• Perplexity returns base64 signed int8 embeddings. The driver decodes them into float vectors in the range -128 to 127. They are not normalized, so compare them with cosine similarity rather than dot product or L2 distance.
• Only the default base64_int8 encoding is supported; base64_binary is rejected. Pass ['dimensions' => 256] (128 up to the model maximum) through withOptions() to request shorter Matryoshka vectors.
• Contextualized models use /contextualizedembeddings. All inputs of one request are sent as the chunks of a single document, and vectors come back in chunk order. Embed each document in its own request, and embed queries with the same contextualized model.
• Standard models accept up to 512 inputs and 120,000 tokens per request; each input must stay under 32K tokens.

$chunks = Embeddings::using('perplexity-context')
    ->withInputs(['First paragraph...', 'Second paragraph...'])
    ->vectors();
// @doctest id="b08e"

Custom Driver Registration

You can register your own driver for providers not bundled with Polyglot by creating a custom EmbeddingsDriverRegistry:

<?php

use Cognesy\Polyglot\Embeddings\Embeddings;
use Cognesy\Polyglot\Embeddings\Creation\EmbeddingsDriverRegistry;

// Start from the bundled registry and add your driver (by class name or factory callable)
$registry = EmbeddingsDriverRegistry::default()
    ->withDriver('custom-provider', CustomEmbeddingsDriver::class);

// Or register with a factory callable
$registry = EmbeddingsDriverRegistry::default()
    ->withDriver('custom-provider', function ($config, $httpClient, $events) {
        return new CustomEmbeddingsDriver($config, $httpClient, $events);
    });
// @doctest id="331a"

Your custom driver must implement the CanHandleVectorization contract. Its handle() method owns provider transport and parsing and returns a normalized EmbeddingsResponse.

Events

The embeddings system dispatches events at key points during execution, which you can listen to through the runtime:

Event	When
EmbeddingsDriverBuilt	After the driver is created from configuration
EmbeddingsRequested	When an embeddings request is initiated
EmbeddingsResponseReceived	After a successful response is received
EmbeddingsFailed	When the request fails after all retry attempts