liminal-sdk-python 2024.3.3__tar.gz → 2024.3.5__tar.gz

{liminal_sdk_python-2024.3.3 → liminal_sdk_python-2024.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: liminal-sdk-python
-Version: 2024.3.3
+Version: 2024.3.5
 Summary: The Liminal SDK for Python
 Home-page: https://github.com/liminal-ai-security/liminal-sdk-python
 License: Apache-2.0
@@ -25,6 +25,7 @@ Description-Content-Type: text/markdown
 
 # Liminal Python SDK
 
+[![CI][ci-badge]][ci]
 [![PyPI][pypi-badge]][pypi]
 [![Version][version-badge]][version]
 [![License][license-badge]][license]
@@ -34,7 +35,19 @@ for interacting with the Liminal API.
 
 - [Installation](#installation)
 - [Python Versions](#python-versions)
-- [Usage](#usage)
+- [Quickstart](#quickstart)
+- [Initial Authentication](#initial-authentication)
+  - [Microsoft Entra ID](#microsoft-entra-id)
+    - [Device Code Flow](#device-code-flow)
+- [Ongoing Authentication](#ongoing-authentication)
+  - [Manually Interacting with the Refresh Token](#manually-interacting-with-the-refresh-token)
+  - [Creating a Liminal Client from a Stored Refresh Token](#creating-a-liminal-client-from-a-stored-refresh-token)
+- [Endpoints](#endpoints)
+  - [Getting Model Instances](#getting-model-instances)
+  - [Managing Threads](#managing-threads)
+  - [Submitting Prompts](#submitting-prompts)
+- [Connection Pooling](#connection-pooling)
+- [Running Examples](#running-examples)
 - [Contributing](#contributing)
 
 # Installation
@@ -59,18 +72,16 @@ API object is easy:
 import asyncio
 
 from liminal import Client
-from liminal.endpoints.auth import MicrosoftAuthProvider
+from liminal.auth.microsoft.device_code_flow import DeviceCodeFlowProvider
 
 
 async def main() -> None:
     """Create the aiohttp session and run the example."""
-    logging.basicConfig(level=logging.DEBUG)
-
     # Create an auth provider to authenticate the user:
-    microsoft_auth_provider = MicrosoftAuthProvider("<TENANT_ID>", "<CLIENT_ID>")
+    auth_provider = DeviceCodeFlowProvider("<TENANT_ID>", "<CLIENT_ID>")
 
     # Create the liminal SDK instance:
-    liminal = Client(microsoft_auth_provider, "<LIMINAL_API_SERVER_URL>")
+    liminal = Client(auth_provider, "<LIMINAL_API_SERVER_URL>")
 
 
 asyncio.run(main())
@@ -88,13 +99,15 @@ the following auth providers are supported:
 
 ## Microsoft Entra ID
 
-Liminal authenticates with Microsoft Entra ID via an
+### Device Code Flow
+
+This authentication process with Microsoft Entra ID involves an
 [OAuth 2.0 Device Authorization Grant][oauth-device-auth-grant]. This flow requires you
 to start your app, retrieve a device code from the logs produced by this SDK, and
 provide that code to Microsoft via a web browser. Once you complete the login process,
 the SDK will be authenticated for use with your Liminal instance.
 
-### Finding your Entra ID Tenant and Client IDs
+To authenticate with this flow, you will need an Entra ID client and tenant ID:
 
 - Log into your [Azure portal][azure-portal].
 - Navigate to `Microsoft Entra ID`.
@@ -103,8 +116,6 @@ the SDK will be authenticated for use with your Liminal instance.
 - In the `Overview` of the registration, look for the `Application (client) ID` and
   `Directory (tenant) ID` values.
 
-### Authenticating Against Entra ID
-
 With a client ID and tenant ID, you can create a Liminal client object and authenticate
 it:
 
@@ -112,18 +123,16 @@ it:
 import asyncio
 
 from liminal import Client
-from liminal.endpoints.auth import MicrosoftAuthProvider
+from liminal.auth.microsoft.device_code_flow import DeviceCodeFlowProvider
 
 
 async def main() -> None:
     """Create the aiohttp session and run the example."""
-    logging.basicConfig(level=logging.DEBUG)
-
     # Create an auth provider to authenticate the user:
-    microsoft_auth_provider = MicrosoftAuthProvider("<TENANT_ID>", "<CLIENT_ID>")
+    auth_provider = DeviceCodeFlowProvider("<TENANT_ID>", "<CLIENT_ID>")
 
     # Create the liminal SDK instance and authenticate it:
-    liminal = Client(microsoft_auth_provider, "<LIMINAL_API_SERVER_URL>")
+    liminal = Client(auth_provider, "<LIMINAL_API_SERVER_URL>")
     await liminal.authenticate_from_auth_provider()
 
 
@@ -165,15 +174,13 @@ callback at any time.
 import asyncio
 
 from liminal import Client
-from liminal.endpoints.auth import MicrosoftAuthProvider
+from liminal.auth.microsoft.device_code_flow import DeviceCodeFlowProvider
 
 
 async def main() -> None:
     """Create the aiohttp session and run the example."""
-    logging.basicConfig(level=logging.DEBUG)
-
     # Create an auth provider to authenticate the user:
-    microsoft_auth_provider = MicrosoftAuthProvider("<TENANT_ID>", "<CLIENT_ID>")
+    auth_provider = DeviceCodeFlowProvider("<TENANT_ID>", "<CLIENT_ID>")
 
     # Create the liminal SDK instance and authenticate it:
     liminal = Client(microsoft_auth_provider, "<LIMINAL_API_SERVER_URL>")
@@ -195,7 +202,32 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
-# Getting Model Instances
+## Creating a Liminal Client from a Stored Refresh Token
+
+Assuming you have a stored refresh token (collected from the callback process shown
+above), it is simple to create a new Limina client using that token:
+
+```python
+import asyncio
+
+from liminal import Client
+
+
+async def main() -> None:
+    """Create the aiohttp session and run the example."""
+    # Retrieve your stored refresh_token:
+    refresh_token = "12345"
+
+    # Create the client:
+    liminal = await client.authenticate_from_refresh_token(refresh_token=refresh_token)
+
+
+asyncio.run(main())
+```
+
+# Endpoints
+
+## Getting Model Instances
 
 Every LLM instance connected in the Liminal admin dashboard is referred to as a "model
 instance." The SDK provides several methods to interact with model instances:
@@ -204,7 +236,7 @@ instance." The SDK provides several methods to interact with model instances:
 import asyncio
 
 from liminal import Client
-from liminal.endpoints.auth import MicrosoftAuthProvider
+from liminal.auth.microsoft.device_code_flow import DeviceCodeFlowProvider
 
 
 async def main() -> None:
@@ -222,7 +254,7 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
-# Managing Threads
+## Managing Threads
 
 Threads are conversations with an LLM instance:
 
@@ -230,7 +262,7 @@ Threads are conversations with an LLM instance:
 import asyncio
 
 from liminal import Client
-from liminal.endpoints.auth import MicrosoftAuthProvider
+from liminal.auth.microsoft.device_code_flow import DeviceCodeFlowProvider
 
 
 async def main() -> None:
@@ -259,7 +291,7 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
-# Submitting Prompts
+## Submitting Prompts
 
 Submitting prompts is easy:
 
@@ -267,7 +299,7 @@ Submitting prompts is easy:
 import asyncio
 
 from liminal import Client
-from liminal.endpoints.auth import MicrosoftAuthProvider
+from liminal.auth.microsoft.device_code_flow import DeviceCodeFlowProvider
 
 
 async def main() -> None:
@@ -306,6 +338,40 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
+# Connection Pooling
+
+By default, the library creates a new connection to the Liminal API server with each
+coroutine. If you are calling a large number of coroutines (or merely want to squeeze
+out every second of runtime savings possible), an [`httpx`][httpx] `AsyncClient` can be
+used for connection pooling:
+
+```python
+import asyncio
+
+from liminal import Client
+from liminal.auth.microsoft.device_code_flow import DeviceCodeFlowProvider
+
+
+async def main() -> None:
+    # Create an auth provider to authenticate the user:
+    microsoft_auth_provider = MicrosoftAuthProvider("<TENANT_ID>", "<CLIENT_ID>")
+
+    # Create the liminal SDK instance with a shared HTTPX AsyncClient:
+    async with httpx.AsyncClient() as client:
+        liminal = Client(
+            microsoft_auth_provider, "<LIMINAL_API_SERVER_URL>", httpx_client=client
+        )
+
+        # Get to work!
+        # ...
+
+
+asyncio.run(main())
+```
+
+Check out the examples, the tests, and the source files themselves for method
+signatures and more examples.
+
 # Running Examples
 
 You can see examples of how to use this SDK via the [`examples`][examples] folder in
@@ -328,7 +394,7 @@ Thanks to all of [our contributors][contributors] so far!
 2. [Fork the repository][fork].
 3. (_optional, but highly recommended_) Create a virtual environment: `python3 -m venv .venv`
 4. (_optional, but highly recommended_) Enter the virtual environment: `source ./.venv/bin/activate`
-5. Install the dev environment: `script/setup`
+5. Install the dev environment: `./scripts/setup.sh`
 6. Code your new feature or bug fix on a new branch.
 7. Write tests that cover your new functionality.
 8. Run tests and ensure 100% code coverage: `poetry run pytest --cov liminal tests`
@@ -336,10 +402,12 @@ Thanks to all of [our contributors][contributors] so far!
 10. Submit a pull request!
 
 [azure-portal]: https://portal.azure.com
+[ci-badge]: https://img.shields.io/github/actions/workflow/status/liminal-ai-security/liminal-sdk-python/test.yml
 [ci]: https://github.com/liminal-ai-security/liminal-sdk-python/actions
 [contributors]: https://github.com/liminal-ai-security/liminal-sdk-python/graphs/contributors
 [examples]: https://github.com/liminal-ai-security/liminal-sdk-python/tree/development/examples
 [fork]: https://github.com/liminal-ai-security/liminal-sdk-python/fork
+[httpx]: https://www.python-httpx.org/
 [issues]: https://github.com/liminal-ai-security/liminal-sdk-python/issues
 [license-badge]: https://img.shields.io/pypi/l/liminal-sdk-python.svg
 [license]: https://github.com/liminal-ai-security/liminal-sdk-python/blob/main/LICENSE

{liminal_sdk_python-2024.3.3 → liminal_sdk_python-2024.3.5}/README.md

@@ -1,5 +1,6 @@
 # Liminal Python SDK
 
+[![CI][ci-badge]][ci]
 [![PyPI][pypi-badge]][pypi]
 [![Version][version-badge]][version]
 [![License][license-badge]][license]
@@ -9,7 +10,19 @@ for interacting with the Liminal API.
 
 - [Installation](#installation)
 - [Python Versions](#python-versions)
-- [Usage](#usage)
+- [Quickstart](#quickstart)
+- [Initial Authentication](#initial-authentication)
+  - [Microsoft Entra ID](#microsoft-entra-id)
+    - [Device Code Flow](#device-code-flow)
+- [Ongoing Authentication](#ongoing-authentication)
+  - [Manually Interacting with the Refresh Token](#manually-interacting-with-the-refresh-token)
+  - [Creating a Liminal Client from a Stored Refresh Token](#creating-a-liminal-client-from-a-stored-refresh-token)
+- [Endpoints](#endpoints)
+  - [Getting Model Instances](#getting-model-instances)
+  - [Managing Threads](#managing-threads)
+  - [Submitting Prompts](#submitting-prompts)
+- [Connection Pooling](#connection-pooling)
+- [Running Examples](#running-examples)
 - [Contributing](#contributing)
 
 # Installation
@@ -34,18 +47,16 @@ API object is easy:
 import asyncio
 
 from liminal import Client
-from liminal.endpoints.auth import MicrosoftAuthProvider
+from liminal.auth.microsoft.device_code_flow import DeviceCodeFlowProvider
 
 
 async def main() -> None:
     """Create the aiohttp session and run the example."""
-    logging.basicConfig(level=logging.DEBUG)
-
     # Create an auth provider to authenticate the user:
-    microsoft_auth_provider = MicrosoftAuthProvider("<TENANT_ID>", "<CLIENT_ID>")
+    auth_provider = DeviceCodeFlowProvider("<TENANT_ID>", "<CLIENT_ID>")
 
     # Create the liminal SDK instance:
-    liminal = Client(microsoft_auth_provider, "<LIMINAL_API_SERVER_URL>")
+    liminal = Client(auth_provider, "<LIMINAL_API_SERVER_URL>")
 
 
 asyncio.run(main())
@@ -63,13 +74,15 @@ the following auth providers are supported:
 
 ## Microsoft Entra ID
 
-Liminal authenticates with Microsoft Entra ID via an
+### Device Code Flow
+
+This authentication process with Microsoft Entra ID involves an
 [OAuth 2.0 Device Authorization Grant][oauth-device-auth-grant]. This flow requires you
 to start your app, retrieve a device code from the logs produced by this SDK, and
 provide that code to Microsoft via a web browser. Once you complete the login process,
 the SDK will be authenticated for use with your Liminal instance.
 
-### Finding your Entra ID Tenant and Client IDs
+To authenticate with this flow, you will need an Entra ID client and tenant ID:
 
 - Log into your [Azure portal][azure-portal].
 - Navigate to `Microsoft Entra ID`.
@@ -78,8 +91,6 @@ the SDK will be authenticated for use with your Liminal instance.
 - In the `Overview` of the registration, look for the `Application (client) ID` and
   `Directory (tenant) ID` values.
 
-### Authenticating Against Entra ID
-
 With a client ID and tenant ID, you can create a Liminal client object and authenticate
 it:
 
@@ -87,18 +98,16 @@ it:
 import asyncio
 
 from liminal import Client
-from liminal.endpoints.auth import MicrosoftAuthProvider
+from liminal.auth.microsoft.device_code_flow import DeviceCodeFlowProvider
 
 
 async def main() -> None:
     """Create the aiohttp session and run the example."""
-    logging.basicConfig(level=logging.DEBUG)
-
     # Create an auth provider to authenticate the user:
-    microsoft_auth_provider = MicrosoftAuthProvider("<TENANT_ID>", "<CLIENT_ID>")
+    auth_provider = DeviceCodeFlowProvider("<TENANT_ID>", "<CLIENT_ID>")
 
     # Create the liminal SDK instance and authenticate it:
-    liminal = Client(microsoft_auth_provider, "<LIMINAL_API_SERVER_URL>")
+    liminal = Client(auth_provider, "<LIMINAL_API_SERVER_URL>")
     await liminal.authenticate_from_auth_provider()
 
 
@@ -140,15 +149,13 @@ callback at any time.
 import asyncio
 
 from liminal import Client
-from liminal.endpoints.auth import MicrosoftAuthProvider
+from liminal.auth.microsoft.device_code_flow import DeviceCodeFlowProvider
 
 
 async def main() -> None:
     """Create the aiohttp session and run the example."""
-    logging.basicConfig(level=logging.DEBUG)
-
     # Create an auth provider to authenticate the user:
-    microsoft_auth_provider = MicrosoftAuthProvider("<TENANT_ID>", "<CLIENT_ID>")
+    auth_provider = DeviceCodeFlowProvider("<TENANT_ID>", "<CLIENT_ID>")
 
     # Create the liminal SDK instance and authenticate it:
     liminal = Client(microsoft_auth_provider, "<LIMINAL_API_SERVER_URL>")
@@ -170,7 +177,32 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
-# Getting Model Instances
+## Creating a Liminal Client from a Stored Refresh Token
+
+Assuming you have a stored refresh token (collected from the callback process shown
+above), it is simple to create a new Limina client using that token:
+
+```python
+import asyncio
+
+from liminal import Client
+
+
+async def main() -> None:
+    """Create the aiohttp session and run the example."""
+    # Retrieve your stored refresh_token:
+    refresh_token = "12345"
+
+    # Create the client:
+    liminal = await client.authenticate_from_refresh_token(refresh_token=refresh_token)
+
+
+asyncio.run(main())
+```
+
+# Endpoints
+
+## Getting Model Instances
 
 Every LLM instance connected in the Liminal admin dashboard is referred to as a "model
 instance." The SDK provides several methods to interact with model instances:
@@ -179,7 +211,7 @@ instance." The SDK provides several methods to interact with model instances:
 import asyncio
 
 from liminal import Client
-from liminal.endpoints.auth import MicrosoftAuthProvider
+from liminal.auth.microsoft.device_code_flow import DeviceCodeFlowProvider
 
 
 async def main() -> None:
@@ -197,7 +229,7 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
-# Managing Threads
+## Managing Threads
 
 Threads are conversations with an LLM instance:
 
@@ -205,7 +237,7 @@ Threads are conversations with an LLM instance:
 import asyncio
 
 from liminal import Client
-from liminal.endpoints.auth import MicrosoftAuthProvider
+from liminal.auth.microsoft.device_code_flow import DeviceCodeFlowProvider
 
 
 async def main() -> None:
@@ -234,7 +266,7 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
-# Submitting Prompts
+## Submitting Prompts
 
 Submitting prompts is easy:
 
@@ -242,7 +274,7 @@ Submitting prompts is easy:
 import asyncio
 
 from liminal import Client
-from liminal.endpoints.auth import MicrosoftAuthProvider
+from liminal.auth.microsoft.device_code_flow import DeviceCodeFlowProvider
 
 
 async def main() -> None:
@@ -281,6 +313,40 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
+# Connection Pooling
+
+By default, the library creates a new connection to the Liminal API server with each
+coroutine. If you are calling a large number of coroutines (or merely want to squeeze
+out every second of runtime savings possible), an [`httpx`][httpx] `AsyncClient` can be
+used for connection pooling:
+
+```python
+import asyncio
+
+from liminal import Client
+from liminal.auth.microsoft.device_code_flow import DeviceCodeFlowProvider
+
+
+async def main() -> None:
+    # Create an auth provider to authenticate the user:
+    microsoft_auth_provider = MicrosoftAuthProvider("<TENANT_ID>", "<CLIENT_ID>")
+
+    # Create the liminal SDK instance with a shared HTTPX AsyncClient:
+    async with httpx.AsyncClient() as client:
+        liminal = Client(
+            microsoft_auth_provider, "<LIMINAL_API_SERVER_URL>", httpx_client=client
+        )
+
+        # Get to work!
+        # ...
+
+
+asyncio.run(main())
+```
+
+Check out the examples, the tests, and the source files themselves for method
+signatures and more examples.
+
 # Running Examples
 
 You can see examples of how to use this SDK via the [`examples`][examples] folder in
@@ -303,7 +369,7 @@ Thanks to all of [our contributors][contributors] so far!
 2. [Fork the repository][fork].
 3. (_optional, but highly recommended_) Create a virtual environment: `python3 -m venv .venv`
 4. (_optional, but highly recommended_) Enter the virtual environment: `source ./.venv/bin/activate`
-5. Install the dev environment: `script/setup`
+5. Install the dev environment: `./scripts/setup.sh`
 6. Code your new feature or bug fix on a new branch.
 7. Write tests that cover your new functionality.
 8. Run tests and ensure 100% code coverage: `poetry run pytest --cov liminal tests`
@@ -311,10 +377,12 @@ Thanks to all of [our contributors][contributors] so far!
 10. Submit a pull request!
 
 [azure-portal]: https://portal.azure.com
+[ci-badge]: https://img.shields.io/github/actions/workflow/status/liminal-ai-security/liminal-sdk-python/test.yml
 [ci]: https://github.com/liminal-ai-security/liminal-sdk-python/actions
 [contributors]: https://github.com/liminal-ai-security/liminal-sdk-python/graphs/contributors
 [examples]: https://github.com/liminal-ai-security/liminal-sdk-python/tree/development/examples
 [fork]: https://github.com/liminal-ai-security/liminal-sdk-python/fork
+[httpx]: https://www.python-httpx.org/
 [issues]: https://github.com/liminal-ai-security/liminal-sdk-python/issues
 [license-badge]: https://img.shields.io/pypi/l/liminal-sdk-python.svg
 [license]: https://github.com/liminal-ai-security/liminal-sdk-python/blob/main/LICENSE

liminal_sdk_python-2024.3.5/liminal/auth/__init__.py

@@ -0,0 +1,17 @@
+"""Define auth providers."""
+
+
+class AuthProvider:
+    """Define an auth provider abstract base class."""
+
+    async def get_access_token(self) -> str:
+        """Retrieve an access token from the auth provider.
+
+        The working principle here is that the auth provider will return an access
+        token that can be used to authenticate with the Liminal API server.
+
+        Returns:
+            The access token.
+
+        """
+        raise NotImplementedError

liminal_sdk_python-2024.3.5/liminal/auth/microsoft/__init__.py

@@ -0,0 +1 @@
+"""Define Microsoft providers."""

liminal_sdk_python-2024.3.3/liminal/endpoints/auth/__init__.py → liminal_sdk_python-2024.3.5/liminal/auth/microsoft/device_code_flow.py

@@ -1,25 +1,28 @@
-"""Define the auth endpoint."""
+"""Define Microsoft providers."""
+
+from __future__ import annotations
 
 import asyncio
+from typing import Final
 
 from msal import PublicClientApplication
 
-from liminal.const import LOGGER
-from liminal.endpoints.auth.models import (
-    AuthProvider,
+from liminal.auth import AuthProvider
+from liminal.auth.microsoft.models import (
     MSALCacheTokenResponse,
     MSALIdentityProviderTokenResponse,
 )
+from liminal.const import LOGGER
 from liminal.errors import AuthError
 
-DEFAULT_AUTH_CHALLENGE_TIMEOUT = 60
+DEFAULT_AUTH_CHALLENGE_TIMEOUT: Final[int] = 60
 
 
-class MicrosoftAuthProvider(AuthProvider):
+class DeviceCodeFlowProvider(AuthProvider):
     """Define a Microsoft auth provider."""
 
-    AUTHORITY_URL = "https://login.microsoftonline.com"
-    DEFAULT_SCOPES = ["User.Read"]
+    AUTHORITY_URL: Final[str] = "https://login.microsoftonline.com"
+    DEFAULT_SCOPES: Final[list[str]] = ["User.Read"]
 
     def __init__(
         self,
@@ -76,7 +79,8 @@ class MicrosoftAuthProvider(AuthProvider):
             # Setting the flow to expire immediately will effectively kill the future
             # that we're awaiting:
             flow["expires_at"] = 0
-            raise AuthError("Timed out waiting for authentication challenge") from err
+            msg = "Timed out waiting for authentication challenge"
+            raise AuthError(msg) from err
 
         identity_provider_response = MSALIdentityProviderTokenResponse.from_dict(result)
         return identity_provider_response.access_token

{liminal_sdk_python-2024.3.3/liminal/endpoints/auth → liminal_sdk_python-2024.3.5/liminal/auth/microsoft}/models.py

@@ -2,31 +2,14 @@
 
 from __future__ import annotations
 
-from abc import ABC
 from dataclasses import dataclass
 from typing import Literal
 
-from liminal.helpers.model import BaseModel
-
-
-class AuthProvider(ABC):
-    """Define an auth provider abstract base class."""
-
-    async def get_access_token(self) -> str:
-        """Retrieve an access token from the auth provider.
-
-        The working principle here is that the auth provider will return an access
-        token that can be used to authenticate with the Liminal API server.
-
-        Returns:
-            The access token.
-
-        """
-        raise NotImplementedError
+from liminal.helpers.model import BaseResponseModel
 
 
 @dataclass(frozen=True, kw_only=True)
-class MSALCacheTokenResponse(BaseModel):
+class MSALCacheTokenResponse(BaseResponseModel):
     """Define an MSAL token response from Entra ID."""
 
     token_type: Literal["Bearer"]
@@ -36,7 +19,7 @@ class MSALCacheTokenResponse(BaseModel):
 
 
 @dataclass(frozen=True, kw_only=True)
-class MSALIdentityProviderTokenResponse(BaseModel):
+class MSALIdentityProviderTokenResponse(BaseResponseModel):
     """Define an MSAL token response from the local in-memory cache."""
 
     token_type: Literal["Bearer"]