feat: Add IBM Granite model support via watsonx.ai provider (OSS-35)

[iris-clawd]

Summary

Adds native support for IBM Granite models through the watsonx.ai Model Gateway's OpenAI-compatible API. No new dependencies required.

What's included

New watsonx provider (llms/providers/watsonx/)

• WatsonxCompletion class extending OpenAICompletion — leverages the OpenAI SDK to talk to watsonx's OpenAI-compatible Model Gateway
• IBM Cloud IAM token exchange — transparently exchanges API keys for Bearer tokens with thread-safe caching and auto-refresh before expiry
• project_id injection via X-Watsonx-Project-Id header
• Regional URL construction (us-south, eu-de, eu-gb, jp-tok, au-syd)

Model constants

12 IBM Granite models added to WATSONX_MODELS:

• Granite 4.x hybrid family (micro/tiny/small)
• Granite 3.x instruct + base models
• Granite Code (8B)
• Granite Guardian (safety)

LLM routing integration

• watsonx and ibm added to SUPPORTED_NATIVE_PROVIDERS
• Provider mapping, validation, pattern matching, and inference all updated
• Works with both prefix syntax and explicit provider param

Tests

Unit tests covering IAM token exchange, caching, refresh, URL resolution, model capabilities, and routing.

Usage

from crewai import LLM

# Provider prefix
llm = LLM(model="watsonx/ibm/granite-4-h-small")

# Explicit provider
llm = LLM(model="ibm/granite-4-h-small", provider="watsonx")

Environment variables:

• WATSONX_API_KEY — IBM Cloud API key (required)
• WATSONX_PROJECT_ID — watsonx.ai project ID (required)
• WATSONX_REGION — IBM Cloud region (optional, default: us-south)
• WATSONX_URL — Full base URL override (optional)

Design decisions

• No new pip dependencies — uses existing openai SDK + httpx (already core deps)
• Extends OpenAICompletion rather than creating from scratch — minimal code, inherits streaming, tool calling, structured output
• Lazy IAM token exchange — only fetches when first call is made
• ibm-watsonx-ai optional dep untouched — that's for embeddings, this is for chat completions via the gateway

Closes OSS-35

---

Note

Medium Risk
Adds a new native LLM provider with IAM token exchange and request header injection, which affects authentication and outbound request behavior. While largely additive and covered by tests, misconfiguration or token-refresh bugs could break watsonx calls at runtime.

Overview
Adds a new native watsonx/ibm provider so LLM can route IBM Granite model names to a dedicated WatsonxCompletion implementation.

Defines WATSONX_MODELS constants and extends provider validation/inference/pattern-matching so Granite models (and granite prefixes) are recognized both with watsonx/... prefixes and via explicit provider="watsonx".

Implements IAM API-key-to-bearer-token exchange with thread-safe caching/refresh, injects X-Watsonx-Project-Id on requests, supports region/URL configuration, and adds unit tests for token handling, URL/region resolution, model capabilities, and factory routing.

^{Reviewed by Cursor Bugbot for commit d3f422a. Bugbot is set up for automated code reviews on this repo. Configure here.}

[linear]

OSS-35 Explore support for IBM Granite models as requested

[cursor]

Cursor Bugbot has reviewed your changes and found 4 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit d3f422a. Configure here.}

[cursor]

Project ID header never injected into API client

High Severity

The _build_client method injects the critical X-Watsonx-Project-Id header, but it overrides a method that doesn't exist in the parent OpenAICompletion class. The parent creates self.client and self.async_client directly in its __init__ without calling any _build_client hook. As a result, the project ID header is never applied to the actual HTTP clients, and all watsonx.ai API requests will lack the required project context. The WatsonxCompletion.__init__ needs to pass default_headers containing the project ID to super().__init__().

Additional Locations (1)

• lib/crewai/src/crewai/llms/providers/watsonx/completion.py#L203-L210

 

^{Reviewed by Cursor Bugbot for commit d3f422a. Configure here.}

[cursor]

Async client token never refreshed before calls

High Severity

_ensure_fresh_token updates self.client.api_key but never updates self.async_client.api_key. When acall() is invoked, it calls _ensure_fresh_token() then delegates to the parent's acall(), which uses self.async_client for the actual API request. After the initial IAM token expires, all async calls will fail with authentication errors because the async client still holds the stale token.

Additional Locations (1)

• lib/crewai/src/crewai/llms/providers/watsonx/completion.py#L359-L372

 

^{Reviewed by Cursor Bugbot for commit d3f422a. Configure here.}

[cursor]

Ternary condition with identical branches is redundant

Low Severity

In to_config_dict, the expression f"watsonx/{self.model}" if "/" not in self.model else f"watsonx/{self.model}" has identical true and false branches, making the condition meaningless. This suggests one branch was intended to handle a different case (e.g., not prepending watsonx/ when the model already contains a provider prefix).

 

^{Reviewed by Cursor Bugbot for commit d3f422a. Configure here.}

[cursor]

Model name mangled when using ibm/ prefix routing

Medium Severity

Adding "ibm": "watsonx" to the provider_mapping causes LLM(model="ibm/granite-4-h-small") to treat "ibm" as a provider prefix and strip it, passing model="granite-4-h-small" to WatsonxCompletion. However, the watsonx.ai API expects the full model name "ibm/granite-4-h-small" — the "ibm/" is part of the model identifier, not a provider prefix. The _matches_provider_pattern fallback accepts the "granite" prefix, so validation passes silently, but the API call will fail with a model-not-found error.

Additional Locations (1)

• lib/crewai/src/crewai/llm.py#L400-L401

 

^{Reviewed by Cursor Bugbot for commit d3f422a. Configure here.}