<?php
/**
 * AI Provider Interface
 *
 * Interface that all AI providers must implement.
 * Provides a consistent API for different AI services (OpenAI, Claude, Gemini, etc).
 *
 * @package FleekDash\AI\Core
 * @since 2.3.0
 */

namespace FleekDash\AI\Core;

defined('ABSPATH') || exit;

/**
 * Interface AIProviderInterface
 *
 * Defines the contract for AI providers.
 */
interface AIProviderInterface
{
    /**
     * Get provider unique identifier
     *
     * @return string Provider ID (e.g., 'openai', 'claude', 'gemini')
     */
    public function getId(): string;

    /**
     * Get provider display name
     *
     * @return string Provider name (e.g., 'OpenAI', 'Claude', 'Gemini')
     */
    public function getName(): string;

    /**
     * Get provider icon name
     *
     * @return string Icon identifier (e.g., 'sparkles', 'brain', 'zap')
     */
    public function getIcon(): string;

    /**
     * Get provider description
     *
     * @return string Provider description
     */
    public function getDescription(): string;

    /**
     * Send chat completion request
     *
     * @param array $messages Array of message objects with 'role' and 'content'
     * @param array $options Additional options (model, temperature, max_tokens, etc)
     * @return array Response array with 'content', 'model', 'usage', etc
     * @throws \Exception If request fails
     */
    public function chat(array $messages, array $options = []): array;

    /**
     * Stream chat completion
     *
     * @param array $messages Array of message objects
     * @param callable $callback Callback function for each chunk: function(string $chunk, bool $done)
     * @param array $options Additional options
     * @return void
     * @throws \Exception If streaming fails
     */
    public function streamChat(array $messages, callable $callback, array $options = []): void;

    /**
     * Get available models for this provider
     *
     * @return array Associative array of model_id => model_name
     */
    public function getModels(): array;

    /**
     * Validate API key format
     *
     * @param string $key API key to validate
     * @return bool True if key format is valid
     */
    public function validateApiKey(string $key): bool;

    /**
     * Test API key by making a simple request
     *
     * @param string $key API key to test
     * @return array ['valid' => bool, 'error' => string|null]
     */
    public function testApiKey(string $key): array;

    /**
     * Get default settings schema for this provider
     *
     * @return array Settings schema with field definitions
     */
    public function getSettingsSchema(): array;

    /**
     * Get default settings values
     *
     * @return array Default settings
     */
    public function getDefaultSettings(): array;

    /**
     * Check if provider is configured and ready to use
     *
     * @return bool True if provider has valid API key
     */
    public function isConfigured(): bool;

    /**
     * Get provider settings
     *
     * @return array Current settings
     */
    public function getSettings(): array;

    /**
     * Update provider settings
     *
     * @param array $settings Settings to update
     * @return bool True on success
     */
    public function updateSettings(array $settings): bool;
}
