Require essential dependencies in vector store builder constructors

This commit refactors the builder pattern implementation across all VectorStore
implementations to make the EmbeddingModel a required constructor parameter
rather than an optional builder method. Key changes include:

- Move embeddingModel from being a builder method to a required constructor parameter
- Make embeddingModel final in AbstractVectorStoreBuilder
- Remove redundant validate() methods since EmbeddingModel validation now happens
  in constructor
- Update all VectorStore builder instantiations to pass EmbeddingModel in builder
  creation
- Add @nullable annotations to appropriate methods in VectorStore interface

This change improves the API design by:
1. Enforcing that EmbeddingModel is provided at builder creation time
2. Removing the possibility of forgotten EmbeddingModel configuration
3. Simplifying the builder implementation by moving validation to construction
4. Making the dependency on EmbeddingModel more explicit in the API

Breaking Changes:
- VectorStore builders must now be created with an EmbeddingModel parameter
- The embeddingModel() builder method has been removed from all implementations

Author: sobychacko

spring-ai-core/src/main/java/org/springframework/ai/embedding/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.embedding;
+
+import org.springframework.lang.NonNullApi;
+import org.springframework.lang.NonNullFields;

spring-ai-core/src/main/java/org/springframework/ai/vectorstore/AbstractVectorStoreBuilder.java

