Constructor Detail

Method Detail

• of

  @JvmOverloads() final static MatryoshkaTool of(String name, String description, List<Tool> innerTools, Boolean removeOnInvoke)

  Create a MatryoshkaTool that exposes all inner tools when invoked.

  Parameters:

  name - Unique name for the tool

  description - Description explaining when to use this tool category

  innerTools - The tools to expose when invoked

  removeOnInvoke - Whether to remove this tool after invocation (default true)

• of

  @JvmOverloads() final static MatryoshkaTool of(String name, String description, List<Tool> innerTools)

  Create a MatryoshkaTool that exposes all inner tools when invoked.

  Parameters:

  name - Unique name for the tool

  description - Description explaining when to use this tool category

  innerTools - The tools to expose when invoked

• selectable

  @JvmOverloads() final static MatryoshkaTool selectable(String name, String description, List<Tool> innerTools, Tool.InputSchema inputSchema, Boolean removeOnInvoke, Function1<String, List<Tool>> selector)

  Create a MatryoshkaTool with a custom tool selector.

  The selector receives the JSON input string and returns the tools to expose. This enables category-based tool disclosure.

  Example:

  val fileTool = MatryoshkaTool.selectable(
      name = "file_operations",
      description = "File operations. Pass 'category': 'read' or 'write'.",
      innerTools = allFileTools,
      inputSchema = Tool.InputSchema.of(
          Tool.Parameter.string("category", "The category of file operations", required = true)
      ),
  ) { input ->
      val json = ObjectMapper().readValue(input, Map::class.java)
      val category = json["category"] as? String
      when (category) {
          "read" -> listOf(readFileTool, listDirTool)
          "write" -> listOf(writeFileTool, deleteTool)
          else -> allFileTools
      }
  }

  Parameters:

  name - Unique name for the tool

  description - Description explaining when to use this tool category

  innerTools - All possible inner tools

  inputSchema - Schema describing the selection parameters

  removeOnInvoke - Whether to remove this tool after invocation

  selector - Function to select tools based on input

• selectable

  @JvmOverloads() final static MatryoshkaTool selectable(String name, String description, List<Tool> innerTools, Tool.InputSchema inputSchema, Function1<String, List<Tool>> selector)

  Create a MatryoshkaTool with a custom tool selector.

  The selector receives the JSON input string and returns the tools to expose. This enables category-based tool disclosure.

  Example:

  val fileTool = MatryoshkaTool.selectable(
      name = "file_operations",
      description = "File operations. Pass 'category': 'read' or 'write'.",
      innerTools = allFileTools,
      inputSchema = Tool.InputSchema.of(
          Tool.Parameter.string("category", "The category of file operations", required = true)
      ),
  ) { input ->
      val json = ObjectMapper().readValue(input, Map::class.java)
      val category = json["category"] as? String
      when (category) {
          "read" -> listOf(readFileTool, listDirTool)
          "write" -> listOf(writeFileTool, deleteTool)
          else -> allFileTools
      }
  }

  Parameters:

  name - Unique name for the tool

  description - Description explaining when to use this tool category

  innerTools - All possible inner tools

  inputSchema - Schema describing the selection parameters

  selector - Function to select tools based on input

• byCategory

  @JvmOverloads() final static MatryoshkaTool byCategory(String name, String description, Map<String, List<Tool>> toolsByCategory, String categoryParameter, Boolean removeOnInvoke)

  Create a MatryoshkaTool with category-based selection.

  Parameters:

  name - Unique name for the tool

  description - Description explaining when to use this tool category

  toolsByCategory - Map of category names to their tools

  categoryParameter - Name of the category parameter (default "category")

  removeOnInvoke - Whether to remove this tool after invocation

• byCategory

  @JvmOverloads() final static MatryoshkaTool byCategory(String name, String description, Map<String, List<Tool>> toolsByCategory, String categoryParameter)

  Create a MatryoshkaTool with category-based selection.

  Parameters:

  name - Unique name for the tool

  description - Description explaining when to use this tool category

  toolsByCategory - Map of category names to their tools

  categoryParameter - Name of the category parameter (default "category")

