docs: enhance Vertex AI Gemini documentation and code organization

- Add javadoc for VertexAiGeminiChatModel including features, examples, and cross-references
- Document JsonSchemaConverter and VertexToolCallingManager classes and methods
- Fix formatter annotation placement in VertexAiGeminiChatOptions

Signed-off-by: Christian Tzolov <[email protected]>

Author: tzolov

models/spring-ai-vertex-ai-gemini/src/main/java/org/springframework/ai/vertexai/gemini/VertexAiGeminiChatModel.java

@@ -93,7 +93,37 @@
 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.
+ *
+ * <p>
+ * Key features include:
+ * <ul>
+ * <li>Support for multiple Gemini model versions including Gemini Pro, Gemini 1.5 Pro,
+ * Gemini 1.5/2.0 Flash variants</li>
+ * <li>Tool/Function calling capabilities through {@link ToolCallingManager}</li>
+ * <li>Streaming support via {@link #stream(Prompt)} method</li>
+ * <li>Configurable safety settings through {@link VertexAiGeminiSafetySetting}</li>
+ * <li>Support for system messages and multi-modal content (text and images)</li>
+ * <li>Built-in retry mechanism and observability through Micrometer</li>
+ * <li>Google Search Retrieval integration</li>
+ * </ul>
+ *
+ * <p>
+ * The model can be configured with various options including temperature, top-k, top-p
+ * sampling, maximum output tokens, and candidate count through
+ * {@link VertexAiGeminiChatOptions}.
+ *
+ * <p>
+ * Use the {@link Builder} to create instances with custom configurations:
+ *
+ * <pre>{@code
+ * VertexAiGeminiChatModel model = VertexAiGeminiChatModel.builder()
+ * 		.vertexAI(vertexAI)
+ * 		.defaultOptions(options)
+ * 		.toolCallingManager(toolManager)
+ * 		.build();
+ * }</pre>
  *
  * @author Christian Tzolov
  * @author Grogdunn
@@ -104,6 +134,9 @@
  * @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 VertexAiGeminiChatModel(VertexAI vertexAI, VertexAiGeminiChatOptions opti
 
 	}
 
+	/**
+	 * 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 VertexAiGeminiChatModel(VertexAI vertexAI, VertexAiGeminiChatOptions defa
 		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;
 		}

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<VertexAiGeminiSafetySetting> 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());

models/spring-ai-vertex-ai-gemini/src/main/java/org/springframework/ai/vertexai/gemini/schema/JsonSchemaConverter.java

@@ -35,6 +35,12 @@ private 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);

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.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.
+ *
+ * <p>
+ * 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<ToolDefinition> resolveToolDefinitions(ToolCallingChatOptions chatOptions) {
 
@@ -58,6 +82,12 @@ public List<ToolDefinition> resolveToolDefinitions(ToolCallingChatOptions chatOp
 		}).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);