RESTful Connector
=================

ARES supports integration with REST API deployments via the ``RESTfulConnector`` class. This connector facilitates communication with external services by handling HTTP requests and responses.

Overview
--------

The ``RESTfulConnector`` inherits from the base ``Connector`` class and is designed to be flexible and extensible. You can subclass it to customize API interactions by overriding methods such as:

- ``generate`` and ``batch_generate`` — main entry points for sending prompts and receiving responses.
- ``_extract_message`` — to customize how responses are parsed.
- ``_obtain_header_key`` — to customize how authorization tokens are retrieved.

Examples of subclasses include:

- ``WatsonxRestConnector``
- ``WatsonxAgentConnector``

Basic Configuration
-------------------

ARES provides a default REST API configuration via the ``RESTParams`` dataclass. It will automatically check for the ``REST_API_KEY`` environment variable in your ``.env`` file.

Minimal example:

.. code-block:: yaml

   type: ares.connectors.restful_connector.RESTfulConnector
   name: "my_local_rest_connector"
   api_config:
     api_endpoint: <your deployment endpoint>

Advanced Configuration
----------------------

You can customize headers, request templates, and additional parameters required by your REST API provider.

.. code-block:: yaml

   type: ares.connectors.restful_connector.RESTfulConnector
   name: "my_local_rest_connector"
   api_config:
     api_endpoint: <your deployment endpoint>
     api_key_env_var: MY_API_KEY  # defaults to REST_API_KEY
     timeout: 100
     header:
       Content-Type: "application/json"
       Authorization: "Bearer $HEADER_TAG"  # $HEADER_TAG is replaced with the API key from .env
     request_template:
       messages: "$MESSAGES"  # $MESSAGES is replaced with the input prompt(s)
     other:
       iam_url: <IAM identity token endpoint>
       grant_type: <grant type for IAM token request>
       token_response_timeout: 40

.. note::

   To align the connector with a custom response format, override the ``_extract_message`` method in a subclass.

   If your API requires IAM-based Bearer tokens, override the ``_obtain_header_key`` method.

WatsonX Agent Connector
-----------------------

The ``WatsonxAgentConnector`` is a subclass of ``RESTfulConnector`` that supports querying agent deployments on the WatsonX platform.

Example config: ``example_configs/custom/wx-agent-ares-native.yaml``
It supports both:

- `No-code deployments <https://www.ibm.com/docs/en/watsonx/saas?topic=solutions-agent-lab-beta>`_
- `Watsonx CLI deployments <https://www.ibm.com/watsonx/developer/agents/quickstart/>`_