{"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":"en","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,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}