Class ToolDefinition.Builder

java.lang.Object
group.worldstandard.pudel.api.agent.ToolDefinition.Builder
Enclosing class:
ToolDefinition
public static class ToolDefinition.Builder extends Object
Builder class for constructing ToolDefinition instances. Provides a fluent API for configuring tool properties including name, description, plugin identification, parameters, keywords, context restrictions, permissions, priority level, and execution logic.

The builder validates that required fields are present when building the final ToolDefinition instance. Required fields include name, description, and executor.

Collection properties such as parameters and keywords are accumulated through multiple method calls, allowing flexible configuration of the tool definition.

Context restriction methods guildOnly and dmOnly allow specifying where the tool can be executed. Permission settings control who can use the tool, while priority affects tool selection order when multiple tools are applicable.

  • Constructor Details

    • Builder

      public Builder()

  • Method Details

    • name

      public ToolDefinition.Builder name(String name)
      Sets the name for the builder instance.
      Parameters:
      name - the name to be set
      Returns:
      the current builder instance

    • description

      public ToolDefinition.Builder description(String description)
      Sets the description of the tool.

      The description should clearly explain what the tool does and is used by the AI agent to determine when to invoke the tool. It should be concise and informative.

      Parameters:
      description - the description of the tool
      Returns:
      this builder instance

    • pluginId

      public ToolDefinition.Builder pluginId(String pluginId)
      Sets the plugin identifier for the tool being built.

      The plugin ID is used to associate the tool with a specific plugin, allowing the system to organize and manage tools by their originating plugin.

      Parameters:
      pluginId - the unique identifier of the plugin that provides this tool
      Returns:
      this builder instance for method chaining

    • parameter

      public ToolDefinition.Builder parameter(String name, Class<?> type, String description, boolean required)
      Adds a parameter to the tool being built.
      Parameters:
      name - the name of the parameter
      type - the data type of the parameter
      description - a textual description of the parameter's purpose
      required - whether the parameter is mandatory
      Returns:
      the current builder instance

    • parameter

      public ToolDefinition.Builder parameter(String name, Class<?> type, String description, boolean required, Object defaultValue)
      Adds a parameter to the tool being built with a default value.
      Parameters:
      name - the name of the parameter
      type - the data type of the parameter
      description - a textual description of the parameter's purpose
      required - whether the parameter is mandatory
      defaultValue - the default value of the parameter if not provided
      Returns:
      the current builder instance

    • parameter

      public ToolDefinition.Builder parameter(ToolDefinition.ToolParameter parameter)
      Adds a parameter to the tool being built.
      Parameters:
      parameter - the ToolParameter object containing the parameter details
      Returns:
      the current builder instance

    • keyword

      public ToolDefinition.Builder keyword(String keyword)
      Adds a keyword to the tool being built.

      Keywords are used to help identify and categorize the tool, and may be used by the system to match user queries with appropriate tools. Keywords are case-insensitive and will be stored in lowercase.

      Parameters:
      keyword - the keyword to add
      Returns:
      the current builder instance for method chaining

    • keywords

      public ToolDefinition.Builder keywords(String... keywords)
      Adds multiple keywords to the tool being built.

      Keywords are used to help identify and categorize the tool. They are typically used for searching or filtering tools based on their functionality or purpose. All keywords are converted to lowercase to ensure consistent casing.

      Parameters:
      keywords - the keywords to be added
      Returns:
      this builder instance for method chaining

    • keywords

      public ToolDefinition.Builder keywords(Collection<String> keywords)
      Sets the keywords associated with the tool being built.

      This method accepts a collection of strings representing keywords, which are used to identify and categorize the tool. Each keyword is converted to lowercase before being added to ensure consistency.

      Parameters:
      keywords - a collection of keywords to associate with the tool
      Returns:
      this builder instance for method chaining

    • guildOnly

      public ToolDefinition.Builder guildOnly(boolean guildOnly)
      Sets whether the tool can only be used within a guild context.

      When set to true, the tool will only be available when invoked within a guild. If set to false, the tool may also be used in other contexts such as direct messages, depending on other restrictions like dmOnly(boolean).

      Parameters:
      guildOnly - true to restrict usage to guilds only, false otherwise
      Returns:
      this builder instance for method chaining

    • dmOnly

      public ToolDefinition.Builder dmOnly(boolean dmOnly)
      Sets whether the tool can only be used in direct messages.
      Parameters:
      dmOnly - true if the tool is restricted to direct messages, false otherwise
      Returns:
      this builder instance for method chaining

    • permission

      public ToolDefinition.Builder permission(AgentTool.ToolPermission permission)
      Sets the permission level required to use the tool.
      Parameters:
      permission - the required permission level for the tool
      Returns:
      this builder instance for method chaining

    • priority

      public ToolDefinition.Builder priority(int priority)
      Sets the priority level for the tool being built.

      The priority determines the order in which tools are considered when multiple tools match a given query. Tools with higher priority values are evaluated before those with lower values.

      Parameters:
      priority - the priority level to assign to the tool
      Returns:
      this builder instance for method chaining

    • executor

      public ToolDefinition.Builder executor(BiFunction<AgentToolContext, Map<String,Object>, String> executor)
      Sets the executor function for this tool. The executor is responsible for performing the actual work when the tool is invoked, using the provided context and parameters.
      Parameters:
      executor - a BiFunction that takes an AgentToolContext and a Map of parameters and returns a String result
      Returns:
      this Builder instance for chaining

    • build

      public ToolDefinition build()
      Builds and returns a new ToolDefinition instance using the current configuration. Validates that all required fields (name, description, and executor) are present before creating the tool definition.
      Returns:
      a new ToolDefinition instance configured with the current builder settings
      Throws:
      NullPointerException - if any of the required fields (name, description, executor) are null