Fix finishReason nullability (JetBrains#771)

Fixes JetBrains#758

Author: tiginamaria

gradle.properties

@@ -1,7 +1,6 @@
 #Kotlin
 kotlin.code.style=official
 kotlin.daemon.jvmargs=-Xmx4096M
-kotlin.native.ignoreDisabledTargets=true
 
 # Build JS targets using npm package manager https://kotlinlang.org/docs/js-project-setup.html#npm-dependencies
 kotlin.js.yarn=false

integration-tests/src/jvmTest/kotlin/ai/koog/integration/tests/executor/SingleLLMPromptExecutorIntegrationTest.kt

@@ -238,10 +238,6 @@ class SingleLLMPromptExecutorIntegrationTest {
         if (model.id == OpenAIModels.Audio.GPT4oAudio.id || model.id == OpenAIModels.Audio.GPT4oMiniAudio.id) {
             assumeTrue(false, "https://github.com/JetBrains/koog/issues/231")
         }
-        // TODO fix (KG-394): OpenRouter anthropic/claude-sonnet-4 streaming is incompatible with our current client setup (SSE/protocol)
-        if (model.provider == LLMProvider.OpenRouter && model.id.contains("anthropic/claude-sonnet-4")) {
-            assumeTrue(false, "Skipping OpenRouter anthropic/claude-sonnet-4 streaming: protocol incompatibility")
-        }
 
         val executor = SingleLLMPromptExecutor(client)
 
@@ -514,10 +510,6 @@ class SingleLLMPromptExecutorIntegrationTest {
         if (model.id == OpenAIModels.Audio.GPT4oAudio.id || model.id == OpenAIModels.Audio.GPT4oMiniAudio.id) {
             assumeTrue(false, "https://github.com/JetBrains/koog/issues/231")
         }
-        // TODO fix (KG-394): OpenRouter anthropic/claude-sonnet-4 streaming is incompatible with our current client setup (SSE/protocol)
-        if (model.provider == LLMProvider.OpenRouter && model.id.contains("anthropic/claude-sonnet-4")) {
-            assumeTrue(false, "Skipping OpenRouter anthropic/claude-sonnet-4 streaming: protocol incompatibility")
-        }
 
         val prompt = Prompt.build("test-streaming") {
             system("You are a helpful assistant. You have NO output length limitations.")
@@ -550,10 +542,6 @@ class SingleLLMPromptExecutorIntegrationTest {
     fun integration_testStructuredDataStreaming(model: LLModel, client: LLMClient) = runTest(timeout = 300.seconds) {
         Models.assumeAvailable(model.provider)
         assumeTrue(model != OpenAIModels.CostOptimized.GPT4_1Nano, "Model $model is too small for structured streaming")
-        // TODO fix (KG-394): OpenRouter anthropic/claude-sonnet-4 streaming is incompatible with our current client setup (SSE/protocol)
-        if (model.provider == LLMProvider.OpenRouter && model.id.contains("anthropic/claude-sonnet-4")) {
-            assumeTrue(false, "Skipping OpenRouter anthropic/claude-sonnet-4 streaming: protocol incompatibility")
-        }
 
         val countries = mutableListOf<Country>()
         val countryDefinition = markdownCountryDefinition()
@@ -641,7 +629,7 @@ class SingleLLMPromptExecutorIntegrationTest {
     @MethodSource("modelClientCombinations")
     fun integration_testToolChoiceNamed(model: LLModel, client: LLMClient) = runTest(timeout = 300.seconds) {
         Models.assumeAvailable(model.provider)
-        assumeTrue(!(model.provider == LLMProvider.OpenRouter && model.id.contains("anthropic")), "KG-282")
+
         assumeTrue(model.capabilities.contains(LLMCapability.ToolChoice), "Model $model does not support tools")
 
         val calculatorTool = createCalculatorTool()
@@ -1142,10 +1130,7 @@ class SingleLLMPromptExecutorIntegrationTest {
             model.capabilities.contains(LLMCapability.Schema.JSON.Standard),
             "Model does not support Standard JSON Schema"
         )
-        // TODO fix (KG-394): OpenRouter anthropic/claude-sonnet-4 streaming is incompatible with our current client setup (SSE/protocol)
-        if (model.provider == LLMProvider.OpenRouter) {
-            assumeTrue(false, "Skipping StructuredOutputNative for OpenRouter due to schema incompatibilities upstream")
-        }
+
         val executor = SingleLLMPromptExecutor(client)
 
         withRetry {
@@ -1167,13 +1152,7 @@ class SingleLLMPromptExecutorIntegrationTest {
             model.capabilities.contains(LLMCapability.Schema.JSON.Standard),
             "Model does not support Standard JSON Schema"
         )
-        // TODO fix (KG-394) OpenRouter
-        if (model.provider == LLMProvider.OpenRouter) {
-            assumeTrue(
-                false,
-                "Skipping StructuredOutputNativeWithFixingParser for OpenRouter due to upstream schema incompatibilities"
-            )
-        }
+
         val executor = SingleLLMPromptExecutor(client)
 
         withRetry {
@@ -1195,6 +1174,11 @@ class SingleLLMPromptExecutorIntegrationTest {
             model.provider !== LLMProvider.Google,
             "Google models fail to return manually requested structured output without fixing"
         )
+        assumeTrue(
+            model.provider == LLMProvider.OpenRouter && model.id.contains("gemini"),
+            "Google models fail to return manually requested structured output without fixing"
+        )
+
         val executor = SingleLLMPromptExecutor(client)
 
         withRetry {

integration-tests/src/jvmTest/kotlin/ai/koog/integration/tests/utils/Models.kt

@@ -84,8 +84,7 @@ object Models {
         OpenRouterModels.GPT5Nano,
         OpenRouterModels.DeepSeekV30324,
         OpenRouterModels.Claude4Sonnet,
-        // ToDo add Gemini when KG-203 is fixed
-        // OpenRouterModels.Gemini2_5FlashLite,
+        OpenRouterModels.Gemini2_5FlashLite,
     )
 
     @JvmStatic

koog-ktor/src/commonMain/kotlin/ai/koog/ktor/utils/LLMModelParser.kt

@@ -237,8 +237,12 @@ private val GOOGLE_MODELS_MAP = mapOf(
 )
 
 private val OPENROUTER_MODELS_MAP = mapOf(
-    "claude3sonnet" to OpenRouterModels.Claude3Sonnet,
     "claude3haiku" to OpenRouterModels.Claude3Haiku,
+    "claude3opus" to OpenRouterModels.Claude3Opus,
+    "claude3sonnet" to OpenRouterModels.Claude3Sonnet,
+    "claude35sonnet" to OpenRouterModels.Claude3_5Sonnet,
+    "claude4sonnet" to OpenRouterModels.Claude4Sonnet,
+    "claude41opus" to OpenRouterModels.Claude4_1Opus,
     "gpt4" to OpenRouterModels.GPT4,
     "gpt4o" to OpenRouterModels.GPT4o,
     "gpt5" to OpenRouterModels.GPT5,

prompt/prompt-executor/prompt-executor-clients/prompt-executor-deepseek-client/build.gradle.kts

@@ -13,6 +13,8 @@ kotlin {
         commonMain {
             dependencies {
                 api(project(":prompt:prompt-executor:prompt-executor-clients:prompt-executor-openai-client-base"))
+                api(project(":prompt:prompt-structure"))
+                api(project(":prompt:prompt-executor:prompt-executor-clients:prompt-executor-openai-client"))
                 implementation(libs.oshai.kotlin.logging)
             }
         }

prompt/prompt-executor/prompt-executor-clients/prompt-executor-deepseek-client/src/commonMain/kotlin/ai/koog/prompt/executor/clients/deepseek/DeepSeekLLMClient.kt

@@ -13,13 +13,20 @@ import ai.koog.prompt.executor.clients.openai.base.OpenAIBasedSettings
 import ai.koog.prompt.executor.clients.openai.base.models.OpenAIMessage
 import ai.koog.prompt.executor.clients.openai.base.models.OpenAITool
 import ai.koog.prompt.executor.clients.openai.base.models.OpenAIToolChoice
+import ai.koog.prompt.executor.clients.openai.structure.OpenAIBasicJsonSchemaGenerator
+import ai.koog.prompt.executor.clients.openai.structure.OpenAIStandardJsonSchemaGenerator
 import ai.koog.prompt.executor.model.LLMChoice
+import ai.koog.prompt.llm.LLMProvider
 import ai.koog.prompt.llm.LLModel
 import ai.koog.prompt.params.LLMParams
 import ai.koog.prompt.streaming.StreamFrameFlowBuilder
+import ai.koog.prompt.structure.RegisteredBasicJsonSchemaGenerators
+import ai.koog.prompt.structure.RegisteredStandardJsonSchemaGenerators
+import ai.koog.prompt.structure.annotations.InternalStructuredOutputApi
 import io.github.oshai.kotlinlogging.KotlinLogging
 import io.ktor.client.HttpClient
 import kotlinx.datetime.Clock
+import kotlin.collections.set
 
 /**
  * Configuration settings for connecting to the DeepSeek API.
@@ -54,8 +61,14 @@ public class DeepSeekLLMClient(
     staticLogger
 ) {
 
+    @OptIn(InternalStructuredOutputApi::class)
     private companion object {
         private val staticLogger = KotlinLogging.logger { }
+
+        init {
+            RegisteredBasicJsonSchemaGenerators[LLMProvider.DeepSeek] = OpenAIBasicJsonSchemaGenerator
+            RegisteredStandardJsonSchemaGenerators[LLMProvider.DeepSeek] = OpenAIStandardJsonSchemaGenerator
+        }
     }
 
     override fun serializeProviderChatRequest(
@@ -92,7 +105,12 @@ public class DeepSeekLLMClient(
 
     override fun processProviderChatResponse(response: DeepSeekChatCompletionResponse): List<LLMChoice> {
         require(response.choices.isNotEmpty()) { "Empty choices in response" }
-        return response.choices.map { it.toMessageResponses(createMetaInfo(response.usage)) }
+        return response.choices.map {
+            it.message.toMessageResponses(
+                it.finishReason,
+                createMetaInfo(response.usage),
+            )
+        }
     }
 
     override fun decodeStreamingResponse(data: String): DeepSeekChatCompletionStreamResponse =

prompt/prompt-executor/prompt-executor-clients/prompt-executor-openai-client-base/src/commonMain/kotlin/ai/koog/prompt/executor/clients/openai/base/AbstractOpenAILLMClient.kt

@@ -12,7 +12,6 @@ import ai.koog.prompt.executor.clients.openai.base.models.Content
 import ai.koog.prompt.executor.clients.openai.base.models.JsonSchemaObject
 import ai.koog.prompt.executor.clients.openai.base.models.OpenAIBaseLLMResponse
 import ai.koog.prompt.executor.clients.openai.base.models.OpenAIBaseLLMStreamResponse
-import ai.koog.prompt.executor.clients.openai.base.models.OpenAIChoice
 import ai.koog.prompt.executor.clients.openai.base.models.OpenAIContentPart
 import ai.koog.prompt.executor.clients.openai.base.models.OpenAIFunction
 import ai.koog.prompt.executor.clients.openai.base.models.OpenAIMessage
@@ -406,10 +405,10 @@ public abstract class AbstractOpenAILLMClient<TResponse : OpenAIBaseLLMResponse,
     }
 
     @OptIn(ExperimentalEncodingApi::class)
-    protected fun OpenAIChoice.toMessageResponses(metaInfo: ResponseMetaInfo): List<Message.Response> {
+    protected fun OpenAIMessage.toMessageResponses(finishReason: String?, metaInfo: ResponseMetaInfo): List<Message.Response> {
         return when {
-            message is OpenAIMessage.Assistant && !message.toolCalls.isNullOrEmpty() -> {
-                message.toolCalls.map { toolCall ->
+            this is OpenAIMessage.Assistant && !this.toolCalls.isNullOrEmpty() -> {
+                this.toolCalls.map { toolCall ->
                     Message.Tool.Call(
                         id = toolCall.id,
                         tool = toolCall.function.name,
@@ -419,20 +418,20 @@ public abstract class AbstractOpenAILLMClient<TResponse : OpenAIBaseLLMResponse,
                 }
             }
 
-            message.content != null -> listOf(
+            this.content != null -> listOf(
                 Message.Assistant(
-                    content = message.content!!.text(),
+                    content = this.content!!.text(),
                     finishReason = finishReason,
                     metaInfo = metaInfo
                 )
             )
 
-            message is OpenAIMessage.Assistant && message.audio?.data != null -> listOf(
+            this is OpenAIMessage.Assistant && this.audio?.data != null -> listOf(
                 Message.Assistant(
-                    content = message.audio.transcript.orEmpty(),
+                    content = this.audio.transcript.orEmpty(),
                     attachments = listOf(
                         Attachment.Audio(
-                            content = AttachmentContent.Binary.Base64(message.audio.data),
+                            content = AttachmentContent.Binary.Base64(this.audio.data),
                             format = "unknown", // FIXME: clarify format from response
                         )
                     ),

prompt/prompt-executor/prompt-executor-clients/prompt-executor-openai-client-base/src/commonMain/kotlin/ai/koog/prompt/executor/clients/openai/base/models/OpenAIDataModels.kt

@@ -352,6 +352,8 @@ public class OpenAIStreamFunction(
  * [coral][OpenAIAudioVoice.Coral], [echo][OpenAIAudioVoice.Echo], [fable][OpenAIAudioVoice.Fable],
  * [nova][OpenAIAudioVoice.Nova], [onyx][OpenAIAudioVoice.Onyx], [sage][OpenAIAudioVoice.Sage]
  * and [shimmer][OpenAIAudioVoice.Shimmer]
+ *
+ * See [audio](https://platform.openai.com/docs/api-reference/chat/create#chat-create-audio)
  */
 @Serializable
 public class OpenAIAudioConfig(
@@ -364,6 +366,8 @@ public class OpenAIAudioConfig(
  *
  * This enum is used to specify the format of the audio output. It contains several standard audio formats
  * which are widely compatible with various audio players and systems.
+ *
+ * See [audio/format](https://platform.openai.com/docs/api-reference/chat/create#chat-create-audio-format)
  */
 @Serializable
 public enum class OpenAIAudioFormat {
@@ -387,6 +391,8 @@ public enum class OpenAIAudioFormat {
  * Represents the available voice options for audio output in OpenAI's system.
  *
  * This enum defines a list of predefined voices that can be used to synthesize audio responses.
+ *
+ * See [audio/voice](https://platform.openai.com/docs/api-reference/chat/create#chat-create-audio-voice)
  */
 @Serializable
 public enum class OpenAIAudioVoice {
@@ -458,6 +464,8 @@ public class OpenAIStaticContent(public val content: Content) {
  * If not set, the model/provider default applies.
  *
  * Serialized as `"minimal" | "low" | "medium" | "high"`.
+ *
+ * See [reasoning_effort](https://platform.openai.com/docs/api-reference/chat/create#chat-create-reasoning_effort)
  */
 @Serializable
 public enum class ReasoningEffort {
@@ -549,6 +557,8 @@ public sealed interface OpenAIResponseFormat {
  * Note: When a tier is requested, the response payload includes the
  * `service_tier` actually used to serve the request. This value may differ from
  * the one provided in the request.
+ *
+ * See [service_tier](https://platform.openai.com/docs/api-reference/chat/create#chat-create-service_tier)
  */
 public enum class ServiceTier {
     /**
@@ -613,6 +623,8 @@ public class JsonSchemaObject(
  * All other chunks will also include a `usage` field, but with a null value.
  * NOTE: If the stream is interrupted,
  * you may not receive the final usage chunk which contains the total token usage for the request.
+ *
+ * See [stream_options](https://platform.openai.com/docs/api-reference/chat/create#chat-create-stream_options)
  */
 @Serializable
 public class OpenAIStreamOptions(public val includeUsage: Boolean? = null)
@@ -764,6 +776,8 @@ public class OpenAIUserLocation(
  * @property index The index of the choice in the list of choices.
  * @property logprobs Log probability information for the choice.
  * @property message A chat completion message generated by the model.
+ *
+ * See [choices](https://platform.openai.com/docs/api-reference/chat/object#chat/object-choices)
  */
 @Serializable
 public class OpenAIChoice(
@@ -776,6 +790,8 @@ public class OpenAIChoice(
 /**
  * @property content A list of message content tokens with log probability information.
  * @property refusal A list of message refusal tokens with log probability information.
+ *
+ * See [choices/logprobs](https://platform.openai.com/docs/api-reference/chat/object#chat/object-choices-logprobs)
  */
 @Serializable
 public class OpenAIChoiceLogProbs(
@@ -793,6 +809,9 @@ public class OpenAIChoiceLogProbs(
      * @property token The token.
      * @property topLogprobs List of the most likely tokens and their log probability, at this token position.
      * In rare cases, there may be fewer than the number of requested `[topLogprobs]` returned.
+     *
+     * See [choices/logprobs/content](https://platform.openai.com/docs/api-reference/chat/object#chat/object-choices-logprobs-content)
+     * and [choices/logprobs/refusal](https://platform.openai.com/docs/api-reference/chat/object#chat/object-choices-logprobs-refusal)
      */
     @Serializable
     public class ContentLogProbs(
@@ -810,6 +829,9 @@ public class OpenAIChoiceLogProbs(
      * @property logprob The log probability of this token, if it is within the top 20 most likely tokens.
      * Otherwise, the value `-9999.0` is used to signify that the token is very unlikely.
      * @property token The token.
+     *
+     * See [choices/logprobs/content/top_logprobs](https://platform.openai.com/docs/api-reference/chat/object#chat/object-choices-logprobs-content-top_logprobs)
+     * and [choices/logprobs/refusal/top_logprobs](https://platform.openai.com/docs/api-reference/chat/object#chat/object-choices-logprobs-refusal-top_logprobs)
      */
     @Serializable
     public class ContentTopLogProbs(
@@ -849,6 +871,9 @@ public class OpenAIWebUrlCitation(public val urlCitation: Citation) {
  * @property totalTokens Total number of tokens used in the request (prompt + completion).
  * @property completionTokensDetails Breakdown of tokens used in a completion.
  * @property promptTokensDetails Breakdown of tokens used in the prompt.
+ *
+ * See [chat completions usage](https://platform.openai.com/docs/api-reference/chat/object#chat/object-usage)
+ * and [streaming usage](https://platform.openai.com/docs/api-reference/chat-streaming/streaming#chat-streaming/streaming-usage)
  */
 @Serializable
 public class OpenAIUsage(
@@ -868,6 +893,9 @@ public class OpenAIUsage(
  * the number of tokens in the prediction that did not appear in the completion.
  * However, like reasoning tokens, these tokens are still counted in the total completion tokens for purposes of billing,
  * output and context window limits.
+ *
+ * See [chat completions usage/completion_tokens_details](https://platform.openai.com/docs/api-reference/chat/object#chat/object-usage-completion_tokens_details)
+ * and [streaming usage/completion_tokens_details](https://platform.openai.com/docs/api-reference/chat-streaming/streaming#chat-streaming/streaming-usage-completion_tokens_details)
  */
 @Serializable
 public class CompletionTokensDetails(
@@ -880,6 +908,9 @@ public class CompletionTokensDetails(
 /**
  * @property audioTokens Audio input tokens generated by the model.
  * @property cachedTokens Cached tokens present in the prompt.
+ *
+ * See [chat completions usage/prompt_tokens_details](https://platform.openai.com/docs/api-reference/chat/object#chat/object-usage-prompt_tokens_details)
+ * and [streaming usage/prompt_tokens_details](https://platform.openai.com/docs/api-reference/chat-streaming/streaming#chat-streaming/streaming-usage-prompt_tokens_details)
  */
 @Serializable
 public class PromptTokensDetails(
@@ -897,6 +928,7 @@ public class PromptTokensDetails(
  * @property index The index of the choice in the list of choices.
  * @property logprobs Log probability information for the choice.
  *
+ * See [choices](https://platform.openai.com/docs/api-reference/chat-streaming/streaming#chat-streaming/streaming-choices)
  */
 @Serializable
 public class OpenAIStreamChoice(
@@ -911,6 +943,8 @@ public class OpenAIStreamChoice(
  * @property refusal The refusal message generated by the model.
  * @property role The role of the author of this message.
  * @property toolCalls
+ *
+ * See [choices/delta](https://platform.openai.com/docs/api-reference/chat-streaming/streaming#chat-streaming/streaming-choices-delta)
  */
 @Serializable
 public class OpenAIStreamDelta(

prompt/prompt-executor/prompt-executor-clients/prompt-executor-openai-client/src/commonMain/kotlin/ai/koog/prompt/executor/clients/openai/OpenAILLMClient.kt

@@ -223,7 +223,12 @@ public open class OpenAILLMClient(
 
     override fun processProviderChatResponse(response: OpenAIChatCompletionResponse): List<LLMChoice> {
         require(response.choices.isNotEmpty()) { "Empty choices in response" }
-        return response.choices.map { it.toMessageResponses(createMetaInfo(response.usage)) }
+        return response.choices.map {
+            it.message.toMessageResponses(
+                it.finishReason,
+                createMetaInfo(response.usage),
+            )
+        }
     }
 
     override fun decodeStreamingResponse(data: String): OpenAIChatCompletionStreamResponse =