Replace bundled ai-http-client with core wp-ai-client

[chubes4]

Context

Data Machine currently bundles vendor/chubes4/ai-http-client (v2.0.13) — a filter-based AI provider abstraction layer. WordPress 7.0 core now ships wp-ai-client with equivalent functionality via a fluent OOP API (wp_ai_client_prompt()). The bundled library should be removed and all AI requests routed through core's client directly.

Key constraints:

• Core's AI client does not support multisite (network-wide API key/model cascading). Data-machine must own that.
• Core requires separate provider plugins (e.g., ai-provider-for-openai) to register actual provider implementations. Data-machine follows the same model.
• No backwards compatibility layer — all chubes_ai_* filter hooks are eliminated; consuming code is rewritten.
• No custom provider implementations — data-machine does not ship or register providers. That's a separate concern.
• No adapter class — RequestBuilder calls wp_ai_client_prompt() directly and normalizes the response inline.

---

API Comparison

Aspect	ai-http-client (old)	wp-ai-client (new)
Request	Array via apply_filters('chubes_ai_request', ...)	Fluent builder: wp_ai_client_prompt()->with_history()->using_model()->generate_text_result()
Response	['success'=>bool, 'data'=>['content','usage','tool_calls'], 'error'=>string]	GenerativeAiResult|WP_Error with ->toText(), ->getTokenUsage(), candidates with MessagePart::getFunctionCall()
Tool calls in	Array in $request['tools']	FunctionDeclaration objects via using_function_declarations()
Tool calls out	$response['data']['tool_calls'] = [['name'=>..., 'parameters'=>...]]	$candidate->getMessage()->getParts() → $part->getFunctionCall() → FunctionCall::getName(), ::getArgs(), ::getId()
API keys	get_site_option('chubes_ai_http_shared_api_keys') (one array)	Connectors system: individual get_option('connectors_ai_{id}_api_key') per provider
Multisite	Built into key storage via get_site_option	None — DM must own this
Streaming	Supported (unused by DM)	Not supported

---

Implementation Plan

Step 1: Create DataMachineAPIKeys — multisite key resolver

New file: inc/Engine/AI/DataMachineAPIKeys.php

Resolution order:

1. Per-site: get_option('connectors_ai_{provider}_api_key')
2. Network: NetworkSettings::get('api_keys')[$provider]
3. Environment variable: {PROVIDER_ID}_API_KEY
4. Empty string

Modify: inc/Core/NetworkSettings.php — add 'api_keys' to NETWORK_KEYS

Step 2: Rewrite RequestBuilder::build()

Modify: inc/Engine/AI/RequestBuilder.php

Replace lines 93-105 (apply_filters('chubes_ai_request', ...)) with direct wp_ai_client_prompt() calls inline:

1. Resolve API key via DataMachineAPIKeys::get($provider)
2. Set auth on registry: $registry->setProviderRequestAuthentication($provider, new ApiKeyRequestAuthentication($key))
3. Extract system messages from $request['messages'] → using_system_instruction()
4. Convert remaining messages to Message objects → with_history()
5. Convert tools to FunctionDeclaration objects → using_function_declarations()
6. Set provider/model → using_provider() + using_model(registry->getProviderModel())
7. Apply config → using_temperature(), using_max_tokens() if set
8. Call generate_text_result()
9. Normalize GenerativeAiResult → DM's expected response array inline:
   • $result->toText() → ['data']['content']
   • $result->getTokenUsage() → ['data']['usage']
   • Tool calls from message parts → ['data']['tool_calls'] as [['name'=>..., 'parameters'=>...]]
   • WP_Error → ['success'=>false, 'error'=>...]

Step 3: Migrate API key storage

Modify: inc/Engine/Filters/DataMachineFilters.php

• Remove the chubes_ai_provider_api_keys filter hook
• Add one-time migration: read get_site_option('chubes_ai_http_shared_api_keys') → write each key into update_option('connectors_ai_{provider}_api_key', $key)

Step 4: Rewrite Providers::handle_get_providers()

Modify: inc/Api/Providers.php

Replace chubes_ai_providers, chubes_ai_provider_api_keys, chubes_ai_models filter calls with:

$registry = AiClient::defaultRegistry();
$provider_ids = $registry->getRegisteredProviderIds();
// For each: wp_get_connector($id) for metadata
// $registry->findProviderModelsMetadataForSupport() for models

Step 5: Rewrite API key management in SettingsAbilities

Modify: inc/Abilities/SettingsAbilities.php

• getAiProviderSettings() (line 340): Replace apply_filters('chubes_ai_provider_api_keys', null) with reading from Connectors + NetworkSettings
• executeUpdateSettings() (line 498-513): Write to update_option('connectors_ai_{provider}_api_key', ...) for per-site, NetworkSettings::update(['api_keys' => ...]) for network

Step 6: Update Chat.php provider validation

Modify: inc/Api/Chat/Chat.php (line 77) — replace apply_filters('chubes_ai_providers', array()) with AiClient::defaultRegistry()->getRegisteredProviderIds() or wp_get_connectors()

Step 7: Remove ai-http-client dependency

