- Upgrade the java client from 0.8.0 to 4.0.1
- Use io.pinecone.clients.Pinecone to setup the client configuration with the API key
- Remove projectId, environment and other deprecated client configurations
- Update upsert, delete, search operations with the new client
- Remove the projectID and Environment configurations from the builder
- Updated the Pinecone vectorstore autoconfiguration
- Update tests
Signed-off-by: Ilayaperumal Gopinathan <ilayaperumal.gopinathan@broadcom.com>
Disable autoconfig IT until the auto-configuration is modularised
Extract common vector store delete tests to base class
This commit extracts shared delete operation tests into a reusable BaseVectorStoreTests class.
This reduces code duplication and provides a consistent test suite for delete operations across
different vector store implementations. The base class includes tests for:
Deleting by ID
Deleting by filter expressions
Deleting by string filter expressions
Most of the vector store implementation now extends this base class and inherits these
common tests while maintaining the ability to add vector store specific tests.
Adding javadoc
Signed-off-by: Soby Chacko <soby.chacko@broadcom.com>
- Change VectorStore.delete() and related implementations to return void instead of Optional<Boolean>
- Remove unnecessary boolean return values and success status checks across all vector store implementations
- Clean up tests by removing redundant assertions
- Implementations continue using runtime exceptions for error signaling
Signed-off-by: Soby Chacko <soby.chacko@broadcom.com>
Adds getNativeClient API to VectorStore interface allowing access to the underlying native client implementation.
This change:
- Adds getNativeClient() default method to VectorStore interface returning Optional<T>
- Implements getNativeClient() in all vector store implementations exposing their respective native clients
- Adds integration tests verifying native client access for all implementations
Fixes: #2137
Signed-off-by: Soby Chacko <soby.chacko@broadcom.com>
Replace the existing builder implementation with a type-safe Step Builder pattern
to enforce required field initialization in a specific order. This change:
- Introduces a new builder() method that guides users through required fields
- Deprecates the old builder method with all parameters
- Makes field configuration more explicit and type-safe
- Updates all usage points to use the new builder pattern
The required fields must now be provided in sequence:
1. embeddingModel
2. apiKey
3. projectId
4. environment
5. indexName
This change improves API usability by preventing parameter confusion and ensuring
all required fields are set before optional configuration.
Add string-based filter deletion alongside the Filter.Expression-based deletion
for Pinecone vector store and improve test organization through refactoring.
Key changes:
- Add delete(Filter.Expression) implementation using two-step process:
* Search for documents matching filter
* Delete matching documents by ID
- Leverage existing search functionality to maintain filter consistency
- Extract common test patterns into helper methods
- Create reusable document factory methods for test data
- Add comprehensive integration tests for filter deletion
- Standardize test cleanup and verification patterns
This maintains consistency with other vector store implementations while
working within Pinecone's API limitations. The test refactoring improves
maintainability and makes the test patterns clearer and more consistent.
Signed-off-by: Soby Chacko <soby.chacko@broadcom.com>
Moving BatchingStrategy configuration from individual vector store implementations
to the base AbstractVectorStoreBuilder to reduce code duplication and provide consistent
batching behavior across all vector stores.
The default TokenCountBatchingStrategy is now set in the base builder class.
* Remove use of Document.getContext method from spring-ai-core, use getText
* Remove deprecated ChatOptionsBuilder class
* Remove deprecated FunctionCallingOptionsBuilder class
- Rename all specific builder inner classes (PineconeBuilder, MongoDBBuilder, etc.)
to simply Builder for consistency across vector store implementations
- Update code references to use the new standardized Builder class names
The change establishes a consistent naming convention for builder classes
across the vector store implementations, improving code uniformity.
- 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.
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
This commit deprecates builder methods with the "with" prefix in the VectorStoreObservationContext class
and introduces new methods without the prefix for a cleaner API. For example:
withCollectionName() → collectionName()
withDimensions() → dimensions()
withNamespace() → namespace()
The old methods are marked as deprecated for maintaining backward compatibility.
All vector store implementations have been updated to use the new method names.
The Document class previously allowed multiple media entries while also having a
text field, leading to ambiguity in content handling. This change enforces a
clear separation between text and media documents to prevent content type
confusion and simplify document processing.
A Document now must contain either text content or a single media entry, but
never both. This aligns with the class's primary use in ETL pipelines where
clear content type boundaries are essential for proper embedding generation and
vector database storage.
Additional architectural changes:
- Document now implements a cleaner API by removing deprecated methods
- Removed MediaContent interface implementation from Document class
- Document.getMedia() now returns a single Media object instead of Collection
- Removed EMPTY_TEXT constant in favor of proper null handling
- Constructor signatures simplified and streamlined
- Builder pattern improved to enforce single content type constraint
The breaking changes include:
- Media is now a single entry instead of a collection
- Content field renamed to text for clarity
- Removed support for mixed content types
- Simplified builder API to prevent ambiguous construction
Prefer using text-related methods over deprecated content methods to
better reflect the actual content type being handled and improve API clarity.
- Since the Document object's reference to the `embedding` is deprecated and will be removed, the VectorStore implementations require a way to store the embedding of the corresponding Document objects
- One way to fix this is, to have the EmbeddingModel#embed to return the embeddings in the same order as that of the Documents passed to it.
- Since both the Document and embedding collections use the List object, their iteration operation will make sure to keep them in line with the same order.
- A fix is required to preserve the order when batching strategy is applied.
- Updated the Javadoc for BatchingStrategy
- Fixed the Document List order in TokenCountBatchingStrategy
- Refactored the vector store implementations to update this change
Resolves #GH-1826
Document
* Introduced “score” attribute in Document API. It stores the similarity score.
* Consolidate “distance” metadata for Documents. It stores the distance measurement.
* Adopted prefix-less naming convention in Document.Builder and deprecated old methods.
* Deprecated the many overloaded Document constructors in favour of Document.Builder.
Vector Stores
* Every vector store implementation now configures a “score” attribute with the similarity score of the Document embedding. It also includes the “distance” metadata with the distance measurement.
* Fixed error in Elasticsearch where distance and similarity were mixed up.
* Added missing integration tests for SimpleVectorStore.
* The Azure Vector Store and HanaDB Vector Store do not include those measurements because the product documentation do not include information about how the similarity score is returned, and without access to the cloud products I could not verify that via debugging.
* Improved tests to actually assert the result of the similarity search based on the returned score.
Signed-off-by: Thomas Vitale <ThomasVitale@users.noreply.github.com>
Vector store observations support several key-value pairs, coming from the Spring AI abstractions. Currently, whenever a value is not available (either because not configured by the user or not supported by the vector store provider), span/metrics attributes are generated anyway with value none.
That causes several issues, including an unneeded increase in time series, challenges in alerting/monitoring (especially for integer/double attributes that suddenly are populated with a string), and non-compliance with the OpenTelemetry Semantic Conventions (according to which, attributes should be excluded altogether if there's no value).
This pull request changes the conventions for vector store observations to exclude the generation of span/metrics attributes for optional values which don't have any value.
Signed-off-by: Thomas Vitale <ThomasVitale@users.noreply.github.com>
Apply batching when adding Documents to the following vector stores:
- Azure vector store
- Cassandra
- MongoDB Atlas
- OpenSearch
- Oracle
- Pinecone
This improves efficiency by processing multiple Documents at once instead of individually, reducing the overhead for each operation.
Related to #1261
* Consolidate usage of “db.collection.name” attribute to track table name, collection name, index name, document name, or whatever concept a vector database uses to store data. Removed “db.index” that was use sometimes instead of “db.collection.name”. This usage is in line with the OpenTelemetry Semantic Conventions.
* Configure query response content to be included as a “span event” instead of a “span attribute” if the backend system supports that, similar to how we do for the model observations.
* Structure vector store observation attributes in dedicated enums, including one for the Spring AI Kinds to avoid hard-coding the same value in a lot of places. This follows the OpenTelemetry Semantic Conventions as much as possible. Also, adopt Spring usual non-null-by-default strategy as much as possible.
* Align vector store conventions to the chat model ones, and follow alphabetical order for values. This is particularly useful for the convention classes, for which the Micrometer performance of exporting telemetry data improves when key values are added already sorted to the context.
* Fix flaky test in Mistral AI.
* Improve Qdrant integration tests.
Signed-off-by: Thomas Vitale <ThomasVitale@users.noreply.github.com>
* Change default schema initialization of vector stores from `true` to `false.`
Users need to explicitly opt-in for schema initialization by setting the
`initialize-schema` property on the corresponding vector store.
* Update integration tests
* Update docs
Fixes#907
- Add `withContentFieldName` and `withDistanceMetadataFieldName` to Pinecone Config Builder
- Add `spring.ai.vectorstore.pinecone.contentFieldName` and `spring.ai.vectorstore.pinecone.distanceMetadataFieldName`
properties to the auto-config
- Default content field name: "document_content", distance field: "distance"
- Update tests and docs
Resolves#882
* Rename the ModelClient class hierarchy into Model:
- Rename ModelClient into Model. Update all code and doc references.
- Rename ChatClient to ChatModel. Update all ChatClient suffixes and chatClient fields and variables in code and doc.
- Rename EmbeddingClient into EmbeddingModel. Update the XxxEmbeddingClient class and variable suffixes and embeddingClient variables and fields in code and docs.
- Rename ImageClient into ImageModel.
- Rename SpeechClient into SpeechModel.
- Rename TranscriptionClient into TranscriptionModel.
- Update all javadocs and antora pages. Update the related diagrams.
* Create fluent API in ChatClient interface that now includes streaming support
* Add OpenAI FunctionCallbackWrapper2IT auto-config tests.
* Add ChatClientTest mockito testing.
* Add ChatModel#getDefaultOptions(), and remove @FunctionalInterface
* ChatModel enums extend the new ModelDescription interface.
* Implement fromOptions copy method in every ChatOptions implementation.
* Extend ChatClient to use the model default options if not provided explicitly.
* Update readme to provide guidance on how to adapt to breaking changes.
Co-authored-by: Christian Tzolov <ctzolov@vmware.com>
Co-authored-by: Mark Pollack <mpollack@vmware.com>
