Merge pull request #20 from Deep-CodeAI/feat/937-typed-input-serialization

feat(#937): serialize typed @generable agent input as JSON

Author: Skobeltsyn

src/main/kotlin/agents_engine/generation/GenerableSupport.kt

@@ -220,6 +220,100 @@ private fun KType.promptTypeName(): String = when (val cls = classifier) {
     else -> "String"
 }
 
+// ─── LLM Input Serialization (typed → wire format) ──────────────────────────
+
+/**
+ * Serializes an agent input value to the form the LLM should see in a user message.
+ *
+ * Symmetric with [fromLlmOutput]: that takes JSON the model produced and reconstructs
+ * a typed instance; this takes a typed instance and emits the wire format the model
+ * should see.
+ *
+ * Rules:
+ * - `null` → `"null"`
+ * - `String` → the string as-is (no JSON quoting; matches the current behavior of
+ *   passing a free-form question/instruction to a model).
+ * - `Boolean` / `Number` → JSON literal.
+ * - `List<*>` → JSON array, recursing on each element.
+ * - `Map<*, *>` → JSON object, recursing on each value.
+ * - `@Generable` data class → JSON object with each constructor param as a field.
+ *   Sealed-class variants get a `"type":"VariantName"` discriminator (matches
+ *   [fromLlmOutput]'s expected shape).
+ * - Anything else → `value.toString()` (backward-compatible fallback for plain
+ *   classes that don't opt into `@Generable`).
+ *
+ * See #937.
+ */
+fun toLlmInput(value: Any?): String = when (value) {
+    null -> "null"
+    is String -> value
+    is Boolean -> value.toString()
+    is Number -> value.toString()
+    is List<*> -> value.joinToString(",", "[", "]") { jsonSerialize(it) }
+    is Map<*, *> -> value.entries.joinToString(",", "{", "}") { (k, v) ->
+        "\"${k.toString().escapeJson()}\":${jsonSerialize(v)}"
+    }
+    else -> {
+        val cls = value::class
+        if (cls.findAnnotation<Generable>() != null) {
+            generableToJson(value, cls)
+        } else {
+            value.toString()
+        }
+    }
+}
+
+/**
+ * Internal recursive serializer — used by collections and Generable field
+ * walking. Differs from [toLlmInput] in that strings get JSON-quoted (since
+ * they're nested inside a JSON value).
+ */
+private fun jsonSerialize(value: Any?): String = when (value) {
+    null -> "null"
+    is String -> "\"${value.escapeJson()}\""
+    is Boolean -> value.toString()
+    is Number -> value.toString()
+    is List<*> -> value.joinToString(",", "[", "]") { jsonSerialize(it) }
+    is Map<*, *> -> value.entries.joinToString(",", "{", "}") { (k, v) ->
+        "\"${k.toString().escapeJson()}\":${jsonSerialize(v)}"
+    }
+    else -> {
+        val cls = value::class
+        if (cls.findAnnotation<Generable>() != null) {
+            generableToJson(value, cls)
+        } else {
+            // Non-Generable, non-primitive nested value — render via toString
+            // and JSON-quote it. Lossy but consistent with falling back to
+            // toString at the top level.
+            "\"${value.toString().escapeJson()}\""
+        }
+    }
+}
+
+private fun generableToJson(value: Any, cls: KClass<*>): String {
+    val ctor = cls.primaryConstructor
+        ?: return "\"${value.toString().escapeJson()}\""
+    val isSealedVariant = cls.allSuperclasses.any { it.isSealed }
+    return buildString {
+        append("{")
+        var first = true
+        if (isSealedVariant) {
+            append("\"type\":\"${cls.simpleName}\"")
+            first = false
+        }
+        ctor.parameters.forEach { param ->
+            val name = param.name ?: return@forEach
+            val prop = cls.memberProperties.find { it.name == name } ?: return@forEach
+            if (!first) append(",")
+            first = false
+            @Suppress("UNCHECKED_CAST")
+            val fieldValue = (prop as kotlin.reflect.KProperty1<Any, *>).get(value)
+            append("\"${name.escapeJson()}\":${jsonSerialize(fieldValue)}")
+        }
+        append("}")
+    }
+}
+
 // ─── Lenient Deserialization ──────────────────────────────────────────────────
 
 /**

src/main/kotlin/agents_engine/model/AgenticLoop.kt

@@ -5,6 +5,7 @@ import agents_engine.core.Skill
 import agents_engine.core.SkillRoute
 import agents_engine.generation.constructFromMap
 import agents_engine.generation.fromLlmOutput
+import agents_engine.generation.toLlmInput
 import java.util.concurrent.atomic.AtomicReference
 import kotlin.reflect.KClass
 import kotlinx.coroutines.Dispatchers
@@ -95,8 +96,10 @@ suspend fun <IN> executeAgentic(
     }
     if (systemContent.isNotBlank()) messages.add(LlmMessage("system", systemContent))
 
-    // User: serialized input
-    messages.add(LlmMessage("user", input.toString()))
+    // User: serialized input. Typed @Generable inputs become JSON; primitives
+    // and Strings render literally; non-Generable types fall back to toString.
+    // See #937 / GenerableSupport.toLlmInput.
+    messages.add(LlmMessage("user", toLlmInput(input)))
 
     var turns = 0
     var toolCalls = 0
@@ -185,7 +188,7 @@ suspend fun <IN> selectSkillByLlm(
 
     val messages = listOf(
         LlmMessage("system", systemPrompt),
-        LlmMessage("user", input.toString()),
+        LlmMessage("user", toLlmInput(input)),  // #937 — typed Generable inputs as JSON
     )
 
     val client = config.client ?: OllamaClient(config.host, config.port, config.name, config.temperature)

src/test/kotlin/agents_engine/generation/LlmInputSerializationTest.kt

@@ -0,0 +1,161 @@
+package agents_engine.generation
+
+import kotlin.test.Test
+import kotlin.test.assertEquals
+import kotlin.test.assertNotNull
+import kotlin.test.assertTrue
+
+// Tests for #937 — toLlmInput serializes typed agent input as JSON when the
+// type is @Generable; falls back to toString() for plain types; preserves
+// literal String passthrough so free-form prompts don't get JSON-quoted.
+
+@Generable("a single field")
+data class InputSingle(val v: String)
+
+@Generable("multiple primitive fields")
+data class InputMulti(val name: String, val count: Int, val active: Boolean)
+
+@Generable("contains a list")
+data class InputWithList(val tags: List<String>)
+
+@Generable("contains a nested generable")
+data class InputWithNested(val inner: InputSingle, val label: String)
+
+@Generable("sealed root")
+sealed interface Decision937 {
+    @Generable("approved")
+    data class Approved(val confidence: Double) : Decision937
+
+    @Generable("rejected")
+    data class Rejected(val reason: String) : Decision937
+}
+
+class PlainNonGenerable(val v: String) {
+    override fun toString(): String = "PLAIN-$v"
+}
+
+class LlmInputSerializationTest {
+
+    @Test
+    fun `null serializes as JSON null literal`() {
+        assertEquals("null", toLlmInput(null))
+    }
+
+    @Test
+    fun `String passes through unchanged (no JSON quoting)`() {
+        // Free-form prompts must not get wrapped in quotes — that would
+        // change what the LLM sees from the user message.
+        assertEquals("hello world", toLlmInput("hello world"))
+    }
+
+    @Test
+    fun `String with quotes and backslashes still passes through unchanged`() {
+        // Top-level String is opaque; the agent passed it as-is, the LLM
+        // sees it as-is.
+        val s = "she said \"hi\" \\ then left"
+        assertEquals(s, toLlmInput(s))
+    }
+
+    @Test
+    fun `primitive Number renders as JSON literal`() {
+        assertEquals("42", toLlmInput(42))
+        assertEquals("3.14", toLlmInput(3.14))
+        assertEquals("9999999999", toLlmInput(9_999_999_999L))
+    }
+
+    @Test
+    fun `Boolean renders as JSON literal`() {
+        assertEquals("true", toLlmInput(true))
+        assertEquals("false", toLlmInput(false))
+    }
+
+    @Test
+    fun `Generable single-field data class serializes as JSON object`() {
+        val out = toLlmInput(InputSingle("hello"))
+        assertEquals("""{"v":"hello"}""", out)
+    }
+
+    @Test
+    fun `Generable multi-field data class serializes with each constructor param`() {
+        val out = toLlmInput(InputMulti(name = "alice", count = 3, active = true))
+        // Field order follows constructor order.
+        assertEquals("""{"name":"alice","count":3,"active":true}""", out)
+    }
+
+    @Test
+    fun `String fields inside Generable are JSON-escaped`() {
+        val out = toLlmInput(InputSingle("she said \"hi\" then \\left"))
+        assertEquals("""{"v":"she said \"hi\" then \\left"}""", out)
+    }
+
+    @Test
+    fun `Generable with List field renders the list as JSON array`() {
+        val out = toLlmInput(InputWithList(listOf("a", "b", "c")))
+        assertEquals("""{"tags":["a","b","c"]}""", out)
+    }
+
+    @Test
+    fun `Generable with nested Generable field recurses`() {
+        val out = toLlmInput(InputWithNested(inner = InputSingle("inside"), label = "outer"))
+        assertEquals("""{"inner":{"v":"inside"},"label":"outer"}""", out)
+    }
+
+    @Test
+    fun `Sealed Generable variant gets a type discriminator`() {
+        val approved = toLlmInput(Decision937.Approved(0.92))
+        assertTrue(
+            approved.contains("\"type\":\"Approved\""),
+            "sealed-variant must include type discriminator: $approved",
+        )
+        assertTrue(approved.contains("\"confidence\":0.92"), "must include field: $approved")
+
+        val rejected = toLlmInput(Decision937.Rejected("not enough data"))
+        assertTrue(
+            rejected.contains("\"type\":\"Rejected\""),
+            "sealed-variant must include type discriminator: $rejected",
+        )
+        assertTrue(rejected.contains("\"reason\":\"not enough data\""))
+    }
+
+    @Test
+    fun `non-Generable plain class falls back to toString`() {
+        val out = toLlmInput(PlainNonGenerable("xyz"))
+        assertEquals("PLAIN-xyz", out)
+    }
+
+    @Test
+    fun `top-level List of Strings renders as JSON array`() {
+        val out = toLlmInput(listOf("a", "b", "c"))
+        assertEquals("""["a","b","c"]""", out)
+    }
+
+    @Test
+    fun `top-level List of Generables renders as JSON array of objects`() {
+        val out = toLlmInput(listOf(InputSingle("x"), InputSingle("y")))
+        assertEquals("""[{"v":"x"},{"v":"y"}]""", out)
+    }
+
+    @Test
+    fun `top-level Map renders as JSON object`() {
+        val out = toLlmInput(mapOf("a" to 1, "b" to "two"))
+        assertEquals("""{"a":1,"b":"two"}""", out)
+    }
+
+    // Round-trip: serialized output should re-parse via fromLlmOutput.
+    @Test
+    fun `round-trip toLlmInput then fromLlmOutput reconstructs the original`() {
+        val original = InputMulti(name = "alice", count = 3, active = true)
+        val json = toLlmInput(original)
+        val reconstructed = InputMulti::class.fromLlmOutput(json)
+        assertNotNull(reconstructed)
+        assertEquals(original, reconstructed)
+    }
+
+    @Test
+    fun `round-trip works for sealed variant`() {
+        val original: Decision937 = Decision937.Rejected("insufficient")
+        val json = toLlmInput(original)
+        val reconstructed = Decision937::class.fromLlmOutput(json)
+        assertEquals(original, reconstructed)
+    }
+}