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

// If this file is called directly, abort.
if (!defined('WPINC')) {
    die;
}

/**
 * AI Provider interface.
 */
interface Inqyra_AI_Provider_Interface {

    /**
     * Send a chat completion request.
     *
     * @param array $messages Array of messages with 'role' and 'content'.
     * @param array $options  Additional options (model, max_tokens, etc.).
     * @return array Response with 'content', 'tokens', and 'model'.
     * @throws Exception On API error.
     */
    public function chat(array $messages, array $options = []): array;

    /**
     * Get the provider identifier.
     *
     * @return string Provider ID (e.g. 'claude', 'openai').
     */
    public function get_id(): string;

    /**
     * Get the provider name.
     *
     * @return string Provider name for display.
     */
    public function get_name(): string;

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

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

    /**
     * Check if the provider is configured (has API key).
     *
     * @return bool Whether the provider is ready to use.
     */
    public function is_configured(): bool;

    /**
     * Fetch available models from the provider's API.
     *
     * @return array Array of model info with id, name, and capabilities.
     */
    public function fetch_available_models(): array;

    /**
     * Get models with pricing information.
     *
     * @return array Array of models with pricing per 1M tokens.
     */
    public function get_models_with_pricing(): array;
}
