feat(convo): add async support for conversation model operations

- add AsyncConversationModel class for async individual model operations
- add AsyncConversationsModels class for async models collection operations
- add async tests for conversation model and models functionality
- add async fixtures for testing async conversation model operations

Author: tharropoulos

src/typesense/async_conversation_model.py

@@ -0,0 +1,104 @@
+"""
+This module provides async functionality for managing individual conversation models in Typesense.
+
+It contains the AsyncConversationModel class, which allows for retrieving, updating, and deleting
+conversation models asynchronously.
+
+Classes:
+    AsyncConversationModel: Manages async operations on a single conversation model in the Typesense API.
+
+Dependencies:
+    - typesense.async_api_call: Provides the AsyncApiCall class for making async API requests.
+    - typesense.types.conversations_model: Provides ConversationModelCreateSchema, ConversationModelDeleteSchema, and ConversationModelSchema types.
+
+Note: This module uses conditional imports to support both Python 3.11+ and earlier versions.
+"""
+
+from typesense.async_api_call import AsyncApiCall
+from typesense.types.conversations_model import (
+    ConversationModelCreateSchema,
+    ConversationModelDeleteSchema,
+    ConversationModelSchema,
+)
+
+
+class AsyncConversationModel:
+    """
+    Manages async operations on a single conversation model in the Typesense API.
+
+    This class provides async methods to retrieve, update, and delete a conversation model.
+
+    Attributes:
+        model_id (str): The ID of the conversation model.
+        api_call (AsyncApiCall): The AsyncApiCall instance for making async API requests.
+    """
+
+    def __init__(self, api_call: AsyncApiCall, model_id: str) -> None:
+        """
+        Initialize the AsyncConversationModel instance.
+
+        Args:
+            api_call (AsyncApiCall): The AsyncApiCall instance for making async API requests.
+            model_id (str): The ID of the conversation model.
+        """
+        self.model_id = model_id
+        self.api_call = api_call
+
+    async def retrieve(self) -> ConversationModelSchema:
+        """
+        Retrieve this specific conversation model.
+
+        Returns:
+            ConversationModelSchema: The schema containing the conversation model details.
+        """
+        response: ConversationModelSchema = await self.api_call.get(
+            self._endpoint_path,
+            as_json=True,
+            entity_type=ConversationModelSchema,
+        )
+        return response
+
+    async def update(
+        self, model: ConversationModelCreateSchema
+    ) -> ConversationModelSchema:
+        """
+        Update this specific conversation model.
+
+        Args:
+            model (ConversationModelCreateSchema):
+              The schema containing the updated model details.
+
+        Returns:
+            ConversationModelSchema: The schema containing the updated conversation model.
+        """
+        response: ConversationModelSchema = await self.api_call.put(
+            self._endpoint_path,
+            body=model,
+            entity_type=ConversationModelSchema,
+        )
+        return response
+
+    async def delete(self) -> ConversationModelDeleteSchema:
+        """
+        Delete this specific conversation model.
+
+        Returns:
+            ConversationModelDeleteSchema: The schema containing the deletion response.
+        """
+        response: ConversationModelDeleteSchema = await self.api_call.delete(
+            self._endpoint_path,
+            entity_type=ConversationModelDeleteSchema,
+        )
+        return response
+
+    @property
+    def _endpoint_path(self) -> str:
+        """
+        Construct the API endpoint path for this specific conversation model.
+
+        Returns:
+            str: The constructed endpoint path.
+        """
+        from typesense.async_conversations_models import AsyncConversationsModels
+
+        return "/".join([AsyncConversationsModels.resource_path, self.model_id])

src/typesense/async_conversations_models.py