• Remove from composer.json: "chubes4/ai-http-client": "^2.0.13"
• Delete vendor/chubes4/ai-http-client/
• Remove autoload references

---

Files to Modify

File	Change
inc/Engine/AI/DataMachineAPIKeys.php	NEW — multisite API key resolution
inc/Engine/AI/RequestBuilder.php	Replace chubes_ai_request filter with direct wp_ai_client_prompt() calls
inc/Api/Providers.php	Replace all chubes_ai_* filters with ProviderRegistry calls
inc/Abilities/SettingsAbilities.php	Replace chubes_ai_provider_api_keys with Connectors + NetworkSettings
inc/Engine/Filters/DataMachineFilters.php	Remove chubes_ai_provider_api_keys filter; add one-time key migration
inc/Api/Chat/Chat.php	Replace chubes_ai_providers filter with registry check
inc/Core/NetworkSettings.php	Add api_keys to NETWORK_KEYS
composer.json	Remove chubes4/ai-http-client dependency
vendor/chubes4/	DELETE entire directory

What does NOT change

• AIConversationLoop.php — consumes RequestBuilder::build() return value which keeps the same array shape
• ConversationManager.php — builds DM's internal message format; RequestBuilder handles the translation
• ToolExecutor.php, ToolPolicyResolver.php, ToolServiceProvider.php — tool execution unchanged
• PromptBuilder.php (DM's directive system) — unchanged, still builds the $request array
• All directive classes — unchanged
• AIStep.php, ChatOrchestrator.php — unchanged (call AIConversationLoop which calls RequestBuilder)
• Logger.php, DirectoryManager.php — unchanged multisite code

Key SDK Classes (for reference)

Class	Full Namespace
Message	WordPress\AiClient\Messages\DTO\Message
MessagePart	WordPress\AiClient\Messages\DTO\MessagePart
MessageRoleEnum	WordPress\AiClient\Messages\Enums\MessageRoleEnum
FunctionDeclaration	WordPress\AiClient\Tools\DTO\FunctionDeclaration
FunctionCall	WordPress\AiClient\Tools\DTO\FunctionCall
FunctionResponse	WordPress\AiClient\Tools\DTO\FunctionResponse
AiClient	WordPress\AiClient\AiClient
ProviderRegistry	WordPress\AiClient\Providers\ProviderRegistry
GenerativeAiResult	WordPress\AiClient\Results\DTO\GenerativeAiResult
ApiKeyRequestAuthentication	WordPress\AiClient\Providers\Http\DTO\ApiKeyRequestAuthentication
WP_AI_Client_Prompt_Builder	(WordPress wrapper class)

Verification Checklist

• RequestBuilder::build() correctly translates DM arrays → wp-ai-client calls and normalizes response back
• API key migration: chubes_ai_http_shared_api_keys → individual connectors_ai_* options
• Multisite cascade: network-level key → per-site override → env var fallback
• GET /datamachine/v1/providers returns correct data from registry
• Chat flow end-to-end with tool calls
• Pipeline flow with token tracking and handler completion
• grep -r 'chubes_ai_' inc/ returns zero results

[chubes4]

Audit Notes — Source Verification (April 16, 2026)

Verified the migration plan against the actual codebase on main. The plan is mostly accurate but has several gaps and one significant architectural blind spot. Here's what I found:

✅ What the plan gets right

1. Single dispatch point — Confirmed. RequestBuilder::build() at line 94 is the only production apply_filters('chubes_ai_request', ...) call. The handler lives in vendor/.../Requests.php:197 at priority 99 with 6 accepted args.

2. Response shape — The normalized response array (success, data.content, data.tool_calls, data.usage) is consumed by AIConversationLoop exactly as described. The loop accesses $ai_response['success'], $ai_response['data']['tool_calls'], $ai_response['data']['content'], $ai_response['data']['usage'].

3. "What does NOT change" section — Correct. AIConversationLoop, ConversationManager, ToolExecutor, ToolPolicyResolver, PromptBuilder (DM's directive system), all directive classes, AIStep, ChatOrchestrator — none need to change in this phase IF we keep the response array shape stable through RequestBuilder.

4. Provider filter call sites — Confirmed 5 production call sites for chubes_ai_providers across the plugin + vendor code.

5. API key dual-purpose pattern — Confirmed. chubes_ai_provider_api_keys uses null=GET, array=SET. There are 12 total call sites (6 in plugin code, 6 in vendor code).

❌ What the plan gets wrong or misses

1. chubes_ai_tools filter survives — it's NOT eliminated

The plan says "No backwards compatibility layer — all chubes_ai_* filter hooks are eliminated." But chubes_ai_tools is used in three places in plugin code (not vendor code):

• ToolPolicyResolver.php:311 — Pipeline handler tool resolution (dynamic tools from adjacent steps)
• PipelinesFilters.php:137 — Admin UI tool listing
• Handlers.php:233 — Handler details API

More critically, HandlerRegistrationTrait.php:97 registers handler tool callbacks directly onto chubes_ai_tools:

if ( $aiToolCallback ) {
    add_filter('chubes_ai_tools', $aiToolCallback, 10, 4);
}

This is how every handler in data-machine-events, data-machine-socials, etc. registers its dynamic tools. These are NOT abilities. They're generated at runtime from handler config + engine data and have no ability linkage. This filter CANNOT be eliminated without first migrating all handler tools to the Abilities API — which is a separate, larger project tracked in MEMORY.md as "handler tool → ability migration."

Fix: Remove chubes_ai_tools from the "eliminated" list. This filter survives this migration. Only chubes_ai_request, chubes_ai_providers, chubes_ai_provider_api_keys, and chubes_ai_models are eliminated.

2. Missing call sites for chubes_ai_provider_api_keys

The plan only accounts for SettingsAbilities.php and vendor code. It misses:

• inc/Api/Pipelines/PipelineSteps.php:532-534 — GET+SET keys when saving a pipeline step (auto-saves API key for the step's provider)

This needs migration too.

3. PipelinesFilters.php has THREE filter calls, not mentioned

• Line 102: apply_filters('chubes_ai_providers', [])
• Line 107: apply_filters('chubes_ai_models', $key) — Note: called with 1 arg (no API key), relies on cached model data
• Line 137: apply_filters('chubes_ai_tools', [])

These power the React admin UI for pipeline configuration. All three need migration (except chubes_ai_tools which survives).

4. Connectors API key storage pattern is wrong

The plan says keys go to connectors_ai_{provider}_api_key. Looking at the actual core code:

$args['authentication']['setting_name'] = "connectors_ai_{$sanitized_id}_api_key";

This is the core Connectors API pattern — it stores keys in individual options. But the plan's DataMachineAPIKeys class proposes a 3-level cascade (site → network → env var). The network level needs to store keys in DM's own NetworkSettings, not in Connectors options. The Connectors API has no multisite awareness.

Cleaner approach: Read from Connectors API first (respects core's key storage), fall back to NetworkSettings::get('api_keys')[$provider] for network-level override, then env var. Don't duplicate keys — use Connectors as the per-site truth.

5. Missing: DataMachineFilters.php serialization safety net

The plan says to "Remove the chubes_ai_provider_api_keys filter hook" from DataMachineFilters.php. But this filter (priority 20) is a serialization corruption fix — it normalizes serialized strings back to arrays. When migrating to Connectors API, this specific safety net becomes unnecessary (individual options don't have the serialization issue), but the one-time migration in Step 3 should also handle the corruption case.

6. Missing: Vendor REST API routes become dead code

vendor/chubes4/ai-http-client/src/Filters/RestApi.php registers routes under ai-http-client/v1/ (providers, models, API keys). Once the vendor package is removed, anything consuming these endpoints breaks. The plan doesn't mention migrating or deprecating these routes. DM's own inc/Api/Providers.php serves equivalent data under datamachine/v1/providers — confirm nothing relies on the vendor routes.

📋 Corrected file change list

File	Change
inc/Engine/AI/DataMachineAPIKeys.php	NEW — multisite key resolution (Connectors → NetworkSettings → env)
inc/Engine/AI/RequestBuilder.php	Replace chubes_ai_request with wp_ai_client_prompt() calls
inc/Api/Providers.php	Replace chubes_ai_providers, chubes_ai_provider_api_keys, chubes_ai_models
inc/Api/Chat/Chat.php	Replace chubes_ai_providers in validation callback
inc/Abilities/SettingsAbilities.php	Replace chubes_ai_provider_api_keys GET/SET
inc/Api/Pipelines/PipelineSteps.php	Replace chubes_ai_provider_api_keys GET/SET (missing from original plan)
inc/Core/Admin/Pages/Pipelines/PipelinesFilters.php	Replace chubes_ai_providers + chubes_ai_models (missing from original plan)
inc/Engine/Filters/DataMachineFilters.php	Remove chubes_ai_provider_api_keys handler + add one-time migration
inc/Core/NetworkSettings.php	Add api_keys to NETWORK_KEYS
composer.json	Remove chubes4/ai-http-client
vendor/chubes4/	DELETE

Files that do NOT change (confirmed)

• AIConversationLoop.php — consumes RequestBuilder output, shape preserved
• ConversationManager.php — internal message format, unrelated
• ToolExecutor.php — tool execution, unrelated to request dispatch
• ToolPolicyResolver.php — still uses chubes_ai_tools for handler tool resolution
• ToolManager.php, BaseTool.php — static tool registry, unrelated
• PromptBuilder.php (DM's directive system) — still builds request arrays, RequestBuilder translates
• All directive classes — unchanged
• AIStep.php, ChatOrchestrator.php — call AIConversationLoop, unchanged
• HandlerRegistrationTrait.php — still registers on chubes_ai_tools

Timing recommendation

7.0 hasn't shipped (delayed, new timeline expected April 22). The @since 7.0.0 API surface has been through 4 betas and 2 RCs — it's stable. But there's no reason to rush this since no public release can depend on it yet.

Suggested approach: Start a feature/wp-ai-client-migration branch with a compatibility shim — detect function_exists('wp_ai_client_prompt'), use core when available, fall back to chubes_ai_request when not. This lets Extra Chill run on it today while keeping backwards compat for sites on 6.x.