.. _sdk_migration:

Migrating from TrustwiseSDK to TrustwiseClient
===============================================

.. note::
   ``TrustwiseSDK`` is deprecated and will be removed in a future release.
   ``TrustwiseClient`` is a superset that covers all metrics, guardrails,
   policies, and the full platform API.

Why Migrate
-----------

- **Deprecation** — ``TrustwiseSDK`` now emits a ``FutureWarning`` on every
  instantiation and will be removed in a future major version.
- **Unified client** — ``TrustwiseClient`` provides agents, guardrails,
  policies, evaluations, risk classification, red-team generation, and
  metrics through a single client.
- **Server-side guardrails** — The old SDK uses local threshold checking;
  the new client leverages platform-managed guardrails with provider
  integrations (AWS Bedrock, Trustwise, etc.).

What Changes
------------

.. list-table::
   :header-rows: 1
   :widths: 40 60

   * - Before (``TrustwiseSDK``)
     - After (``TrustwiseClient``)
   * - ``from trustwise.sdk import TrustwiseSDK``
     - ``from trustwise.sdk.platform import TrustwiseClient``
   * - ``TrustwiseSDK(config)``
     - ``TrustwiseClient(config)``
   * - ``sdk.metrics.faithfulness.evaluate(...)``
     - ``client.metrics.faithfulness(...)``
   * - ``sdk.guardrails(thresholds={...})`` (removed)
     - ``client.guardrails.evaluate(id, ...)`` (server-side)
   * - N/A
     - ``client.agents``, ``client.policies``, ``client.evaluations``, etc.

Both clients use the same :class:`~trustwise.sdk.config.TrustwiseConfig`, so
the configuration step is unchanged.

Step-by-Step
------------

1. Update Imports
~~~~~~~~~~~~~~~~~

.. code-block:: diff

    - from trustwise.sdk import TrustwiseSDK
    + from trustwise.sdk.platform import TrustwiseClient

2. Replace Instantiation
~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: diff

    - sdk = TrustwiseSDK(config)
    + client = TrustwiseClient(config)

3. Update Metric Calls
~~~~~~~~~~~~~~~~~~~~~~

The ``TrustwiseClient`` metrics API uses direct keyword arguments instead of
the ``.evaluate()`` wrapper:

.. code-block:: diff

    - result = sdk.metrics.faithfulness.evaluate(
    -     query="...", response="...", context=[...]
    - )
    + result = client.metrics.faithfulness(
    +     query="...", response="...", context=[...]
    + )

4. Use Server-Side Guardrails
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The old local guardrail system (``sdk.guardrails(...)``) has been removed.
Use platform-managed guardrails instead:

.. code-block:: python

    # Create a guardrail on the platform (once)
    guardrail = client.guardrails.create(
        name="My Guardrail",
        evaluators=[
            {"evaluator": "faithfulness", "threshold": 0.8},
            {"evaluator": "toxicity", "threshold": 0.3},
        ],
    )

    # Evaluate against it
    result = client.guardrails.evaluate(
        guardrail["id"], input="user message", output="assistant reply"
    )

Complete Before / After
-----------------------

**Before:**

.. code-block:: python

    import os
    from trustwise.sdk import TrustwiseSDK
    from trustwise.sdk.config import TrustwiseConfig

    config = TrustwiseConfig(api_key=os.environ["TW_API_KEY"])
    sdk = TrustwiseSDK(config)

    result = sdk.metrics.faithfulness.evaluate(
        query="What is the capital of France?",
        response="The capital of France is Paris.",
        context=[{"chunk_text": "Paris is the capital of France.", "chunk_id": "1"}],
    )
    print(result.score)

**After:**

.. code-block:: python

    import os
    from trustwise.sdk.config import TrustwiseConfig
    from trustwise.sdk.platform import TrustwiseClient

    config = TrustwiseConfig(api_key=os.environ["TW_API_KEY"])
    client = TrustwiseClient(config)

    result = client.metrics.faithfulness(
        query="What is the capital of France?",
        response="The capital of France is Paris.",
        context=[{"chunk_text": "Paris is the capital of France.", "chunk_id": "1"}],
    )
    print(result.score)

    # Plus: access agents, policies, guardrails, evaluations, etc.
    agents = client.agents.list(limit=5)

FAQ
---

**Can I use both clients side-by-side?**
   Yes. They share the same ``TrustwiseConfig`` and can coexist during
   migration. However, ``TrustwiseSDK`` will emit a ``FutureWarning`` each
   time it is instantiated.

**Is there an async version of TrustwiseClient?**
   Not yet. ``TrustwiseClient`` is synchronous. An async counterpart is
   planned for a future release.

**When will TrustwiseSDK be removed?**
   A removal date has not been set yet. Watch the :doc:`changelog` for
   deprecation timeline updates.