Enum description in tools (#732)

* support enum descriptions

* added example

---------

Co-authored-by: José Carlos Montañez <jc@MacBook-Pro.local>
Co-authored-by: Raúl Raja Martínez <raulraja@gmail.com>

core/src/commonMain/kotlin/com/xebia/functional/xef/llm/models/functions/JsonSchema.kt

@@ -307,6 +307,7 @@ private fun SerialDescriptor.createJsonSchema(
   }
 }
 
+@OptIn(ExperimentalSerializationApi::class)
 private fun JsonObjectBuilder.applyJsonSchemaDefaults(
   descriptor: SerialDescriptor,
   annotations: List<Annotation>,
@@ -322,25 +323,25 @@ private fun JsonObjectBuilder.applyJsonSchemaDefaults(
     }
   }
 
-  if (descriptor.kind == SerialKind.ENUM) {
-    this["enum"] = descriptor.elementNames
-  }
-
-  if (annotations.isNotEmpty()) {
-    val multiplatformDescription = annotations.filterIsInstance<Description>()
-    val description =
-      if (multiplatformDescription.isEmpty()) {
-        try {
-          val jvmDescription = annotations.filterIsInstance<Description>()
-          jvmDescription.firstOrNull()?.value
-        } catch (e: Throwable) {
-          null
+  val additionalEnumDescription: String? =
+    if (descriptor.kind == SerialKind.ENUM) {
+      this["enum"] = descriptor.elementNames
+      descriptor.elementNames
+        .mapIndexed { index, name ->
+          "$name (${descriptor.getElementAnnotations(index).lastOfInstance<Description>()?.value})"
         }
-      } else {
-        multiplatformDescription.firstOrNull()?.value
-      }
+        .joinToString("\n - ")
+    } else null
 
-    this["description"] = description
+  if (annotations.isNotEmpty()) {
+    val description = annotations.filterIsInstance<Description>().firstOrNull()?.value
+    if (additionalEnumDescription != null) {
+      this["description"] = "$description\n - $additionalEnumDescription"
+    } else {
+      this["description"] = description
+    }
+  } else if (additionalEnumDescription != null) {
+    this["description"] = " - $additionalEnumDescription"
   }
 }
 

examples/src/main/kotlin/com/xebia/functional/xef/assistants/ToolsWithDescriptions.kt

@@ -0,0 +1,36 @@
+package com.xebia.functional.xef.assistants
+
+import com.xebia.functional.xef.conversation.Description
+import com.xebia.functional.xef.llm.assistants.Assistant
+import com.xebia.functional.xef.llm.assistants.AssistantThread
+import com.xebia.functional.xef.llm.assistants.RunDelta
+import com.xebia.functional.xef.llm.assistants.Tool
+import kotlinx.serialization.Serializable
+
+@Description("Natural numbers")
+enum class NaturalWithDescriptions {
+  @Description("If the number is positive.") POSITIVE,
+  @Description("If the number is negative.") NEGATIVE
+}
+
+@Serializable
+data class SumInputWithDescription(
+  @Description("Left operand") val left: Int,
+  @Description("Right operand") val right: Int,
+  val natural: NaturalWithDescriptions
+)
+
+class SumToolWithDescription : Tool<SumInputWithDescription, Int> {
+  override suspend fun invoke(input: SumInputWithDescription): Int {
+    return input.left + input.right
+  }
+}
+
+suspend fun main() {
+  val toolConfig = Tool.toolOf(SumToolWithDescription()).functionObject
+  println(toolConfig.parameters)
+}
+
+private suspend fun runAssistantAndDisplayResults(thread: AssistantThread, assistant: Assistant) {
+  thread.run(assistant).collect(RunDelta::printEvent)
+}