> ## Documentation Index
> Fetch the complete documentation index at: https://docs.instructorphp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 theme={null}
<?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',
    dimensions: 1536,
    maxInputs: 2048,
    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="7ac1"
```

## 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)   |

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

## Custom Driver Registration

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

```php theme={null}
<?php

use Cognesy\Polyglot\Embeddings\Embeddings;
use Cognesy\Polyglot\Embeddings\Creation\BundledEmbeddingsDrivers;

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

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

Your custom driver must implement the `CanHandleVectorization` contract.

## 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 |