<?php

namespace Limb_Chatbot\Includes\Chatbot_Tools\Tools;

use Limb_Chatbot\Includes\Agent_Operations\Agent_Operation;
use Limb_Chatbot\Includes\Chatbot_Tools\Chatbot_Tool;
use Limb_Chatbot\Includes\Data_Objects\Agent_Operation_Results_Message;
use Limb_Chatbot\Includes\Data_Objects\Tool_Calls_Message;
use Limb_Chatbot\Includes\Utilities\Chatbot_Utility;

/**
 * Agent Operation Tool
 *
 * Wrapper class that converts Agent_Operation instances into Chatbot_Tool instances
 * for function calling support.
 *
 * @package Limb_Chatbot\Includes\Chatbot_Tools\Tools
 * @since 1.0.0
 */
class Agent_Operation_Tool extends Chatbot_Tool {

	/**
	 * The agent operation instance.
	 *
	 * @var Agent_Operation
	 * @since 1.0.0
	 */
	private Agent_Operation $operation;

	/**
	 * Constructor.
	 *
	 * @param Agent_Operation $operation The agent operation to wrap.
	 * @since 1.0.0
	 */
	public function __construct( Agent_Operation $operation ) {
		$this->operation = $operation;
		parent::__construct();
	}

	/**
	 * Define the tool's internal name.
	 *
	 * @return string Tool name.
	 * @since 1.0.0
	 */
	protected function define_name(): string {
		return $this->operation->get_name();
	}

	/**
	 * Define the tool's description for the AI.
	 *
	 * @return string Tool description.
	 * @since 1.0.0
	 */
	protected function define_description(): string {
		return $this->operation->get_description();
	}

	/**
	 * Define the parameters schema for the tool.
	 *
	 * @return array Parameters schema.
	 * @since 1.0.0
	 */
	protected function define_parameters_schema(): array {
		return $this->operation->get_parameters_schema();
	}

	/**
	 * Execute the agent operation.
	 *
	 * @param array              $params  Tool parameters.
	 * @param Tool_Calls_Message $message Original message that triggered the tool.
	 * @param Chatbot_Utility    $utility Chatbot utility instance.
	 *
	 * @return array|Agent_Operation_Results_Message Result from the agent operation.
	 * @since 1.0.0
	 */
	public function execute( array $params, Tool_Calls_Message $message, Chatbot_Utility $utility ) {
		return $this->operation->execute( $params, $utility );
	}

	/**
	 * Get the underlying agent operation.
	 *
	 * @return Agent_Operation The agent operation instance.
	 * @since 1.0.0
	 */
	public function get_operation(): Agent_Operation {
		return $this->operation;
	}
}
