Adds GemFireVectorStore Auto-Configuration

- Adds spring boot auto-configuration support for GemFireVectorStore
- Adds integration test GemFireVectorStoreAutoConfigurationIT
- Includes gemfire-testcontainers in integration tests
- Adds unit test GemFireVectorStorePropertiesTests
- Refactors GemFireVectorStore.java extracting GemFireVectorStoreConfig.java
- Renames spring-ai-gemfire to spring-ai-gemfire-store
- Adds GemFireConnectionDetails
- Adds GemFireVectorStoreProperties with default values

Co-authored-by: Louis Jacome <[email protected]>
Co-authored-by: Jason Huyn <[email protected]>

Author: 3 people

pom.xml

@@ -46,6 +46,7 @@
 		<module>spring-ai-spring-boot-starters/spring-ai-starter-stability-ai</module>
 		<module>spring-ai-spring-boot-starters/spring-ai-starter-neo4j-store</module>
 		<module>spring-ai-spring-boot-starters/spring-ai-starter-qdrant-store</module>
+		<module>spring-ai-spring-boot-starters/spring-ai-starter-gemfire-store</module>
 		<module>spring-ai-spring-boot-starters/spring-ai-starter-postgresml-embedding</module>
 		<module>spring-ai-docs</module>
 		<module>vector-stores/spring-ai-cassandra</module>
@@ -60,7 +61,7 @@
 		<module>vector-stores/spring-ai-azure</module>
 		<module>vector-stores/spring-ai-weaviate</module>
 		<module>vector-stores/spring-ai-redis</module>
-		<module>vector-stores/spring-ai-gemfire</module>
+		<module>vector-stores/spring-ai-gemfire-store</module>
 		<module>spring-ai-spring-boot-starters/spring-ai-starter-vertex-ai-palm2</module>
 		<module>spring-ai-spring-boot-starters/spring-ai-starter-vertex-ai-gemini</module>
 		<module>vector-stores/spring-ai-qdrant</module>

spring-ai-bom/pom.xml

@@ -206,7 +206,7 @@
 
 			<dependency>
 				<groupId>org.springframework.ai</groupId>
-				<artifactId>spring-ai-gemfire</artifactId>
+				<artifactId>spring-ai-gemfire-store</artifactId>
 				<version>${project.version}</version>
 			</dependency>
 
@@ -384,6 +384,12 @@
                 <artifactId>spring-ai-elasticsearch-store-spring-boot-starter</artifactId>
                 <version>${project.version}</version>
             </dependency>
+
+            <dependency>
+                <groupId>org.springframework.ai</groupId>
+                <artifactId>spring-ai-gemfire-store-spring-boot-starter</artifactId>
+                <version>${project.version}</version>
+            </dependency>
         </dependencies>
     </dependencyManagement>
 

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/gemfire.adoc

@@ -1,122 +1,131 @@
 = GemFire Vector Store
 
-This section walks you through setting up the GemFire VectorStore to store document embeddings and perform similarity searches.
+This section walks you through setting up the `GemFireVectorStore` to store document embeddings and perform similarity searches.
 
-link:https://tanzu.vmware.com/gemfire[GemFire] is an ultra high speed in-memory data and compute grid, with vector extensions to store and search vectors efficiently.
+link:https://tanzu.vmware.com/gemfire[GemFire] is a distributed, in-memory, key-value store that performs read and write operations at blazingly fast speeds. It offers highly available parallel message queues, continuous availability, and an event-driven architecture you can scale dynamically with no downtime. As your data size requirements increase to support high-performance, real-time apps, GemFire can scale linearly with ease.
 
-link:https://docs.vmware.com/en/VMware-GemFire-VectorDB/1.0/gemfire-vectordb/overview.html[GemFire VectorDB] extends GemFire's capabilities, serving as a versatile vector database that efficiently stores, retrieves, and performs vector searches through a distributed and resilient infrastructure:
-
-Capabilities:
-- Create Indexes
-- Store vectors and the associated metadata
-- Perform vector searches based on similarity
+link:https://docs.vmware.com/en/VMware-GemFire-VectorDB/1.0/gemfire-vectordb/overview.html[GemFire VectorDB] extends GemFire's capabilities, serving as a versatile vector database that efficiently stores, retrieves, and performs vector similarity searches.
 
 == Prerequisites
 
