<?php

namespace Limb_Chatbot\Includes\Agent_Operations;

use Limb_Chatbot\Includes\Data_Objects\Agent_Operation_Results_Message;
use Limb_Chatbot\Includes\Utilities\Chatbot_Utility;

/**
 * Base class for agent operations.
 *
 * Provides common structure for agent-specific function-calling operations.
 *
 * @package Limb_Chatbot\Includes\Agent_Operations
 * @since 1.0.0
 */
abstract class Agent_Operation {

	/**
	 * Execute the operation.
	 *
	 * @param array           $params  Parsed function-calling parameters.
	 * @param Chatbot_Utility $utility Chatbot utility instance.
	 *
	 * @return array|Agent_Operation_Results_Message Response payload returned to the model.
	 */
	abstract public function execute( array $params, Chatbot_Utility $utility );

	/**
	 * Machine-readable operation name.
	 *
	 * @return string
	 */
	abstract public function get_name(): string;

	/**
	 * Human-readable description of what the operation does.
	 *
	 * @return string
	 */
	abstract public function get_description(): string;

	/**
	 * JSON schema-like parameters definition.
	 *
	 * @return array
	 */
	abstract public function get_parameters_schema(): array;
}