feat(polyglot): add Perplexity embeddings driver

Add a `perplexity` Embeddings driver for pplx-embed-v1-{0.6b,4b} and
the contextualized pplx-embed-context-v1-{0.6b,4b} models.

- decode base64 signed int8 embeddings into float vectors; reject
  encodings other than base64_int8
- route contextualized models to /contextualizedembeddings, sending the
  request inputs as chunks of one document and flattening in chunk order
- bundled `perplexity` and `perplexity-context` presets and model
  profiles with limits, default dimensions, and pricing
- adapter, mock-HTTP, catalog and opt-in live tests; overview docs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: ddebowczyk

packages/polyglot/docs/embeddings/overview.md

@@ -112,9 +112,36 @@ Polyglot ships with presets for the following providers:
 | `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.
+
+```php
+$chunks = Embeddings::using('perplexity-context')
+    ->withInputs(['First paragraph...', 'Second paragraph...'])
+    ->vectors();
+```
+
 ## Custom Driver Registration
 
 You can register your own driver for providers not bundled with Polyglot by creating a custom `EmbeddingsDriverRegistry`:

packages/polyglot/resources/config/embed/models/perplexity/pplx-embed-context-v1-0.6b.yaml

@@ -0,0 +1,16 @@
+# Sources reviewed 2026-10-01:
+# https://docs.perplexity.ai/docs/embeddings/quickstart.md
+# https://docs.perplexity.ai/docs/embeddings/contextualized-embeddings.md
+# Embeddings are returned as unnormalized base64 int8 values; compare them by
+# cosine similarity. Matryoshka dimensions range from 128 to 1024.
+# The driver sends all request inputs as the chunks of one document.
+schemaVersion: 1
+version: '2026-10-01'
+profile:
+  driver: perplexity
+  model: pplx-embed-context-v1-0.6b
+  maxInputs: 16000
+  maxInputTokens: 32000
+  defaultDimensions: 1024
+  pricing:
+    inputPerMToken: 0.008

packages/polyglot/resources/config/embed/models/perplexity/pplx-embed-context-v1-4b.yaml

@@ -0,0 +1,16 @@
+# Sources reviewed 2026-10-01:
+# https://docs.perplexity.ai/docs/embeddings/quickstart.md
+# https://docs.perplexity.ai/docs/embeddings/contextualized-embeddings.md
+# Embeddings are returned as unnormalized base64 int8 values; compare them by
+# cosine similarity. Matryoshka dimensions range from 128 to 2560.
+# The driver sends all request inputs as the chunks of one document.
+schemaVersion: 1
+version: '2026-10-01'
+profile:
+  driver: perplexity
+  model: pplx-embed-context-v1-4b
+  maxInputs: 16000
+  maxInputTokens: 32000
+  defaultDimensions: 2560
+  pricing:
+    inputPerMToken: 0.05

packages/polyglot/resources/config/embed/models/perplexity/pplx-embed-v1-0.6b.yaml

@@ -0,0 +1,16 @@
+# Sources reviewed 2026-10-01:
+# https://docs.perplexity.ai/docs/embeddings/quickstart.md
+# https://docs.perplexity.ai/docs/embeddings/standard-embeddings.md
+# Embeddings are returned as unnormalized base64 int8 values; compare them by
+# cosine similarity. Matryoshka dimensions range from 128 to 1024.
+schemaVersion: 1
+version: '2026-10-01'
+profile:
+  driver: perplexity
+  model: pplx-embed-v1-0.6b
+  maxInputs: 512
+  maxInputTokens: 32000
+  maxRequestTokens: 120000
+  defaultDimensions: 1024
+  pricing:
+    inputPerMToken: 0.004

packages/polyglot/resources/config/embed/models/perplexity/pplx-embed-v1-4b.yaml

@@ -0,0 +1,16 @@
+# Sources reviewed 2026-10-01:
+# https://docs.perplexity.ai/docs/embeddings/quickstart.md
+# https://docs.perplexity.ai/docs/embeddings/standard-embeddings.md
+# Embeddings are returned as unnormalized base64 int8 values; compare them by
+# cosine similarity. Matryoshka dimensions range from 128 to 2560.
+schemaVersion: 1
+version: '2026-10-01'
+profile:
+  driver: perplexity
+  model: pplx-embed-v1-4b
+  maxInputs: 512
+  maxInputTokens: 32000
+  maxRequestTokens: 120000
+  defaultDimensions: 2560
+  pricing:
+    inputPerMToken: 0.03

packages/polyglot/resources/config/embed/presets/perplexity-context.yaml

@@ -0,0 +1,5 @@
+driver: perplexity
+apiUrl: 'https://api.perplexity.ai/v1'
+apiKey: '${PERPLEXITY_API_KEY}'
+endpoint: /embeddings
+model: pplx-embed-context-v1-0.6b

packages/polyglot/resources/config/embed/presets/perplexity.yaml

@@ -0,0 +1,5 @@
+driver: perplexity
+apiUrl: 'https://api.perplexity.ai/v1'
+apiKey: '${PERPLEXITY_API_KEY}'
+endpoint: /embeddings
+model: pplx-embed-v1-0.6b

packages/polyglot/src/Embeddings/Creation/EmbeddingsDriverRegistry.php

@@ -11,6 +11,7 @@
 use Cognesy\Polyglot\Embeddings\Drivers\Gemini\GeminiDriver;
 use Cognesy\Polyglot\Embeddings\Drivers\Jina\JinaDriver;
 use Cognesy\Polyglot\Embeddings\Drivers\OpenAI\OpenAIDriver;
+use Cognesy\Polyglot\Embeddings\Drivers\Perplexity\PerplexityDriver;
 use InvalidArgumentException;
 use Override;
 use Psr\EventDispatcher\EventDispatcherInterface;
@@ -37,6 +38,7 @@ public static function default(): self {
             'mistral' => OpenAIDriver::class,
             'openai' => OpenAIDriver::class,
             'ollama' => OpenAIDriver::class,
+            'perplexity' => PerplexityDriver::class,
         ]);
     }
 

packages/polyglot/src/Embeddings/Drivers/Perplexity/PerplexityBodyFormat.php

@@ -0,0 +1,47 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Cognesy\Polyglot\Embeddings\Drivers\Perplexity;
+
+use Cognesy\Polyglot\Embeddings\Config\EmbeddingsConfig;
+use Cognesy\Polyglot\Embeddings\Contracts\CanMapRequestBody;
+use Cognesy\Polyglot\Embeddings\Data\EmbeddingsRequest;
+use InvalidArgumentException;
+
+/**
+ * Standard models take a flat list of texts. Contextualized models take
+ * documents as lists of chunks; the request inputs are sent as the chunks of
+ * one document. Only `base64_int8` output is decodable into vectors.
+ */
+class PerplexityBodyFormat implements CanMapRequestBody
+{
+    public const string ENCODING_FORMAT = 'base64_int8';
+
+    public function __construct(
+        private readonly EmbeddingsConfig $config
+    ) {}
+
+    #[\Override]
+    public function toRequestBody(EmbeddingsRequest $request): array
+    {
+        $model = $request->model() ?: $this->config->model;
+        $options = $request->options();
+        $encoding = $options['encoding_format'] ?? self::ENCODING_FORMAT;
+        if ($encoding !== self::ENCODING_FORMAT) {
+            throw new InvalidArgumentException(
+                "Perplexity embeddings support only the '".self::ENCODING_FORMAT."' encoding format.",
+            );
+        }
+        $inputs = $request->inputs();
+
+        return array_filter(array_merge($options, [
+            'input' => match (true) {
+                PerplexityModels::isContextualized($model) => [$inputs],
+                default => $inputs,
+            },
+            'model' => $model,
+            'encoding_format' => self::ENCODING_FORMAT,
+        ]), static fn (mixed $value): bool => (bool) $value);
+    }
+}

packages/polyglot/src/Embeddings/Drivers/Perplexity/PerplexityDriver.php

@@ -0,0 +1,32 @@
+<?php declare(strict_types=1);
+
+namespace Cognesy\Polyglot\Embeddings\Drivers\Perplexity;
+
+use Cognesy\Http\Contracts\CanSendHttpRequests;
+use Cognesy\Polyglot\Embeddings\Config\EmbeddingsConfig;
+use Cognesy\Polyglot\Embeddings\Contracts\EmbedRequestAdapter;
+use Cognesy\Polyglot\Embeddings\Contracts\EmbedResponseAdapter;
+use Cognesy\Polyglot\Embeddings\Drivers\BaseEmbedDriver;
+use Cognesy\Polyglot\Embeddings\Drivers\OpenAI\OpenAIUsageFormat;
+use Psr\EventDispatcher\EventDispatcherInterface;
+
+class PerplexityDriver extends BaseEmbedDriver
+{
+    protected EmbedRequestAdapter  $requestAdapter;
+    protected EmbedResponseAdapter $responseAdapter;
+
+    public function __construct(
+        protected EmbeddingsConfig $config,
+        protected CanSendHttpRequests $httpClient,
+        protected EventDispatcherInterface $events,
+    ) {
+        $requestAdapter = new PerplexityRequestAdapter(
+            $config,
+            new PerplexityBodyFormat($config)
+        );
+        $responseAdapter = new PerplexityResponseAdapter(
+            new OpenAIUsageFormat()
+        );
+        parent::__construct($config, $httpClient, $events, $requestAdapter, $responseAdapter);
+    }
+}