feat: add advanced usage documentation and getting started guide; refactor tool argument handling for improved type safety

Author: brunoborges

src/main/java/com/github/copilot/sdk/json/ToolDefinition.java

@@ -20,13 +20,22 @@
  * <h2>Example Usage</h2>
  *
  * <pre>{@code
+ * // Define a record for your tool's arguments
+ * record WeatherArgs(String location) {
+ * }
+ *
  * var tool = ToolDefinition.create("get_weather", "Get the current weather for a location",
  * 		Map.of("type", "object", "properties",
  * 				Map.of("location", Map.of("type", "string", "description", "City name")), "required",
  * 				List.of("location")),
  * 		invocation -> {
- * 			String location = ((Map<String, Object>) invocation.getArguments()).get("location").toString();
- * 			return CompletableFuture.completedFuture(getWeatherData(location));
+ * 			// Type-safe access with records (recommended)
+ * 			WeatherArgs args = invocation.getArgumentsAs(WeatherArgs.class);
+ * 			return CompletableFuture.completedFuture(getWeatherData(args.location()));
+ *
+ * 			// Or use Map-based access
+ * 			// Map<String, Object> args = invocation.getArguments();
+ * 			// String location = (String) args.get("location");
  * 		});
  * }</pre>
  *

src/main/java/com/github/copilot/sdk/json/ToolHandler.java

@@ -16,13 +16,21 @@
  * <h2>Example Implementation</h2>
  *
  * <pre>{@code
+ * // Option 1: Type-safe access with records (recommended)
+ * record SearchArgs(String query) {
+ * }
+ *
  * ToolHandler handler = invocation -> {
- * 	Map<String, Object> args = (Map<String, Object>) invocation.getArguments();
- * 	String query = args.get("query").toString();
+ * 	SearchArgs args = invocation.getArgumentsAs(SearchArgs.class);
+ * 	String result = performSearch(args.query());
+ * 	return CompletableFuture.completedFuture(result);
+ * };
  *
- * 	// Perform the tool's action
+ * // Option 2: Map-based access
+ * ToolHandler handler = invocation -> {
+ * 	Map<String, Object> args = invocation.getArguments();
+ * 	String query = (String) args.get("query");
  * 	String result = performSearch(query);
- *
  * 	return CompletableFuture.completedFuture(result);
  * };
  * }</pre>

src/main/java/com/github/copilot/sdk/json/ToolInvocation.java

@@ -4,7 +4,13 @@
 
 package com.github.copilot.sdk.json;
 
+import java.util.Map;
+
 import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonSetter;
+import com.fasterxml.jackson.core.type.TypeReference;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
 
 /**
  * Represents a tool invocation request from the AI assistant.
@@ -20,10 +26,14 @@
 @JsonInclude(JsonInclude.Include.NON_NULL)
 public final class ToolInvocation {
 
+    private static final ObjectMapper MAPPER = new ObjectMapper();
+    private static final TypeReference<Map<String, Object>> MAP_TYPE = new TypeReference<>() {
+    };
+
     private String sessionId;
     private String toolCallId;
     private String toolName;
-    private Object arguments;
+    private JsonNode argumentsNode;
 
     /**
      * Gets the session ID where the tool was invoked.
@@ -91,26 +101,71 @@ public ToolInvocation setToolName(String toolName) {
     }
 
     /**
-     * Gets the arguments passed to the tool.
+     * Gets the arguments passed to the tool as a Map.
+     * <p>
+     * The arguments are provided as a {@code Map<String, Object>} matching the
+     * parameter schema defined in the tool's {@link ToolDefinition}. Values can be
+     * accessed using standard Map operations.
+     * <p>
+     * For type-safe access, use {@link #getArgumentsAs(Class)} to deserialize
+     * arguments into a record or POJO.
+     *
+     * @return the arguments as a Map, or null if no arguments
+     * @see #getArgumentsAs(Class)
+     */
+    public Map<String, Object> getArguments() {
+        if (argumentsNode == null) {
+            return null;
+        }
+        return MAPPER.convertValue(argumentsNode, MAP_TYPE);
+    }
+
+    /**
+     * Deserializes the tool arguments into the specified type.
      * <p>
-     * This is typically a {@code Map<String, Object>} matching the parameter schema
-     * defined in the tool's {@link ToolDefinition}.
+     * This method provides type-safe access to tool arguments by converting the
+     * JSON arguments into a record, POJO, or other compatible type.
      *
-     * @return the arguments object
+     * <pre>{@code
+     * // Define a record for your tool's arguments
+     * record WeatherArgs(String city) {
+     * }
+     *
+     * // In your tool handler
+     * WeatherArgs args = invocation.getArgumentsAs(WeatherArgs.class);
+     * String city = args.city();
+     * }</pre>
+     *
+     * @param <T>
+     *            the type to deserialize to
+     * @param type
+     *            the class of the target type
+     * @return the arguments deserialized as the specified type
+     * @throws IllegalArgumentException
+     *             if deserialization fails
+     * @since 1.0.0
      */
-    public Object getArguments() {
-        return arguments;
+    public <T> T getArgumentsAs(Class<T> type) {
+        try {
+            return MAPPER.treeToValue(argumentsNode, type);
+        } catch (Exception e) {
+            throw new IllegalArgumentException("Failed to deserialize arguments to " + type.getName(), e);
+        }
     }
 
     /**
      * Sets the tool arguments.
+     * <p>
+     * <strong>Note:</strong> This method is intended for internal SDK use and JSON
+     * deserialization. Users typically do not need to call this method directly.
      *
      * @param arguments
-     *            the arguments object
+     *            the arguments as a JsonNode
      * @return this invocation for method chaining
      */
-    public ToolInvocation setArguments(Object arguments) {
-        this.arguments = arguments;
+    @JsonSetter("arguments")
+    public ToolInvocation setArguments(JsonNode arguments) {
+        this.argumentsNode = arguments;
         return this;
     }
 }