Getting Started

Welcome to the IBM watsonx.ai Java SDK documentation.

Overview

The IBM watsonx.ai Java SDK is an open-source client library for IBM watsonx.ai, an enterprise-grade AI platform for building, training, and deploying AI models at scale. It provides a unified Java interface to the watsonx.ai ecosystem and works with both IBM Cloud and CP4D (on-premises deployments).

Service	Description
Chat	Conversational AI with multi-turn dialogue, streaming, tool calling, vision, and reasoning
Embedding	Dense vector representations for semantic search, similarity, and RAG
Rerank	Relevance scoring and reordering of candidate documents
Detection	Identification of harmful content (HAP), PII, and safety violations
Tokenization	Token counting and analysis for any model
Foundation Model	Browse and query the watsonx.ai model catalog
Text Classification	Document classification from IBM Cloud Object Storage
Text Extraction	Structured data extraction from documents in IBM Cloud Object Storage
Time Series	Time series forecasting using IBM Granite TTM models
Tool	Server-side utility tools for agentic workflows
Deployment	Chat, text generation, and forecasting via deployed model endpoints

Prerequisites

Before getting started, ensure you have:

A watsonx.ai service instance (IBM Cloud or on-premises)
Java 17 or higher
Maven or Gradle

Installation

Add the SDK to your Maven project:

<dependency>
    <groupId>com.ibm.watsonx</groupId>
    <artifactId>watsonx-ai</artifactId>
    <version>0.18.0</version>
</dependency>

Or for Gradle:

implementation 'com.ibm.watsonx:watsonx-ai:0.18.0'

Quick Start

ChatService chatService = ChatService.builder()
    .apiKey(WATSONX_API_KEY)
    .projectId(WATSONX_PROJECT_ID)
    .baseUrl(CloudRegion.DALLAS)
    .modelId("ibm/granite-4-h-small")
    .build();

AssistantMessage response = chatService.chat("Tell me a joke").toAssistantMessage();
System.out.println(response.content());

Framework Integrations

The IBM watsonx.ai Java SDK is also integrated with popular LLM application frameworks, enabling seamless usage within agentic and AI-powered applications.

Developers can leverage watsonx.ai models through:

Contributing

Contributions are welcome. See the Contributing Guide for details.

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.