-Access to a GemFire cluster with the link:https://docs.vmware.com/en/VMware-GemFire-VectorDB/1.0/gemfire-vectordb/install.html[GemFire Vector Database] extension installed.
-You can download the GemFire VectorDB extension from the link:https://network.pivotal.io/products/gemfire-vectordb/[VMware Tanzu Network] after signing in.
+1. A GemFire cluster with the GemFire VectorDB extension enabled
+- link:https://docs.vmware.com/en/VMware-GemFire-VectorDB/1.0/gemfire-vectordb/install.html[Install GemFire VectorDB extension]
+
+2. An `EmbeddingClient` bean to compute the document embeddings. Refer to the xref:api/embeddings.adoc#available-implementations[EmbeddingClient] section for more information.
 
 == Dependencies
 
-Add these dependencies to your project:
+=== Maven
 
-- Embedding Client boot starter, required for calculating embeddings.
-- Transformers Embedding (Local) and follow the ONNX Transformers Embedding instructions.
+To use just the `GemFireVectorStore`, add the following dependency to your project’s Maven `pom.xml`:
 
-[source,xml]
+[source, xml]
 ----
 <dependency>
-     <groupId>org.springframework.ai</groupId>
-     <artifactId>spring-ai-transformers</artifactId>
+    <groupId>org.springframework.ai</groupId>
+    <artifactId>spring-ai-gemfire-store</artifactId>
 </dependency>
 ----
 
-- Add the GemFire VectorDB dependencies
+To enable Spring Boot’s Auto-Configuration for the `GemFireVectorStore`, also add the following to your project’s Maven `pom.xml`:
 
-[source,xml]
+[source, xml]
 ----
 <dependency>
     <groupId>org.springframework.ai</groupId>
-    <artifactId>spring-ai-gemfire</artifactId>
+    <artifactId>spring-ai-gemfire-store-spring-boot-starter</artifactId>
 </dependency>
+
 ----
 
 
-TIP: Refer to the xref:getting-started.adoc#dependency-management[Dependency Management] section to add the Spring AI BOM to your build file.
+=== Gradle
 
+For Gradle users, add the following to your `build.gradle` file under the dependencies block to use just the `GemFireVectorStore`:
 
-== Sample Code
+[souce, xml]
+----
+dependencies {
+    implementation 'org.springframework.ai:spring-ai-gemfire-store'
+}
+----
 
-- To configure GemFire in your application, use the following setup:
+To enable Spring Boot’s Auto-Configuration for the `GemFireVectorStore`, also include this dependency:
 
-[source,java]
+[source, xml]
 ----
