<?php
/**
 * Costudio_AI_Client — interface for all AI provider adapters.
 *
 * @package Contentosapp_Studio
 * @since   3.0.0
 */

defined( 'ABSPATH' ) || exit;

interface Costudio_AI_Client {

    /**
     * Generate a text response for the given prompt.
     *
     * @param  string  $prompt   Instruction / task.
     * @param  array   $context  Previous turns: [ ['role'=>'user'|'model', 'content'=>...], ... ]
     * @return string            Generated text.
     * @throws Exception         On API errors or blocked content.
     */
    public function generate( string $prompt, array $context = [] ): string;

    /**
     * Generate a response with web search access.
     *
     * Adapters that support native grounding (Gemini) use it directly.
     * Others delegate to Costudio_Search_Engine and prepend results.
     *
     * @param  string  $prompt
     * @param  array   $context
     * @return string
     * @throws Exception
     */
    public function generateWithSearch( string $prompt, array $context = [] ): string;

    /**
     * Executes a specific agent by ID. 
     * 
     * Adapters supporting secure remote execution (ContentOS) will send inputs 
     * to the server, where the strategic prompt is added. Others may 
     * throw a logic exception if they are not intended to be called this way.
     *
     * @param  int    $agent_id  ID (1-7).
     * @param  array  $inputs    Key-value pairs for interpolation.
     * @param  array  $context   Previous turns.
     * @return string            Generated text.
     */
    public function generate_via_agent( int $agent_id, array $inputs, array $context = [] ): string;
}
