Package com.tnsai.llm.providers

Class WatsonxClient

java.lang.Object

com.tnsai.llm.providers.AbstractLLMClient

com.tnsai.llm.providers.WatsonxClient

All Implemented Interfaces:

com.tnsai.llm.LLMClient

public class WatsonxClient
extends AbstractLLMClient

IBM watsonx.ai LLM client.

watsonx.ai is IBM's enterprise LLM platform. The chat endpoint at /ml/v1/text/chat returns OpenAI-shaped responses but the request body uses IBM-specific fields (model_id instead of model, plus a required project_id) — so it can't reuse the same Request construction as the OpenAI-shape providers in this module.

Auth: IBM Cloud IAM token exchange. Unlike bearer-token cloud providers, watsonx requires an IAM access token obtained by exchanging an IBM Cloud API key. The client does the exchange lazily on first call against https://iam.cloud.ibm.com/identity/token, caches the resulting token until its expires_in window closes (minus a 5-minute safety margin), and re-exchanges transparently on cache miss or when the cached token enters the safety window. The exchange happens under the this monitor so concurrent chat calls block on at most one refresh — never multiple racing exchanges. Tokens themselves are never logged; only the expiry timestamp is.

Supported models (built-in catalog at time of writing):

• ibm/granite-3-8b-instruct — IBM's own Granite 3
• meta-llama/llama-3-3-70b-instruct — Llama 3.3 hosted on watsonx
• mistralai/mistral-large — Mistral Large via watsonx

The catalog evolves; check the live list at cloud.ibm.com/apidocs/watsonx-ai.

Configuration via environment variables:

• WATSONX_API_KEY — Required. The IBM Cloud API key; the client exchanges it for an IAM token automatically.
• WATSONX_PROJECT_ID — Required. The watsonx project ID that scopes model access and billing.
• WATSONX_BASE_URL — Optional. Defaults to the us-south region endpoint (https://us-south.ml.cloud.ibm.com); override for eu-de, jp-tok, etc.

See Also:

• watsonx.ai API documentation

Constructor Summary

Constructors

Constructor	Description
WatsonxClient(String model)
WatsonxClient(String model, float temperature)
WatsonxClient(String model, float temperature, Float topP, Integer maxTokens)
WatsonxClient(String model, float temperature, Integer maxTokens)
WatsonxClient(String baseUrl, String model, float temperature, Float topP, Integer maxTokens, String apiKey, String projectId)

Method Summary

Modifier and Type	Method	Description
com.tnsai.llm.ChatResponse	chat(String message, Optional<String> systemPrompt, Optional<List<Map<String,Object>>> history, Optional<List<Map<String,Object>>> tools)
Stream<String>	streamChat(String message, Optional<String> systemPrompt, Optional<List<Map<String,Object>>> history, Optional<List<Map<String,Object>>> tools)

Methods inherited from class com.tnsai.llm.providers.AbstractLLMClient

getBaseUrl, getCallTimeoutMs, getMaxTokens, getModel, getTemperature, getTopP

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.tnsai.llm.LLMClient

chat, chat, chat, chat, chat, getCapabilities, getProviderName, listModels, streamChat, streamChat, streamChatWithHandler, streamChatWithHandler, streamChatWithSpec, streamChatWithSpec

Constructor Details

WatsonxClient

public WatsonxClient(String model)

WatsonxClient

public WatsonxClient(String model,
 float temperature)

WatsonxClient

public WatsonxClient(String model,
 float temperature,
 Integer maxTokens)

WatsonxClient

public WatsonxClient(String model,
 float temperature,
 Float topP,
 Integer maxTokens)

WatsonxClient

public WatsonxClient(String baseUrl,
 String model,
 float temperature,
 Float topP,
 Integer maxTokens,
 String apiKey,
 String projectId)

Method Details

chat

public com.tnsai.llm.ChatResponse chat(String message,
 Optional<String> systemPrompt,
 Optional<List<Map<String,Object>>> history,
 Optional<List<Map<String,Object>>> tools)

streamChat

public Stream<String> streamChat(String message,
 Optional<String> systemPrompt,
 Optional<List<Map<String,Object>>> history,
 Optional<List<Map<String,Object>>> tools)