<?php
/**
 * AI Client Interface
 *
 * Contract for AI text generation services. Enables swapping OpenAI
 * for another provider without changing consumer code.
 *
 * @package Niwa_AI
 * @since   0.10.36
 */

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

interface Niwa_AI_AI_Client_Interface {

	/**
	 * @return string Current profile name (e.g. 'frontend_fast', 'founder_deep').
	 */
	public function get_profile();

	/**
	 * Simple text generation.
	 *
	 * @param string $model        Model identifier.
	 * @param string|array $input  User prompt or role-ordered conversation messages.
	 * @param string $instructions System instructions.
	 * @param string $auth_mode    'api_key' or 'oauth'.
	 * @param array  $creds        Credentials array.
	 * @param int    $timeout      Request timeout in seconds.
	 * @return array { success: bool, answer: string, error: string }
	 */
	public function generate( $model, $input, $instructions, $auth_mode, $creds, $timeout = 30 );

	/**
	 * Text generation with tool/function calling.
	 *
	 * @param string $model        Model identifier.
	 * @param string $input        User prompt.
	 * @param string $instructions System instructions.
	 * @param array  $tools        Tool definitions.
	 * @param string $auth_mode    'api_key' or 'oauth'.
	 * @param array  $creds        Credentials array.
	 * @param int    $timeout      Request timeout in seconds.
	 * @return array { success: bool, answer: string, tool_calls: array, error: string }
	 */
	public function generate_with_tools( $model, $input, $instructions, $tools, $auth_mode, $creds, $timeout = 30 );

	/**
	 * Chat-style completions with optional tools.
	 *
	 * @param string     $model       Model identifier.
	 * @param array      $messages    Message array [{role, content}, ...].
	 * @param string     $auth_mode   'api_key' or 'oauth'.
	 * @param array      $creds       Credentials array.
	 * @param int        $timeout     Request timeout in seconds.
	 * @param array|null $tools       Tool definitions or null.
	 * @param mixed      $tool_choice Tool selection strategy or null.
	 * @return array { success: bool, answer: string, message: array, tool_calls: array, error: string }
	 */
	public function chat_complete( $model, $messages, $auth_mode, $creds, $timeout = 30, $tools = null, $tool_choice = null );

	/**
	 * Check if a model supports native web search.
	 *
	 * @param string $model     Model identifier.
	 * @param string $auth_mode 'api_key' or 'oauth'.
	 * @return bool
	 */
	public function supports_native_web_search( $model, $auth_mode = 'api_key' );

	/**
	 * Transcribe an audio file.
	 *
	 * @param string $file_path Local path to audio file.
	 * @param string $auth_mode 'api_key' or 'oauth'.
	 * @param array  $creds     Credentials array.
	 * @param string $language  ISO 639-1 language code (empty = auto-detect).
	 * @param int    $timeout   Request timeout in seconds.
	 * @return array { success: bool, text: string, error: string }
	 */
	public function transcribe_audio( $file_path, $auth_mode, $creds, $language = '', $timeout = 120 );
}
