Add the AiClient with testing suite #55

Ref34t · 2025-08-15T23:46:58Z

This introduces the AiClient, which is intended to be the primary face for Implementors to construct and execute prompts. See the "Traditional API" examples in the code examples in the Architecture doc.

This provides the foundation that the PromptBuilder (PR #49 ) depends on to be complete.

Ref34t · 2025-08-15T23:53:29Z

@felixarntz could you please add the [Feature] label and 'Complete Implementor API' milestone to this PR? This continues the AiClient work from PR #53, which you had previously labeled and milestone-tagged, but I decided to close it and create this separate one as the other one had commits from the other feature

Add provider availability checking functionality to complete architecture specification. - Add isConfigured(ProviderAvailabilityInterface $availability): bool method - Delegate to ProviderAvailabilityInterface::isConfigured() for consistency

Add base generation method that automatically detects model capabilities and delegates to appropriate generation interfaces. - Add generateResult(prompt, ModelInterface): GenerativeAiResult method - Smart delegation to generateTextResult() or generateImageResult() based on model interface - Comprehensive error handling for unsupported model types - 3 new tests covering text generation, image generation, and error cases

Add streaming text generation using PHP Generator pattern. - Add streamGenerateTextResult() method with Generator return type - Delegate to model's streaming method using yield from - Support model auto-discovery and comprehensive error handling

Add properly typed async operations with model interface validation. - Add generateTextOperation() with TextGenerationModelInterface validation - Add generateImageOperation() with ImageGenerationModelInterface validation - Prefixed operation IDs for better tracking (text_op_, image_op_) - 4 comprehensive tests covering validation and error cases

- Add convertTextToSpeechResult() method with model auto-discovery - Add convertTextToSpeechOperation() method for async processing - Enhance generateResult() to support TextToSpeechConversionModelInterface - Add findSuitableTextToSpeechModel() helper method - Update test expectations for extended generation interface support

- Add generateSpeechResult() method with model auto-discovery - Add generateSpeechOperation() method for async speech processing - Enhance generateResult() to support SpeechGenerationModelInterface - Add findSuitableSpeechModel() helper with speechGeneration capability - Update prompt() method with comprehensive PromptBuilder integration docs

- Add Embedding DTO with vector data representation and dimension tracking - Add EmbeddingResult class extending ResultInterface for embedding results - Add EmbeddingOperation class for async embedding operations - Add EmbeddingGenerationModelInterface for synchronous embedding generation - Add EmbeddingGenerationOperationModelInterface for async embedding operations - Implement generateEmbeddingsResult() method with model auto-discovery - Implement generateEmbeddingsOperation() method for async processing - Add findSuitableEmbeddingModel() helper with embeddingGeneration capability - Support both string[] and Message[] input formats for embeddings - Update PromptBuilder integration documentation to include embeddings

- Create EmbeddingTest.php with 9 test methods covering vector operations and transformations - Create EmbeddingResultTest.php with 12 test methods covering result validation and serialization - Create EmbeddingOperationTest.php with 14 test methods covering all operation states - Create MockEmbeddingGenerationModel.php and MockEmbeddingGenerationOperationModel.php for testing - Add 5 embedding test methods to AiClientTest.php with proper mock integration

- Fix type errors by ensuring proper list types for embedding interfaces - Convert Message arrays to proper lists using array_values() for interface compliance

- Add missing newlines at end of files - Remove trailing whitespace - Fix alphabetical import sorting in test files - All PHPCS violations resolved automatically

- Implement message() method with placeholder that throws RuntimeException - Add comprehensive test coverage for message() method

…ability - Extract PromptNormalizer utility class for prompt format standardization - Extract ModelDiscovery utility class for capability-based model discovery

- Fix list type annotations in PromptNormalizer and AiClient - Ensure all Message arrays are converted to proper lists using array_values() - Remove 4 redundant tests from AiClientTest that are now covered by utility tests - Maintain 100% test coverage while eliminating duplicate test logic - All PHPStan errors resolved, all tests passing

Extract interface validation, operation factory, embedding input normalization, and generation strategy resolution into dedicated utility classes.

…ation - Implement template method pattern in AiClient for generation methods - Add dynamic validation system to InterfaceValidator with configuration mapping - Consolidate EmbeddingInputNormalizer functionality into PromptNormalizer - Refactor operation methods with factory pattern approach - Update all tests to use consolidated normalizer methods

Ref34t · 2025-08-18T19:42:34Z

@felixarntz @JasonTheAdams after going back and forth a couple of times over this feature, I can say that I'm satisfied with it right now. Looking forward for your thoughts and improvements

Adds documentation references to RequirementsUtil and CapabilityUtil (from PR WordPress#64) with usage examples showing integration patterns.

src/Utils/PromptNormalizer.php

- Fix broken generateResult() method for null model handling - Add model auto-discovery via PromptBuilder delegation - Add generateResultWithCapability() for multi-interface models - Remove redundant utility classes (Models, PromptNormalizer) - Improve error messages with model metadata - Add comprehensive test coverage - Fix coding style issues

- Fix supportsCapability method calls - use getSupportedCapabilities() instead - Update test mocks to use proper ProviderRegistry mocking - Fix capability validation logic with proper capability comparison - Update error message test expectations for improved error formatting - Replace non-existent supportsCapability() with proper capability checking

- Fix mock expectation count in testGenerateResultWithCapabilityUnsupportedCapability - Update exception message format to match capability enum value - Fix code style violations with import sorting and whitespace

Remove over-engineering while preserving full MVP compatibility: - Remove 5 operation methods (not in MVP scope, purely premature) - Remove streaming method (not implemented, throws RuntimeException) - Consolidate duplicate generateResult() logic into single method - Fix broken mock implementations to return actual test data - Remove tests for non-existent methods - Clean up unused imports and code style issues

- Replace complex PHPUnit mock expectations with anonymous classes - Remove global mock setup in favor of test-specific helper methods - Add helper methods following PromptBuilderTest patterns - Remove unused MockTextGenerationModel and MockImageGenerationModel classes - Simplify test code while maintaining same coverage and behavior

felixarntz

@Ref34t Looks pretty good! A few points of follow up feedback where we can simplify, and most importantly enable passing a ModelConfig.

src/AiClient.php

felixarntz · 2025-08-27T22:20:50Z

src/AiClient.php

+        if ($model === null) {
+            return self::prompt($prompt)->generateResult();
+        }
+
+        // Infer capability from model interface (priority order matters)
+        if ($model instanceof TextGenerationModelInterface) {
+            return self::generateResultWithCapability($prompt, CapabilityEnum::textGeneration(), $model);
+        }
+
+        if ($model instanceof ImageGenerationModelInterface) {
+            return self::generateResultWithCapability($prompt, CapabilityEnum::imageGeneration(), $model);
+        }
+
+        if ($model instanceof TextToSpeechConversionModelInterface) {
+            return self::generateResultWithCapability($prompt, CapabilityEnum::textToSpeechConversion(), $model);
+        }
+
+        if ($model instanceof SpeechGenerationModelInterface) {
+            return self::generateResultWithCapability($prompt, CapabilityEnum::speechGeneration(), $model);
+        }
+
+        throw new \InvalidArgumentException(
+            sprintf(
+                'Model "%s" must implement at least one supported generation interface ' .
+                '(TextGeneration, ImageGeneration, TextToSpeechConversion, SpeechGeneration)',
+                $model->metadata()->getId()
+            )
+        );


We should always rely on PromptBuilder here, even if a ModelInterface is provided:

If the second parameter is a ModelConfig, we need to pass it to PromptBuilder::usingModelConfig.

If a ModelInterface is provided, we need to call PromptBuilder::usingModel before calling PromptBuilder::generateResult.

I updated this to work like the other methods where it simply relies on the PromptBuilder to figure things out. Happily, it did point out a bug in the builder where it didn't infer the capability from the model if provided, which was resolved in 403e3f3.

src/AiClient.php

src/Builders/PromptBuilder.php

…nto feature/ai-client

felixarntz · 2025-08-27T23:25:33Z

@Ref34t I've updated this PR just to include the updates from #65, so that you can use PromptBuilder::usingModelConfig in here. Back to you!

…er support • Enhanced AiClient class-level documentation with detailed model specification approaches • Added ModelInterface|ModelConfig|null parameter support across all generation methods • Implemented intelligent parameter validation with descriptive error messages • Created shared MockModelCreationTrait for consistent test infrastructure • Added comprehensive ModelConfig parameter testing with various configurations • Implemented data providers for improved test organization and coverage • Added helper method tests using reflection for private method validation • Enhanced test assertions with better specificity and error context • Refactored mock registry setup to reduce code duplication • Updated provider registration comments for better clarity

Ref34t · 2025-08-28T15:24:04Z

@felixarntz @JasonTheAdams I believe now that the PR is in good shape. Kindly let me know if you have any other thoughts

JasonTheAdams

I helped move this along based on the feedback. I think we should be just about there! Awaiting a (hopefully) final review from @felixarntz!

felixarntz

@Ref34t @JasonTheAdams Thank you for all the iterations. Looks good to go 🎉

Mohamed Khaled added 3 commits August 15, 2025 12:38

feat: first draft of AiClient

d44cdad

fix: reduce comment line length in test file

634a18a

fix: shorten final comment line for code style

5fda968

Ref34t marked this pull request as ready for review August 15, 2025 23:55

Ref34t marked this pull request as draft August 15, 2025 23:56

felixarntz added the [Feature] New feature to highlight in changelogs. label Aug 16, 2025

felixarntz added this to the Complete Implementor API milestone Aug 16, 2025

Mohamed Khaled added 20 commits August 17, 2025 17:28

Merge branch 'trunk' into feature/ai-client

5a964d9

Implement isConfigured() method in AiClient

282bcbe

Add provider availability checking functionality to complete architecture specification. - Add isConfigured(ProviderAvailabilityInterface $availability): bool method - Delegate to ProviderAvailabilityInterface::isConfigured() for consistency

Fix code style: Remove trailing whitespace

c52357d

Resolve PHPStan type errors in embedding methods

a5d85b2

- Fix type errors by ensuring proper list types for embedding interfaces - Convert Message arrays to proper lists using array_values() for interface compliance

Fix code style violations in embedding infrastructure

9d5893d

- Add missing newlines at end of files - Remove trailing whitespace - Fix alphabetical import sorting in test files - All PHPCS violations resolved automatically

Add message() method placeholder for complete architecture compliance

4ce660b

- Implement message() method with placeholder that throws RuntimeException - Add comprehensive test coverage for message() method

Refactor AiClient utilities into separate classes for better maintain…

948b3d5

…ability - Extract PromptNormalizer utility class for prompt format standardization - Extract ModelDiscovery utility class for capability-based model discovery

Implement comprehensive AiClient refactoring with utility classes

23f287b

Extract interface validation, operation factory, embedding input normalization, and generation strategy resolution into dedicated utility classes.

Fix PHPStan errors and PHP 7.4 compatibility issues

8cb7875

Refactor: organize the functionality

b8db9ea

Fix code style violations

2c8c79d

Ref34t marked this pull request as ready for review August 18, 2025 19:42

felixarntz and others added 4 commits August 26, 2025 23:55

Fix some bugs.

9bdc681

refactor: traditional API methods to delegate to PromptBuilder

109d0f3

fix: style improvements

077cc8d

Add utility classes documentation to AiClient

587489c

Adds documentation references to RequirementsUtil and CapabilityUtil (from PR WordPress#64) with usage examples showing integration patterns.

JasonTheAdams reviewed Aug 27, 2025

View reviewed changes

src/Utils/PromptNormalizer.php Outdated Show resolved Hide resolved

Ref34t and others added 5 commits August 27, 2025 22:59

fix: resolve test failures and code style violations

0d4c6de

- Fix mock expectation count in testGenerateResultWithCapabilityUnsupportedCapability - Update exception message format to match capability enum value - Fix code style violations with import sorting and whitespace

felixarntz reviewed Aug 27, 2025

View reviewed changes

felixarntz added 2 commits August 27, 2025 16:23

Merge branch 'trunk' into feature/ai-client

f638664

Merge branch 'feature/ai-client' of github.com:Ref34t/php-ai-client i…

70d0bb2

…nto feature/ai-client

Mohamed Khaled added 5 commits August 28, 2025 11:40

docs: update outdated PromptBuilder integration comment

f4b3174

implement dependency injection pattern for registry management

ad23c59

fix code style issues: line length and whitespace

9f7424f

fix function declaration brace formatting

0130294

JasonTheAdams added 4 commits August 28, 2025 13:39

refactor: renames method to getConfiguredPromptBuilder

4e86daa

test: removes getConfiguredPromptBuilder tests

7d007d1

feat: infers prompt capability from model if provided

403e3f3

refactor: simplifies generateResult to rely on PromptBuilder

09aa789

JasonTheAdams self-requested a review August 28, 2025 21:48

JasonTheAdams approved these changes Aug 28, 2025

View reviewed changes

felixarntz approved these changes Aug 28, 2025

View reviewed changes

felixarntz merged commit 2c8bfa2 into WordPress:trunk Aug 28, 2025
4 checks passed

Ref34t deleted the feature/ai-client branch August 29, 2025 06:53

felixarntz mentioned this pull request Sep 2, 2025

Initial MVP task breakdown #20

Closed

11 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add the AiClient with testing suite #55

Add the AiClient with testing suite #55

Uh oh!

Ref34t commented Aug 15, 2025

Uh oh!

Ref34t commented Aug 15, 2025 •

edited

Loading

Uh oh!

Ref34t commented Aug 18, 2025

Uh oh!

Uh oh!

felixarntz left a comment

Uh oh!

Uh oh!

Uh oh!

felixarntz Aug 27, 2025 •

edited

Loading

Uh oh!

JasonTheAdams Aug 28, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

felixarntz commented Aug 27, 2025

Uh oh!

Ref34t commented Aug 28, 2025

Uh oh!

JasonTheAdams left a comment

Uh oh!

felixarntz left a comment

Uh oh!

Uh oh!

Uh oh!

Add the AiClient with testing suite #55

Add the AiClient with testing suite #55

Uh oh!

Conversation

Ref34t commented Aug 15, 2025

Uh oh!

Ref34t commented Aug 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Ref34t commented Aug 18, 2025

Uh oh!

Uh oh!

felixarntz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

felixarntz Aug 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JasonTheAdams Aug 28, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

felixarntz commented Aug 27, 2025

Uh oh!

Ref34t commented Aug 28, 2025

Uh oh!

JasonTheAdams left a comment

Choose a reason for hiding this comment

Uh oh!

felixarntz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Ref34t commented Aug 15, 2025 •

edited

Loading

felixarntz Aug 27, 2025 •

edited

Loading