@@ -33,13 +33,18 @@
 public abstract class AbstractVectorStoreBuilder<T extends AbstractVectorStoreBuilder<T>>
 		implements VectorStore.Builder<T> {
 
-	protected EmbeddingModel embeddingModel;
+	protected final EmbeddingModel embeddingModel;
 
 	protected ObservationRegistry observationRegistry = ObservationRegistry.NOOP;
 
 	@Nullable
 	protected VectorStoreObservationConvention customObservationConvention;
 
+	public AbstractVectorStoreBuilder(EmbeddingModel embeddingModel) {
+		Assert.notNull(embeddingModel, "EmbeddingModel must be configured");
+		this.embeddingModel = embeddingModel;
+	}
+
 	public EmbeddingModel getEmbeddingModel() {
 		return this.embeddingModel;
 	}
@@ -71,20 +76,9 @@ public T observationRegistry(ObservationRegistry observationRegistry) {
 	}
 
 	@Override
-	public T customObservationConvention(VectorStoreObservationConvention convention) {
+	public T customObservationConvention(@Nullable VectorStoreObservationConvention convention) {
 		this.customObservationConvention = convention;
 		return self();
 	}
 
-	@Override
-	public T embeddingModel(EmbeddingModel embeddingModel) {
-		Assert.notNull(embeddingModel, "EmbeddingModel must not be null");
-		this.embeddingModel = embeddingModel;
-		return self();
-	}
-
-	protected void validate() {
-		Assert.notNull(this.embeddingModel, "EmbeddingModel must be configured");
-	}
-
 }

spring-ai-core/src/main/java/org/springframework/ai/vectorstore/SimpleVectorStore.java

@@ -92,8 +92,7 @@ public SimpleVectorStore(EmbeddingModel embeddingModel) {
 	@Deprecated(forRemoval = true, since = "1.0.0-M5")
 	public SimpleVectorStore(EmbeddingModel embeddingModel, ObservationRegistry observationRegistry,
 			VectorStoreObservationConvention customObservationConvention) {
-		this(builder().embeddingModel(embeddingModel)
-			.observationRegistry(observationRegistry)
+		this(builder(embeddingModel).observationRegistry(observationRegistry)
 			.customObservationConvention(customObservationConvention));
 	}
 
@@ -106,8 +105,8 @@ protected SimpleVectorStore(SimpleVectorStoreBuilder builder) {
 	 * Creates an instance of SimpleVectorStore builder.
 	 * @return the SimpleVectorStore builder.
 	 */
-	public static SimpleVectorStoreBuilder builder() {
-		return new SimpleVectorStoreBuilder();
+	public static SimpleVectorStoreBuilder builder(EmbeddingModel embeddingModel) {
+		return new SimpleVectorStoreBuilder(embeddingModel);
 	}
 
 	@Override
@@ -297,9 +296,12 @@ public static float norm(float[] vector) {
 
 	public static final class SimpleVectorStoreBuilder extends AbstractVectorStoreBuilder<SimpleVectorStoreBuilder> {
 
+		private SimpleVectorStoreBuilder(EmbeddingModel embeddingModel) {
+			super(embeddingModel);
+		}
+
 		@Override
 		public SimpleVectorStore build() {
-			validate();
 			return new SimpleVectorStore(this);
 		}
 

spring-ai-core/src/main/java/org/springframework/ai/vectorstore/VectorStore.java

@@ -23,7 +23,6 @@
 
 import org.springframework.ai.document.Document;
 import org.springframework.ai.document.DocumentWriter;
-import org.springframework.ai.embedding.EmbeddingModel;
 import org.springframework.ai.vectorstore.observation.DefaultVectorStoreObservationConvention;
 import org.springframework.ai.vectorstore.observation.VectorStoreObservationConvention;
 import org.springframework.lang.Nullable;
@@ -59,6 +58,7 @@ default void accept(List<Document> documents) {
 	 * @param idList list of document ids for which documents will be removed.
 	 * @return Returns true if the documents were successfully deleted.
 	 */
+	@Nullable
 	Optional<Boolean> delete(List<String> idList);
 
 	/**
@@ -68,6 +68,7 @@ default void accept(List<Document> documents) {
 	 * topK, similarity threshold and metadata filter expressions.
 	 * @return Returns documents th match the query request conditions.
 	 */
+	@Nullable
 	List<Document> similaritySearch(SearchRequest request);
 
 	/**
@@ -77,6 +78,7 @@ default void accept(List<Document> documents) {
 	 * @return Returns a list of documents that have embeddings similar to the query text
 	 * embedding.
 	 */
+	@Nullable
 	default List<Document> similaritySearch(String query) {
 		return this.similaritySearch(SearchRequest.query(query));
 	}
@@ -90,8 +92,6 @@ default List<Document> similaritySearch(String query) {
 	 */
 	interface Builder<T extends Builder<T>> {
 
-		T embeddingModel(EmbeddingModel embeddingModel);
-
 		/**
 		 * Sets the registry for collecting observations and metrics. Defaults to
 		 * {@link ObservationRegistry#NOOP} if not specified.

spring-ai-core/src/main/java/org/springframework/ai/vectorstore/observation/AbstractObservationVectorStore.java

@@ -45,7 +45,6 @@ public abstract class AbstractObservationVectorStore implements VectorStore {
 	@Nullable
 	private final VectorStoreObservationConvention customObservationConvention;
 
-	@Nullable
 	protected final EmbeddingModel embeddingModel;
 
 	/**
@@ -59,8 +58,7 @@ public AbstractObservationVectorStore(ObservationRegistry observationRegistry,
 		this(null, observationRegistry, customObservationConvention);
 	}
 
-	private AbstractObservationVectorStore(@Nullable EmbeddingModel embeddingModel,
-			ObservationRegistry observationRegistry,
+	private AbstractObservationVectorStore(EmbeddingModel embeddingModel, ObservationRegistry observationRegistry,
 			@Nullable VectorStoreObservationConvention customObservationConvention) {
 		this.embeddingModel = embeddingModel;
 		this.observationRegistry = observationRegistry;
@@ -94,6 +92,7 @@ public void add(List<Document> documents) {
 	}
 
 	@Override
+	@Nullable
 	public Optional<Boolean> delete(List<String> deleteDocIds) {
 
 		VectorStoreObservationContext observationContext = this
@@ -107,6 +106,7 @@ public Optional<Boolean> delete(List<String> deleteDocIds) {
 	}
 
 	@Override
+	@Nullable
 	public List<Document> similaritySearch(SearchRequest request) {
 
 		VectorStoreObservationContext searchObservationContext = this

spring-ai-core/src/test/java/org/springframework/ai/vectorstore/SimpleVectorStoreTests.java

@@ -57,7 +57,7 @@ void setUp() {
 		when(this.mockEmbeddingModel.dimensions()).thenReturn(3);
 		when(this.mockEmbeddingModel.embed(any(String.class))).thenReturn(new float[] { 0.1f, 0.2f, 0.3f });
 		when(this.mockEmbeddingModel.embed(any(Document.class))).thenReturn(new float[] { 0.1f, 0.2f, 0.3f });
-		this.vectorStore = new SimpleVectorStore(SimpleVectorStore.builder().embeddingModel(this.mockEmbeddingModel));
+		this.vectorStore = new SimpleVectorStore(SimpleVectorStore.builder(this.mockEmbeddingModel));
 	}
 
 	@Test

spring-ai-spring-boot-autoconfigure/src/main/java/org/springframework/ai/autoconfigure/vectorstore/azure/AzureVectorStoreAutoConfiguration.java

@@ -84,9 +84,7 @@ public AzureVectorStore vectorStore(SearchIndexClient searchIndexClient, Embeddi
 			ObjectProvider<VectorStoreObservationConvention> customObservationConvention,
 			BatchingStrategy batchingStrategy) {
 
-		var builder = AzureVectorStore.builder()
-			.searchIndexClient(searchIndexClient)
-			.embeddingModel(embeddingModel)
+		var builder = AzureVectorStore.builder(searchIndexClient, embeddingModel)
 			.initializeSchema(properties.isInitializeSchema())
 			.filterMetadataFields(List.of())
 			.observationRegistry(observationRegistry.getIfUnique(() -> ObservationRegistry.NOOP))

spring-ai-spring-boot-autoconfigure/src/main/java/org/springframework/ai/autoconfigure/vectorstore/cassandra/CassandraVectorStoreAutoConfiguration.java

@@ -62,7 +62,7 @@ public CassandraVectorStore vectorStore(EmbeddingModel embeddingModel, Cassandra
 			ObjectProvider<VectorStoreObservationConvention> customObservationConvention,
 			BatchingStrategy batchingStrategy) {
 
-		return CassandraVectorStore.builder()
+		return CassandraVectorStore.builder(embeddingModel)
 			.session(cqlSession)
 			.keyspace(properties.getKeyspace())
 			.table(properties.getTable())
@@ -72,7 +72,6 @@ public CassandraVectorStore vectorStore(EmbeddingModel embeddingModel, Cassandra
 			.fixedThreadPoolExecutorSize(properties.getFixedThreadPoolExecutorSize())
 			.disallowSchemaChanges(!properties.isInitializeSchema())
 			.returnEmbeddings(properties.getReturnEmbeddings())
-			.embeddingModel(embeddingModel)
 			.observationRegistry(observationRegistry.getIfUnique(() -> ObservationRegistry.NOOP))
 			.customObservationConvention(customObservationConvention.getIfAvailable(() -> null))
 			.batchingStrategy(batchingStrategy)

spring-ai-spring-boot-autoconfigure/src/main/java/org/springframework/ai/autoconfigure/vectorstore/chroma/ChromaVectorStoreAutoConfiguration.java

@@ -86,9 +86,7 @@ public ChromaVectorStore vectorStore(EmbeddingModel embeddingModel, ChromaApi ch
 			ChromaVectorStoreProperties storeProperties, ObjectProvider<ObservationRegistry> observationRegistry,
 			ObjectProvider<VectorStoreObservationConvention> customObservationConvention,
 			BatchingStrategy chromaBatchingStrategy) {
-		return ChromaVectorStore.builder()
-			.chromaApi(chromaApi)
-			.embeddingModel(embeddingModel)
+		return ChromaVectorStore.builder(chromaApi, embeddingModel)
 			.collectionName(storeProperties.getCollectionName())
 			.initializeSchema(storeProperties.isInitializeSchema())
 			.observationRegistry(observationRegistry.getIfUnique(() -> ObservationRegistry.NOOP))

spring-ai-spring-boot-autoconfigure/src/main/java/org/springframework/ai/autoconfigure/vectorstore/elasticsearch/ElasticsearchVectorStoreAutoConfiguration.java

@@ -73,10 +73,8 @@ ElasticsearchVectorStore vectorStore(ElasticsearchVectorStoreProperties properti
 			elasticsearchVectorStoreOptions.setSimilarity(properties.getSimilarity());
 		}
 
-		return ElasticsearchVectorStore.builder()
-			.restClient(restClient)
+		return ElasticsearchVectorStore.builder(restClient, embeddingModel)
 			.options(elasticsearchVectorStoreOptions)
-			.embeddingModel(embeddingModel)
 			.initializeSchema(properties.isInitializeSchema())
 			.observationRegistry(observationRegistry.getIfUnique(() -> ObservationRegistry.NOOP))
 			.customObservationConvention(customObservationConvention.getIfAvailable(() -> null))