Fix handling for openai chat portable options

 - Now you can use an arbitrary ChatOption instance as Prompt options for the OpenAIChatClinet.
 - Add Unit tests for OpenAiApi and ModelOptionsUtils.
 - Document portable options support.

Author: tzolov

models/spring-ai-openai/src/main/java/org/springframework/ai/openai/OpenAiChatClient.java

@@ -25,6 +25,7 @@
 import reactor.core.publisher.Flux;
 
 import org.springframework.ai.chat.ChatClient;
+import org.springframework.ai.chat.ChatOptions;
 import org.springframework.ai.chat.ChatResponse;
 import org.springframework.ai.chat.Generation;
 import org.springframework.ai.chat.StreamingChatClient;
@@ -166,8 +167,10 @@ ChatCompletionRequest createRequest(Prompt prompt, boolean stream) {
 		}
 
 		if (prompt.getOptions() != null) {
-			if (prompt.getOptions() instanceof OpenAiChatOptions runtimeOptions) {
-				request = ModelOptionsUtils.merge(runtimeOptions, request, ChatCompletionRequest.class);
+			if (prompt.getOptions() instanceof ChatOptions runtimeOptions) {
+				OpenAiChatOptions updatedRuntimeOptions = ModelOptionsUtils.copyToTarget(runtimeOptions,
+						ChatOptions.class, OpenAiChatOptions.class);
+				request = ModelOptionsUtils.merge(updatedRuntimeOptions, request, ChatCompletionRequest.class);
 			}
 			else {
 				throw new IllegalArgumentException("Prompt options are not of type ChatCompletionRequest:"

spring-ai-core/src/main/java/org/springframework/ai/chat/ChatOptions.java

@@ -19,12 +19,10 @@
 import org.springframework.ai.model.ModelOptions;
 
 /**
- * portable options
+ * The ChatOptions represent the common options, portable across different chat models.
  */
 public interface ChatOptions extends ModelOptions {
 
-	// determine portable optionsb
-
 	Float getTemperature();
 
 	void setTemperature(Float temperature);

spring-ai-core/src/main/java/org/springframework/ai/model/ModelOptionsUtils.java

@@ -16,8 +16,10 @@
 
 package org.springframework.ai.model;
 
+import java.beans.PropertyDescriptor;
 import java.lang.reflect.Field;
 import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
@@ -30,25 +32,37 @@
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.databind.SerializationFeature;
 
+import org.springframework.beans.BeanWrapper;
+import org.springframework.beans.BeanWrapperImpl;
+import org.springframework.util.Assert;
 import org.springframework.util.CollectionUtils;
 
 /**
  * Utility class for manipulating {@link ModelOptions} objects.
  *
  * @author Christian Tzolov
+ * @since 0.8.0
  */
 public final class ModelOptionsUtils {
 
 	private final static ObjectMapper OBJECT_MAPPER = new ObjectMapper()
 		.disable(SerializationFeature.FAIL_ON_EMPTY_BEANS);
 
+	private final static List<String> BEAN_MERGE_FIELD_EXCISIONS = List.of("class");
+
+	private static ConcurrentHashMap<Class<?>, List<String>> REQUEST_FIELD_NAMES_PER_CLASS = new ConcurrentHashMap<Class<?>, List<String>>();
+
 	private ModelOptionsUtils() {
 
 	}
 
 	/**
 	 * Merges the source object into the target object and returns an object represented
-	 * by the given class. The source null values are ignored.
+	 * by the given class. The JSON property names are used to match the fields to merge.
+	 * The source non-null values override the target values with the same field name. The
+	 * source null values are ignored. If the acceptedFieldNames is not empty, only the
+	 * fields with the given names are merged and returned. If the acceptedFieldNames is
+	 * empty, use the {@code @JsonProperty} names, inferred from the provided clazz.
 	 * @param <T> they type of the class to return.
 	 * @param source the source object to merge.
 	 * @param target the target object to merge into.
@@ -62,8 +76,12 @@ public static <T> T merge(Object source, Object target, Class<T> clazz, List<Str
 				? REQUEST_FIELD_NAMES_PER_CLASS.computeIfAbsent(clazz, ModelOptionsUtils::getJsonPropertyValues)
 				: acceptedFieldNames;
 
-		Map<String, Object> sourceMap = objectToMap(source);
-		Map<String, Object> targetMap = objectToMap(target);
+		if (CollectionUtils.isEmpty(requestFieldNames)) {
+			throw new IllegalArgumentException("No @JsonProperty fields found in the " + clazz.getName());
+		}
+
+		Map<String, Object> sourceMap = ModelOptionsUtils.objectToMap(source);
+		Map<String, Object> targetMap = ModelOptionsUtils.objectToMap(target);
 
 		targetMap.putAll(sourceMap.entrySet()
 			.stream()
@@ -77,22 +95,23 @@ public static <T> T merge(Object source, Object target, Class<T> clazz, List<Str
 				.collect(Collectors.toMap(e -> e.getKey(), e -> e.getValue()));
 		}
 
-		return mapToClass(targetMap, clazz);
+		return ModelOptionsUtils.mapToClass(targetMap, clazz);
 	}
 
-	private static ConcurrentHashMap<Class<?>, List<String>> REQUEST_FIELD_NAMES_PER_CLASS = new ConcurrentHashMap<Class<?>, List<String>>();
-
 	/**
 	 * Merges the source object into the target object and returns an object represented
-	 * by the given class. The source null values are ignored.
+	 * by the given class. The JSON property names are used to match the fields to merge.
+	 * The source non-null values override the target values with the same field name. The
+	 * source null values are ignored. Returns the only field names that match the
+	 * {@code @JsonProperty} names, inferred from the provided clazz.
 	 * @param <T> they type of the class to return.
 	 * @param source the source object to merge.
 	 * @param target the target object to merge into.
 	 * @param clazz the class to return.
 	 * @return the merged object represented by the given class.
 	 */
 	public static <T> T merge(Object source, Object target, Class<T> clazz) {
-		return merge(source, target, clazz, null);
+		return ModelOptionsUtils.merge(source, target, clazz, null);
 	}
 
 	/**
@@ -132,7 +151,7 @@ public static <T> T mapToClass(Map<String, Object> source, Class<T> clazz) {
 	}
 
 	/**
-	 * Returns the list of values of the {@link JsonProperty} annotations.
+	 * Returns the list of name values of the {@link JsonProperty} annotations.
 	 * @param clazz the class that contains fields annotated with {@link JsonProperty}.
 	 * @return the list of values of the {@link JsonProperty} annotations.
 	 */
@@ -148,4 +167,95 @@ public static List<String> getJsonPropertyValues(Class<?> clazz) {
 		return values;
 	}
 
+	/**
+	 * Returns a new instance of the targetBeanClazz that copies the bean values from the
+	 * sourceBean instance.
+	 * @param sourceBean the source bean to copy the values from.
+	 * @param sourceInterfaceClazz the source interface class. Only the fields with the
+	 * same name as the interface methods are copied. This allow the source object to be a
+	 * subclass of the source interface with additional, non-interface fields.
+	 * @param targetBeanClazz the target class, a subclass of the ChatOptions, to convert
+	 * into.
+	 * @param <T> the target class type.
+	 * @return a new instance of the targetBeanClazz with the values from the sourceBean
+	 * instance.
+	 */
+	public static <I, S extends I, T extends S> T copyToTarget(S sourceBean, Class<I> sourceInterfaceClazz,
+			Class<T> targetBeanClazz) {
+
+		Assert.notNull(sourceInterfaceClazz, "SourceOptionsClazz must not be null");
+		Assert.notNull(targetBeanClazz, "TargetOptionsClazz must not be null");
+
+		if (sourceBean == null) {
+			return null;
+		}
+
+		if (sourceBean.getClass().isAssignableFrom(targetBeanClazz)) {
+			return (T) sourceBean;
+		}
+
+		try {
+			T targetOptions = targetBeanClazz.getConstructor().newInstance();
+
+			ModelOptionsUtils.mergeBeans(sourceBean, targetOptions, sourceInterfaceClazz, true);
+
+			return targetOptions;
+		}
+		catch (Exception e) {
+			throw new RuntimeException(
+					"Failed to convert the " + sourceInterfaceClazz.getName() + " into " + targetBeanClazz.getName(),
+					e);
+		}
+	}
+
+	/**
+	 * Merges the source object into the target object. The source null values are
+	 * ignored. Only objects with Getter and Setter methods are supported.
+	 * @param <T> the type of the source and target object.
+	 * @param source the source object to merge.
+	 * @param target the target object to merge into.
+	 * @param sourceInterfaceClazz the source interface class. Only the fields with the
+	 * same name as the interface methods are merged. This allow the source object to be a
+	 * subclass of the source interface with additional, non-interface fields.
+	 * @param overrideNonNullTargetValues if true, the source non-null values override the
+	 * target values with the same field name. If false, the source non-null values are
+	 * ignored.
+	 * @return the merged target object.
+	 */
+	public static <I, S extends I, T extends S> T mergeBeans(S source, T target, Class<I> sourceInterfaceClazz,
+			boolean overrideNonNullTargetValues) {
+		Assert.notNull(source, "Source object must not be null");
+		Assert.notNull(target, "Target object must not be null");
+
+		BeanWrapper sourceBeanWrap = new BeanWrapperImpl(source);
+		BeanWrapper targetBeanWrap = new BeanWrapperImpl(target);
+
+		List<String> interfaceNames = Arrays.stream(sourceInterfaceClazz.getMethods()).map(m -> m.getName()).toList();
+
+		for (PropertyDescriptor descriptor : sourceBeanWrap.getPropertyDescriptors()) {
+
+			if (!BEAN_MERGE_FIELD_EXCISIONS.contains(descriptor.getName())
+					&& interfaceNames.contains(toGetName(descriptor.getName()))) {
+
+				String propertyName = descriptor.getName();
+				Object value = sourceBeanWrap.getPropertyValue(propertyName);
+
+				// Copy value to the target object
+				if (value != null) {
+					var targetValue = targetBeanWrap.getPropertyValue(propertyName);
+
+					if (targetValue == null || overrideNonNullTargetValues) {
+						targetBeanWrap.setPropertyValue(propertyName, value);
+					}
+				}
+			}
+		}
+
+		return target;
+	}
+
+	private static String toGetName(String name) {
+		return "get" + name.substring(0, 1).toUpperCase() + name.substring(1);
+	}
+
 }