<?php
/**
 * Chat Model Base Class.
 *
 * Abstract base class for all chat-based language models. Defines common
 * methods for conversation handling and response generation.
 *
 * @package   Agenistrator
 * @since     1.0.0
 * @author    Alex Ruban <alex@maximum.guru>
 * @author    Maximum Software Inc <contact@maximum.software>
 * @license   GPL-3.0-only
 * @link      https://agenistrator.com/
 *
 * SPDX-FileCopyrightText: 2025-2026 Alex Ruban <alex@maximum.guru>
 * SPDX-FileCopyrightText: 2025-2026 Maximum Software Inc <contact@maximum.software>
 * SPDX-License-Identifier: GPL-3.0-only
 */

namespace Agenistrator;

// Direct access prevention
if ( ! defined( 'ABSPATH' ) ) {
	exit;
}

/**
 * LLM_Chat class.
 */
abstract class LLM_Chat extends LLM {
	/**
	 * Create a new context object specific to this model's provider
	 *
	 * @param      string $system_message Optional custom system message
	 * @return     Context A context object specific to this provider
	 * @since     1.0.0
	 */
	abstract public function create_context( $system_message = null );

	/**
	 * Generate a synchronous (non-streaming) chat completion
	 *
	 * @param      Context $context Context object containing all request information
	 * @return     array Response data
	 * @since     1.0.0
	 */
	abstract public function generate_sync_completion( $context );

	/**
	 * Generate a streaming chat completion
	 *
	 * @param      Context $context Context object containing all request information
	 * @param      callable $stream_callback Callback function for streaming. Should return bool: true to continue, false to stop.
	 * @return     bool Success flag (true if streaming completed successfully)
	 * @since     1.0.0
	 */
	abstract public function generate_streaming_completion( $context, $stream_callback = null );

	/**
	 * Convert a tool to a provider-specific tool definition format
	 *
	 * @param      Tool $tool The tool to convert
	 * @return     array Tool definition in provider-specific format
	 * @since     1.0.0
	 */
	abstract public function convert_tool_to_definition( $tool );

	/**
	 * Convert an array of tools to provider-specific tool definitions
	 *
	 * All tools are included regardless of enabled status.
	 * Disabled tools will throw an error when executed, allowing
	 * the LLM to inform the user that the tool needs to be enabled.
	 *
	 * @param      array $tools Array of Tool objects
	 * @return     array Array of tool definitions in provider-specific format
	 * @since     1.0.0
	 */
	public function convert_tools_to_definitions( $tools ) {
		$definitions = array();

		foreach ( $tools as $tool ) {
			if ( $tool instanceof Tool ) {
				$definitions[] = $this->convert_tool_to_definition( $tool );
			}
		}

		return $definitions;
	}
}