V1 Migration Guide
==================

.. raw:: html

    <div style="text-align: justify;">

The new ``ibm_watsonx_ai`` Python SDK 1.0 is backward compatible in most common scenarios,
but a few minor adjustments in code might be needed.

.. raw:: html

   </div>


What's new?
------------

Refactor and Cleanup
""""""""""""""""""""""

This major release marks a thorough refactoring and cleanup of the codebase.
We've diligently worked to improve code readability and enhance overall performance.
As a result, you can expect a more efficient and maintainable package.

New authorization
"""""""""""""""""
In ``ibm_watsonx_ai`` 1.0, ``Credentials``, a new class, was introduced and it replaces the credentials dictionary.
For examples and more information, see :doc:`Authentication Cloud <setup_cloud>` and :doc:`Authentication <setup_cpd>`

✅ New approach

.. code:: python

    from ibm_watsonx_ai import APIClient
    from ibm_watsonx_ai import Credentials

    credentials = Credentials(
                       url = "https://us-south.ml.cloud.ibm.com",
                       token = "***********",
                      )

    client = APIClient(credentials)

❌ Old approach

.. code:: python

    from ibm_watsonx_ai import APIClient

    credentials = {
                       "url": "https://us-south.ml.cloud.ibm.com",
                       "token":"***********",
                      }

    client = APIClient(credentials)

Easier project and space setup
""""""""""""""""""""""""""""""

Starting from ``ibm_watsonx_ai`` 1.0, you can set the default space
or project while initializing the APIClient object.

✅ New approach

.. code:: python

    client_project = APIClient(credentials, project_id = project_id)
    client_space = APIClient(credentials, space_id = space_id)

❌ Old approach

.. code:: python

    client_project = APIClient(credentials)
    client_project.set.default_project(project_id)

    client_space = APIClient(credentials)
    client_space.set.default_space(space_id)

Foundation model functions moved under APIClient
""""""""""""""""""""""""""""""""""""""""""""""""

Starting from ``ibm_watsonx_ai`` 1.0, foundation model functions (``get_model_specs``, ``get_custom_model_specs``,
``get_model_lifecycle``, ``get_model_specs_with_prompt_tuning_support``, ``get_embedding_model_specs``) are moved into the ``client.foundation_models`` object.

Old versions of the functions are not removed but will no longer work because they lack authentication.


✅ New approach - Using functions from `client.foundation_models`.

.. code:: python

    client.foundation_models.get_model_specs()

    client.foundation_models.get_custom_model_specs()
    client.foundation_models.get_custom_model_specs(
        model_id='mistralai/Mistral-7B-Instruct-v0.2'
    )
    client.foundation_models.get_custom_model_specs(limit=20)
    client.foundation_models.get_custom_model_specs(limit=20, get_all=True)

    client.foundation_models.get_model_lifecycle(
        model_id="ibm/granite-13b-instruct-v2"
    )

    client.foundation_models.get_model_specs_with_prompt_tuning_support()

    client.foundation_models.get_embeddings_model_specs()

❌ Old approach - Using functions from the `ibm_watsonx_ai.foundation_models` module.

.. code:: python

    from ibm_watsonx_ai.foundation_models import (
        get_model_specs,
        get_custom_models_spec,
        get_model_lifecycle,
        get_model_specs_with_prompt_tuning_support,
        get_embedding_model_specs
    )

    get_model_specs(
        url="https://us-south.ml.cloud.ibm.com"
    )

    get_custom_models_spec(api_client=client)
    get_custom_models_spec(credentials=credentials)
    get_custom_models_spec(api_client=client, model_id='mistralai/Mistral-7B-Instruct-v0.2')
    get_custom_models_spec(api_client=client, limit=20)
    get_custom_models_spec(api_client=client, limit=20, get_all=True)

    get_model_lifecycle(
        url="https://us-south.ml.cloud.ibm.com",
        model_id="ibm/granite-13b-instruct-v2"
    )

    get_model_specs_with_prompt_tuning_support(
        url="https://us-south.ml.cloud.ibm.com"
    )

    get_embedding_model_specs(
        url="https://us-south.ml.cloud.ibm.com"
    )



Breaking changes
""""""""""""""""

* The ``client.<resource>.list()`` methods don't print the table with listed assets. They return the table as ``pandas.DataFrame``. The optional parameter for the ``return_as_df`` methods was removed.

✅ New approach - Access to credential fields as class attributes.

.. code:: python

    conn_list = client.connections.list()  ## table not printed

❌ Old approach - Table with listed resources printed.

.. code:: python

    conn_list = client.connections.list()
    ### Table returned as pandas.DataFrame `conn_list` object and printed output:
    ---------------------------  ------------------------------------  --------------------  ------------------------------------
    NAME                         ID                                    CREATED               DATASOURCE_TYPE_ID
    Connection to COS            71738a79-6585-4f33-bf4a-18907abcf06a  2024-04-25T10:42:23Z  193a97c1-4475-4a19-b90c-295c4fdc6517
    ---------------------------  ------------------------------------  --------------------  ------------------------------------




* Methods and parameters that were marked as deprecated in ``ibm_watsonx_ai v0`` were removed. For example:

✅ New approach - Use the method that replaced the deprecated one, for ``get_uid`` it's ``get_id``

.. code:: python

    asset_id = client.data_assets.get_id(asset_details)

❌ Old approach - Deprecated ``get_uid`` method called

.. code:: python

    client.data_assets.get_uid(asset_details)

*  ``client.credentials`` and ``client.wml_credentials`` returns a ``Credentials`` object instead of a dictionary.

✅ New approach - Access to credential fields as class attributes.

.. code:: python

    from ibm_watsonx_ai import APIClient
    from ibm_watsonx_ai import Credentials

    credentials = Credentials(
                       url = "https://us-south.ml.cloud.ibm.com",
                       token = "***********",
                      )

    client = APIClient(credentials)

    url = client.credentials.url
    # OR
    url = credentials.url

❌ Old approach - Access to credential fields as keys in a dictionary.

.. code:: python

    from ibm_watsonx_ai import APIClient

    credentials = {
                       "url": "https://us-south.ml.cloud.ibm.com",
                       "token":"***********",
                      }
    client = APIClient(credentials)
    url = client.wml_credentials.get('url')


*  Parameter changes in ``service.score(...)`` for online deployment

``service.score(...)`` has an additional ``forecast_window`` parameter added before the ``transaction_id`` parameter.
From ``ibm_watsonx_ai`` 1.0.0,  in the ``service.score(...)`` function, you need to pass all named parameters except for the ``payload`` parameter. 

✅ New approach - named parameters and a new parameter.

.. code:: python

    predictions = service.score({
            "observations": AbstractTestTSAsync.observations,
            "supporting_features": AbstractTestTSAsync.supporting_features,
        },
        forecast_window=1,
        transaction_id=transaction_id,
    )

❌ Old approach - all parameters are not named, the ``forecast_window`` parameter is absent

.. code:: python

    predictions = service.score({
            "observations": AbstractTestTSAsync.observations,
            "supporting_features": AbstractTestTSAsync.supporting_features,
        },
        transaction_id,
    )


Deprecations
""""""""""""

* Initializing ``APIClient`` with ``credentials`` as a dictionary is deprecated.

* All parameters with ``wml`` in the name are deprecated. They were renamed to:
    - ``wml_credentials`` -> ``credentials``
    - ``wml_client`` -> ``api_client``.

* ``id`` naming was aligned in parameters and methods and all ``uid`` were replaced by ``id``. Methods that were using ``uid`` were removed or marked as deprecated.