@@ -0,0 +1,131 @@
+"""
+This module provides async functionality for managing conversation models in Typesense.
+
+It contains the AsyncConversationsModels class, which allows for creating, retrieving, and
+accessing individual conversation models asynchronously.
+
+Classes:
+    AsyncConversationsModels: Manages conversation models in the Typesense API (async).
+
+Dependencies:
+    - typesense.async_api_call: Provides the AsyncApiCall class for making async API requests.
+    - typesense.async_conversation_model: Provides the AsyncConversationModel class for individual conversation model operations.
+    - typesense.types.conversations_model: Provides ConversationModelCreateSchema and ConversationModelSchema types.
+
+Note: This module uses conditional imports to support both Python 3.11+ and earlier versions.
+"""
+
+import sys
+
+from typesense.async_api_call import AsyncApiCall
+from typesense.async_conversation_model import AsyncConversationModel
+from typesense.types.conversations_model import (
+    ConversationModelCreateSchema,
+    ConversationModelSchema,
+)
+
+if sys.version_info >= (3, 11):
+    import typing
+else:
+    import typing_extensions as typing
+
+
+class AsyncConversationsModels:
+    """
+    Manages conversation models in the Typesense API (async).
+
+    This class provides async methods to create, retrieve, and access individual conversation models.
+
+    Attributes:
+        resource_path (str): The API endpoint path for conversation models operations.
+        api_call (AsyncApiCall): The AsyncApiCall instance for making async API requests.
+        conversations_models (Dict[str, AsyncConversationModel]):
+            A dictionary of AsyncConversationModel instances, keyed by model ID.
+    """
+
+    resource_path: typing.Final[str] = "/conversations/models"
+
+    def __init__(self, api_call: AsyncApiCall) -> None:
+        """
+        Initialize the AsyncConversationsModels instance.
+
+        Args:
+            api_call (AsyncApiCall): The AsyncApiCall instance for making async API requests.
+        """
+        self.api_call = api_call
+        self.conversations_models: typing.Dict[str, AsyncConversationModel] = {}
+
+    def __getitem__(self, model_id: str) -> AsyncConversationModel:
+        """
+        Get or create an AsyncConversationModel instance for a given model ID.
+
+        This method allows accessing conversation models using dictionary-like syntax.
+        If the AsyncConversationModel instance doesn't exist, it creates a new one.
+
+        Args:
+            model_id (str): The ID of the conversation model.
+
+        Returns:
+            AsyncConversationModel: The AsyncConversationModel instance for the specified model ID.
+
+        Example:
+            >>> conversations_models = AsyncConversationsModels(async_api_call)
+            >>> model = conversations_models["model_id"]
+        """
+        if model_id not in self.conversations_models:
+            self.conversations_models[model_id] = AsyncConversationModel(
+                self.api_call,
+                model_id,
+            )
+        return self.conversations_models[model_id]
+
+    async def create(
+        self, model: ConversationModelCreateSchema
+    ) -> ConversationModelSchema:
+        """
+        Create a new conversation model.
+
+        Args:
+            model (ConversationModelCreateSchema):
+                The schema for creating the conversation model.
+
+        Returns:
+            ConversationModelSchema: The created conversation model.
+
+        Example:
+            >>> conversations_models = AsyncConversationsModels(async_api_call)
+            >>> model = await conversations_models.create(
+            ...     {
+            ...         "api_key": "key",
+            ...         "model_name": "openai/gpt-3.5-turbo",
+            ...         "history_collection": "conversation_store",
+            ...     }
+            ... )
+        """
+        response: ConversationModelSchema = await self.api_call.post(
+            endpoint=AsyncConversationsModels.resource_path,
+            entity_type=ConversationModelSchema,
+            as_json=True,
+            body=model,
+        )
+        return response
+
+    async def retrieve(self) -> typing.List[ConversationModelSchema]:
+        """
+        Retrieve all conversation models.
+
+        Returns:
+            List[ConversationModelSchema]: A list of all conversation models.
+
+        Example:
+            >>> conversations_models = AsyncConversationsModels(async_api_call)
+            >>> all_models = await conversations_models.retrieve()
+            >>> for model in all_models:
+            ...     print(model["id"])
+        """
+        response: typing.List[ConversationModelSchema] = await self.api_call.get(
+            endpoint=AsyncConversationsModels.resource_path,
+            entity_type=typing.List[ConversationModelSchema],
+            as_json=True,
+        )
+        return response

tests/conversation_model_test.py

@@ -11,6 +11,9 @@
     assert_to_contain_keys,
 )
 from typesense.api_call import ApiCall
+from typesense.async_api_call import AsyncApiCall
+from typesense.async_conversation_model import AsyncConversationModel
+from typesense.async_conversations_models import AsyncConversationsModels
 from typesense.conversation_model import ConversationModel
 from typesense.conversations_models import ConversationsModels
 from typesense.types.conversations_model import (
@@ -44,6 +47,29 @@ def test_init(fake_api_call: ApiCall) -> None:
     )
 
 
+def test_init_async(fake_async_api_call: AsyncApiCall) -> None:
+    """Test that the AsyncConversationModel object is initialized correctly."""
+    conversation_model = AsyncConversationModel(
+        fake_async_api_call,
+        "conversation_model_id",
+    )
+
+    assert conversation_model.model_id == "conversation_model_id"
+    assert_match_object(conversation_model.api_call, fake_async_api_call)
+    assert_object_lists_match(
+        conversation_model.api_call.node_manager.nodes,
+        fake_async_api_call.node_manager.nodes,
+    )
+    assert_match_object(
+        conversation_model.api_call.config.nearest_node,
+        fake_async_api_call.config.nearest_node,
+    )
+    assert (
+        conversation_model._endpoint_path  # noqa: WPS437
+        == "/conversations/models/conversation_model_id"
+    )
+
+
 @pytest.mark.open_ai
 def test_actual_retrieve(
     actual_conversations_models: ConversationsModels,
@@ -113,3 +139,80 @@ def test_actual_delete(
     assert response.get("system_prompt") == "This is a system prompt"
     assert response.get("id") == create_conversations_model
     assert response.get("id") == create_conversations_model
+
+
+@pytest.mark.open_ai
+async def test_actual_retrieve_async(
+    actual_async_conversations_models: AsyncConversationsModels,
+    delete_all_conversations_models: None,
+    create_conversations_model: str,
+) -> None:
+    """Test it can retrieve a conversation_model from Typesense Server."""
+    response = await actual_async_conversations_models[
+        create_conversations_model
+    ].retrieve()
+
+    assert_to_contain_keys(
+        response,
+        ["id", "model_name", "system_prompt", "max_bytes", "api_key"],
+    )
+    assert response.get("id") == create_conversations_model
+
+
+@pytest.mark.open_ai
+async def test_actual_update_async(
+    actual_async_conversations_models: AsyncConversationsModels,
+    delete_all_conversations_models: None,
+    create_conversations_model: str,
+) -> None:
+    """Test that it can update a conversation_model from Typesense Server."""
+    response = await actual_async_conversations_models[
+        create_conversations_model
+    ].update(
+        {"system_prompt": "This is a new system prompt"},
+    )
+
+    assert_to_contain_keys(
+        response,
+        [
+            "id",
+            "model_name",
+            "system_prompt",
+            "max_bytes",
+            "api_key",
+            "ttl",
+            "history_collection",
+        ],
+    )
+
+    assert response.get("system_prompt") == "This is a new system prompt"
+    assert response.get("id") == create_conversations_model
+
+
+@pytest.mark.open_ai
+async def test_actual_delete_async(
+    actual_async_conversations_models: AsyncConversationsModels,
+    delete_all_conversations_models: None,
+    create_conversations_model: str,
+) -> None:
+    """Test that it can delete an conversation_model from Typesense Server."""
+    response = await actual_async_conversations_models[
+        create_conversations_model
+    ].delete()
+
+    assert_to_contain_keys(
+        response,
+        [
+            "id",
+            "model_name",
+            "system_prompt",
+            "max_bytes",
+            "api_key",
+            "ttl",
+            "history_collection",
+        ],
+    )
+
+    assert response.get("system_prompt") == "This is a system prompt"
+    assert response.get("id") == create_conversations_model
+    assert response.get("id") == create_conversations_model