<?php
/**
 * Abstract AI provider base class.
 *
 * @package MasterQuiz
 * @since   1.0.0
 */

if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * Class MasterQuiz_Ai_Provider
 *
 * Abstract base class for all AI provider implementations.
 *
 * @since 1.0.0
 */
abstract class MasterQuiz_Ai_Provider {

	/**
	 * The API key for this provider.
	 *
	 * @var string
	 */
	protected $api_key;

	/**
	 * Constructor.
	 *
	 * @since 1.0.0
	 *
	 * @param string $api_key The API key.
	 */
	public function __construct( $api_key = '' ) {
		$this->api_key = $api_key;
	}

	/**
	 * Make an API call to the provider.
	 *
	 * @since 1.0.0
	 *
	 * @param string $prompt  The prompt to send.
	 * @param array  $schema  Optional JSON schema for structured output.
	 * @param int    $timeout Request timeout in seconds.
	 * @param string $model   Optional specific model to use.
	 * @return string|WP_Error Raw response text or error.
	 */
	abstract public function call( $prompt, $schema = array(), $timeout = 60, $model = '' );

	/**
	 * Get the provider name.
	 *
	 * @since 1.0.0
	 *
	 * @return string Provider identifier (gemini, openrouter, groq).
	 */
	abstract public function get_provider_name();

	/**
	 * Get available models for this provider.
	 *
	 * @since 1.0.0
	 *
	 * @return array List of model identifiers.
	 */
	abstract public function get_models();

	/**
	 * Test the API connection.
	 *
	 * @since 1.0.0
	 *
	 * @return true|WP_Error True on success, WP_Error on failure.
	 */
	abstract public function test_connection();

	/**
	 * Check if this provider has a valid API key.
	 *
	 * @since 1.0.0
	 *
	 * @return bool True if API key is set.
	 */
	public function has_api_key() {
		return ! empty( $this->api_key );
	}
}
