<?php

/**
 * Interface for AI Magic Providers
 *
 * @since      1.0.8
 * @package    Ai_Magic
 * @subpackage Ai_Magic/includes
 */
interface AI_Magic_Provider_Interface
{
    /**
     * Generate text based on a prompt
     *
     * @param string $prompt The prompt to send to the AI
     * @return array Response with 'type' (success/error) and 'data' or 'message'
     */
    public function generateText($prompt);

    /**
     * Get available models from the provider
     *
     * @return array List of models with 'id' and 'name'
     */
    public function getModels();

    /**
     * Validate the API key
     *
     * @return bool|WP_Error True if valid, WP_Error if invalid
     */
    public function validateApiKey();

    /**
     * Build the prompt string based on settings and input
     * 
     * @param string $title_text The user input/title
     * @param array $overrides Optional overrides for settings
     * @return string The constructed prompt
     */
    public function buildPrompt($title_text, $overrides = array());

    /**
     * Generate SEO meta description
     *
     * @param string $title Post title
     * @param string $content Post content
     * @param array $keywords Focus keywords
     * @return array Response
     */
    public function generateMetaDescription($title, $content = '', $keywords = array());

    /**
     * Generate focus keywords from content
     *
     * @param string $content Post content
     * @param int $count Number of keywords to generate
     * @return array Response
     */
    public function generateFocusKeywords($content, $count = 5);
}
