feat(embedding): Add EmbeddingParams and batch embedding support to LLMEmbeddingProvider

- Add LLMCapability.Embedding.Dimensions for models supporting variable output dimensions
- Add EmbeddingParams base class in prompt-model with dimensions parameter
- Update LLMEmbeddingProvider interface:
  - Add EmbeddingParams parameter to embed() method
  - Add embedBatch() with default parallel polyfill implementation
- Apply minimal signature updates to all provider clients (OpenAI, Mistral, Ollama, Bedrock)
  to enable compilation (full implementation pending)

Part of KG-104 (dimension control) and KG-538 (batch embedding)

Author: mltheuser

prompt/prompt-executor/prompt-executor-clients/prompt-executor-bedrock-client/src/jvmMain/kotlin/ai/koog/prompt/executor/clients/bedrock/BedrockLLMClient.kt

@@ -354,7 +354,11 @@ public class BedrockLLMClient(
         }
     }
 
-    override suspend fun embed(text: String, model: LLModel): List<Double> {
+    override suspend fun embed(
+        text: String,
+        model: LLModel,
+        params: ai.koog.prompt.params.EmbeddingParams
+    ): List<Double> {
         model.requireCapability(LLMCapability.Embed)
         logger.debug { "Embedding text with model: ${model.id}" }
         val modelFamily = getBedrockModelFamily(model)

prompt/prompt-executor/prompt-executor-clients/prompt-executor-mistralai-client/src/commonMain/kotlin/ai/koog/prompt/executor/clients/mistralai/MistralAILLMClient.kt

@@ -177,10 +177,15 @@ public open class MistralAILLMClient(
      *
      * @param text The text to embed.
      * @param model The model to use for embedding. Must have the Embed capability.
+     * @param params Embedding parameters (dimensions support TODO in MistralAI migration)
      * @return A list of floating-point values representing the embedding.
      * @throws IllegalArgumentException if the model does not have the Embed capability.
      */
-    override suspend fun embed(text: String, model: LLModel): List<Double> {
+    override suspend fun embed(
+        text: String,
+        model: LLModel,
+        params: ai.koog.prompt.params.EmbeddingParams
+    ): List<Double> {
         model.requireCapability(LLMCapability.Embed)
 
         logger.debug { "Embedding text with model: ${model.id}" }

prompt/prompt-executor/prompt-executor-clients/prompt-executor-ollama-client/src/commonMain/kotlin/ai/koog/prompt/executor/ollama/client/OllamaClient.kt

@@ -330,10 +330,15 @@ public class OllamaClient(
      *
      * @param text The text to embed.
      * @param model The model to use for embedding. Must have the Embed capability.
+     * @param params Embedding parameters (dimensions support TODO in Ollama migration)
      * @return A vector representation of the text.
      * @throws LLMClientException if the model does not have the Embed capability.
      */
-    override suspend fun embed(text: String, model: LLModel): List<Double> {
+    override suspend fun embed(
+        text: String,
+        model: LLModel,
+        params: ai.koog.prompt.params.EmbeddingParams
+    ): List<Double> {
         require(model.provider == LLMProvider.Ollama) { "Model not supported by Ollama" }
 
         if (!model.capabilities.contains(LLMCapability.Embed)) {

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

@@ -398,10 +398,15 @@ public open class OpenAILLMClient(
      *
      * @param text The text to embed.
      * @param model The model to use for embedding. Must have the Embed capability.
+     * @param params Embedding parameters (dimensions support TODO in OpenAI migration)
      * @return A list of floating-point values representing the embedding.
      * @throws IllegalArgumentException if the model does not have the Embed capability.
      */
-    override suspend fun embed(text: String, model: LLModel): List<Double> {
+    override suspend fun embed(
+        text: String,
+        model: LLModel,
+        params: ai.koog.prompt.params.EmbeddingParams
+    ): List<Double> {
         model.requireCapability(LLMCapability.Embed)
 
         logger.debug { "Embedding text with model: ${model.id}" }

prompt/prompt-executor/prompt-executor-clients/src/commonMain/kotlin/ai/koog/prompt/executor/clients/LLMEmbeddingProvider.kt

@@ -1,19 +1,52 @@
 package ai.koog.prompt.executor.clients
 
 import ai.koog.prompt.llm.LLModel
+import ai.koog.prompt.params.EmbeddingParams
+import kotlinx.coroutines.async
+import kotlinx.coroutines.awaitAll
+import kotlinx.coroutines.coroutineScope
 
 /**
  * Extension of the LLMClient interface which includes functionality for generating text embeddings
  * in addition to executing prompts and streaming outputs.
  */
 public interface LLMEmbeddingProvider {
     /**
-     * Embeds the given text using into a vector of double-precision numbers.
+     * Embeds the given text into a vector of double-precision numbers.
      *
      * @param text The text to embed.
      * @param model The model to use for embedding. Must have the Embed capability.
+     * @param params Optional embedding parameters (e.g., dimensions).
      * @return A list of floating-point values representing the embedding.
+     * @throws IllegalArgumentException if the model does not have the Embed capability,
+     *   or if dimensions are specified but the model lacks Embedding.Dimensions capability.
+     */
+    public suspend fun embed(
+        text: String,
+        model: LLModel,
+        params: EmbeddingParams = EmbeddingParams()
+    ): List<Double>
+
+    /**
+     * Embeds multiple texts in a batch.
+     *
+     * Default implementation processes texts in parallel using single [embed] calls.
+     * Providers with native batch APIs should override this for better performance.
+     *
+     * @param texts The list of texts to embed.
+     * @param model The model to use for embedding. Must have the Embed capability.
+     * @param params Optional embedding parameters (e.g., dimensions).
+     * @return A list of embeddings, one for each input text.
      * @throws IllegalArgumentException if the model does not have the Embed capability.
      */
-    public suspend fun embed(text: String, model: LLModel): List<Double>
+    public suspend fun embedBatch(
+        texts: List<String>,
+        model: LLModel,
+        params: EmbeddingParams = EmbeddingParams()
+    ): List<List<Double>> = coroutineScope {
+        texts.map { text ->
+            async { embed(text, model, params) }
+        }.awaitAll()
+    }
 }
+

prompt/prompt-llm/src/commonMain/kotlin/ai/koog/prompt/llm/LLMCapability.kt

@@ -119,10 +119,34 @@ public sealed class LLMCapability(public val id: String) {
      *
      * This capability can be utilized in tasks like semantic search, document clustering,
      * or other operations requiring an understanding of textual similarity.
+     *
+     * Note: For models that support additional embedding features (like variable dimensions),
+     * see [Embedding] sealed class for more granular capabilities.
      */
     @Serializable
     public data object Embed : LLMCapability("embed")
 
+    /**
+     * Represents embedding-specific capabilities beyond basic embedding generation.
+     *
+     * These capabilities are **additive** to the base [Embed] capability. A model should have
+     * both [Embed] and the relevant [Embedding] sub-capability. For example:
+     * - OpenAI text-embedding-ada-002: has [Embed] only
+     * - OpenAI text-embedding-3-small: has [Embed] AND [Embedding.Dimensions]
+     *
+     * @property embeddingFeature The specific embedding feature identifier.
+     */
+    @Serializable
+    public sealed class Embedding(public val embeddingFeature: String) : LLMCapability(embeddingFeature) {
+        /**
+         * Indicates that the model supports variable output dimensions for embeddings.
+         * Models with this capability can accept a `dimensions` parameter to control
+         * the size of the output embedding vector.
+         */
+        @Serializable
+        public data object Dimensions : Embedding("embedding-dimensions")
+    }
+
     /**
      * Represents the "completion" capability for Language Learning Models (LLMs). This capability
      * typically encompasses the generation of text or content based on the given input context.

prompt/prompt-model/src/commonMain/kotlin/ai/koog/prompt/params/EmbeddingParams.kt

@@ -0,0 +1,43 @@
+package ai.koog.prompt.params
+
+import kotlinx.serialization.Serializable
+
+/**
+ * Parameters for embedding generation.
+ *
+ * This is an `open class` (not a `data class`) to allow provider-specific subclasses
+ * (e.g., [ai.koog.prompt.executor.clients.google.GoogleEmbeddingParams]) to add additional
+ * parameters while maintaining polymorphism. This mirrors the [LLMParams] pattern.
+ *
+ * @property dimensions Desired output embedding dimensions.
+ *   Only applicable to models that support variable dimensions
+ *   (models with [ai.koog.prompt.llm.LLMCapability.Embedding.Dimensions] capability).
+ *   If null, uses model's default dimension.
+ */
+@Serializable
+public open class EmbeddingParams(
+    public val dimensions: Int? = null,
+) {
+    init {
+        dimensions?.let {
+            require(it > 0) { "dimensions must be > 0, but was $it" }
+        }
+    }
+
+    /**
+     * Creates a copy of this instance with the ability to modify the dimensions property.
+     */
+    public open fun copy(dimensions: Int? = this.dimensions): EmbeddingParams =
+        EmbeddingParams(dimensions)
+
+    override fun equals(other: Any?): Boolean = when {
+        this === other -> true
+        other !is EmbeddingParams -> false
+        else -> dimensions == other.dimensions
+    }
+
+    override fun hashCode(): Int = dimensions?.hashCode() ?: 0
+
+    override fun toString(): String = "EmbeddingParams(dimensions=$dimensions)"
+}
+