Adds HttpxOCIAuth AQUA client integration section to documentation.

Author: mrDzurb

ads/aqua/__init__.py

@@ -7,7 +7,7 @@
 from logging import getLogger
 
 from ads import logger, set_auth
-from ads.aqua.client.client import AsyncClient, Client
+from ads.aqua.client.client import AsyncClient, Client, HttpxOCIAuth
 from ads.aqua.common.utils import fetch_service_compartment
 from ads.config import OCI_RESOURCE_PRINCIPAL_VERSION
 

ads/aqua/client/client.py

@@ -51,22 +51,23 @@
 logger = logging.getLogger(__name__)
 
 
-class OCIAuth(httpx.Auth):
+class HttpxOCIAuth(httpx.Auth):
     """
     Custom HTTPX authentication class that uses the OCI Signer for request signing.
 
     Attributes:
         signer (oci.signer.Signer): The OCI signer used to sign requests.
     """
 
-    def __init__(self, signer: oci.signer.Signer):
+    def __init__(self, signer: Optional[oci.signer.Signer] = None):
         """
-        Initialize the OCIAuth instance.
+        Initialize the HttpxOCIAuth instance.
 
         Args:
             signer (oci.signer.Signer): The OCI signer to use for signing requests.
         """
-        self.signer = signer
+
+        self.signer = signer or authutil.default_signer().get("signer")
 
     def auth_flow(self, request: httpx.Request) -> Iterator[httpx.Request]:
         """
@@ -256,7 +257,7 @@ def __init__(
         auth = auth or authutil.default_signer()
         if not callable(auth.get("signer")):
             raise ValueError("Auth object must have a 'signer' callable attribute.")
-        self.auth = OCIAuth(auth["signer"])
+        self.auth = HttpxOCIAuth(auth["signer"])
 
         logger.debug(
             f"Initialized {self.__class__.__name__} with endpoint={self.endpoint}, "
@@ -352,7 +353,7 @@ def __init__(self, *args, **kwargs) -> None:
             **kwargs: Keyword arguments forwarded to BaseClient.
         """
         super().__init__(*args, **kwargs)
-        self._client = httpx.Client(timeout=self.timeout)
+        self._client = httpx.Client(timeout=self.timeout, auth=self.auth)
 
     def is_closed(self) -> bool:
         return self._client.is_closed
