| 1 |
<?php |
| 2 |
|
| 3 |
namespace Better_Payment\Lite\AI\Contracts; |
| 4 |
|
| 5 |
if ( ! defined( 'ABSPATH' ) ) { |
| 6 |
exit; |
| 7 |
} |
| 8 |
|
| 9 |
/** |
| 10 |
* Contract every AI provider must implement. |
| 11 |
* |
| 12 |
* The rest of the AI layer talks only to this interface — never to a concrete |
| 13 |
* provider — so switching providers (or adding a new one) requires no change to |
| 14 |
* the builder, services, or REST layer. Providers are provider-agnostic in and |
| 15 |
* out: they receive normalised messages + tool descriptors and return a |
| 16 |
* normalised result. |
| 17 |
* |
| 18 |
* @see \Better_Payment\Lite\AI\Providers\AbstractProvider Shared HTTP plumbing. |
| 19 |
* @see \Better_Payment\Lite\AI\ProviderRegistry Discovery / instantiation. |
| 20 |
*/ |
| 21 |
interface AIProviderInterface { |
| 22 |
|
| 23 |
/** |
| 24 |
* Send a chat/completion request. |
| 25 |
* |
| 26 |
* @param array $messages Normalised turns: [ [ 'role' => 'user'|'assistant'|'system', 'content' => string ], ... ]. |
| 27 |
* @param array $options { |
| 28 |
* @type string $system System prompt. |
| 29 |
* @type string $model Model id override. |
| 30 |
* @type float $temperature Sampling temperature. |
| 31 |
* @type int $max_tokens Output token cap. |
| 32 |
* @type array $tools Provider-agnostic tool descriptors (see OperationRegistry::as_tools()). |
| 33 |
* } |
| 34 |
* @return array { |
| 35 |
* @type string $text Assistant natural-language message. |
| 36 |
* @type array $tool_calls [ [ 'name' => string, 'arguments' => array ], ... ]. |
| 37 |
* @type array $usage Token usage, when reported. |
| 38 |
* @type string|null $error Human-readable error, or null on success. |
| 39 |
* @type mixed $raw Raw decoded provider response (for debugging). |
| 40 |
* } |
| 41 |
*/ |
| 42 |
public function chat( array $messages, array $options = [] ): array; |
| 43 |
|
| 44 |
/** |
| 45 |
* Generate an image from a prompt. |
| 46 |
* |
| 47 |
* @param string $prompt |
| 48 |
* @param array $options { @type string $model; @type string $size; } |
| 49 |
* @return array { |
| 50 |
* @type string $url Remote image URL, when the provider returns one. |
| 51 |
* @type string $b64 Base64 image data, when the provider returns bytes. |
| 52 |
* @type string $mime Image mime type. |
| 53 |
* @type string|null $error Human-readable error, or null on success. |
| 54 |
* } |
| 55 |
*/ |
| 56 |
public function generate_image( string $prompt, array $options = [] ): array; |
| 57 |
|
| 58 |
/** Stable provider id (e.g. "openai"). */ |
| 59 |
public function get_id(): string; |
| 60 |
|
| 61 |
/** Human label (e.g. "OpenAI"). */ |
| 62 |
public function get_label(): string; |
| 63 |
|
| 64 |
/** |
| 65 |
* Available model ids for this provider. |
| 66 |
* |
| 67 |
* @return array<int, string> |
| 68 |
*/ |
| 69 |
public function get_models(): array; |
| 70 |
|
| 71 |
/** Whether this provider can generate images. */ |
| 72 |
public function supports_images(): bool; |
| 73 |
|
| 74 |
/** Whether the provider has the configuration (API key) it needs to run. */ |
| 75 |
public function is_configured(): bool; |
| 76 |
} |
| 77 |
|
