package me.neurodock.plugin.tool;

import me.neurodock.plugin.Plugin;
import me.neurodock.plugin.exceptions.ToolRuntimeException;
import org.jetbrains.annotations.NotNull;
import org.json.JSONObject;

public abstract class Tool {
    /**
     * Magic constant for RPCP sources.<br>
     * This is solely here to replace the case of a magic string being used in the code
     */
    public static final String RPCP_SOURCE = "RPCP";

    /**
     * The parent plugin of this tool, used by {@link Tool#getToolJSON()}.
     */
    protected final Plugin PLUGIN;

    /**
     * A base contructor, as the {@link Plugin} is used within this class
     * @param plugin The plugin that owns this tool
     */
    public Tool(Plugin plugin) {
        this.PLUGIN = plugin;
    }

    /**
     * The core uses this method when generating the list of available functions to the LLM
     * @return a string formated JSON containing the representation of the tool definitions
     */
    public final String getToolJSON() {
        JSONObject ret = new JSONObject();
        ret.put("type", "function");

        JSONObject function = new JSONObject();
        function.put("name", String.format("%s_%s_%s", name(), PLUGIN.getMetadata().getName(), RPCP_SOURCE).replaceAll(" ", "_"));
        if(description() != null) {
            function.put("description", description());
        }
        function.put("parameters", (parameters() == null? new JSONObject() : new JSONObject(parameters().toString())));

        ret.put("function", function);

        return ret.toString();
    }

    /**
     * <p>Name of the tool.</p>
     * @apiNote This is a lower snake_case formated string.
     * <p>Example: {@code "get_clock"}</p>
     * @return returns the name of this tool
     */
    @NotNull
    abstract public String name();

    /**
     * Description for the LLM on what this tool does
     * @return Short description defining the scope of this tool
     */
    public String description() {
        return null;
    }

    /**
     * The parameters this tool allows
     * @apiNote Can return {@link ToolParameters#empty()} if no arguments are needed
     * @return A {@link ToolParameters} object defining what this tool expects when being called
     */
    @NotNull
    abstract public ToolParameters parameters();

    /**
     * This is the main course of the tool. The LLM will call this on request of using your tool
     * @param arguments A collective of your {@link ToolParameters} from {@link Tool#parameters()}
     * @return The expected results, or {@link ToolResponse#empty(Tool)} if this is a "void" function
     * @throws ToolRuntimeException This indicates that an {@link Exception} is not fatal, any other exceptions thrown from this tool will be treated as fatal, and will result in this tool, or it's plugin being disabled
     */
    abstract public ToolResponse callTool(ToolArguments arguments) throws ToolRuntimeException;
}