Add AI_Service layer for centralized AI operations #101

caseymanos · 2025-11-26T09:44:30Z

What?

Closes #26

Implements a centralized AI service layer (AI_Service) that provides a consistent interface for experimental features to communicate with AI providers through the WP AI Client SDK.

Why?

The plugin needs a unified service layer so that experimental features can communicate with AI providers without duplicating logic or directly coupling to the AI_Client SDK. This provides:

A single point of configuration for AI provider requests
Graceful handling when no provider is configured
Hooks and filters for developers/hosts to customize behavior
A foundation for future AI-powered features

How?

New files:

includes/Services/AI_Service.php - Singleton service class with generate_text(), generate_texts(), create_prompt(), is_available() methods
includes/Services/Contracts/AI_Service_Interface.php - Interface contract ensuring consistent implementation
tests/Integration/Includes/Services/AI_ServiceTest.php - Integration tests (26 test cases)

Modified files:

includes/bootstrap.php - Initializes AI_Service after AI_Client::init()
includes/helpers.php - Adds get_ai_service() helper function

Hooks and filters:

Hook	Type	Description
`ai_service_available`	Filter	Override provider availability detection
`ai_service_initialized`	Action	Fires when AI service initializes
`ai_service_prompt_builder`	Filter	Modify prompt builder before generation

Testing Instructions

Ensure you have an AI provider configured (Settings > AI Credentials)
Run automated tests: npm run test:php
Verify the service via WP-CLI:

npm run wp-env -- run cli wp eval '
$service = WordPress\AI\get_ai_service();
echo "Available: " . ($service->is_available() ? "yes" : "no") . "\n";
if ($service->is_available()) {
    $result = $service->generate_text("Say hello in 3 words");
    echo "Result: " . $result . "\n";
}
'

Test without credentials by temporarily removing them - is_available() should return false
Verify hooks work by adding a filter:

add_filter( 'ai_service_available', '__return_false' );
// Service should now report unavailable

Testing Instructions for Keyboard

Not applicable - this PR adds backend service infrastructure only with no UI changes.

Screenshots or screencast

Not applicable - this PR adds backend service infrastructure only with no UI changes.

Implements a service layer that provides a consistent interface for experimental features to communicate with AI providers through the WP AI Client SDK. New files: - includes/Services/AI_Service.php - Singleton service class - includes/Services/Contracts/AI_Service_Interface.php - Interface contract - tests/Integration/Includes/Services/AI_ServiceTest.php - Integration tests Features: - Centralized AI provider configuration and request handling - Model preference caching with clear_model_cache() method - Graceful handling when no provider is configured - Helper function get_ai_service() for easy access Hooks and filters: - ai_service_available: Override provider availability detection - ai_service_initialized: Action when service initializes - ai_service_prompt_builder: Filter prompt builder before generation Closes WordPress#26

github-actions · 2025-11-26T09:44:43Z

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.

Unlinked Accounts

The following contributors have not linked their GitHub and WordPress.org accounts: @iTsphillgood.

Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases.

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

Unlinked contributors: iTsphillgood.

Co-authored-by: caseymanos <[email protected]>
Co-authored-by: dkotter <[email protected]>
Co-authored-by: felixarntz <[email protected]>
Co-authored-by: jeffpaul <[email protected]>

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

codecov · 2025-11-26T09:47:46Z

Codecov Report

❌ Patch coverage is 88.88889% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 50.91%. Comparing base (1c00879) to head (9a4845d).
⚠️ Report is 35 commits behind head on develop.

Files with missing lines	Patch %	Lines
...bilities/Excerpt_Generation/Excerpt_Generation.php	0.00%	1 Missing ⚠️
includes/Abilities/Summarization/Summarization.php	0.00%	1 Missing ⚠️
...es/Abilities/Title_Generation/Title_Generation.php	0.00%	1 Missing ⚠️

Additional details and impacted files

