<?php

namespace AIBP\AI;

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

interface Provider {

    /**
     * Get the provider identifier.
     */
    public static function id(): string;

    /**
     * Get the provider display name.
     */
    public static function name(): string;

    /**
     * Get available models for this provider.
     *
     * @return array<string, array{id: string, name: string, context: int, input_price: float, output_price: float}>
     */
    public static function models(): array;

    /**
     * Generate text using the provider's API.
     *
     * @param string $prompt The prompt to send.
     * @param array  $args   Optional arguments (model, temperature, max_tokens, etc.).
     * @return string The generated text.
     * @throws \Exception If the API call fails.
     */
    public function generate( string $prompt, array $args = [] ): string;

    /**
     * Validate that an API key works.
     *
     * @param string $api_key The API key to validate.
     * @return bool True if the key is valid.
     */
    public function validate_key( string $api_key ): bool;

    /**
     * Get the API key from plugin settings.
     */
    public function get_api_key(): string;

    /**
     * Get the base URL for the provider's API.
     */
    public static function api_base_url(): string;
}