feat: add support for removing thinking tags from input text in BeanOutputConverter

 - enhance BeanOutputConverter with customizable text cleaning capabilities
 - Update @SInCE to 1.1.0 as suggested by nicolaskrier
 - Add fast-path optimization in ThinkingTagCleaner for non-thinking models
 - Enhance documentation explaining why ThinkingTagCleaner is safe to use by default
 - Clarify performance characteristics in JavaDoc

 - Addresses review comments from nicolaskrier in PR #4667

 - Improve documentation for ThinkingTagCleaner and BeanOutputConverter

Signed-off-by: liugddx <liugddx@gmail.com>

Author: liugddx

spring-ai-model/src/main/java/org/springframework/ai/converter/BeanOutputConverter.java

@@ -60,6 +60,7 @@
  * @author Sebastien Deleuze
  * @author Soby Chacko
  * @author Thomas Vitale
+ * @author liugddx
  */
 public class BeanOutputConverter<T> implements StructuredOutputConverter<T> {
 
@@ -76,12 +77,15 @@ public class BeanOutputConverter<T> implements StructuredOutputConverter<T> {
 	/** Holds the generated JSON schema for the target type. */
 	private String jsonSchema;
 
+	/** The text cleaner used to preprocess LLM responses before parsing. */
+	private final ResponseTextCleaner textCleaner;
+
 	/**
 	 * Constructor to initialize with the target type's class.
 	 * @param clazz The target type's class.
 	 */
 	public BeanOutputConverter(Class<T> clazz) {
-		this(ParameterizedTypeReference.forType(clazz));
+		this(clazz, null, null);
 	}
 
 	/**
@@ -91,15 +95,26 @@ public BeanOutputConverter(Class<T> clazz) {
 	 * @param objectMapper Custom object mapper for JSON operations. endings.
 	 */
 	public BeanOutputConverter(Class<T> clazz, ObjectMapper objectMapper) {
-		this(ParameterizedTypeReference.forType(clazz), objectMapper);
+		this(clazz, objectMapper, null);
+	}
+
+	/**
+	 * Constructor to initialize with the target type's class, a custom object mapper, and
+	 * a custom text cleaner.
+	 * @param clazz The target type's class.
+	 * @param objectMapper Custom object mapper for JSON operations.
+	 * @param textCleaner Custom text cleaner for preprocessing responses.
+	 */
+	public BeanOutputConverter(Class<T> clazz, ObjectMapper objectMapper, ResponseTextCleaner textCleaner) {
+		this(ParameterizedTypeReference.forType(clazz), objectMapper, textCleaner);
 	}
 
 	/**
 	 * Constructor to initialize with the target class type reference.
 	 * @param typeRef The target class type reference.
 	 */
 	public BeanOutputConverter(ParameterizedTypeReference<T> typeRef) {
-		this(typeRef.getType(), null);
+		this(typeRef, null, null);
 	}
 
 	/**
@@ -110,7 +125,19 @@ public BeanOutputConverter(ParameterizedTypeReference<T> typeRef) {
 	 * @param objectMapper Custom object mapper for JSON operations. endings.
 	 */
 	public BeanOutputConverter(ParameterizedTypeReference<T> typeRef, ObjectMapper objectMapper) {
-		this(typeRef.getType(), objectMapper);
+		this(typeRef, objectMapper, null);
+	}
+
+	/**
+	 * Constructor to initialize with the target class type reference, a custom object
+	 * mapper, and a custom text cleaner.
+	 * @param typeRef The target class type reference.
+	 * @param objectMapper Custom object mapper for JSON operations.
+	 * @param textCleaner Custom text cleaner for preprocessing responses.
+	 */
+	public BeanOutputConverter(ParameterizedTypeReference<T> typeRef, ObjectMapper objectMapper,
+			ResponseTextCleaner textCleaner) {
+		this(typeRef.getType(), objectMapper, textCleaner);
 	}
 
 	/**
@@ -119,14 +146,42 @@ public BeanOutputConverter(ParameterizedTypeReference<T> typeRef, ObjectMapper o
 	 * platform.
 	 * @param type The target class type.
 	 * @param objectMapper Custom object mapper for JSON operations. endings.
+	 * @param textCleaner Custom text cleaner for preprocessing responses.
 	 */
-	private BeanOutputConverter(Type type, ObjectMapper objectMapper) {
+	private BeanOutputConverter(Type type, ObjectMapper objectMapper, ResponseTextCleaner textCleaner) {
 		Objects.requireNonNull(type, "Type cannot be null;");
 		this.type = type;
 		this.objectMapper = objectMapper != null ? objectMapper : getObjectMapper();
+		this.textCleaner = textCleaner != null ? textCleaner : createDefaultTextCleaner();
 		generateSchema();
 	}
 
+	/**
+	 * Creates the default text cleaner that handles common response formats from various
+	 * AI models.
+	 * <p>
+	 * The default cleaner includes:
+	 * <ul>
+	 * <li>{@link ThinkingTagCleaner} - Removes thinking tags from models like Amazon Nova
+	 * and Qwen. For models that don't generate thinking tags, this has minimal
+	 * performance impact due to fast-path optimization.</li>
+	 * <li>{@link MarkdownCodeBlockCleaner} - Removes markdown code block formatting.</li>
+	 * <li>{@link WhitespaceCleaner} - Trims whitespace.</li>
+	 * </ul>
+	 * <p>
+	 * To customize the cleaning behavior, provide a custom {@link ResponseTextCleaner}
+	 * via the constructor.
+	 * @return a composite text cleaner with default cleaning strategies
+	 */
+	private static ResponseTextCleaner createDefaultTextCleaner() {
+		return CompositeResponseTextCleaner.builder()
+			.addCleaner(new WhitespaceCleaner())
+			.addCleaner(new ThinkingTagCleaner())
+			.addCleaner(new MarkdownCodeBlockCleaner())
+			.addCleaner(new WhitespaceCleaner()) // Final trim after all cleanups
+			.build();
+	}
+
 	/**
 	 * Generates the JSON schema for the target type.
 	 */
@@ -166,26 +221,9 @@ private void generateSchema() {
 	@Override
 	public T convert(@NonNull String text) {
 		try {
-			// Remove leading and trailing whitespace
-			text = text.trim();
-
-			// Check for and remove triple backticks and "json" identifier
-			if (text.startsWith("```") && text.endsWith("```")) {
-				// Remove the first line if it contains "```json"
-				String[] lines = text.split("\n", 2);
-				if (lines[0].trim().equalsIgnoreCase("```json")) {
-					text = lines.length > 1 ? lines[1] : "";
-				}
-				else {
-					text = text.substring(3); // Remove leading ```
-				}
-
-				// Remove trailing ```
-				text = text.substring(0, text.length() - 3);
-
-				// Trim again to remove any potential whitespace
-				text = text.trim();
-			}
+			// Clean the text using the configured text cleaner
+			text = this.textCleaner.clean(text);
+
 			return (T) this.objectMapper.readValue(text, this.objectMapper.constructType(this.type));
 		}
 		catch (JsonProcessingException e) {

spring-ai-model/src/main/java/org/springframework/ai/converter/CompositeResponseTextCleaner.java

@@ -0,0 +1,108 @@
+/*
+ * Copyright 2023-2024 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.ai.converter;
+
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+
+import org.springframework.util.Assert;
+
+/**
+ * A composite {@link ResponseTextCleaner} that applies multiple cleaners in sequence.
+ * This allows for a flexible pipeline of text cleaning operations.
+ *
+ * @author liugddx
+ * @since 1.1.0
+ */
+public class CompositeResponseTextCleaner implements ResponseTextCleaner {
+
+	private final List<ResponseTextCleaner> cleaners;
+
+	/**
+	 * Creates a composite cleaner with the given cleaners.
+	 * @param cleaners the list of cleaners to apply in order
+	 */
+	public CompositeResponseTextCleaner(List<ResponseTextCleaner> cleaners) {
+		Assert.notNull(cleaners, "cleaners cannot be null");
+		this.cleaners = new ArrayList<>(cleaners);
+	}
+
+	/**
+	 * Creates a composite cleaner with no cleaners. Text will be returned unchanged.
+	 */
+	public CompositeResponseTextCleaner() {
+		this(new ArrayList<>());
+	}
+
+	/**
+	 * Creates a composite cleaner with the given cleaners.
+	 * @param cleaners the cleaners to apply in order
+	 */
+	public CompositeResponseTextCleaner(ResponseTextCleaner... cleaners) {
+		this(Arrays.asList(cleaners));
+	}
+
+	@Override
+	public String clean(String text) {
+		String result = text;
+		for (ResponseTextCleaner cleaner : this.cleaners) {
+			result = cleaner.clean(result);
+		}
+		return result;
+	}
+
+	/**
+	 * Creates a builder for constructing a composite cleaner.
+	 * @return a new builder instance
+	 */
+	public static Builder builder() {
+		return new Builder();
+	}
+
+	/**
+	 * Builder for {@link CompositeResponseTextCleaner}.
+	 */
+	public static final class Builder {
+
+		private final List<ResponseTextCleaner> cleaners = new ArrayList<>();
+
+		private Builder() {
+		}
+
+		/**
+		 * Add a cleaner to the pipeline.
+		 * @param cleaner the cleaner to add
+		 * @return this builder
+		 */
+		public Builder addCleaner(ResponseTextCleaner cleaner) {
+			Assert.notNull(cleaner, "cleaner cannot be null");
+			this.cleaners.add(cleaner);
+			return this;
+		}
+
+		/**
+		 * Build the composite cleaner.
+		 * @return a new composite cleaner instance
+		 */
+		public CompositeResponseTextCleaner build() {
+			return new CompositeResponseTextCleaner(this.cleaners);
+		}
+
+	}
+
+}

spring-ai-model/src/main/java/org/springframework/ai/converter/MarkdownCodeBlockCleaner.java

@@ -0,0 +1,73 @@
+/*
+ * Copyright 2023-2024 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.ai.converter;
+
+/**
+ * A {@link ResponseTextCleaner} that removes markdown code block formatting from LLM
+ * responses. This cleaner handles:
+ * <ul>
+ * <li>{@code ```json ... ```}</li>
+ * <li>{@code ``` ... ```}</li>
+ * </ul>
+ *
+ * @author liugddx
+ * @since 1.1.0
+ */
+public class MarkdownCodeBlockCleaner implements ResponseTextCleaner {
+
+	@Override
+	public String clean(String text) {
+		if (text == null || text.isEmpty()) {
+			return text;
+		}
+
+		// Trim leading and trailing whitespace first
+		text = text.trim();
+
+		// Check for and remove triple backticks
+		if (text.startsWith("```") && text.endsWith("```")) {
+			// Remove the first line if it contains "```json" or similar
+			String[] lines = text.split("\n", 2);
+			if (lines[0].trim().toLowerCase().startsWith("```")) {
+				// Extract language identifier if present
+				String firstLine = lines[0].trim();
+				if (firstLine.length() > 3) {
+					// Has language identifier like ```json
+					text = lines.length > 1 ? lines[1] : "";
+				}
+				else {
+					// Just ``` without language
+					text = text.substring(3);
+				}
+			}
+			else {
+				text = text.substring(3);
+			}
+
+			// Remove trailing ```
+			if (text.endsWith("```")) {
+				text = text.substring(0, text.length() - 3);
+			}
+
+			// Trim again to remove any potential whitespace
+			text = text.trim();
+		}
+
+		return text;
+	}
+
+}

spring-ai-model/src/main/java/org/springframework/ai/converter/ResponseTextCleaner.java

@@ -0,0 +1,37 @@
+/*
+ * Copyright 2023-2024 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.ai.converter;
+
+/**
+ * Strategy interface for cleaning LLM response text before parsing. Different
+ * implementations can handle various response formats and patterns from different AI
+ * models.
+ *
+ * @author liugddx
+ * @since 1.1.0
+ */
+@FunctionalInterface
+public interface ResponseTextCleaner {
+
+	/**
+	 * Clean the given text by removing unwanted patterns, tags, or formatting.
+	 * @param text the raw text from LLM response
+	 * @return the cleaned text ready for parsing
+	 */
+	String clean(String text);
+
+}