<?php
/**
 * AI Client Factory Interface
 *
 * Extracted from RestAPIClientFactory.php so PSR-4 autoload can locate it
 * before Mockery synthesizes a phantom class during test runs. Co-locating
 * the interface with its implementation caused Mockery (which falls back to
 * a generated phantom when autoload fails) to redeclare the symbol later
 * when the real file finally loaded.
 *
 * @package AIPT\Api\Services
 * @since   2.4.1
 */

namespace AIPT\Api\Services;

use AIPT\Api\AIClientInterface;

/**
 * Interface for AI Client Factory
 *
 * Defines contract for creating AI client instances based on provider.
 *
 * @internal Used by RestEndpoints and bulk/chatbot service layers.
 */
interface AIClientFactoryInterface {
	/**
	 * Create AI client instance
	 *
	 * @param string|null $provider Provider name (openai|gemini|openrouter|claude). If null, uses configured provider.
	 * @return AIClientInterface AI client instance
	 * @throws \Exception If API key is not configured for provider
	 */
	public function create( ?string $provider = null ): AIClientInterface;

	/**
	 * Get default model for provider
	 *
	 * @param string $provider Provider name
	 * @return string Default model identifier
	 */
	public function getDefaultModel( string $provider ): string;

	/**
	 * Normalize model identifier for provider
	 *
	 * Validates model against provider's supported models and returns normalized identifier.
	 * If model is invalid, persists fallback to options and returns fallback.
	 *
	 * @param string $provider Provider name
	 * @param string|null $model Model identifier to normalize
	 * @return string Normalized model identifier
	 */
	public function normalizeModel( string $provider, ?string $model ): string;
}
