| 1 |
<?php |
| 2 |
/** |
| 3 |
* ProviderInterface — contract every AI provider adapter implements. |
| 4 |
* |
| 5 |
* The agent loop speaks one NORMALIZED dialect; adapters translate to and from |
| 6 |
* each provider's wire format. |
| 7 |
* |
| 8 |
* Normalized message (stored in wpfnl_ai_messages.content as JSON): |
| 9 |
* role 'user' : { text: string } |
| 10 |
* role 'assistant' : { text: string, tool_calls: [ {id, name, arguments:object} ] } |
| 11 |
* role 'tool' : { tool_call_id: string, name: string, content: string, is_error: bool } |
| 12 |
* |
| 13 |
* Assistant messages may carry provider-native blocks in meta['raw'] (e.g. |
| 14 |
* Anthropic thinking blocks) which adapters replay verbatim when rebuilding |
| 15 |
* history for the SAME provider — required for tool-use loops with thinking. |
| 16 |
* |
| 17 |
* Normalized response from chat(): |
| 18 |
* { |
| 19 |
* text: string, |
| 20 |
* tool_calls: [ {id, name, arguments:object} ], |
| 21 |
* stop_reason: 'end_turn'|'tool_use'|'max_tokens', |
| 22 |
* raw: mixed, // provider-native assistant payload for history replay |
| 23 |
* usage: { input_tokens:int, output_tokens:int } |
| 24 |
* } |
| 25 |
* |
| 26 |
* @package WPFunnels\AI |
| 27 |
* @since 3.13.0 |
| 28 |
*/ |
| 29 |
|
| 30 |
namespace WPFunnels\AI\Providers; |
| 31 |
|
| 32 |
defined( 'ABSPATH' ) || exit; |
| 33 |
|
| 34 |
/** |
| 35 |
* Interface ProviderInterface |
| 36 |
*/ |
| 37 |
interface ProviderInterface { |
| 38 |
|
| 39 |
/** |
| 40 |
* Run one model turn. |
| 41 |
* |
| 42 |
* @param string $system System prompt. |
| 43 |
* @param array $messages Normalized message list (each: role, content, meta). |
| 44 |
* @param array $tools Normalized tool defs: [ {name, description, input_schema} ]. |
| 45 |
* @param bool $force_tool_use When true, the model must call a tool instead of |
| 46 |
* replying with narration-only text. Set on the first |
| 47 |
* model call of a turn so an autonomous build request |
| 48 |
* can't end with a promise ("I'll do X now...") and no |
| 49 |
* tool_calls — which AgentLoop would otherwise treat as |
| 50 |
* a finished turn. |
| 51 |
* @return array|\WP_Error Normalized response. |
| 52 |
*/ |
| 53 |
public function chat( $system, $messages, $tools, $force_tool_use = false ); |
| 54 |
|
| 55 |
/** |
| 56 |
* Cheap live credential check. |
| 57 |
* |
| 58 |
* @return true|\WP_Error |
| 59 |
*/ |
| 60 |
public function validateKey(); |
| 61 |
|
| 62 |
/** |
| 63 |
* Provider slug ('anthropic' | 'openai' | 'gemini' | 'wordpress_ai'). |
| 64 |
* |
| 65 |
* @return string |
| 66 |
*/ |
| 67 |
public function slug(); |
| 68 |
} |
| 69 |
|
