Add embedding generation support #132

Jameswlepage · 2025-11-26T20:27:28Z

Fixes #130

Summary

add embedding DTOs/results/operations and expose helper transformers
extend PromptBuilder, AiClient, and the CLI with embedding-specific inputs, result helpers, and output formats
introduce embedding contracts in the provider layer plus an OpenAI embedding model implementation alongside updated mocks/tests/documentation

Testing

composer phpstan
composer phpunit
php cli.php "["Embed this doc"]" --capability=embeddings --providerId=openai --modelId=text-embedding-3-large --outputFormat=embeddings-vectors

github-actions · 2025-11-26T21:39:26Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: Jameswlepage <[email protected]>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

Copilot

Pull request overview

This PR adds comprehensive embedding generation support to the PHP AI Client, enabling developers to generate vector embeddings using compatible AI models. The implementation extends the existing architecture with minimal disruption while maintaining consistency with the established patterns for text and image generation.

Key Changes:

Introduces embedding-specific DTOs (Embedding, EmbeddingResult, EmbeddingOperation) with full serialization support
Adds embedding generation interfaces for model implementations
Implements OpenAI embedding model support with proper request/response handling
Extends PromptBuilder and AiClient with embedding-specific methods
Updates CLI with embedding capability support and multiple output formats

Reviewed changes

Copilot reviewed 24 out of 24 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/unit/Results/DTO/EmbeddingResultTest.php	Comprehensive test coverage for EmbeddingResult including validation, transformations, and helpers
tests/unit/Providers/ProviderRegistryTest.php	Adds test for discovering embedding-capable models through registry
tests/unit/Providers/Models/DTO/ModelRequirementsTest.php	Ensures embeddings don't incorrectly require chat history capability
tests/unit/ProviderImplementations/OpenAi/OpenAiEmbeddingModelTest.php	Tests OpenAI embedding model with mocked HTTP responses
tests/unit/Operations/DTO/EmbeddingOperationTest.php	Tests embedding operation state management and serialization
tests/unit/Embeddings/DTO/EmbeddingTest.php	Tests embedding vector validation and normalization
tests/unit/Builders/PromptBuilderTest.php	Tests new embedding-specific builder methods
tests/unit/AiClientTest.php	Tests static helper methods for embedding generation
tests/traits/MockModelCreationTrait.php	Adds mock model creation helpers for embedding tests
tests/mocks/MockProvider.php	Registers mock embedding model for testing
src/Results/DTO/EmbeddingResult.php	Core result DTO with vector extraction helpers
src/Providers/Models/EmbeddingGeneration/Contracts/EmbeddingGenerationOperationModelInterface.php	Interface for async embedding operations
src/Providers/Models/EmbeddingGeneration/Contracts/EmbeddingGenerationModelInterface.php	Interface for synchronous embedding generation
src/Providers/Models/DTO/ModelRequirements.php	Excludes chat history requirement for embedding capability
src/Providers/Models/Contracts/WithEmbeddingOperationsInterface.php	Interface for retrieving embedding operations by ID
src/ProviderImplementations/OpenAi/OpenAiProvider.php	Adds embedding model instantiation in factory method
src/ProviderImplementations/OpenAi/OpenAiModelMetadataDirectory.php	Detects and categorizes embedding models from OpenAI API
src/ProviderImplementations/OpenAi/OpenAiEmbeddingModel.php	Full OpenAI embedding API implementation
src/Operations/DTO/EmbeddingOperation.php	Operation DTO for async embedding workflows
src/Embeddings/DTO/Embedding.php	Single embedding vector DTO with validation
src/Builders/PromptBuilder.php	Adds withEmbeddingInputs and generate methods for embeddings
src/AiClient.php	Adds static helper methods for embedding generation
cli.php	Extends CLI with embeddings capability and output formats
README.md	Documents embedding generation usage and CLI examples

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-12-13T21:17:42Z

src/ProviderImplementations/OpenAi/OpenAiModelMetadataDirectory.php

+                    /** @var list<CapabilityEnum> $modelCaps */
+                    $modelCaps = [];
+                    /** @var list<SupportedOption> $modelOptions */


These PHPStan type annotations for $modelCaps and $modelOptions are unnecessary. The variables are immediately assigned values from the closure's use clause parameters ($embeddingCapabilities, $ttsCapabilities, etc.), which already have their types defined. Since these annotations don't add value and clutter the code, consider removing them.

Suggested change

/** @var list<CapabilityEnum> $modelCaps */

$modelCaps = [];

/** @var list<SupportedOption> $modelOptions */

$modelCaps = [];

felixarntz

@Jameswlepage This is coming along nicely - sorry for the delay in review.