-@Bean
-public GemFireVectorStoreConfig gemFireVectorStoreConfig() {
-    return GemFireVectorStoreConfig.builder()
-        .withUrl("http://localhost:8080")
-        .withIndexName("spring-ai-test-index")
-        .build();
+dependencies {
+    implementation 'org.springframework.ai:spring-ai-gemfire-store-spring-boot-starter'
 }
 ----
 
-- Create a GemFireVectorStore instance connected to your GemFire VectorDB:
+== Usage
+
+- Create a `GemFireVectorStore` instance connected to the GemFire cluster:
 
 [source,java]
 ----
 @Bean
-public VectorStore vectorStore(GemFireVectorStoreConfig config, EmbeddingClient embeddingClient) {
-    return new GemFireVectorStore(config, embeddingClient);
+public VectorStore vectorStore(EmbeddingClient embeddingClient) {
+    return new GemFireVectorStore(new GemFireVectorStoreConfig()
+                                    .setIndexName("my-vector-index")
+                                    .setPort(7071), embeddingClient);
 }
 ----
-- Create a Vector Index which will configure GemFire region.
+
+[NOTE]
+====
+The default configuration connects to a GemFire cluster at `localhost:8080`
+====
+
+- In your application, create a few documents:
 
 [source,java]
 ----
-  public void createIndex() {
-		try {
-			CreateRequest createRequest = new CreateRequest();
-			createRequest.setName(INDEX_NAME);
-			createRequest.setBeamWidth(20);
-			createRequest.setMaxConnections(16);
-			ObjectMapper objectMapper = new ObjectMapper();
-			String index = objectMapper.writeValueAsString(createRequest);
-			client.post()
-				.contentType(MediaType.APPLICATION_JSON)
-				.bodyValue(index)
-				.retrieve()
-				.bodyToMono(Void.class)
-				.block();
-		}
-		catch (Exception e) {
-			logger.warn("An unexpected error occurred while creating the index");
-		}
-	}
-----
-
-- Create some documents:
+List<Document> documents = List.of(
+   new Document("Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!! Spring AI rocks!!", Map.of("country", "UK", "year", 2020)),
+   new Document("The World is Big and Salvation Lurks Around the Corner", Map.of()),
+   new Document("You walk forward facing the past and you turn back toward the future.", Map.of("country", "NL", "year", 2023)));
+----
+
+- Add the documents to the vector store:
 
 [source,java]
 ----
-    List<Document> documents = List.of(
-        new Document("1", getText("classpath:/test/data/spring.ai.txt"), Map.of("meta1", "meta1")),
-        new Document("2", getText("classpath:/test/data/time.shelter.txt"), Map.of()),
-        new Document("3", getText("classpath:/test/data/great.depression.txt"), Map.of("meta2", "meta2")));
+vectorStore.add(documents);
 ----
 
-- Add the documents to GemFire VectorDB:
+- And to retrieve documents using similarity search:
 
 [source,java]
 ----
-vectorStore.add(List.of(document));
+List<Document> results = vectorStore.similaritySearch(
+   SearchRequest.query("Spring").withTopK(5));
 ----
 
-- And finally, retrieve documents similar to a query:
+You should retrieve the document containing the text "Spring AI rocks!!".
 
+You can also limit the number of results using a similarity threshold:
 [source,java]
 ----
-  List<Document> results = vectorStore.similaritySearch("Spring", 5);
+List<Document> results = vectorStore.similaritySearch(
+   SearchRequest.query("Spring").withTopK(5)
+      .withSimilarityThreshold(0.5d));
 ----
 
-If all goes well, you should retrieve the document containing the text "Spring AI rocks!!".
+== GemFireVectorStore properties
+
+You can use the following properties in your Spring Boot configuration to further configure the `GemFireVectorStore`.
+
+|===
+|Property|Default value
 
+|`spring.ai.vectorstore.gemfire.host`|localhost
+|`spring.ai.vectorstore.gemfire.port`|8080
+|`spring.ai.vectorstore.gemfire.index-name`|spring-ai-gemfire-store
+|`spring.ai.vectorstore.gemfire.beam-width`|100
+|`spring.ai.vectorstore.gemfire.max-connections`|16
+|`spring.ai.vectorstore.gemfire.vector-similarity-function`|COSINE
+|`spring.ai.vectorstore.gemfire.fields`|[]
+|`spring.ai.vectorstore.gemfire.buckets`|0
+|===

spring-ai-spring-boot-autoconfigure/pom.xml

@@ -18,6 +18,13 @@
 		<connection>git://github.com/spring-projects/spring-ai.git</connection>
 		<developerConnection>[email protected]:spring-projects/spring-ai.git</developerConnection>
 	</scm>
+	<repositories>
+		<repository>
+			<id>gemfire-release-repo</id>
+			<name>Pivotal GemFire Release Repository</name>
+			<url>https://commercial-repo.pivotal.io/data3/gemfire-release-repo/gemfire</url>
+		</repository>
+	</repositories>
 
 	<dependencies>
 
@@ -267,6 +274,13 @@
 			<optional>true</optional>
 		</dependency>
 
+		<dependency>
+			<groupId>org.springframework.ai</groupId>
+			<artifactId>spring-ai-gemfire-store</artifactId>
+			<version>${project.parent.version}</version>
+			<optional>true</optional>
+		</dependency>
+
 		<!-- test dependencies -->
 
 		<dependency>
@@ -354,13 +368,18 @@
 			<scope>test</scope>
 		</dependency>
 
+		<dependency>
+			<groupId>com.vmware.gemfire</groupId>
+			<artifactId>gemfire-testcontainers</artifactId>
+			<version>2.0.0</version>
+           <scope>test</scope>
+		</dependency>
 		<dependency>
 			<groupId>org.skyscreamer</groupId>
 			<artifactId>jsonassert</artifactId>
 			<version>1.5.0</version>
 			<scope>test</scope>
 		</dependency>
-
-    </dependencies>
+	</dependencies>
 
 </project>

spring-ai-spring-boot-autoconfigure/src/main/java/org/springframework/ai/autoconfigure/vectorstore/gemfire/GemFireConnectionDetails.java

@@ -0,0 +1,29 @@
+/*
+ * 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.
+ */
+package org.springframework.ai.autoconfigure.vectorstore.gemfire;
+
+import org.springframework.boot.autoconfigure.service.connection.ConnectionDetails;
+
+/**
+ * @author Geet Rawat
+ */
+public interface GemFireConnectionDetails extends ConnectionDetails {
+
+	String getHost();
+
+	int getPort();
+
+}

spring-ai-spring-boot-autoconfigure/src/main/java/org/springframework/ai/autoconfigure/vectorstore/gemfire/GemFireVectorStoreAutoConfiguration.java

@@ -0,0 +1,84 @@
+/*
+ * 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.
+ */
+
+package org.springframework.ai.autoconfigure.vectorstore.gemfire;
+
+import org.springframework.ai.embedding.EmbeddingClient;
+import org.springframework.ai.vectorstore.GemFireVectorStore;
+import org.springframework.ai.vectorstore.GemFireVectorStoreConfig;
+import org.springframework.boot.autoconfigure.AutoConfiguration;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.boot.context.properties.EnableConfigurationProperties;
+import org.springframework.context.annotation.Bean;
+
+/**
+ * @author Geet Rawat
+ */
+@AutoConfiguration
+@ConditionalOnClass({ GemFireVectorStore.class, EmbeddingClient.class })
+@EnableConfigurationProperties(GemFireVectorStoreProperties.class)
+@ConditionalOnProperty(prefix = "spring.ai.vectorstore.gemfire", value = { "index-name" })
+public class GemFireVectorStoreAutoConfiguration {
+
+	@Bean
+	@ConditionalOnMissingBean(GemFireConnectionDetails.class)
+	GemFireVectorStoreAutoConfiguration.PropertiesGemFireConnectionDetails gemfireConnectionDetails(
+			GemFireVectorStoreProperties properties) {
+		return new GemFireVectorStoreAutoConfiguration.PropertiesGemFireConnectionDetails(properties);
+	}
+
+	@Bean
+	@ConditionalOnMissingBean
+	public GemFireVectorStore vectorStore(EmbeddingClient embeddingClient, GemFireVectorStoreProperties properties,
+			GemFireConnectionDetails gemFireConnectionDetails) {
+		var config = new GemFireVectorStoreConfig();
+
+		config.setHost(gemFireConnectionDetails.getHost())
+			.setPort(gemFireConnectionDetails.getPort())
+			.setIndexName(properties.getIndexName())
+			.setBeamWidth(properties.getBeamWidth())
+			.setMaxConnections(properties.getMaxConnections())
+			.setBuckets(properties.getBuckets())
+			.setVectorSimilarityFunction(properties.getVectorSimilarityFunction())
+			.setFields(properties.getFields())
+			.setSslEnabled(properties.isSslEnabled());
+		return new GemFireVectorStore(config, embeddingClient);
+	}
+
+	private static class PropertiesGemFireConnectionDetails implements GemFireConnectionDetails {
+
+		private final GemFireVectorStoreProperties properties;
+
+		PropertiesGemFireConnectionDetails(GemFireVectorStoreProperties properties) {
+
+			this.properties = properties;
+		}
+
+		@Override
+		public String getHost() {
+			return this.properties.getHost();
+		}
+
+		@Override
+		public int getPort() {
+			return this.properties.getPort();
+		}
+
+	}
+
+}