{"id":3515,"library":"ibm-watsonx-ai","title":"IBM watsonx.ai Python SDK","description":"The `ibm-watsonx-ai` library is the official Python SDK for IBM watsonx.ai, an enterprise-grade AI and data platform for building, training, tuning, deploying, and operating AI models at scale. It provides a unified interface to watsonx.ai capabilities, including Foundation Models (LLMs), AutoAI experiments, Retrieval-Augmented Generation (RAG), model tuning, deployment, and data integration. The library is actively maintained with regular updates and new feature releases.","status":"active","version":"1.5.6","language":"python","source_language":"en","source_url":"https://github.com/IBM/watsonx-ai-python-sdk","tags":["watsonx.ai","machine learning","IBM","AI","generative AI","foundation models","LLM"],"install":[{"cmd":"pip install ibm-watsonx-ai","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"APIClient","correct":"from ibm_watsonx_ai import APIClient"},{"symbol":"Credentials","correct":"from ibm_watsonx_ai import Credentials"},{"symbol":"Model","correct":"from ibm_watsonx_ai.foundation_models import Model"},{"symbol":"ModelTypes","correct":"from ibm_watsonx_ai.foundation_models.utils.enums import ModelTypes"},{"symbol":"DecodingMethods","correct":"from ibm_watsonx_ai.foundation_models.utils.enums import DecodingMethods"}],"quickstart":{"code":"import os\nfrom ibm_watsonx_ai import APIClient, Credentials\nfrom ibm_watsonx_ai.foundation_models import Model\nfrom ibm_watsonx_ai.foundation_models.utils.enums import ModelTypes, DecodingMethods\n\n# --- Authentication ---\n# Set these environment variables: IBM_CLOUD_API_KEY, WATSONX_AI_URL, WATSONX_PROJECT_ID\napi_key = os.environ.get(\"IBM_CLOUD_API_KEY\", \"\")\nwatsonx_url = os.environ.get(\"WATSONX_AI_URL\", \"https://us-south.ml.cloud.ibm.com\")\nproject_id = os.environ.get(\"WATSONX_PROJECT_ID\", \"\")\n\nif not all([api_key, watsonx_url, project_id]):\n    raise ValueError(\"Please set IBM_CLOUD_API_KEY, WATSONX_AI_URL, and WATSONX_PROJECT_ID environment variables.\")\n\ncredentials = Credentials(\n    api_key=api_key,\n    url=watsonx_url\n)\n\nclient = APIClient(credentials)\nclient.set.default_project(project_id)\nprint(f\"Authenticated successfully for project_id: {project_id}\")\n\n# --- Foundation Model Inference (Text Generation) ---\nmodel_id = ModelTypes.GRANITE_13B_INSTRUCT.value # Or other supported model like MISTRAL_7B_INSTRUCT\n\n# Model parameters for text generation\nparameters = {\n    \"decoding_method\": DecodingMethods.GREEDY,\n    \"max_new_tokens\": 50,\n    \"min_new_tokens\": 1,\n    \"stop_sequences\": []\n}\n\n# Initialize the model object\nmodel = Model(\n    model_id=model_id,\n    credentials=credentials,\n    project_id=project_id,\n    parameters=parameters\n)\n\n# Define the prompt\nprompt = \"Write a short poem about artificial intelligence:\"\n\n# Generate text\ntry:\n    print(f\"\\nPrompt: {prompt}\")\n    generated_text = model.generate_text(prompt=prompt)\n    print(f\"Generated Text:\\n{generated_text}\")\nexcept Exception as e:\n    print(f\"An error occurred during text generation: {e}\")\n","lang":"python","description":"This quickstart demonstrates how to authenticate with the `ibm-watsonx-ai` SDK using environment variables and perform a basic text generation task with a foundation model. Ensure your `IBM_CLOUD_API_KEY`, `WATSONX_AI_URL`, and `WATSONX_PROJECT_ID` environment variables are set."},"warnings":[{"fix":"Update your code to expect a `pandas.DataFrame` from `.list()` methods. Process the returned DataFrame directly instead of relying on printed output.","message":"The `client.<resource>.list()` methods no longer directly print a table of assets. Instead, they now return a `pandas.DataFrame` object. The `return_as_df` optional parameter has been removed as it is now the default and only behavior.","severity":"breaking","affected_versions":"Likely V1 and newer, check documentation for specific exact version transition."},{"fix":"Migrate existing prompt tuning deployments to alternative tuning methods, such as LoRA or QLoRA, which are available programmatically. Refer to the official `watsonx.ai` documentation for guidance on new tuning approaches.","message":"Prompt tuning as a method to tune foundation models is no longer supported and all existing prompt tuning deployments will be removed upon upgrading the `watsonx.ai` service. Parameter-efficient fine-tuning (PEFT) techniques like LoRA and QLoRA are now the recommended alternatives.","severity":"breaking","affected_versions":"From February 2025 releases (IBM Software Hub 5.1.1) and newer."},{"fix":"Review your application's use of foundation models. If you are using a deprecated model, migrate to a recommended alternative listed in the `watsonx.ai` documentation. IBM regularly updates its list of supported models.","message":"Several foundation models are regularly deprecated and eventually withdrawn. For example, `pixtral-12b` was deprecated in a recent release, and models like `codestral-22b`, `llama-2-13b-chat`, `mistral-small-instruct`, `mistral-large`, and `mixtral-8x7b-instruct-v01` were deprecated in the August 2025 release (IBM Software Hub 5.2.1). Older versions of IBM foundation models remain available for at least 90 days after an update.","severity":"deprecated","affected_versions":"Ongoing, check 'What's new and changed in watsonx.ai' documentation for specific model lifecycles."},{"fix":"Always call `client.set.default_project(your_project_id)` or `client.set.default_space(your_space_id)` after creating the `APIClient` instance, unless you are specifically using a lightweight engine which does not require it.","message":"For most operations, setting a default `project_id` or `space_id` using `client.set.default_project()` or `client.set.default_space()` is mandatory after initializing `APIClient`. Failure to do so will result in errors.","severity":"gotcha","affected_versions":"All versions."},{"fix":"Before attempting to import a PyTorch model, ensure it has been converted and exported to the `.onnx` format using `torch.onnx.export()`.","message":"When importing PyTorch models into `watsonx.ai`, they must first be exported to the `.onnx` format. Direct import of other PyTorch model formats is not supported.","severity":"gotcha","affected_versions":"All versions."}],"env_vars":null,"search_vec":"'activ':66 'ai':9,23,34,79,81 'augment':54 'autoai':50 'build':28 'capabl':45 'data':25,61 'deploy':31,59 'enterpris':21 'enterprise-grad':20 'experi':51 'featur':73 'foundat':47,82 'generat':55,80 'grade':22 'ibm':1,7,17,78 'ibm-watsonx-ai':6 'includ':46 'integr':62 'interfac':42 'learn':77 'librari':10,64 'llm':84 'llms':49 'machin':76 'maintain':67 'model':35,48,57,83 'new':72 'offici':13 'oper':33 'platform':26 'provid':39 'python':3,14 'rag':56 'regular':69 'releas':74 'retriev':53 'retrieval-aug':52 'scale':37 'sdk':4,15 'train':29 'tune':30,58 'unifi':41 'updat':70 'watsonx':8 'watsonx.ai':2,18,44,75","created_at":"2026-04-11T17:32:55.150746+00:00","updated_at":"2026-04-16T15:40:26.816559+00:00","problems":[{"fix":"Verify that your API key or IAM token is valid and active, ensure the `project_id` matches your watsonx.ai project, and confirm that the watsonx.ai Runtime service instance is correctly associated with your project by re-associating it if necessary.","cause":"The API key, IAM token, or project ID provided for authentication is incorrect, expired, or lacks the necessary permissions, or the associated Watson Machine Learning (WML) service instance is inactive or not correctly linked to the project.","error":"401 error"},{"fix":"Install the required `unitxt` library using pip: `pip install unitxt==1.14.0`.","cause":"The `unitxt` library, which is required for evaluating patterns in AutoAI Retrieval-Augmented Generation (RAG) experiments, is not installed in the Python environment by default.","error":"ModuleNotFoundError: No module named 'unitxt'"},{"fix":"Reduce the values for `max_sequence_length` and `max_new_tokens` in your model deployment configuration to be within the acceptable limits defined in the model's configuration file.","cause":"The `max_sequence_length` or `max_new_token` parameters configured for a custom foundation model deployment exceed the model's or the system's capacity, leading to an out-of-memory or resource allocation failure during prefill.","error":"Failed to deploy the custom foundation model. The operation failed due to 'max_batch_weight (xxx) not large enough for (prefill) max_sequence_length (yyy)'"},{"fix":"Use a compatible Python version (e.g., Python 3.10, 3.11, or 3.12) for your development environment until the `ibm-watsonx-ai` SDK is updated to support Python 3.14.","cause":"This error indicates an incompatibility between the `ibm-watsonx-ai` library and Python 3.14, specifically due to changes in how `Enum.__init__` is handled in newer CPython versions.","error":"TypeError: object.__init__() takes exactly one argument (the instance to initialize)"},{"fix":"Carefully review the request payload, headers, and parameters to ensure they conform to the specific watsonx.ai API documentation. For RAG experiments, check if the input token count exceeds the model's limits and adjust document chunking or model selection.","cause":"The API request sent to watsonx.ai contains invalid input arguments, malformed data, or parameters that do not adhere to the service's API specifications, often including exceeding token limits for models in RAG experiments.","error":"400: Bad request - The request or response is invalid"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.7.1","cli_name":"","cli_version":null,"type":"library","homepage":"https://www.ibm.com/products/watsonx-ai","github":"https://github.com/IBM/watsonx-ai-samples","docs":"https://ibm.github.io/watsonx-ai-python-sdk","changelog":"https://ibm.github.io/watsonx-ai-python-sdk/changelog.html","pypi":"https://pypi.org/project/ibm-watsonx-ai/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["ai-ml","llm-agents","aws","gcp","azure"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-29","next_check":"2026-07-28","install_tag":null}}