Skip to main content
Deprecated: The native WatsonX backend is deprecated since v0.4. Use the LiteLLM or OpenAI backend with a WatsonX-compatible endpoint instead.
The WatsonX backend connects to IBM’s managed AI platform. It requires an API key, project ID, and service URL. Prerequisites: pip install 'mellea[watsonx]' and IBM Cloud credentials.

​
Credentials

export WATSONX_URL=https://us-south.ml.cloud.ibm.com
export WATSONX_API_KEY=your-watsonx-api-key
export WATSONX_PROJECT_ID=your-project-id
Obtain these from the IBM Cloud console:
  • API key: IBM Cloud IAM
  • Project ID: Your Watson Studio project settings
  • URL: Region-specific endpoint (e.g., https://us-south.ml.cloud.ibm.com)

​
Connecting

The quickest path is start_session() with backend_name="watsonx": 
from mellea import start_session

m = start_session(
    backend_name="watsonx",
    model_id="ibm/granite-4-h-small",
)
result = m.instruct("Summarise this document in three bullet points.")
print(str(result))
# Output will vary — LLM responses depend on model and temperature.
Or construct the Backend directly for full control: 
from mellea import MelleaSession
from mellea.backends import model_ids
from mellea.backends.watsonx import WatsonxAIBackend

m = MelleaSession(
    WatsonxAIBackend(model_id=model_ids.IBM_GRANITE_4_HYBRID_SMALL)
)
Credentials are read from the environment variables by default. Pass them explicitly if needed: 
from mellea import MelleaSession
from mellea.backends.watsonx import WatsonxAIBackend

m = MelleaSession(
    WatsonxAIBackend(
        model_id="ibm/granite-3-3-8b-instruct",
        base_url="https://us-south.ml.cloud.ibm.com",
        api_key="your-api-key",
        project_id="your-project-id",
    )
)

​
Available models

model_ids constantWatsonX model nameNotes
IBM_GRANITE_4_HYBRID_SMALLibm/granite-4-h-smallDefault WatsonX model
IBM_GRANITE_3_3_8Bibm/granite-3-3-8b-instruct
IBM_GRANITE_3_2_8Bibm/granite-3-2b-instruct
Pass the WatsonX model name string directly for any model not listed in model_ids.

​
Troubleshooting

Missing credentials: 
KeyError: WATSONX_URL / WATSONX_API_KEY / WATSONX_PROJECT_ID
All three environment variables must be set. Check your IBM Cloud project settings for the correct values. pip install "mellea[watsonx]" required: The WatsonX backend requires the ibm-watson-machine-learning package, which is not installed by default: 
pip install 'mellea[watsonx]'

​
Vision support

Note: WatsonxAIBackend does not currently support image input. Passing images=[...] to instruct() or chat() will raise an error. Use the OpenAI backend or Ollama for vision tasks.
See also: Backends and Configuration