Add FinishReasonCategory for provider-agnostic finish reason normalization

spring-ai-model/src/main/java/org/springframework/ai/chat/metadata/ChatGenerationMetadata.java

@@ -42,6 +42,22 @@ public interface ChatGenerationMetadata extends ResultMetadata {
 	 */
 	@Nullable String getFinishReason();
 
+	/**
+	 * Get the normalized category for this finish reason.
+	 *
+	 * <p>
+	 * This method provides a provider-agnostic categorization of the raw finish reason,
+	 * making it easier to build consistent audits, metrics, and alerts across multiple AI
+	 * providers.
+	 * </p>
+	 * @return the categorized finish reason, never null
+	 * @see FinishReasonCategory#categorize(String)
+	 * @since 1.0.0
+	 */
+	default FinishReasonCategory getFinishReasonCategory() {
+		return FinishReasonCategory.categorize(getFinishReason());
+	}
+
 	Set<String> getContentFilters();
 
 	<T> @Nullable T get(String key);

spring-ai-model/src/main/java/org/springframework/ai/chat/metadata/FinishReasonCategory.java

@@ -0,0 +1,121 @@
+/*
+ * Copyright 2023-2026 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.chat.metadata;
+
+import java.util.Locale;
+
+import org.jspecify.annotations.Nullable;
+
+/**
+ * Normalized categories for chat completion finish reasons.
+ *
+ * <p>
+ * This enum provides a provider-agnostic categorization of finish reasons, making it
+ * easier to build consistent audits, metrics, and alerts across multiple AI providers.
+ * </p>
+ *
+ * <p>
+ * Provider-specific finish reason strings vary widely:
+ * </p>
+ * <ul>
+ * <li>OpenAI: {@code STOP}, {@code LENGTH}, {@code TOOL_CALLS},
+ * {@code CONTENT_FILTER}</li>
+ * <li>Anthropic: {@code end_turn}, {@code max_tokens}, {@code tool_use}</li>
+ * <li>Gemini: {@code STOP}, {@code MAX_TOKENS}, {@code SAFETY}, {@code RECITATION}</li>
+ * <li>Azure OpenAI: {@code stop}, {@code length}, {@code tool_calls},
+ * {@code content_filter}</li>
+ * <li>Bedrock: {@code end_turn}, {@code max_tokens}, {@code tool_use}</li>
+ * </ul>
+ *
+ * @author Spring AI Team
+ * @since 1.0.0
+ * @see ChatGenerationMetadata#getFinishReasonCategory()
+ */
+public enum FinishReasonCategory {
+
+	/**
+	 * Normal completion - the model finished generating naturally. Corresponds to:
+	 * {@code stop}, {@code end_turn}, {@code STOP}, {@code stop_sequence}.
+	 */
+	COMPLETED,
+
+	/**
+	 * Output was truncated due to length or token limits. Corresponds to: {@code length},
+	 * {@code max_tokens}, {@code MAX_TOKENS}, {@code context_window_exceeded}.
+	 */
+	TRUNCATED,
+
+	/**
+	 * The model invoked a tool/function. Corresponds to: {@code tool_calls},
+	 * {@code tool_call}, {@code tool_use}, {@code TOOL_CALLS}.
+	 */
+	TOOL_CALL,
+
+	/**
+	 * Content was filtered due to safety or policy constraints. Corresponds to:
+	 * {@code content_filter}, {@code SAFETY}, {@code RECITATION}, {@code refusal},
+	 * {@code PROHIBITED_CONTENT}, {@code SPII}, {@code BLOCKLIST}.
+	 */
+	FILTERED,
+
+	/**
+	 * A known finish reason that doesn't fit other categories.
+	 */
+	OTHER,
+
+	/**
+	 * The finish reason is null, empty, or not recognized.
+	 */
+	UNKNOWN;
+
+	/**
+	 * Categorize a raw finish reason string into a normalized category.
+	 *
+	 * <p>
+	 * This method performs case-insensitive matching against known provider finish reason
+	 * values.
+	 * </p>
+	 * @param rawReason the raw finish reason string from the provider (may be null)
+	 * @return the categorized finish reason, never null
+	 */
+	public static FinishReasonCategory categorize(@Nullable String rawReason) {
+		if (rawReason == null || rawReason.isBlank()) {
+			return UNKNOWN;
+		}
+
+		String normalized = rawReason.toLowerCase(Locale.ROOT).trim();
+
+		return switch (normalized) {
+			// Completed - normal end of generation
+			case "stop", "end_turn", "stop_sequence" -> COMPLETED;
+
+			// Truncated - hit token/length limits
+			case "length", "max_tokens", "context_window_exceeded" -> TRUNCATED;
+
+			// Tool call - model wants to invoke a tool
+			case "tool_calls", "tool_call", "tool_use" -> TOOL_CALL;
+
+			// Filtered - content policy/safety
+			case "content_filter", "safety", "recitation", "prohibited_content", "spii", "blocklist", "refusal" ->
+				FILTERED;
+
+			// Unknown or unrecognized
+			default -> OTHER;
+		};
+	}
+
+}

spring-ai-model/src/test/java/org/springframework/ai/chat/metadata/ChatGenerationMetadataTests.java

@@ -0,0 +1,85 @@
+/*
+ * Copyright 2023-2026 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.chat.metadata;
+
+import org.junit.jupiter.api.Test;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * Tests for {@link ChatGenerationMetadata}.
+ *
+ * @author Spring AI Team
+ */
+class ChatGenerationMetadataTests {
+
+	@Test
+	void shouldBuildMetadataWithFinishReason() {
+		ChatGenerationMetadata metadata = ChatGenerationMetadata.builder().finishReason("stop").build();
+
+		assertThat(metadata.getFinishReason()).isEqualTo("stop");
+		assertThat(metadata.getFinishReasonCategory()).isEqualTo(FinishReasonCategory.COMPLETED);
+	}
+
+	@Test
+	void shouldReturnCorrectCategoryForDifferentReasons() {
+		ChatGenerationMetadata stopMetadata = ChatGenerationMetadata.builder().finishReason("STOP").build();
+		assertThat(stopMetadata.getFinishReasonCategory()).isEqualTo(FinishReasonCategory.COMPLETED);
+
+		ChatGenerationMetadata lengthMetadata = ChatGenerationMetadata.builder().finishReason("length").build();
+		assertThat(lengthMetadata.getFinishReasonCategory()).isEqualTo(FinishReasonCategory.TRUNCATED);
+
+		ChatGenerationMetadata toolMetadata = ChatGenerationMetadata.builder().finishReason("tool_calls").build();
+		assertThat(toolMetadata.getFinishReasonCategory()).isEqualTo(FinishReasonCategory.TOOL_CALL);
+
+		ChatGenerationMetadata filterMetadata = ChatGenerationMetadata.builder().finishReason("content_filter").build();
+		assertThat(filterMetadata.getFinishReasonCategory()).isEqualTo(FinishReasonCategory.FILTERED);
+	}
+
+	@Test
+	void shouldReturnUnknownForNullFinishReason() {
+		ChatGenerationMetadata metadata = ChatGenerationMetadata.builder().build();
+
+		assertThat(metadata.getFinishReason()).isNull();
+		assertThat(metadata.getFinishReasonCategory()).isEqualTo(FinishReasonCategory.UNKNOWN);
+	}
+
+	@Test
+	void nullMetadataShouldReturnUnknownCategory() {
+		assertThat(ChatGenerationMetadata.NULL.getFinishReason()).isNull();
+		assertThat(ChatGenerationMetadata.NULL.getFinishReasonCategory()).isEqualTo(FinishReasonCategory.UNKNOWN);
+	}
+
+	@Test
+	void shouldReturnOtherForUnrecognizedReason() {
+		ChatGenerationMetadata metadata = ChatGenerationMetadata.builder().finishReason("custom_reason").build();
+
+		assertThat(metadata.getFinishReason()).isEqualTo("custom_reason");
+		assertThat(metadata.getFinishReasonCategory()).isEqualTo(FinishReasonCategory.OTHER);
+	}
+
+	@Test
+	void shouldPreserveOriginalFinishReasonString() {
+		ChatGenerationMetadata metadata = ChatGenerationMetadata.builder().finishReason("END_TURN").build();
+
+		// Raw reason preserved with original case
+		assertThat(metadata.getFinishReason()).isEqualTo("END_TURN");
+		// Category normalized correctly
+		assertThat(metadata.getFinishReasonCategory()).isEqualTo(FinishReasonCategory.COMPLETED);
+	}
+
+}

spring-ai-model/src/test/java/org/springframework/ai/chat/metadata/FinishReasonCategoryTests.java

@@ -0,0 +1,109 @@
+/*
+ * Copyright 2023-2026 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.chat.metadata;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.CsvSource;
+import org.junit.jupiter.params.provider.NullAndEmptySource;
+import org.junit.jupiter.params.provider.ValueSource;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+/**
+ * Tests for {@link FinishReasonCategory}.
+ *
+ * @author Spring AI Team
+ */
+class FinishReasonCategoryTests {
+
+	@ParameterizedTest
+	@CsvSource({
+			// OpenAI
+			"STOP, COMPLETED", "stop, COMPLETED",
+			// Anthropic
+			"end_turn, COMPLETED", "END_TURN, COMPLETED",
+			// Stop sequence
+			"stop_sequence, COMPLETED", "STOP_SEQUENCE, COMPLETED" })
+	void shouldCategorizeCompletedReasons(String rawReason, FinishReasonCategory expected) {
+		assertThat(FinishReasonCategory.categorize(rawReason)).isEqualTo(expected);
+	}
+
+	@ParameterizedTest
+	@CsvSource({
+			// OpenAI
+			"LENGTH, TRUNCATED", "length, TRUNCATED",
+			// Anthropic/Gemini/Bedrock
+			"max_tokens, TRUNCATED", "MAX_TOKENS, TRUNCATED",
+			// Context window
+			"context_window_exceeded, TRUNCATED" })
+	void shouldCategorizeTruncatedReasons(String rawReason, FinishReasonCategory expected) {
+		assertThat(FinishReasonCategory.categorize(rawReason)).isEqualTo(expected);
+	}
+
+	@ParameterizedTest
+	@CsvSource({
+			// OpenAI
+			"tool_calls, TOOL_CALL", "TOOL_CALLS, TOOL_CALL",
+			// Mistral compatibility
+			"tool_call, TOOL_CALL", "TOOL_CALL, TOOL_CALL",
+			// Anthropic/Bedrock
+			"tool_use, TOOL_CALL", "TOOL_USE, TOOL_CALL" })
+	void shouldCategorizeToolCallReasons(String rawReason, FinishReasonCategory expected) {
+		assertThat(FinishReasonCategory.categorize(rawReason)).isEqualTo(expected);
+	}
+
+	@ParameterizedTest
+	@CsvSource({
+			// OpenAI/Azure
+			"content_filter, FILTERED", "CONTENT_FILTER, FILTERED",
+			// Gemini
+			"safety, FILTERED", "SAFETY, FILTERED", "recitation, FILTERED", "RECITATION, FILTERED",
+			// Other safety-related
+			"prohibited_content, FILTERED", "spii, FILTERED", "blocklist, FILTERED", "refusal, FILTERED" })
+	void shouldCategorizeFilteredReasons(String rawReason, FinishReasonCategory expected) {
+		assertThat(FinishReasonCategory.categorize(rawReason)).isEqualTo(expected);
+	}
+
+	@ParameterizedTest
+	@NullAndEmptySource
+	@ValueSource(strings = { "   ", "\t", "\n" })
+	void shouldCategorizeNullOrBlankAsUnknown(String rawReason) {
+		assertThat(FinishReasonCategory.categorize(rawReason)).isEqualTo(FinishReasonCategory.UNKNOWN);
+	}
+
+	@ParameterizedTest
+	@ValueSource(strings = { "unknown_reason", "custom_stop", "model_specific", "foo_bar" })
+	void shouldCategorizeUnrecognizedAsOther(String rawReason) {
+		assertThat(FinishReasonCategory.categorize(rawReason)).isEqualTo(FinishReasonCategory.OTHER);
+	}
+
+	@Test
+	void shouldHandleMixedCaseAndWhitespace() {
+		assertThat(FinishReasonCategory.categorize("  STOP  ")).isEqualTo(FinishReasonCategory.COMPLETED);
+		assertThat(FinishReasonCategory.categorize("  End_Turn  ")).isEqualTo(FinishReasonCategory.COMPLETED);
+		assertThat(FinishReasonCategory.categorize("MAX_TOKENS")).isEqualTo(FinishReasonCategory.TRUNCATED);
+	}
+
+	@Test
+	void shouldReturnNonNullForAllEnumValues() {
+		for (FinishReasonCategory category : FinishReasonCategory.values()) {
+			assertThat(category).isNotNull();
+		}
+	}
+
+}