I think there are a few things we can simplify, but most importantly let's not add full operation support yet, as we don't have that elsewhere and it requires a bit more thinking through holistically.

felixarntz · 2025-12-20T02:38:56Z

src/Builders/PromptBuilder.php

+     * @param mixed ...$inputs The embedding inputs to add.
+     * @return self
+     */
+    public function withEmbeddingInputs(...$inputs): self


There's no need for this. The input for embeddings is fully compatible with regular prompts. So you can use the same consistent API.

felixarntz · 2025-12-20T02:39:35Z

src/Builders/PromptBuilder.php

+    /**
+     * @var list<Message> Embedding-specific input messages.
+     */
+    protected array $embeddingInputs = [];


See other comment, we can simply use $messages for embeddings too. They won't hold prompts in that case, but input data.

felixarntz · 2025-12-20T02:40:35Z

src/AiClient.php

+        $builder = self::prompt(null, $registry);
+        if ($modelOrConfig instanceof ModelInterface) {
+            $builder->usingModel($modelOrConfig);
+        } elseif ($modelOrConfig instanceof ModelConfig) {
+            $builder->usingModelConfig($modelOrConfig);
+        }


Can you use the getConfiguredPromptBuilder method instead of duplicating this logic? You can pass $input as the first parameter to the prompt method - they're supposed to be interoperable so you can use the same consistent API.

felixarntz · 2025-12-20T02:41:00Z

src/AiClient.php

+            $builder->usingModelConfig($modelOrConfig);
+        }
+
+        $builder->withEmbeddingInputs($input);


See my comments on PromptBuilder, this won't be needed. Input data can be passed via prompt.

felixarntz · 2025-12-20T02:42:03Z

src/AiClient.php

+     * @param ProviderRegistry|null $registry Optional custom registry.
+     * @return EmbeddingOperation The embeddings operation.
+     */
+    public static function generateEmbeddingsOperation(


Let's not implement this yet - we don't support long-running operations for anything yet, so doing that here would be preliminary.

felixarntz · 2025-12-20T02:54:46Z

src/Builders/PromptBuilder.php

+     * @param mixed $input The embedding input to append.
+     * @return void
+     */
+    private function appendEmbeddingInput($input): void


This is probably not needed? Or, why is it?

felixarntz · 2025-12-20T02:55:23Z

src/Embeddings/DTO/Embedding.php

+     *
+     * @since 0.2.0
+     *
+     * @param list<float|int> $vector The embedding vector values.


Can these really be both? Or should they always be float?

felixarntz · 2025-12-20T02:59:45Z

src/Providers/Models/Contracts/WithEmbeddingOperationsInterface.php

+ *
+ * @since 0.2.0
+ */
+interface WithEmbeddingOperationsInterface


See above, we don't need this yet.

felixarntz · 2025-12-20T03:02:31Z

src/Results/DTO/EmbeddingResult.php

+ *
+ * @extends AbstractDataTransferObject<EmbeddingResultArrayShape>
+ */
+class EmbeddingResult extends AbstractDataTransferObject implements ResultInterface


I realize this was named like that in ARCHITECTURE.md, but I think it may be better to call it EmbeddingsResult, in alignment with the other method naming and the fact that 95% of the time you'll be generating multiple embeddings.

felixarntz · 2025-12-20T03:02:58Z

src/Operations/DTO/EmbeddingOperation.php

+ *
+ * @extends AbstractDataTransferObject<EmbeddingOperationArrayShape>
+ */
+class EmbeddingOperation extends AbstractDataTransferObject implements OperationInterface


See my other comment on EmbeddingResult, maybe we should call this EmbeddingsResult?

Jameswlepage added 2 commits November 26, 2025 15:02

feat: add embedding generation support

8ce851d

chore: sort new embedding use statements

d0f83c0

Jameswlepage requested review from JasonTheAdams and felixarntz November 26, 2025 20:27

Jameswlepage marked this pull request as ready for review November 26, 2025 21:39

Jameswlepage requested a review from Copilot December 13, 2025 21:14

Copilot started reviewing on behalf of Jameswlepage December 13, 2025 21:14 View session

Copilot AI reviewed Dec 13, 2025

View reviewed changes

felixarntz requested changes Dec 20, 2025

View reviewed changes

Add embedding generation support #132

Are you sure you want to change the base?

Add embedding generation support #132

Uh oh!

Conversation

Jameswlepage commented Nov 26, 2025

Summary

Testing

Uh oh!

github-actions bot commented Nov 26, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Dec 13, 2025

Choose a reason for hiding this comment

Uh oh!

felixarntz left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants