feat: add Java-friendly convenience methods for JsonValue and tool response output (#9)

Author: bdemers

arcade-java-core/src/main/kotlin/dev/arcade/core/Values.kt

@@ -274,6 +274,42 @@ sealed class JsonValue : JsonField<Nothing>() {
 
     fun <R : Any> convert(type: Class<R>): R? = JSON_MAPPER.convertValue(this, type)
 
+    // -------------------------------------------------------------------------
+    // Start of manually added code
+    // -------------------------------------------------------------------------
+
+    /**
+     * Returns this value's map representation, or an empty map if this value is not a JSON object.
+     *
+     * Example usage:
+     * ```java
+     * Map<String, JsonValue> map = jsonValue.toMapOrEmpty();
+     * ```
+     */
+    fun toMapOrEmpty(): Map<String, JsonValue> =
+        when (this) {
+            is JsonObject -> values
+            else -> emptyMap()
+        }
+
+    /**
+     * Returns this value's list representation, or an empty list if this value is not a JSON array.
+     *
+     * Example usage:
+     * ```java
+     * List<JsonValue> items = jsonValue.toListOrEmpty();
+     * ```
+     */
+    fun toListOrEmpty(): List<JsonValue> =
+        when (this) {
+            is JsonArray -> values
+            else -> emptyList()
+        }
+
+    // -------------------------------------------------------------------------
+    // End of manually added code
+    // -------------------------------------------------------------------------
+
     /** Returns the result of calling the [visitor] method corresponding to this value's variant. */
     fun <R> accept(visitor: Visitor<R>): R =
         when (this) {

arcade-java-core/src/main/kotlin/dev/arcade/models/tools/ExecuteToolRequest.kt

@@ -216,6 +216,9 @@ private constructor(
         /** JSON input to the tool, if any */
         fun input(input: Input) = input(JsonField.of(input))
 
+        /** JSON input to the tool, if any */
+        fun input(input: Map<String, Any?>) = input(Input.from(input))
+
         /**
          * Sets [Builder.input] to an arbitrary JSON value.
          *
@@ -359,6 +362,11 @@ private constructor(
 
             /** Returns a mutable builder for constructing an instance of [Input]. */
             @JvmStatic fun builder() = Builder()
+
+            /** Converts a Map of input objects to an [Input] Map<String, JsonValue>. */
+            @JvmStatic
+            fun from(input: Map<String, Any?>) =
+                Input(input.mapValues { (_, value) -> JsonValue.from(value) })
         }
 
         /** A builder for [Input]. */

arcade-java-core/src/main/kotlin/dev/arcade/models/tools/ExecuteToolResponse.kt

@@ -8,8 +8,10 @@ import com.fasterxml.jackson.annotation.JsonCreator
 import com.fasterxml.jackson.annotation.JsonProperty
 import dev.arcade.core.Enum
 import dev.arcade.core.ExcludeMissing
+import dev.arcade.core.JsonArray
 import dev.arcade.core.JsonField
 import dev.arcade.core.JsonMissing
+import dev.arcade.core.JsonObject
 import dev.arcade.core.JsonValue
 import dev.arcade.core.checkKnown
 import dev.arcade.core.checkRequired
@@ -467,6 +469,78 @@ private constructor(
          */
         @JsonProperty("value") @ExcludeMissing fun _value(): JsonValue = value
 
+        // -------------------------------------------------------------------------
+        // Start of manually added code
+        // -------------------------------------------------------------------------
+
+        /**
+         * Returns an [Optional] containing the output value as a `Map<String, JsonValue>`, or an
+         * empty [Optional] if the value is not a JSON object.
+         *
+         * Example usage:
+         * ```java
+         * Map<String, JsonValue> result = response.output()
+         *     .flatMap(Output::valueAsObject)
+         *     .orElse(Map.of());
+         * ```
+         */
+        fun valueAsObject(): Optional<Map<String, JsonValue>> =
+            when (value) {
+                is JsonObject -> Optional.of(value.values)
+                else -> Optional.empty()
+            }
+
+        /**
+         * Returns the output value as a `Map<String, JsonValue>`, or an empty map if the value is
+         * not a JSON object.
+         *
+         * Example usage:
+         * ```java
+         * Map<String, JsonValue> result = output.valueAsObjectOrEmpty();
+         * ```
+         */
+        fun valueAsObjectOrEmpty(): Map<String, JsonValue> =
+            when (value) {
+                is JsonObject -> value.values
+                else -> emptyMap()
+            }
+
+        /**
+         * Returns an [Optional] containing the output value as a `List<JsonValue>`, or an empty
+         * [Optional] if the value is not a JSON array.
+         *
+         * Example usage:
+         * ```java
+         * List<JsonValue> items = response.output()
+         *     .flatMap(Output::valueAsArray)
+         *     .orElse(List.of());
+         * ```
+         */
+        fun valueAsArray(): Optional<List<JsonValue>> =
+            when (value) {
+                is JsonArray -> Optional.of(value.values)
+                else -> Optional.empty()
+            }
+
+        /**
+         * Returns the output value as a `List<JsonValue>`, or an empty list if the value is not a
+         * JSON array.
+         *
+         * Example usage:
+         * ```java
+         * List<JsonValue> items = output.valueAsArrayOrEmpty();
+         * ```
+         */
+        fun valueAsArrayOrEmpty(): List<JsonValue> =
+            when (value) {
+                is JsonArray -> value.values
+                else -> emptyList()
+            }
+
+        // -------------------------------------------------------------------------
+        // End of manually added code
+        // -------------------------------------------------------------------------
+
         /**
          * Returns the raw JSON value of [authorization].
          *