1	<?php
2	declare(strict_types=1);
3
4	namespace App\Service\Api;
5
6	use Cake\Http\Client\Response;
7
8	/**
9	* AiProviderInterface
10	*
11	* Defines the contract for AI API providers (Anthropic, OpenRouter, etc.).
12	* This interface allows generators to work with any AI provider that implements it,
13	* enabling easy switching between providers without changing generator code.
14	*/
15	interface AiProviderInterface
16	{
17	/**
18	* Sends a request to the AI provider API.
19	*
20	* @param array $payload The request payload in Anthropic format.
21	* @param int $timeout Request timeout in seconds.
22	* @return \Cake\Http\Client\Response The HTTP response from the API.
23	* @throws \Cake\Http\Exception\ServiceUnavailableException If the API request fails.
24	*/
25	public function sendRequest(array $payload, int $timeout = 30): Response;
26
27	/**
28	* Parses the API response and extracts the content.
29	*
30	* @param \Cake\Http\Client\Response $response The HTTP response from the API.
31	* @return array The parsed response data as an associative array.
32	*/
33	public function parseResponse(Response $response): array;
34
35	/**
36	* Checks if the provider is properly configured with valid credentials.
37	*
38	* @return bool True if the provider has a valid API key configured.
39	*/
40	public function isConfigured(): bool;
41
42	/**
43	* Gets the provider name for logging and identification purposes.
44	*
45	* @return string The provider identifier (e.g., 'anthropic', 'openrouter').
46	*/
47	public function getProviderName(): string;
48	}