IBM WatsonX

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":

# Requires: mellea[watsonx]
# Returns: str
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:

# Requires: mellea[watsonx]
# Returns: MelleaSession
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:

# Requires: mellea[watsonx]
# Returns: MelleaSession
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 constant	WatsonX model name	Notes
IBM_GRANITE_4_HYBRID_SMALL	ibm/granite-4-h-small	Default WatsonX model
IBM_GRANITE_3_3_8B	ibm/granite-3-3-8b-instruct
IBM_GRANITE_3_2_8B	ibm/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