diff --git a/models/spring-ai-vertex-ai-gemini/src/main/java/org/springframework/ai/vertexai/gemini/VertexAiGeminiChatModel.java b/models/spring-ai-vertex-ai-gemini/src/main/java/org/springframework/ai/vertexai/gemini/VertexAiGeminiChatModel.java index 402e5f2d5..2378d7bc9 100644 --- a/models/spring-ai-vertex-ai-gemini/src/main/java/org/springframework/ai/vertexai/gemini/VertexAiGeminiChatModel.java +++ b/models/spring-ai-vertex-ai-gemini/src/main/java/org/springframework/ai/vertexai/gemini/VertexAiGeminiChatModel.java @@ -93,7 +93,37 @@ import org.springframework.util.CollectionUtils; import org.springframework.util.StringUtils; /** - * Vertex AI Gemini Chat Model implementation. + * Vertex AI Gemini Chat Model implementation that provides access to Google's Gemini + * language models. + * + *

+ * Key features include: + *

+ * + *

+ * The model can be configured with various options including temperature, top-k, top-p + * sampling, maximum output tokens, and candidate count through + * {@link VertexAiGeminiChatOptions}. + * + *

+ * Use the {@link Builder} to create instances with custom configurations: + * + * 

{@code
+ * VertexAiGeminiChatModel model = VertexAiGeminiChatModel.builder()
+ * 		.vertexAI(vertexAI)
+ * 		.defaultOptions(options)
+ * 		.toolCallingManager(toolManager)
+ * 		.build();
+ * }
* * @author Christian Tzolov * @author Grogdunn @@ -104,6 +134,9 @@ import org.springframework.util.StringUtils; * @author Jihoon Kim * @author Alexandros Pappas * @since 0.8.1 + * @see VertexAiGeminiChatOptions + * @see ToolCallingManager + * @see ChatModel */ public class VertexAiGeminiChatModel extends AbstractToolCallSupport implements ChatModel, DisposableBean { @@ -203,6 +236,16 @@ public class VertexAiGeminiChatModel extends AbstractToolCallSupport implements } + /** + * Creates a new instance of VertexAiGeminiChatModel. + * @param vertexAI the Vertex AI instance to use + * @param defaultOptions the default options to use + * @param toolCallingManager the tool calling manager to use. It is wrapped in a + * {@link VertexToolCallingManager} to ensure compatibility with Vertex AI's OpenAPI + * schema format. + * @param retryTemplate the retry template to use + * @param observationRegistry the observation registry to use + */ public VertexAiGeminiChatModel(VertexAI vertexAI, VertexAiGeminiChatOptions defaultOptions, ToolCallingManager toolCallingManager, RetryTemplate retryTemplate, ObservationRegistry observationRegistry) { @@ -221,6 +264,8 @@ public class VertexAiGeminiChatModel extends AbstractToolCallSupport implements this.retryTemplate = retryTemplate; this.observationRegistry = observationRegistry; + // Wrap the provided tool calling manager in a VertexToolCallingManager to ensure + // compatibility with Vertex AI's OpenAPI schema format. if (toolCallingManager instanceof VertexToolCallingManager) { this.toolCallingManager = toolCallingManager; } diff --git a/models/spring-ai-vertex-ai-gemini/src/main/java/org/springframework/ai/vertexai/gemini/VertexAiGeminiChatOptions.java b/models/spring-ai-vertex-ai-gemini/src/main/java/org/springframework/ai/vertexai/gemini/VertexAiGeminiChatOptions.java index 9a39d9195..db75de5c7 100644 --- a/models/spring-ai-vertex-ai-gemini/src/main/java/org/springframework/ai/vertexai/gemini/VertexAiGeminiChatOptions.java +++ b/models/spring-ai-vertex-ai-gemini/src/main/java/org/springframework/ai/vertexai/gemini/VertexAiGeminiChatOptions.java @@ -126,13 +126,12 @@ public class VertexAiGeminiChatOptions implements ToolCallingChatOptions { @JsonIgnore private List safetySettings = new ArrayList<>(); + // @formatter:on public static Builder builder() { return new Builder(); } - // @formatter:on - public static VertexAiGeminiChatOptions fromOptions(VertexAiGeminiChatOptions fromOptions) { VertexAiGeminiChatOptions options = new VertexAiGeminiChatOptions(); options.setStopSequences(fromOptions.getStopSequences()); diff --git a/models/spring-ai-vertex-ai-gemini/src/main/java/org/springframework/ai/vertexai/gemini/schema/JsonSchemaConverter.java b/models/spring-ai-vertex-ai-gemini/src/main/java/org/springframework/ai/vertexai/gemini/schema/JsonSchemaConverter.java index dddddf7a1..fbdbc9904 100644 --- a/models/spring-ai-vertex-ai-gemini/src/main/java/org/springframework/ai/vertexai/gemini/schema/JsonSchemaConverter.java +++ b/models/spring-ai-vertex-ai-gemini/src/main/java/org/springframework/ai/vertexai/gemini/schema/JsonSchemaConverter.java @@ -35,6 +35,12 @@ public final class JsonSchemaConverter { // Prevent instantiation } + /** + * Parses a JSON string into an ObjectNode. + * @param jsonString The JSON string to parse + * @return ObjectNode containing the parsed JSON + * @throws RuntimeException if the JSON string cannot be parsed + */ public static ObjectNode fromJson(String jsonString) { try { return (ObjectNode) JsonParser.getObjectMapper().readTree(jsonString); diff --git a/models/spring-ai-vertex-ai-gemini/src/main/java/org/springframework/ai/vertexai/gemini/schema/VertexToolCallingManager.java b/models/spring-ai-vertex-ai-gemini/src/main/java/org/springframework/ai/vertexai/gemini/schema/VertexToolCallingManager.java index 451fa6860..0f7e7185e 100644 --- a/models/spring-ai-vertex-ai-gemini/src/main/java/org/springframework/ai/vertexai/gemini/schema/VertexToolCallingManager.java +++ b/models/spring-ai-vertex-ai-gemini/src/main/java/org/springframework/ai/vertexai/gemini/schema/VertexToolCallingManager.java @@ -26,20 +26,44 @@ import org.springframework.ai.model.tool.ToolCallingManager; import org.springframework.ai.model.tool.ToolExecutionResult; import org.springframework.ai.tool.definition.ToolDefinition; import org.springframework.ai.util.json.schema.JsonSchemaGenerator; +import org.springframework.util.Assert; /** + * Implementation of {@link ToolCallingManager} specifically designed for Vertex AI + * Gemini. This manager adapts tool definitions to be compatible with Vertex AI's OpenAPI + * schema format by converting JSON schemas and ensuring proper type value upper-casing. + * + *

+ * It delegates the actual tool execution to another {@link ToolCallingManager} while + * handling the necessary schema conversions for Vertex AI compatibility. + * * @author Christian Tzolov * @since 1.0.0 */ - public class VertexToolCallingManager implements ToolCallingManager { + /** + * The underlying tool calling manager that handles actual tool execution. + */ private final ToolCallingManager delegateToolCallingManager; + /** + * Creates a new instance of VertexToolCallingManager. + * @param delegateToolCallingManager the underlying tool calling manager that handles + * actual tool execution + */ public VertexToolCallingManager(ToolCallingManager delegateToolCallingManager) { + Assert.notNull(delegateToolCallingManager, "Delegate tool calling manager must not be null"); this.delegateToolCallingManager = delegateToolCallingManager; } + /** + * Resolves tool definitions and converts their input schemas to be compatible with + * Vertex AI's OpenAPI format. This includes converting JSON schemas to OpenAPI format + * and ensuring proper type value casing. + * @param chatOptions the options containing tool preferences and configurations + * @return a list of tool definitions with Vertex AI compatible schemas + */ @Override public List resolveToolDefinitions(ToolCallingChatOptions chatOptions) { @@ -58,6 +82,12 @@ public class VertexToolCallingManager implements ToolCallingManager { }).toList(); } + /** + * Executes tool calls by delegating to the underlying tool calling manager. + * @param prompt the original prompt that triggered the tool calls + * @param chatResponse the chat response containing the tool calls to execute + * @return the result of executing the tool calls + */ @Override public ToolExecutionResult executeToolCalls(Prompt prompt, ChatResponse chatResponse) { return this.delegateToolCallingManager.executeToolCalls(prompt, chatResponse);