Enhance vector stores with consistent APIs and null safety

- Replace Document.getContent() with getText() across all vector store implementations
- Fix incorrect package declarations in package-info.java files
- Make builder constructors private and implement proper builder patterns
- Add @nullable annotations for better null safety
- Simplify PineconeVectorStore builder API by requiring essential parameters in factory method
- Make static Map fields final
- Clean up code and improve JavaDoc documentation

The changes focus on making the vector store APIs more consistent,
type-safe, and maintainable while following best practices for
builder patterns and null safety.

Author: sobychacko

spring-ai-spring-boot-autoconfigure/src/main/java/org/springframework/ai/autoconfigure/vectorstore/pinecone/PineconeVectorStoreAutoConfiguration.java

@@ -55,11 +55,9 @@ public PineconeVectorStore vectorStore(EmbeddingModel embeddingModel, PineconeVe
 			ObjectProvider<VectorStoreObservationConvention> customObservationConvention,
 			BatchingStrategy batchingStrategy) {
 
-		return PineconeVectorStore.builder(embeddingModel)
-			.apiKey(properties.getApiKey())
-			.environment(properties.getEnvironment())
-			.projectId(properties.getProjectId())
-			.indexName(properties.getIndexName())
+		return PineconeVectorStore
+			.builder(embeddingModel, properties.getApiKey(), properties.getProjectId(), properties.getEnvironment(),
+					properties.getIndexName())
 			.namespace(properties.getNamespace())
 			.contentFieldName(properties.getContentFieldName())
 			.distanceMetadataFieldName(properties.getDistanceMetadataFieldName())

vector-stores/spring-ai-azure-cosmos-db-store/src/main/java/org/springframework/ai/vectorstore/cosmosdb/CosmosDBVectorStore.java

@@ -69,6 +69,7 @@
 import org.springframework.ai.vectorstore.observation.AbstractObservationVectorStore;
 import org.springframework.ai.vectorstore.observation.VectorStoreObservationContext;
 import org.springframework.ai.vectorstore.observation.VectorStoreObservationConvention;
+import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
 
 /**
@@ -108,7 +109,8 @@ public class CosmosDBVectorStore extends AbstractObservationVectorStore implemen
 	 * @param cosmosClient the Cosmos DB client
 	 * @param properties the configuration properties
 	 * @param embeddingModel the embedding model
-	 * @deprecated Since 1.0.0-M5, use {@link #builder()} instead
+	 * @deprecated Since 1.0.0-M5, use {@link #builder(CosmosAsyncClient, EmbeddingModel)}
+	 * ()} instead
 	 */
 	@Deprecated(since = "1.0.0-M5", forRemoval = true)
 	public CosmosDBVectorStore(ObservationRegistry observationRegistry,
@@ -126,7 +128,8 @@ public CosmosDBVectorStore(ObservationRegistry observationRegistry,
 	 * @param properties the configuration properties
 	 * @param embeddingModel the embedding model
 	 * @param batchingStrategy the batching strategy
-	 * @deprecated Since 1.0.0-M5, use {@link #builder()} instead
+	 * @deprecated Since 1.0.0-M5, use {@link #builder(CosmosAsyncClient, EmbeddingModel)}
+	 * ()} instead
 	 */
 	@Deprecated(since = "1.0.0-M5", forRemoval = true)
 	public CosmosDBVectorStore(ObservationRegistry observationRegistry,
@@ -241,7 +244,7 @@ private JsonNode mapCosmosDocument(Document document, float[] queryEmbedding) {
 		ObjectMapper objectMapper = new ObjectMapper();
 
 		String id = document.getId();
-		String content = document.getContent();
+		String content = document.getText();
 
 		// Convert metadata and embedding directly to JsonNode
 		JsonNode metadataNode = objectMapper.valueToTree(document.getMetadata());
@@ -430,10 +433,13 @@ public static class CosmosDBBuilder extends AbstractVectorStoreBuilder<CosmosDBB
 
 		private final CosmosAsyncClient cosmosClient;
 
+		@Nullable
 		private String containerName;
 
+		@Nullable
 		private String databaseName;
 
+		@Nullable
 		private String partitionKeyPath;
 
 		private int vectorStoreThroughput = 400;
@@ -444,13 +450,7 @@ public static class CosmosDBBuilder extends AbstractVectorStoreBuilder<CosmosDBB
 
 		private BatchingStrategy batchingStrategy = new TokenCountBatchingStrategy();
 
-		/**
-		 * Sets the Cosmos DB client.
-		 * @param cosmosClient the client to use
-		 * @return the builder instance
-		 * @throws IllegalArgumentException if cosmosClient is null
-		 */
-		public CosmosDBBuilder(CosmosAsyncClient cosmosClient, EmbeddingModel embeddingModel) {
+		private CosmosDBBuilder(CosmosAsyncClient cosmosClient, EmbeddingModel embeddingModel) {
 			super(embeddingModel);
 			Assert.notNull(cosmosClient, "CosmosClient must not be null");
 			this.cosmosClient = cosmosClient;

vector-stores/spring-ai-azure-cosmos-db-store/src/main/java/org/springframework/ai/vectorstore/cosmosdb/package-info.java

@@ -0,0 +1,25 @@
+/*
+ * 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.
+ */
+
+/**
+ * Provides the API for embedding observations.
+ */
+@NonNullApi
+@NonNullFields
+package org.springframework.ai.vectorstore.cosmosdb;
+
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

vector-stores/spring-ai-azure-store/src/main/java/org/springframework/ai/vectorstore/azure/AzureVectorStore.java

@@ -62,6 +62,7 @@
 import org.springframework.ai.vectorstore.observation.VectorStoreObservationContext;
 import org.springframework.ai.vectorstore.observation.VectorStoreObservationConvention;
 import org.springframework.beans.factory.InitializingBean;
+import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
 import org.springframework.util.CollectionUtils;
 import org.springframework.util.StringUtils;
@@ -122,6 +123,7 @@ public class AzureVectorStore extends AbstractObservationVectorStore implements
 	 */
 	private final List<MetadataField> filterMetadataFields;
 
+	@Nullable
 	private SearchClient searchClient;
 
 	private int defaultTopK;
@@ -135,7 +137,8 @@ public class AzureVectorStore extends AbstractObservationVectorStore implements
 	 * @param searchIndexClient the Azure search index client
 	 * @param embeddingModel the embedding model to use
 	 * @param initializeSchema whether to initialize schema
-	 * @deprecated Since 1.0.0-M5, use {@link #builder()} instead
+	 * @deprecated Since 1.0.0-M5, use {@link #builder(SearchIndexClient, EmbeddingModel)}
+	 * ()} instead
 	 */
 	@Deprecated(since = "1.0.0-M5", forRemoval = true)
 	public AzureVectorStore(SearchIndexClient searchIndexClient, EmbeddingModel embeddingModel,
@@ -149,7 +152,8 @@ public AzureVectorStore(SearchIndexClient searchIndexClient, EmbeddingModel embe
 	 * @param embeddingModel the embedding model to use
 	 * @param initializeSchema whether to initialize schema
 	 * @param filterMetadataFields list of metadata fields for filtering
-	 * @deprecated Since 1.0.0-M5, use {@link #builder()} instead
+	 * @deprecated Since 1.0.0-M5, use {@link #builder(SearchIndexClient, EmbeddingModel)}
+	 * ()} instead
 	 */
 	@Deprecated(since = "1.0.0-M5", forRemoval = true)
 	public AzureVectorStore(SearchIndexClient searchIndexClient, EmbeddingModel embeddingModel,
@@ -166,7 +170,8 @@ public AzureVectorStore(SearchIndexClient searchIndexClient, EmbeddingModel embe
 	 * @param filterMetadataFields list of metadata fields for filtering
 	 * @param observationRegistry the observation registry
 	 * @param customObservationConvention the custom observation convention
-	 * @deprecated Since 1.0.0-M5, use {@link #builder()} instead
+	 * @deprecated Since 1.0.0-M5, use {@link #builder(SearchIndexClient, EmbeddingModel)}
+	 * ()} instead
 	 */
 	@Deprecated(since = "1.0.0-M5", forRemoval = true)
 	public AzureVectorStore(SearchIndexClient searchIndexClient, EmbeddingModel embeddingModel,
@@ -208,8 +213,8 @@ public static AzureBuilder builder(SearchIndexClient searchIndexClient, Embeddin
 	/**
 	 * Change the Index Name.
 	 * @param indexName The Azure VectorStore index name to use.
-	 * @deprecated Since 1.0.0-M5, use {@link #builder()} with
-	 * {@link AzureBuilder#indexName(String)} instead
+	 * @deprecated Since 1.0.0-M5, use {@link #builder(SearchIndexClient, EmbeddingModel)}
+	 * ()} with {@link AzureBuilder#indexName(String)} instead
 	 */
 	@Deprecated(since = "1.0.0-M5", forRemoval = true)
 	public void setIndexName(String indexName) {
@@ -220,8 +225,8 @@ public void setIndexName(String indexName) {
 	/**
 	 * Sets the a default maximum number of similar documents returned.
 	 * @param topK The default maximum number of similar documents returned.
-	 * @deprecated Since 1.0.0-M5, use {@link #builder()} with
-	 * {@link AzureBuilder#indexName(String)} instead
+	 * @deprecated Since 1.0.0-M5, use {@link #builder(SearchIndexClient, EmbeddingModel)}
+	 * ()} with {@link AzureBuilder#indexName(String)} instead
 	 */
 	@Deprecated(since = "1.0.0-M5", forRemoval = true)
 	public void setDefaultTopK(int topK) {
@@ -233,8 +238,8 @@ public void setDefaultTopK(int topK) {
 	 * Sets the a default similarity threshold for returned documents.
 	 * @param similarityThreshold The a default similarity threshold for returned
 	 * documents.
-	 * @deprecated Since 1.0.0-M5, use {@link #builder()} with
-	 * {@link AzureBuilder#indexName(String)} instead
+	 * @deprecated Since 1.0.0-M5, use {@link #builder(SearchIndexClient, EmbeddingModel)}
+	 * ()} with {@link AzureBuilder#indexName(String)} instead
 	 */
 	@Deprecated(since = "1.0.0-M5", forRemoval = true)
 	public void setDefaultSimilarityThreshold(Double similarityThreshold) {
@@ -258,7 +263,7 @@ public void doAdd(List<Document> documents) {
 			SearchDocument searchDocument = new SearchDocument();
 			searchDocument.put(ID_FIELD_NAME, document.getId());
 			searchDocument.put(EMBEDDING_FIELD_NAME, embeddings.get(documents.indexOf(document)));
-			searchDocument.put(CONTENT_FIELD_NAME, document.getContent());
+			searchDocument.put(CONTENT_FIELD_NAME, document.getText());
 			searchDocument.put(METADATA_FIELD_NAME, new JSONObject(document.getMetadata()).toJSONString());
 
 			// Add the filterable metadata fields as top level fields, allowing filler
@@ -481,13 +486,7 @@ public static class AzureBuilder extends AbstractVectorStoreBuilder<AzureBuilder
 
 		private String indexName = DEFAULT_INDEX_NAME;
 
-		/**
-		 * Sets the Azure search index client.
-		 * @param searchIndexClient the client to use
-		 * @return the builder instance
-		 * @throws IllegalArgumentException if searchIndexClient is null
-		 */
-		public AzureBuilder(SearchIndexClient searchIndexClient, EmbeddingModel embeddingModel) {
+		private AzureBuilder(SearchIndexClient searchIndexClient, EmbeddingModel embeddingModel) {
 			super(embeddingModel);
 			Assert.notNull(searchIndexClient, "SearchIndexClient must not be null");
 			this.searchIndexClient = searchIndexClient;

vector-stores/spring-ai-azure-store/src/main/java/org/springframework/ai/vectorstore/azure/package-info.java

@@ -0,0 +1,25 @@
+/*
+ * 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.
+ */
+
+/**
+ * Provides the API for embedding observations.
+ */
+@NonNullApi
+@NonNullFields
+package org.springframework.ai.vectorstore.azure;
+
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

vector-stores/spring-ai-cassandra-store/src/main/java/org/springframework/ai/vectorstore/cassandra/CassandraVectorStore.java

@@ -235,15 +235,15 @@ public class CassandraVectorStore extends AbstractObservationVectorStore impleme
 	private final boolean returnEmbeddings;
 
 	/**
-	 * @deprecated since 1.0.0-M5, use {@link #builder()} instead
+	 * @deprecated since 1.0.0-M5, use {@link #builder(EmbeddingModel)} ()} instead
 	 */
 	@Deprecated(since = "1.0.0-M5", forRemoval = true)
 	public CassandraVectorStore(CassandraVectorStoreConfig conf, EmbeddingModel embeddingModel) {
 		this(conf, embeddingModel, ObservationRegistry.NOOP, null, new TokenCountBatchingStrategy());
 	}
 
 	/**
-	 * @deprecated since 1.0.0-M5, use {@link #builder()} instead
+	 * @deprecated since 1.0.0-M5, use {@link #builder(EmbeddingModel)} ()} instead
 	 */
 	@Deprecated(since = "1.0.0-M5", forRemoval = true)
 	public CassandraVectorStore(CassandraVectorStoreConfig conf, EmbeddingModel embeddingModel,
@@ -319,7 +319,7 @@ public void doAdd(List<Document> documents) {
 					builder = builder.set(keyColumn.name(), primaryKeyValues.get(k), keyColumn.javaType());
 				}
 
-				builder = builder.setString(this.schema.content(), d.getContent())
+				builder = builder.setString(this.schema.content(), d.getText())
 					.setVector(this.schema.embedding(),
 							CqlVector.newInstance(EmbeddingUtils.toList(embeddings.get(documents.indexOf(d)))),
 							Float.class);

vector-stores/spring-ai-cassandra-store/src/main/java/org/springframework/ai/vectorstore/cassandra/package-info.java

@@ -0,0 +1,25 @@
+/*
+ * 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.
+ */
+
+/**
+ * Provides the API for embedding observations.
+ */
+@NonNullApi
+@NonNullFields
+package org.springframework.ai.vectorstore.cassandra;
+
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

vector-stores/spring-ai-coherence-store/src/main/java/org/springframework/ai/vectorstore/coherence/CoherenceVectorStore.java

@@ -143,7 +143,8 @@ public enum DistanceType {
 	 * Creates a new CoherenceVectorStore with minimal configuration.
 	 * @param embeddingModel the embedding model to use
 	 * @param session the Coherence session
-	 * @deprecated Since 1.0.0-M5, use {@link #builder()} instead
+	 * @deprecated Since 1.0.0-M5, use {@link #builder(Session, EmbeddingModel)} ()}
+	 * instead
 	 */
 	@Deprecated(since = "1.0.0-M5", forRemoval = true)
 	public CoherenceVectorStore(EmbeddingModel embeddingModel, Session session) {
@@ -177,7 +178,8 @@ public static CoherenceBuilder builder(Session session, EmbeddingModel embedding
 	}
 
 	/**
-	 * @deprecated Since 1.0.0-M5, use {@link #builder()} instead
+	 * @deprecated Since 1.0.0-M5, use {@link #builder(Session, EmbeddingModel)} ()}
+	 * instead
 	 */
 	@Deprecated(since = "1.0.0-M5", forRemoval = true)
 	public CoherenceVectorStore setMapName(String mapName) {
@@ -186,7 +188,8 @@ public CoherenceVectorStore setMapName(String mapName) {
 	}
 
 	/**
-	 * @deprecated Since 1.0.0-M5, use {@link #builder()} instead
+	 * @deprecated Since 1.0.0-M5, use {@link #builder(Session, EmbeddingModel)} ()}
+	 * instead
 	 */
 	@Deprecated(since = "1.0.0-M5", forRemoval = true)
 	public CoherenceVectorStore setDistanceType(DistanceType distanceType) {
@@ -195,7 +198,8 @@ public CoherenceVectorStore setDistanceType(DistanceType distanceType) {
 	}
 
 	/**
-	 * @deprecated Since 1.0.0-M5, use {@link #builder()} instead
+	 * @deprecated Since 1.0.0-M5, use {@link #builder(Session, EmbeddingModel)} ()}
+	 * instead
 	 */
 	@Deprecated(since = "1.0.0-M5", forRemoval = true)
 	public CoherenceVectorStore setIndexType(IndexType indexType) {
@@ -204,7 +208,8 @@ public CoherenceVectorStore setIndexType(IndexType indexType) {
 	}
 
 	/**
-	 * @deprecated Since 1.0.0-M5, use {@link #builder()} instead
+	 * @deprecated Since 1.0.0-M5, use {@link #builder(Session, EmbeddingModel)} ()}
+	 * instead
 	 */
 	@Deprecated(since = "1.0.0-M5", forRemoval = true)
 	public CoherenceVectorStore setForcedNormalization(boolean forcedNormalization) {
@@ -217,7 +222,7 @@ public void doAdd(final List<Document> documents) {
 		Map<DocumentChunk.Id, DocumentChunk> chunks = new HashMap<>((int) Math.ceil(documents.size() / 0.75f));
 		for (Document doc : documents) {
 			var id = toChunkId(doc.getId());
-			var chunk = new DocumentChunk(doc.getContent(), doc.getMetadata(),
+			var chunk = new DocumentChunk(doc.getText(), doc.getMetadata(),
 					toFloat32Vector(this.embeddingModel.embed(doc)));
 			chunks.put(id, chunk);
 		}
@@ -342,13 +347,7 @@ public static class CoherenceBuilder extends AbstractVectorStoreBuilder<Coherenc
 
 		private IndexType indexType = IndexType.NONE;
 
-		/**
-		 * Sets the Coherence session.
-		 * @param session the session to use
-		 * @return the builder instance
-		 * @throws IllegalArgumentException if session is null
-		 */
-		public CoherenceBuilder(Session session, EmbeddingModel embeddingModel) {
+		private CoherenceBuilder(Session session, EmbeddingModel embeddingModel) {
 			super(embeddingModel);
 			Assert.notNull(session, "Session must not be null");
 			this.session = session;

vector-stores/spring-ai-coherence-store/src/main/java/org/springframework/ai/vectorstore/coherence/package-info.java

@@ -0,0 +1,25 @@
+/*
+ * 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.
+ */
+
+/**
+ * Provides the API for embedding observations.
+ */
+@NonNullApi
+@NonNullFields
+package org.springframework.ai.vectorstore.coherence;
+
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;