@@              Coverage Diff              @@
##             develop     #101      +/-   ##
=============================================
+ Coverage      50.33%   50.91%   +0.57%     
- Complexity       366      375       +9     
=============================================
  Files             26       27       +1     
  Lines           1951     1974      +23     
=============================================
+ Hits             982     1005      +23     
  Misses           969      969

Flag	Coverage Δ
unit	`50.91% <88.88%> (+0.57%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

jeffpaul · 2025-11-26T18:34:29Z

@caseymanos thanks for the PR! I see you note this closes #26, but looking to double confirm that the various goals in that issue description are all covered by your work here; correct?

felixarntz

While overall I agree that a more opinionated AI service makes sense in the context of this plugin, I think it does too many things. Specifically, it obscures some of the flexibility that the underlying WordPress AI Client APIs provide, for no good reason as far as I can tell.

I think we should simplify the implementation to focus on creating a prompt builder with plugin specific defaults applied, and leave the rest to the regular prompt builder APIs.

includes/Services/Contracts/AI_Service_Interface.php

includes/Services/AI_Service.php

iTsphillgood · 2025-11-26T21:54:38Z

While overall I agree that a more opinionated AI service makes sense in the context of this plugin, I think it does too many things. Specifically, it obscures some of the flexibility that the underlying WordPress AI Client APIs provide, for no good reason as far as I can tell.

I think we should simplify the implementation to focus on creating a prompt builder with plugin specific defaults applied, and leave the rest to the regular prompt builder APIs.

Have you tried Google Jules agent or Gemini 3 on cli?

@felixarntz

Address @felixarntz review comments: - Remove AI_Service_Interface (premature abstraction) - Remove DEFAULT_TEMPERATURE constant (no forced defaults) - Remove generate_text/generate_texts methods (redundant wrappers) - Make create_prompt() the centerpiece with optional $options array - Use existing get_preferred_models() helper instead of duplicating - Simplify from 311 to 181 lines The new API follows Felix's suggested pattern: $text = $ai_service->create_prompt($prompt, $options)->generate_text();

caseymanos · 2025-11-27T10:19:45Z

@felixarntz @jeffpaul
Thanks for the feedback! I made the following improvements:

Removed the interface - Deleted AI_Service_Interface.php
Removed DEFAULT_TEMPERATURE - No forced defaults; consumers specify explicitly or use provider defaults
Made create_prompt() the centerpiece - Removed generate_text() and generate_texts() wrapper methods

Additional improvements:

Simplified options handling using the SDK's ModelConfig::fromArray()
Options array supports all 11 SDK scalar options with snake_case keys
Full SDK API remains available via method chaining after create_prompt()

Updated API

// Simple usage - model preferences auto-applied
$text = get_ai_service()->create_prompt('Summarize this...')->generate_text();

// With options array
$text = get_ai_service()->create_prompt('Translate to French', [
    'system_instruction' => 'You are a translator.',
    'temperature'        => 0.3,
])->generate_text();

// Full SDK access via chaining
$titles = get_ai_service()->create_prompt('Generate titles')
    ->using_candidate_count(5)
    ->generate_texts();

Hooks Available

| Hook                   | Type   | Description                              |
|------------------------|--------|------------------------------------------|
| ai_service_available   | Filter | Override provider availability detection |
| ai_service_initialized | Action | Fires when AI service initializes        |
| ai_preferred_models    | Filter | Customize default model preferences      |

Note: Removed ai_service_prompt_builder filter as it's no longer needed - create_prompt() returns the builder directly so consumers can modify it with the SDK

felixarntz

@caseymanos Almost LGTM, just one remaining concern.

includes/Services/AI_Service.php

felixarntz · 2025-11-29T04:15:09Z

Related: @dkotter @caseymanos I'm not sure about the get_preferred_models() function, only spotted it now. Didn't want to flag it during the review since it's already in the codebase. Can we rename this to something like get_preferred_models_for_text_generation()? Because that's closer to what that function does, based on the models it currently returns.

Address Felix's review feedback: - Remove is_available() method from AI_Service (SDK provides is_supported_for_*() methods on Prompt_Builder for capability checking) - Rename get_preferred_models() to get_preferred_models_for_text_generation() to clarify the function returns text-generation-specific models - Rename filter from ai_preferred_models to ai_preferred_models_for_text_generation - Update docstring example to use SDK's is_supported_for_text_generation()

caseymanos · 2025-11-29T12:32:18Z

@felixarntz
Addressed both comments - removed is_available() entirely, which also gets rid of the hardcoded
option string. Updated the docstring example to show using the SDK's
is_supported_for_text_generation() instead.

Also renamed get_preferred_models() to get_preferred_models_for_text_generation() (filter renamed too).

felixarntz

@caseymanos Thanks, LGTM!

Note there are some merge conflicts though that need to be resolved.

includes/Services/AI_Service.php

@SInCE

Address dkotter and felixarntz review feedback: - Rename create_prompt() to create_textgen_prompt() to clarify this method is specifically for text generation - Update @SInCE tags from 0.1.0 to x.x.x for release process - Rename hook from ai_service_initialized to ai_experiments_service_initialized to use correct prefix

caseymanos · 2025-12-02T02:48:40Z

@felixarntz @dkotter

Renamed create_prompt() to create_textgen_prompt() to make it clear this is specifically for text
generation, and gives space for future image/audio prompts
Updated all @ since tags to x.x.x for the release process
Renamed hook from ai_service_initialized to ai_experiments_service_initialized to use the correct prefix

dkotter · 2026-01-13T19:30:23Z

@caseymanos Thanks for the work here. We've merged in a few other PRs that used the get_preferred_models function and since this PR changes the name of that, we now have a few linting errors. Do you have time to update those references?

…ls_for_text_generation

dkotter · 2026-01-14T17:33:44Z

includes/bootstrap.php

+		// Initialize the WP AI Client.
+		AI_Client::init();


Looking at this again, we already run this exact same code a few lines above (currently line 206). Is there a reason to initialize it again here? Or can this be removed?

Note I removed that here 9a4845d but let me know if that is wrong

dkotter · 2026-01-14T17:38:14Z

includes/bootstrap.php

+		$ai_service = AI_Service::get_instance();
+		$ai_service->init();


I guess question on this as well looking at it again. It seems the init method we are calling here doesn't actually do anything (beyond just running a hook). Do we need this init method and the loading of this class here? Or can we remove this and anyone that wants to use this class can be done via the get_ai_service helper function?

Note I removed these lines and the init method here: 9a4845d. But let me know if that will cause problems

…ed the function and filter names

jeffpaul assigned caseymanos Nov 26, 2025

jeffpaul added this to the 0.2.0 milestone Nov 26, 2025

jeffpaul requested review from JasonTheAdams, dkotter and felixarntz November 26, 2025 18:33

felixarntz requested changes Nov 26, 2025

View reviewed changes

includes/Services/Contracts/AI_Service_Interface.php Outdated Show resolved Hide resolved

includes/Services/AI_Service.php Outdated Show resolved Hide resolved

includes/Services/AI_Service.php Outdated Show resolved Hide resolved

jeffpaul changed the base branch from trunk to develop November 26, 2025 22:08

caseymanos force-pushed the issue-26-ai-connection-manager branch from b3bfd72 to 8e0a728 Compare November 27, 2025 09:26

refactor to use ModelConfig for options array

edc69eb

jeffpaul requested a review from felixarntz November 28, 2025 15:54

felixarntz reviewed Nov 29, 2025

View reviewed changes

includes/Services/AI_Service.php Outdated Show resolved Hide resolved

includes/Services/AI_Service.php Outdated Show resolved Hide resolved

jeffpaul requested a review from felixarntz December 1, 2025 03:25

felixarntz previously approved these changes Dec 1, 2025

View reviewed changes

dkotter requested changes Dec 1, 2025

View reviewed changes

includes/Services/AI_Service.php Outdated Show resolved Hide resolved

includes/Services/AI_Service.php Outdated Show resolved Hide resolved

includes/Services/AI_Service.php Outdated Show resolved Hide resolved

includes/Services/AI_Service.php Show resolved Hide resolved

caseymanos added 3 commits December 1, 2025 17:25

Merge origin/trunk into issue-26-ai-connection-manager

34ab73a

Merge origin/develop into issue-26-ai-connection-manager

45f813a

jeffpaul modified the milestones: 0.1.1, 0.2.0 Dec 2, 2025

dkotter previously approved these changes Dec 2, 2025

View reviewed changes

Merge branch 'develop' into issue-26-ai-connection-manager

acdbfaf

caseymanos dismissed felixarntz’s stale review via acdbfaf December 8, 2025 23:30

JasonTheAdams removed their request for review December 9, 2025 00:02

jeffpaul requested a review from felixarntz January 7, 2026 18:17

dkotter and others added 3 commits January 13, 2026 11:47

Merge branch 'develop' into issue-26-ai-connection-manager

67d61ae

Merge branch 'develop' into issue-26-ai-connection-manager

31b2f3a

Merge branch 'develop' into issue-26-ai-connection-manager

60149e1

Update all uses of get_preferred_models to the new get_preferred_mode…

3411092

…ls_for_text_generation

dkotter dismissed their stale review via 3411092 January 14, 2026 17:25

dkotter requested changes Jan 14, 2026

View reviewed changes

dkotter reviewed Jan 14, 2026

View reviewed changes

jeffpaul mentioned this pull request Jan 16, 2026

Release version 0.2.0 #178

Closed

20 tasks

jeffpaul modified the milestones: 0.2.0, 0.3.0 Jan 20, 2026

dkotter added 2 commits January 20, 2026 14:36

Merge branch 'develop' into issue-26-ai-connection-manager

6baf933

Remove code that isn't needed. Update since statements since we chang…

9a4845d

…ed the function and filter names

dkotter approved these changes Jan 20, 2026

View reviewed changes

jeffpaul merged commit 0412047 into WordPress:develop Jan 23, 2026
28 checks passed

dkotter modified the milestones: 0.3.0, 0.2.1 Jan 26, 2026

		$ai_service = AI_Service::get_instance();
		$ai_service->init();

Add AI_Service layer for centralized AI operations #101

Add AI_Service layer for centralized AI operations #101

Uh oh!

Conversation

caseymanos commented Nov 26, 2025 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What?

Why?

How?

Testing Instructions

Testing Instructions for Keyboard

Screenshots or screencast

Uh oh!

github-actions bot commented Nov 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Unlinked Accounts

Uh oh!

codecov bot commented Nov 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

jeffpaul commented Nov 26, 2025

Uh oh!

felixarntz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

iTsphillgood commented Nov 26, 2025

Uh oh!

caseymanos commented Nov 27, 2025

Updated API

Uh oh!

felixarntz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

felixarntz commented Nov 29, 2025

Uh oh!

caseymanos commented Nov 29, 2025

Uh oh!

felixarntz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

caseymanos commented Dec 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dkotter commented Jan 13, 2026

Uh oh!

dkotter Jan 14, 2026

Choose a reason for hiding this comment

Uh oh!

dkotter Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

dkotter Jan 14, 2026 • 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!

dkotter Jan 20, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

caseymanos commented Nov 26, 2025 •

edited by github-actions bot

Loading

github-actions bot commented Nov 26, 2025 •

edited

Loading

codecov bot commented Nov 26, 2025 •

edited

Loading

caseymanos commented Dec 2, 2025 •

edited

Loading

dkotter Jan 14, 2026 •

edited

Loading