Class WatsonxChatModel.Builder

java.lang.Object
dev.langchain4j.model.watsonx.WatsonxChatModel.Builder
Enclosing class:
WatsonxChatModel
public static class WatsonxChatModel.Builder extends Object
Builder class for constructing WatsonxChatModel instances with configurable parameters.

  • Field Details

    • baseUrl

      protected URI baseUrl

    • version

      protected String version

    • apiKey

      protected String apiKey

    • projectId

      protected String projectId

    • spaceId

      protected String spaceId

    • logRequests

      protected Boolean logRequests

    • logResponses

      protected Boolean logResponses

    • timeout

      protected Duration timeout

    • authenticator

      protected com.ibm.watsonx.ai.core.auth.Authenticator authenticator

    • httpClient

      protected HttpClient httpClient

    • verifySsl

      protected boolean verifySsl

  • Method Details

    • build

      public WatsonxChatModel build()

    • modelName

      public WatsonxChatModel.Builder modelName(String modelName)
      Sets the watsonx.ai model ID, e.g. "ibm/granite-3-8b-instruct".
      Parameters:
      modelName - the model ID
      Returns:
      this

    • temperature

      public WatsonxChatModel.Builder temperature(Double temperature)
      Sets the sampling temperature in the range [0.0, 2.0]. Higher values produce more random output; lower values are more deterministic.
      Parameters:
      temperature - the sampling temperature
      Returns:
      this

    • topP

      public WatsonxChatModel.Builder topP(Double topP)
      Sets the nucleus sampling probability in the range (0.0, 1.0]. The model considers only the tokens whose cumulative probability reaches this threshold.
      Parameters:
      topP - the nucleus sampling threshold
      Returns:
      this

    • frequencyPenalty

      public WatsonxChatModel.Builder frequencyPenalty(Double frequencyPenalty)
      Sets the frequency penalty in the range [-2.0, 2.0]. Positive values reduce the likelihood of repeating tokens proportional to how often they have appeared.
      Parameters:
      frequencyPenalty - the frequency penalty
      Returns:
      this

    • presencePenalty

      public WatsonxChatModel.Builder presencePenalty(Double presencePenalty)
      Sets the presence penalty in the range [-2.0, 2.0]. Positive values reduce the likelihood of repeating any token that has already appeared in the output.
      Parameters:
      presencePenalty - the presence penalty
      Returns:
      this

    • maxOutputTokens

      public WatsonxChatModel.Builder maxOutputTokens(Integer maxOutputTokens)
      Sets the maximum number of tokens to generate in the response.
      Parameters:
      maxOutputTokens - the maximum number of output tokens
      Returns:
      this

    • stopSequences

      public WatsonxChatModel.Builder stopSequences(List<String> stopSequences)
      Sets the sequences that will stop generation when encountered.
      Parameters:
      stopSequences - the stop sequences
      Returns:
      this

    • stopSequences

      public WatsonxChatModel.Builder stopSequences(String... stopSequences)
      Sets the sequences that will stop generation when encountered.
      Parameters:
      stopSequences - the stop sequences
      Returns:
      this

    • toolChoice

      public WatsonxChatModel.Builder toolChoice(ToolChoice toolChoice)
      Sets how the model selects tools. Controls whether tool use is automatic, forced, or disabled.
      Parameters:
      toolChoice - the tool choice mode
      Returns:
      this

    • responseFormat

      public WatsonxChatModel.Builder responseFormat(ResponseFormat responseFormat)
      Sets the response format to control structured output, e.g. JSON mode.
      Parameters:
      responseFormat - the response format
      Returns:
      this

    • logitBias

      public WatsonxChatModel.Builder logitBias(Map<String,Integer> logitBias)
      Sets per-token logit biases to increase or decrease the likelihood of specific tokens. Keys are token IDs; values are bias offsets in the range [-100, 100].
      Parameters:
      logitBias - the logit bias map
      Returns:
      this

    • logprobs

      public WatsonxChatModel.Builder logprobs(Boolean logprobs)
      Enables returning log probabilities of the output tokens.
      Parameters:
      logprobs - true to include log probabilities in the response
      Returns:
      this

    • topLogprobs

      public WatsonxChatModel.Builder topLogprobs(Integer topLogprobs)
      Sets the number of most likely tokens to return log probabilities for at each position. Requires WatsonxChat.Builder.logprobs to be true. Value must be between 0 and 20.
      Parameters:
      topLogprobs - the number of top log probabilities to return
      Returns:
      this

    • seed

      public WatsonxChatModel.Builder seed(Integer seed)
      Sets the random seed for deterministic sampling. Using the same seed and parameters should produce the same output across calls.
      Parameters:
      seed - the random seed
      Returns:
      this

    • toolChoiceName

      public WatsonxChatModel.Builder toolChoiceName(String toolChoiceName)
      Sets the name of the specific tool to force when WatsonxChat.Builder.toolChoice is set to force a particular tool.
      Parameters:
      toolChoiceName - the tool name to force
      Returns:
      this

    • supportedCapabilities

      public WatsonxChatModel.Builder supportedCapabilities(Set<Capability> supportedCapabilities)
      Declares the capabilities supported by this model instance, e.g. vision or token-level streaming.
      Parameters:
      supportedCapabilities - the set of supported capabilities
      Returns:
      this

    • supportedCapabilities

      public WatsonxChatModel.Builder supportedCapabilities(Capability... supportedCapabilities)
      Declares the capabilities supported by this model instance.
      Parameters:
      supportedCapabilities - the supported capabilities
      Returns:
      this

    • toolSpecifications

      public WatsonxChatModel.Builder toolSpecifications(List<ToolSpecification> toolSpecifications)
      Sets the tool definitions available to the model for function calling.
      Parameters:
      toolSpecifications - the list of tool specifications
      Returns:
      this

    • toolSpecifications

      public WatsonxChatModel.Builder toolSpecifications(ToolSpecification... toolSpecifications)
      Sets the tool definitions available to the model for function calling.
      Parameters:
      toolSpecifications - the tool specifications
      Returns:
      this

    • listeners

      public WatsonxChatModel.Builder listeners(List<ChatModelListener> listeners)
      Sets the list of ChatModelListener instances for observing chat model interactions.
      Parameters:
      listeners - the listeners to register
      Returns:
      this

    • defaultRequestParameters

      public WatsonxChatModel.Builder defaultRequestParameters(ChatRequestParameters defaultRequestParameters)
      Sets default request parameters that are merged into every chat request.
      Parameters:
      defaultRequestParameters - the default request parameters
      Returns:
      this

    • deploymentId

      public WatsonxChatModel.Builder deploymentId(String deploymentId)

    • thinking

      public WatsonxChatModel.Builder thinking(boolean enabled)
      Enables or disables extended thinking (chain-of-thought reasoning before the response).
      Parameters:
      enabled - true to enable extended thinking
      Returns:
      this

    • thinking

      public WatsonxChatModel.Builder thinking(com.ibm.watsonx.ai.chat.model.ExtractionTags tags)
      Configures extended thinking with custom extraction tags for parsing the thinking block. Passing null disables thinking.
      Parameters:
      tags - the extraction tags, or null to disable thinking
      Returns:
      this

    • thinking

      public WatsonxChatModel.Builder thinking(com.ibm.watsonx.ai.chat.model.ThinkingEffort thinkingEffort)
      Configures extended thinking with a specific effort level. Passing null disables thinking.
      Parameters:
      thinkingEffort - the thinking effort level, or null to disable thinking
      Returns:
      this

    • thinking

      public WatsonxChatModel.Builder thinking(com.ibm.watsonx.ai.chat.model.Thinking thinking)
      Sets a fully configured Thinking object for extended thinking.
      Parameters:
      thinking - the thinking configuration
      Returns:
      this

    • guidedChoice

      public WatsonxChatModel.Builder guidedChoice(String... guidedChoice)
      Constrains the model output to one of the given string choices (guided decoding).
      Parameters:
      guidedChoice - the allowed output values
      Returns:
      this

    • guidedChoice

      public WatsonxChatModel.Builder guidedChoice(Set<String> guidedChoices)
      Constrains the model output to one of the given string choices (guided decoding).
      Parameters:
      guidedChoices - the set of allowed output values
      Returns:
      this

    • guidedRegex

      public WatsonxChatModel.Builder guidedRegex(String guidedRegex)
      Constrains the model output to match the given regular expression (guided decoding).
      Parameters:
      guidedRegex - the regular expression pattern
      Returns:
      this

    • guidedGrammar

      public WatsonxChatModel.Builder guidedGrammar(String guidedGrammar)
      Constrains the model output to conform to the given EBNF grammar (guided decoding).
      Parameters:
      guidedGrammar - the EBNF grammar string
      Returns:
      this

    • repetitionPenalty

      public WatsonxChatModel.Builder repetitionPenalty(Double repetitionPenalty)
      Sets the repetition penalty. Values greater than 1.0 discourage repetition; values less than 1.0 encourage it.
      Parameters:
      repetitionPenalty - the repetition penalty
      Returns:
      this

    • lengthPenalty

      public WatsonxChatModel.Builder lengthPenalty(Double lengthPenalty)
      Sets the length penalty applied to the sequence score during beam search. Values greater than 1.0 favor longer sequences.
      Parameters:
      lengthPenalty - the length penalty
      Returns:
      this

    • baseUrl

      public WatsonxChatModel.Builder baseUrl(com.ibm.watsonx.ai.CloudRegion baseUrl)
      Sets the IBM watsonx.ai endpoint from a predefined CloudRegion.
      Parameters:
      baseUrl - the IBM Cloud region whose ML endpoint will be used
      Returns:
      this

    • baseUrl

      public WatsonxChatModel.Builder baseUrl(String url)
      Sets the base URL of the IBM watsonx.ai API.
      Parameters:
      url - the base URL string, e.g. "https://us-south.ml.cloud.ibm.com"
      Returns:
      this

    • baseUrl

      public WatsonxChatModel.Builder baseUrl(URI url)
      Sets the base URL of the IBM watsonx.ai API as a URI.
      Parameters:
      url - the base URL URI
      Returns:
      this

    • version

      public WatsonxChatModel.Builder version(String version)
      Sets the watsonx.ai API version date, e.g. "2024-05-31".
      Parameters:
      version - the API version date string
      Returns:
      this

    • projectId

      public WatsonxChatModel.Builder projectId(String projectId)
      Sets the IBM Cloud project ID that owns the watsonx.ai resources. Exactly one of projectId or spaceId must be set.
      Parameters:
      projectId - the IBM Cloud project ID
      Returns:
      this

    • spaceId

      public WatsonxChatModel.Builder spaceId(String spaceId)
      Sets the IBM Cloud deployment space ID. Exactly one of projectId or spaceId must be set.
      Parameters:
      spaceId - the IBM Cloud deployment space ID
      Returns:
      this

    • apiKey

      public WatsonxChatModel.Builder apiKey(String apiKey)
      Sets the IBM Cloud API key used to generate IAM access tokens for authentication.
      Parameters:
      apiKey - the IBM Cloud API key
      Returns:
      this

    • logRequests

      public WatsonxChatModel.Builder logRequests(Boolean logRequests)
      Enables debug logging of request bodies sent to the watsonx.ai API.
      Parameters:
      logRequests - true to enable request logging
      Returns:
      this

    • logResponses

      public WatsonxChatModel.Builder logResponses(Boolean logResponses)
      Enables debug logging of response bodies received from the watsonx.ai API.
      Parameters:
      logResponses - true to enable response logging
      Returns:
      this

    • timeout

      public WatsonxChatModel.Builder timeout(Duration timeout)
      Sets the HTTP request timeout. Defaults to 60 seconds.
      Parameters:
      timeout - the request timeout
      Returns:
      this

    • authenticator

      public WatsonxChatModel.Builder authenticator(com.ibm.watsonx.ai.core.auth.Authenticator authenticator)
      Sets a custom Authenticator for generating bearer tokens. Use this instead of apiKey when you need a non-standard authentication flow.
      Parameters:
      authenticator - the authenticator
      Returns:
      this

    • httpClient

      public WatsonxChatModel.Builder httpClient(HttpClient httpClient)
      Sets a custom HttpClient to use for all API calls.
      Parameters:
      httpClient - the HTTP client
      Returns:
      this

    • verifySsl

      public WatsonxChatModel.Builder verifySsl(boolean verifySsl)
      Controls whether SSL certificate verification is performed. Defaults to true. Set to false only in non-production environments.
      Parameters:
      verifySsl - false to disable SSL verification
      Returns:
      this