• byCategory

  @JvmOverloads() final static MatryoshkaTool byCategory(String name, String description, Map<String, List<Tool>> toolsByCategory)

  Create a MatryoshkaTool with category-based selection.

  Parameters:

  name - Unique name for the tool

  description - Description explaining when to use this tool category

  toolsByCategory - Map of category names to their tools

• fromInstance

  @JvmOverloads() final static MatryoshkaTool fromInstance(Object instance, ObjectMapper objectMapper)

  Create a MatryoshkaTool from an instance annotated with @MatryoshkaTools.

  The instance's class must be annotated with @MatryoshkaTools and contain methods annotated with @LlmTool. If any @LlmTool methods have a category specified, a category-based MatryoshkaTool is created; otherwise, all tools are exposed when the facade is invoked.

  Example - Simple facade:

  @MatryoshkaTools(
      name = "database_operations",
      description = "Database operations. Invoke to see specific tools."
  )
  public class DatabaseTools {
      @LlmTool(description = "Execute a SQL query")
      public QueryResult query(String sql) { ... }
  
      @LlmTool(description = "Insert a record")
      public InsertResult insert(String table, String data) { ... }
  }
  
  MatryoshkaTool tool = MatryoshkaTool.fromInstance(new DatabaseTools());

  Example - Category-based:

  @MatryoshkaTools(
      name = "file_operations",
      description = "File operations. Pass category to select tools."
  )
  public class FileTools {
      @LlmTool(description = "Read file", category = "read")
      public String readFile(String path) { ... }
  
      @LlmTool(description = "Write file", category = "write")
      public void writeFile(String path, String content) { ... }
  }
  
  MatryoshkaTool tool = MatryoshkaTool.fromInstance(new FileTools());
  // Automatically creates category-based selection with "read" and "write" categories

  Parameters:

  instance - The object instance annotated with @MatryoshkaTools

  objectMapper - ObjectMapper for JSON parsing (optional)

  Returns:

  A MatryoshkaTool wrapping the annotated methods

• fromInstance

  @JvmOverloads() final static MatryoshkaTool fromInstance(Object instance)

  Create a MatryoshkaTool from an instance annotated with @MatryoshkaTools.

  The instance's class must be annotated with @MatryoshkaTools and contain methods annotated with @LlmTool. If any @LlmTool methods have a category specified, a category-based MatryoshkaTool is created; otherwise, all tools are exposed when the facade is invoked.

  Example - Simple facade:

  @MatryoshkaTools(
      name = "database_operations",
      description = "Database operations. Invoke to see specific tools."
  )
  public class DatabaseTools {
      @LlmTool(description = "Execute a SQL query")
      public QueryResult query(String sql) { ... }
  
      @LlmTool(description = "Insert a record")
      public InsertResult insert(String table, String data) { ... }
  }
  
  MatryoshkaTool tool = MatryoshkaTool.fromInstance(new DatabaseTools());

  Example - Category-based:

  @MatryoshkaTools(
      name = "file_operations",
      description = "File operations. Pass category to select tools."
  )
  public class FileTools {
      @LlmTool(description = "Read file", category = "read")
      public String readFile(String path) { ... }
  
      @LlmTool(description = "Write file", category = "write")
      public void writeFile(String path, String content) { ... }
  }
  
  MatryoshkaTool tool = MatryoshkaTool.fromInstance(new FileTools());
  // Automatically creates category-based selection with "read" and "write" categories

  Parameters:

  instance - The object instance annotated with @MatryoshkaTools

  Returns:

  A MatryoshkaTool wrapping the annotated methods

• safelyFromInstance

  @JvmOverloads() final static MatryoshkaTool safelyFromInstance(Object instance, ObjectMapper objectMapper)

  Safely create a MatryoshkaTool from an instance. Returns null if the class is not annotated with @MatryoshkaTools or has no @LlmTool methods.

  Parameters:

  instance - The object instance to check

  objectMapper - ObjectMapper for JSON parsing (optional)

  Returns:

  A MatryoshkaTool if the instance is properly annotated, null otherwise

• safelyFromInstance

  @JvmOverloads() final static MatryoshkaTool safelyFromInstance(Object instance)

  Safely create a MatryoshkaTool from an instance. Returns null if the class is not annotated with @MatryoshkaTools or has no @LlmTool methods.

  Parameters:

  instance - The object instance to check

  Returns:

  A MatryoshkaTool if the instance is properly annotated, null otherwise