- Useful for not Web apps.
- Introduce ErrorLoggingObservationHandler for tracing errors across various AI contexts
- Add error logging configuration option to ChatObservationProperties
- Include ErrorLoggingObservationHandler bean in ChatObservationAutoConfiguration
- Update docs
Resolves#1440
This commit addresses the NPE issue in TextReader's source metadata
handling. It introduces a new method getResourceIdentifier() to
robustly extract identifiers from various Resource types.
The fix ensures that:
1. Filename is used if available
2. Falls back to URI, then URL if filename is not present
3. Uses resource description as a last resort
Additionally, the commit includes updated tests to verify the behavior
with different Resource types, particularly ByteArrayResource
This change prevents NPEs when dealing with Resources that lack
certain properties, improving the overall reliability of TextReader.
Fixes https://github.com/spring-projects/spring-ai/issues/1386
This commit introduces a major overhaul of the advisor system in Spring AI,
improving modularity, type safety, and consistency
Core Changes:
- Replace RequestAdvisor and ResponseAdvisor with CallAroundAdvisor and StreamAroundAdvisor
- Introduce AdvisedRequest and AdvisedResponse classes for better encapsulation
- Deprecate RequestResponseAdvisor in favor of new advisor types
- Remove AdvisorObservableHelper class
Advisor Implementation Updates:
- Update AbstractChatMemoryAdvisor, MessageChatMemoryAdvisor, PromptChatMemoryAdvisor,
QuestionAnswerAdvisor, SafeGuardAroundAdvisor, SimpleLoggerAdvisor, and
VectorStoreChatMemoryAdvisor to implement new advisor interfaces
- Remove CacheAroundAdvisor (functionality likely moved elsewhere)
- Make CallAroundAdvisor and StreamAroundAdvisor extend Ordered interface
Client and Chain Management:
- Modify DefaultChatClient to use new advisor chain approach
- Refactor DefaultAroundAdvisorChain for better ordering and observation
- Implement builder pattern for advisor chain construction in DefaultChatClient
- Separate call and stream advisors in DefaultAroundAdvisorChain
Observation and Context Handling:
- Update observation conventions and context handling in advisors
- Add order field to AdvisorObservationContext
- Modify DefaultAdvisorObservationConvention to include order in high cardinality key values
Testing and Integration:
- Refactor ChatClientAdvisorTests and add new AdvisorsTests
- Update integration tests to reflect new advisor structure
- Enhance AdvisorsTests to verify correct advisor execution order
New Features:
- Generalize the Protect From Blocking functionality across all advisors
- Add (experimental) Re2 advisor to enhance reasoning capabilities of LLMs
- Add disabled Re2 test in OpenAiChatClientIT
Documentation:
- Add Advisors documentation
- Enhance advisors documentation with order explanation and Re2 example
Advisor Ordering:
- Introduce Advisor constants for precedence ordering
- Update AbstractChatMemoryAdvisor to use new precedence constant
- Improve advisor ordering and management in DefaultAroundAdvisorChain.Builder
- Remove redundant reordering logic from DefaultAroundAdvisorChain
These changes aim to provide a more flexible and powerful advisor system,
allowing for easier implementation of complex AI-driven interactions
Co-authored-by: Dariusz Jędrzejczyk <dariusz.jedrzejczyk@broadcom.com>
This commit adds comprehensive documentation for the BatchingStrategy
in vector stores and enhances the TokenCountBatchingStrategy class.
Key changes:
- Explain batching necessity due to embedding model thresholds
- Describe BatchingStrategy interface and its purpose
- Detail TokenCountBatchingStrategy default implementation
- Provide guidance on using and customizing batching strategies
- Note pre-configured vector stores with default strategy
- Add new constructor for custom TokenCountEstimator in
TokenCountBatchingStrategy
- Implement null checks with Spring's Assert utility
- Update docs with new customization options and code examples
This commit introduces support for Oracle Cloud Infrastructure (OCI)
GenAI embedding models in Spring AI. It includes:
* New OCIEmbeddingModel class for interacting with OCI GenAI API
* Auto-configuration for easy setup and integration
* Properties for configuring OCI connection and embedding options
* Documentation updates explaining usage and configuration
* Integration tests to verify functionality
Signed-off-by: Anders Swanson <anders.swanson@oracle.com>
Replace parallelStream with stream to prevent thread-unsafe appends to
the shared StringBuilder. This fixes the issue of intermingled key-value
pairs in the generated Document content. Also, replace StringBuffer
with StringBuilder for better performance in single-threaded context.
The change ensures correct ordering of extracted JSON keys and their
values in the resulting Document, improving the reliability and
readability of the parsed output.
Replace Objects::nonNull and instanceof checks with StringUtils::hasText
for more efficient and cleaner content filtering. This change simplifies
the stream operation in the getContent method, improving readability
and potentially performance.
- When ChatClientRequestSpec#prompt(Prompt) is used, unseal the prompt instance.
Convert the last message instance (if user message) into spec#user and spec#media
and add the remaining messages (excluding the last) to the spec#messages.
Add the prompt#options to the spec#options.
- Improve DefaultChatClient to handle UserMessage media and content separately.
- Update AbstractToolCallSupport to use new hasToolCalls() method.
- Add hasToolCalls() method to AssistantMessage.
- Enhance ChatClientTest with additional test cases for media handling.
- Disable Groq and Nvidia integration tests due to rate limiting and credit requirements.
This commit introduces a new proxyToolCalls option for various chat
models in the Spring AI project. When enabled, it allows the client to
handle function calls externally instead of being processed internally
by Spring AI.
The change affects multiple chat model implementations, including:
AnthropicChatModel
AzureOpenAiChatModel
MiniMaxChatModel
MistralAiChatModel
MoonshotChatModel
OllamaChatModel
OpenAiChatModel
VertexAiGeminiChatModel
ZhiPuAiChatModel
The proxyToolCalls option is added to the respective chat options
classes and integrated into the AbstractToolCallSupport class for
consistent handling across different implementations.
The proxyToolCalls option can be set either programmatically via
the <ModelName>ChatOptions.builder().withProxyToolCalls() method
or the spring.ai.<model-name>.chat.options.proxy-tool-calls
application property.
Documentation for the new option is also updated in the relevant
Antora pages.
Added ITs for proxy tool calls
Remove ChatClientPromptRequestSpec and all ChatClient.prompt() overloads can how take advantage of the full fluent API. Docs updated
Resolves#1367
This commit introduces a new overloaded method prompt(String content)
to the ChatClient API. It provides a convenient way to create prompts
using only a string of user content, simplifying the process for basic
chat interactions.
Fixes gh-1286
Signed-off-by: Thomas Vitale <ThomasVitale@users.noreply.github.com>
This change updates the type of portable chat options from Float to
Double. Affected options include:
- frequencyPenalty
- presencePenalty
- temperature
- topP
The motivation for this change is to simplify coding. In Java, Float
values require an "f" suffix (e.g., 0.5f), while Double values don't
need any suffix. This makes Double easier to type and reduces
potential errors from forgetting the "f" suffix.
APIs, tests, and documentation have been updated to reflect this
change.
Fixes gh-712
Signed-off-by: Thomas Vitale <ThomasVitale@users.noreply.github.com>
Refactoring and enhancements to the advisor functionality.
New Advisor interfaces in the org.springframework.ai.chat.client.advisor.api package:
- Advisor: Base interface for all advisor types.
- RequestAdvisor: For advising on request data before execution.
- ResponseAdvisor: For advising on response data after execution, with enhanced streaming modes.
- CallAroundAdvisor and StreamAroundAdvisor: For around advice on synchronous and streaming requests respectively.
- AroundAdvisorChain and DefaultAroundAdvisorChain: To manage chaining of around advisors.
Advisor Chain and Prompt Generation:
- Added the DefaultAroundAdvisorChain class to manage the sequence of advisors applied around chat model methods.
- Adjusted the prompt generation (toPrompt) to integrate with the refactored AdvisedRequest object.
Refactoring and Updates:
- Replaced the deprecated RequestResponseAdvisor interface with RequestAdvisor and ResponseAdvisor across the spring-ai-core and test modules.
- Updated the DefaultChatClient and related classes to use the new Advisor interface, improving modularity and consistency.
- Refactored DefaultAdvisorSpec and DefaultChatClientRequestSpec to handle the new Advisor type, and revised advisor lists and methods accordingly.
- Enhanced the handling of streaming responses, introducing StreamResponseMode for better control during streaming scenarios.
- Precompute document token counts before batching into List<List<Document>>
- Introduce configurable reserve percentage for max input token count
Resolves#1260
* Fixes an issue with advisor name resolution
* Streamlines repeating code
* Add a new advisor strategy for ON_FINISH_REASON streaming responses, which is used by the Q&A advisor
* Improve observable instrumentation by passing the parent observation to the advisor observation
This commit introduces the OpenAiModerationModel and related classes:
- Add OpenAiModerationModel for content moderation
- Create OpenAiModerationOptions for configuration
- Implement OpenAiModerationProperties for Spring Boot setup
- Add integration tests in OpenAiModerationModelIT
- Add documentation
Co-authored-by: hemeda3 <hemeda3@users.noreply.github.com>
* 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>
Enhance JsonReader to detect and process both JSON objects and arrays at
the root level. This update introduces type checking for the JSON root node
using JsonNode and leverages the Stream API to handle JSON arrays.
- Refactor parsing logic to support both JSON arrays and objects
- Rename variable: resourceArray to arrayResource for clarity
- Convert for-loop to Stream API for processing JSON keys
- Add additional tests to ensure proper array handling
- When embedding documents, allow batching the documents using some criteria.
- `BatchingStrategy` interface with a `TokenCountBatchingStrategy` implementation that uses
the openai max input token size of 8191 as the default.
- Add a default method in EmbeddingModel to embed document using this new batching strategy.
- Change `MilvusVectorStore` to make use of this new batching API.
- Adding unit tests for `TokenCountBatchingStrategy`.
- Adding openai integration test to call the embed API that uses batching.
Resolves https://github.com/spring-projects/spring-ai/issues/1214
Other vector stores will be updated seperately
Implementation:
- Introduce AbstractObservationVectorStore with instrumentation for add, delete, and similaritySearch methods
- Create VectorStoreObservationContext to capture operation details
- Implement DefaultVectorStoreObservationConvention for naming and tagging
- Add VectorStoreObservationDocumentation for defining observation keys
- Create VectorStoreObservationAutoConfiguration for auto-configuring observations
- Add VectorStoreObservationProperties to control optional observation content filters
- Update VectorStore interface with getName() method
- Modify PgVectorStore and SimpleVectorStore to extend AbstractObservationVectorStore
- Add vector_store Spring AI kind
Filters:
- Implement VectorStoreQueryResponseObservationFilter
- Add VectorStoreDeleteRequestContentObservationFilter and VectorStoreAddRequestContentObservationFilter
Enhancements:
- Update PgVectorStoreAutoConfiguration to support observations
- Add observation support to PgVectorStore's Builder
- Add VectorStoreObservationContext.Operation enum with ADD, DELETE, and QUERY options
Tests:
- Add tests for VectorStore context, convention, and filters
- Add VectorStoreObservationAutoConfiguration tests
- Add PgVectorObservationIT
Resolves#1205
- Implement observable chat responses in DefaultChatClient
- Add ChatClientObservationContext and related classes for metrics
- Update ChatClient and builder methods to support ObservationRegistry
- Enhance RequestResponseAdvisor with getName() method
- Add ChatClient streaming observability support
- Introduce ChatClientObservationDocumentation for metric key names
- Create DefaultChatClientObservationConvention for implementing conventions
- Add ChatClientInputContentObservationFilter for optional input content logging
- Update ChatClientAutoConfiguration to include new observation components
- Extend ChatClientBuilderProperties with observation configuration options
- Add unit tests for new observation classes and configurations
- Update AiOperationType and AiProvider enums with new values
- Implement safeguards and warnings for sensitive data in observations
Resolves#1206
* Surface more configuration APIs to ChatOptions
* Use abstraction in Observations directly instead of dedicated implementation
* Simplify metadata config in observations for defined models
* Improve merging of runtime and default options in OpenAI
* Fix missing option in Mistral AI
Relates to gh-1148
Signed-off-by: Thomas Vitale <ThomasVitale@users.noreply.github.com>
- Added support for OpenAI's structured outputs feature, which allows specifying a JSON schema for the model to match
- Introduced new record to configure the desired response format
- Added support for configuring the response format via application properties or the chat options builder
- Extend teh BeanOutputConverter to help generate JSON schema from a target domain object and convert the response.
- Added comprehensive tests to cover the new response format functionality
Resolves#1196
Integrated Micrometer's Observation into the OpenAiChatModel#stream reactive chain.
Included changes:
- Added ability to aggregate streaming responses for use in Observation metadata.
- Improved error handling and logging for chat response processing.
- Updated unit tests to include new observation logic and subscribe to Flux responses.
- Refined validation of observations in both normal and streaming chat operations.
- Disabled retry for streaming which used RetryTemplate - should use .retryWhen operator as the next step.
- Added an integration test.
Resolves#1190
Co-authored-by Christian Tzolov <ctzolov@vmware.com>
* Add model and dimensions to option abstraction
* Use abstraction in Observations directly instead of dedicated implementation
* Clean-up the merge of runtime and default embedding options in OpenAI
Relates to #gh-1148
Signed-off-by: Thomas Vitale <ThomasVitale@users.noreply.github.com>
* Add style to option abstraction
* Use abstraction in Observations directly instead of dedicated implementation
* Clean-up the merge of runtime and default image options in OpenAI and Stability AI
Related to #1148
Signed-off-by: Thomas Vitale <ThomasVitale@users.noreply.github.com>
- Update OllamaEmbeddingModel to support batch embedding requests
- Rename EmbeddingRequest/Response to EmbeddingsRequest/Response
- Add truncate option to control input truncation
- Update documentation and tests for new embedding API
- Remove deprecated withModel and withDefaultOptions methods
- Adjust default values for various Ollama model options
- Include response medata with response model name
Resolves#1158
* Observation APIs for chat, embedding and image models
* Conventions based on OpenTelemetry Semantic Conventions for GenAI
* Instrumentation for OpenAI chat, embedding, and image models
* Autoconfiguration for observability for OpenAI
Fixes gh-953
Signed-off-by: Thomas Vitale <ThomasVitale@users.noreply.github.com>
The autoconfiguration adds the FunctionCallbacks directly to the model's ChatOptions,
which results in the FunctionCallback being included in the request each time it is called.
The modification registers the container's FunctionCallback directly to the model's functionCallbackRegister
using the parent AbstractToolCallSupport constsructor.
Replace the handleFunctionCallbackConfigurations by simplified runtimeFunctionCallbackConfigurations.
Co-authored-by Christian Tzolov <ctzolov@vmware.com>
