<?php
/**
 * AI Provider Interface
 *
 * Defines the contract that all AI providers must implement.
 *
 * @package Askany
 * @since 1.0.0
 */

namespace Askany\Providers;

/**
 * Interface for AI providers.
 */
interface AIProviderInterface {
	/**
	 * Get the provider name (internal identifier).
	 *
	 * @return string Provider name (e.g., 'openai', 'deepseek', 'gemini').
	 */
	public function get_provider_name(): string;

	/**
	 * Get the provider display name.
	 *
	 * @return string Display name (e.g., 'OpenAI', 'DeepSeek', 'Google Gemini').
	 */
	public function get_provider_display_name(): string;

	/**
	 * Get available models for this provider.
	 *
	 * @return array Array of models with their configurations.
	 */
	public function get_available_models(): array;

	/**
	 * Get the default model for this provider.
	 *
	 * @return string Default model identifier.
	 */
	public function get_default_model(): string;

	/**
	 * Get the default API endpoint.
	 *
	 * @return string Default API endpoint URL.
	 */
	public function get_default_endpoint(): string;

	/**
	 * Send a chat completion request to the provider.
	 *
	 * @param array $messages Array of messages in the conversation.
	 * @param array $options Optional parameters (model, temperature, max_tokens, etc.).
	 * @return array|false Response data or false on failure.
	 */
	public function send_chat_request( array $messages, array $options = array() );

	/**
	 * Test the connection to the provider.
	 *
	 * @param array $options Optional parameters like model selection.
	 * @return array Connection test results with status, message, and details.
	 */
	public function test_connection( array $options = array() ): array;
}
