⚠️ Development Status: This project is currently in active development and is not yet ready for production use. Features and APIs may change without notice.

Spring AI Watsonx.ai provides Spring AI integration with IBM's Watsonx.ai platform, enabling developers to leverage powerful foundation models for chat, embeddings, and text extraction capabilities in their applications.

IBM Watsonx.ai is an enterprise-ready AI platform that provides access to various foundation models including:

• Chat Models: IBM Granite, Meta Llama, Mistral AI, and other conversational AI models
• Embedding Models: IBM's embedding models for semantic search and similarity analysis
• Text Extraction: AI-powered document processing and structured data extraction

This integration brings these capabilities to Spring Boot applications through familiar Spring AI abstractions.

• Chat Models: Support for multiple foundation models with streaming capabilities
• Embedding Models: Generate embeddings for semantic search and similarity analysis
• Text Extraction: Extract structured data from documents using AI
• Spring Boot Auto-configuration: Zero-configuration setup with Spring Boot
• Flexible Configuration: Runtime parameter overrides and multiple model configurations
• Function Calling: Connect LLMs with external tools and APIs
• Reactive Support: Built-in support for reactive programming with WebFlux

1. Create an account at IBM Cloud
2. Set up a Watsonx.ai service instance
3. Generate API keys from the IBM Cloud console

Add the Spring AI Watsonx.ai starter to your project:

Maven:

<dependency> <groupId>io.github.springaicommunity</groupId> <artifactId>spring-ai-starter-model-watsonx-ai</artifactId> <version>1.1.0-SNAPSHOT</version> </dependency>

Gradle:

implementation 'io.github.springaicommunity:spring-ai-starter-model-watsonx-ai:1.1.0-SNAPSHOT'

Configure your application with Watsonx.ai credentials:

application.yml:

spring: ai: watsonx: ai: api-key: ${WATSONX_AI_API_KEY} url: ${WATSONX_AI_URL} project-id: ${WATSONX_AI_PROJECT_ID}

Environment Variables:

export WATSONX_AI_API_KEY=your_api_key_here export WATSONX_AI_URL=https://us-south.ml.cloud.ibm.com export WATSONX_AI_PROJECT_ID=your_project_id_here

@RestController public class ChatController { private final WatsonxAiChatModel chatModel; public ChatController(WatsonxAiChatModel chatModel) { this.chatModel = chatModel; } @GetMapping("/chat") public String chat(@RequestParam String message) { return chatModel.call(message); } @GetMapping("/chat/stream") public Flux<String> chatStream(@RequestParam String message) { return chatModel.stream(new Prompt(message)) .map(response -> response.getResult().getOutput().getContent()); } }

@RestController public class EmbeddingController { private final WatsonxAiEmbeddingModel embeddingModel; public EmbeddingController(WatsonxAiEmbeddingModel embeddingModel) { this.embeddingModel = embeddingModel; } @GetMapping("/embed") public List<Double> embed(@RequestParam String text) { return embeddingModel.embed(text); } }

The Spring AI Watsonx.ai integration consists of three main modules:

• watsonx-ai-core: Core implementation with API clients and model classes
• spring-ai-autoconfigure-model-watsonx-ai: Spring Boot auto-configuration
• spring-ai-starter-model-watsonx-ai: Spring Boot starter for easy integration

spring-ai-watsonx-ai/ ├── watsonx-ai-core/ │ ├── WatsonxAiChatModel # Chat model implementation │ ├── WatsonxAiEmbeddingModel # Embedding model implementation │ ├── WatsonxAiTextExtraction # Text extraction implementation │ └── WatsonxAiAuthentication # IBM Cloud IAM authentication ├── spring-ai-autoconfigure-model-watsonx-ai/ │ └── Auto-configuration classes └── spring-ai-starter-model-watsonx-ai/ └── Starter dependencies 

A comprehensive list of supported models under the watsonx.ai platform: watsonx.ai Supported Models

spring: ai: watsonx: ai: chat: options: model: ibm/granite-13b-chat-v2 temperature: 0.7 max-new-tokens: 1024 top-p: 1.0 top-k: 50 repetition-penalty: 1.0

spring: ai: watsonx: ai: embedding: options: model: ibm/slate-125m-english-rtrvr truncate-input-tokens: true

Connect your LLMs with external tools and APIs:

@Bean @Description("Get current weather information") public Function<WeatherRequest, WeatherResponse> getCurrentWeather() { return request -> { // Implementation to fetch weather data return new WeatherResponse(25.0, "sunny", request.location()); }; }

Configure different models for different use cases:

@Configuration public class MultiModelConfiguration { @Bean("creativeChatModel") public WatsonxAiChatModel creativeChatModel(WatsonxAiChatApi chatApi) { return new WatsonxAiChatModel(chatApi, WatsonxAiChatOptions.builder() .withModel("meta-llama/llama-3-70b-instruct") .withTemperature(1.2) .build()); } }

Built-in support for reactive programming:

@GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE) public Flux<ServerSentEvent<String>> streamResponse(@RequestParam String prompt) { return chatModel.stream(new Prompt(prompt)) .map(response -> response.getResult().getOutput().getContent()) .map(content -> ServerSentEvent.<String>builder().data(content).build()); }

@Service public class CustomerSupportService { private final WatsonxAiChatModel chatModel; public String handleQuery(String customerId, String query) { var options = WatsonxAiChatOptions.builder() .withModel("ibm/granite-13b-chat-v2") .withTemperature(0.3) .withFunction("getOrderStatus") .withFunction("createSupportTicket") .build(); return chatModel.call(new Prompt(buildContextualPrompt(customerId, query), options)); } }

@Service public class DocumentAnalysisService { private final WatsonxAiChatModel chatModel; private final WatsonxAiEmbeddingModel embeddingModel; public DocumentAnalysis analyzeDocument(String content) { // Generate summary String summary = chatModel.call("Summarize: " + content); // Generate embeddings for similarity search List<Double> embeddings = embeddingModel.embed(content); return new DocumentAnalysis(summary, embeddings); } }

For comprehensive documentation, examples, and API reference, visit:

• Full Documentation
• Getting Started Guide
• Chat Models
• Embedding Models
• Text Extraction
• Configuration
• Examples

• Java 17 or later
• Maven 3.8.4 or later

git clone https://github.com/spring-ai-community/spring-ai-watsonx-ai.git cd spring-ai-watsonx-ai mvn clean install

mvn test

cd docs mvn clean package

We welcome contributions! Please see our Contributing Guide for details on:

• Code of Conduct
• Development setup
• Submitting pull requests
• Reporting issues

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

• GitHub Discussions - Ask questions and share ideas
• Issues - Report bugs and request features
• Mailing List - Stay updated with announcements

This project is licensed under the Apache License, Version 2.0. See LICENSE for the full license text.

• Spring AI - The foundational framework
• IBM Watsonx.ai - The AI platform
• Spring Community - The vibrant community