@@ -400,7 +401,6 @@ def _request(
             response = self._client.post(
                 self.endpoint,
                 headers=self._prepare_headers(stream=False, headers=headers),
-                auth=self.auth,
                 json=payload,
             )
             logger.debug(f"Received response with status code: {response.status_code}")
@@ -447,7 +447,6 @@ def _stream(
                     "POST",
                     self.endpoint,
                     headers=self._prepare_headers(stream=True, headers=headers),
-                    auth=self.auth,
                     json={**payload, "stream": True},
                 ) as response:
                     try:
@@ -581,7 +580,7 @@ def __init__(self, *args, **kwargs) -> None:
             **kwargs: Keyword arguments forwarded to BaseClient.
         """
         super().__init__(*args, **kwargs)
-        self._client = httpx.AsyncClient(timeout=self.timeout)
+        self._client = httpx.AsyncClient(timeout=self.timeout, auth=self.auth)
 
     def is_closed(self) -> bool:
         return self._client.is_closed
@@ -637,7 +636,6 @@ async def _request(
             response = await self._client.post(
                 self.endpoint,
                 headers=self._prepare_headers(stream=False, headers=headers),
-                auth=self.auth,
                 json=payload,
             )
             logger.debug(f"Received response with status code: {response.status_code}")
@@ -683,7 +681,6 @@ async def _stream(
                     "POST",
                     self.endpoint,
                     headers=self._prepare_headers(stream=True, headers=headers),
-                    auth=self.auth,
                     json={**payload, "stream": True},
                 ) as response:
                     try:

ads/common/auth.py

@@ -20,6 +20,7 @@
 from ads.common import logger
 from ads.common.decorator.deprecate import deprecated
 from ads.common.extended_enum import ExtendedEnum
+from ads.config import OCI_ODSC_SERVICE_ENDPOINT
 
 SECURITY_TOKEN_LEFT_TIME = 600
 
@@ -88,13 +89,15 @@ def set_auth(
     auth: Optional[str] = AuthType.API_KEY,
     oci_config_location: Optional[str] = DEFAULT_LOCATION,
     profile: Optional[str] = DEFAULT_PROFILE,
-    config: Optional[Dict] = {"region": os.environ["OCI_RESOURCE_REGION"]}
-    if os.environ.get("OCI_RESOURCE_REGION")
-    else {},
+    config: Optional[Dict] = (
+        {"region": os.environ["OCI_RESOURCE_REGION"]}
+        if os.environ.get("OCI_RESOURCE_REGION")
+        else {}
+    ),
     signer: Optional[Any] = None,
     signer_callable: Optional[Callable] = None,
-    signer_kwargs: Optional[Dict] = {},
-    client_kwargs: Optional[Dict] = {},
+    signer_kwargs: Optional[Dict] = None,
+    client_kwargs: Optional[Dict] = None,
 ) -> None:
     """
     Sets the default authentication type.
@@ -195,6 +198,12 @@ def set_auth(
     >>> # instance principals authentication dictionary created based on callable with kwargs parameters:
     >>> ads.set_auth(signer_callable=signer_callable, signer_kwargs=signer_kwargs)
     """
+    signer_kwargs = signer_kwargs or {}
+    client_kwargs = {
+        "service_endpoint": OCI_ODSC_SERVICE_ENDPOINT,
+        **(client_kwargs or {}),
+    }
+
     auth_state = AuthState()
 
     valid_auth_keys = AuthFactory.classes.keys()
@@ -258,9 +267,11 @@ def api_keys(
     """
     signer_args = dict(
         oci_config=oci_config if isinstance(oci_config, Dict) else {},
-        oci_config_location=oci_config
-        if isinstance(oci_config, str)
-        else os.path.expanduser(DEFAULT_LOCATION),
+        oci_config_location=(
+            oci_config
+            if isinstance(oci_config, str)
+            else os.path.expanduser(DEFAULT_LOCATION)
+        ),
         oci_key_profile=profile,
         client_kwargs=client_kwargs,
     )
@@ -334,9 +345,11 @@ def security_token(
     """
     signer_args = dict(
         oci_config=oci_config if isinstance(oci_config, Dict) else {},
-        oci_config_location=oci_config
-        if isinstance(oci_config, str)
-        else os.path.expanduser(DEFAULT_LOCATION),
+        oci_config_location=(
+            oci_config
+            if isinstance(oci_config, str)
+            else os.path.expanduser(DEFAULT_LOCATION)
+        ),
         oci_key_profile=profile,
         client_kwargs=client_kwargs,
     )
@@ -485,6 +498,7 @@ def default_signer(client_kwargs: Optional[Dict] = None) -> Dict:
     >>> auth = ads.auth.default_signer() # signer_callable instantiated
     >>> oc.OCIClientFactory(**auth).object_storage # Creates Object storage client using instance principal authentication
     """
+    default_client_kwargs = {"service_endpoint": OCI_ODSC_SERVICE_ENDPOINT}
     auth_state = AuthState()
     if auth_state.oci_signer or auth_state.oci_signer_callable:
         configuration = ads.telemetry.update_oci_client_config(auth_state.oci_config)
@@ -496,6 +510,7 @@ def default_signer(client_kwargs: Optional[Dict] = None) -> Dict:
             "config": configuration,
             "signer": signer,
             "client_kwargs": {
+                **default_client_kwargs,
                 **(auth_state.oci_client_kwargs or {}),
                 **(client_kwargs or {}),
             },
@@ -508,6 +523,7 @@ def default_signer(client_kwargs: Optional[Dict] = None) -> Dict:
             oci_key_profile=auth_state.oci_key_profile,
             oci_config=auth_state.oci_config,
             client_kwargs={
+                **default_client_kwargs,
                 **(auth_state.oci_client_kwargs or {}),
                 **(client_kwargs or {}),
             },

docs/source/user_guide/large_language_model/aqua_client.rst

@@ -129,3 +129,50 @@ The following examples demonstrate how to perform the same operations using the
         input=["one", "two"]
     )
     print(response)
+
+
+HTTPX Client Integration with OCI Authentication (HttpxOCIAuth)
+================================================================
+
+.. versionadded:: 2.13.1
+
+In recent updates to the client, a new class, ``HttpxOCIAuth``, has been introduced.
+This class allows signing of HTTPX requests using OCI signers, making the HTTPX client compatible
+with the LLM models deployed on the OCI Model Deployment service. With this integration, you can use
+HTTPX-based clients with any compatible third-party libraries (e.g., the OpenAi client).
+
+Usage
+-----
+
+**Synchronous HTTPX Client**
+
+.. code-block:: python3
+
+    import httpx
+    import ads
+    from ads.aqua import HttpxOCIAuth
+
+    ads.set_auth(auth="security_token", profile="<replace-with-your-profile>")
+    client = httpx.Client(auth=HttpxOCIAuth())
+
+    response = client.post(
+        url="https://<MD_OCID>/predict",
+        json={
+            "model": "odsc-llm",
+            "prompt": "Tell me a joke."
+        },
+    )
+
+    response.raise_for_status()
+    json_response = response.json()
+
+**Asynchronous HTTPX Client**
+
+.. code-block:: python3
+
+    import httpx
+    import ads
+    from ads.aqua import HttpxOCIAuth
+
+    ads.set_auth(auth="security_token", profile="<replace-with-your-profile>")
+    async_client = httpx.AsyncClient(auth=HttpxOCIAuth())

tests/unitary/with_extras/aqua/test_client.py

@@ -15,20 +15,20 @@
     BaseClient,
     Client,
     ExtendedRequestError,
-    OCIAuth,
+    HttpxOCIAuth,
     _create_retry_decorator,
     _retry_decorator,
     _should_retry_exception,
 )
 from ads.common import auth as authutil
 
 
-class TestOCIAuth:
-    """Unit tests for OCIAuth class."""
+class TestHttpxOCIAuth:
+    """Unit tests for HttpxOCIAuth class."""
 
     def setup_method(self):
         self.signer_mock = Mock()
-        self.oci_auth = OCIAuth(self.signer_mock)
+        self.oci_auth = HttpxOCIAuth(self.signer_mock)
 
     def test_auth_flow(self):
         """Ensures that the auth_flow signs the request correctly."""
@@ -226,7 +226,7 @@ def test_init(self):
         assert self.base_client.retries == self.retries
         assert self.base_client.backoff_factor == self.backoff_factor
         assert self.base_client.timeout == self.timeout
-        assert isinstance(self.base_client.auth, OCIAuth)
+        assert isinstance(self.base_client.auth, HttpxOCIAuth)
 
     def test_init_default_auth(self):
         """Ensures that default auth is used when auth is None."""