airia 0.1.13__py3-none-any.whl → 0.1.15__py3-none-any.whl

airia/client/conversations/base_conversations.py

@@ -0,0 +1,135 @@
+from typing import Any, Dict, Optional, Union
+from urllib.parse import urljoin
+
+from ...types._api_version import ApiVersion
+from .._request_handler import AsyncRequestHandler, RequestHandler
+
+
+class BaseConversations:
+    def __init__(self, request_handler: Union[RequestHandler, AsyncRequestHandler]):
+        self._request_handler = request_handler
+
+    def _pre_create_conversation(
+        self,
+        user_id: str,
+        title: Optional[str] = None,
+        deployment_id: Optional[str] = None,
+        data_source_files: Dict[str, Any] = {},
+        is_bookmarked: bool = False,
+        correlation_id: Optional[str] = None,
+        api_version: str = ApiVersion.V1.value,
+    ):
+        """
+        Prepare request data for creating a new conversation.
+
+        This internal method constructs the URL and payload for conversation creation
+        requests, including all conversation metadata and settings.
+
+        Args:
+            user_id: ID of the user creating the conversation
+            title: Optional title for the conversation
+            deployment_id: Optional deployment to associate with the conversation
+            data_source_files: Optional data source files configuration
+            is_bookmarked: Whether the conversation should be bookmarked
+            correlation_id: Optional correlation ID for tracing
+            api_version: API version to use for the request
+
+        Returns:
+            RequestData: Prepared request data for the conversation creation endpoint
+
+        Raises:
+            ValueError: If an invalid API version is provided
+        """
+        if api_version not in ApiVersion.as_list():
+            raise ValueError(
+                f"Invalid API version: {api_version}. Valid versions are: {', '.join(ApiVersion.as_list())}"
+            )
+        url = urljoin(self._request_handler.base_url, f"{api_version}/Conversations")
+
+        payload = {
+            "userId": user_id,
+            "title": title,
+            "deploymentId": deployment_id,
+            "dataSourceFiles": data_source_files,
+            "isBookmarked": is_bookmarked,
+        }
+
+        request_data = self._request_handler.prepare_request(
+            url=url, payload=payload, correlation_id=correlation_id
+        )
+
+        return request_data
+
+    def _pre_get_conversation(
+        self,
+        conversation_id: str,
+        correlation_id: Optional[str] = None,
+        api_version: str = ApiVersion.V1.value,
+    ):
+        """
+        Prepare request data for retrieving a conversation by ID.
+
+        This internal method constructs the URL for conversation retrieval
+        requests using the provided conversation identifier.
+
+        Args:
+            conversation_id: ID of the conversation to retrieve
+            correlation_id: Optional correlation ID for tracing
+            api_version: API version to use for the request
+
+        Returns:
+            RequestData: Prepared request data for the conversation retrieval endpoint
+
+        Raises:
+            ValueError: If an invalid API version is provided
+        """
+        if api_version not in ApiVersion.as_list():
+            raise ValueError(
+                f"Invalid API version: {api_version}. Valid versions are: {', '.join(ApiVersion.as_list())}"
+            )
+        url = urljoin(
+            self._request_handler.base_url,
+            f"{api_version}/Conversations/{conversation_id}",
+        )
+        request_data = self._request_handler.prepare_request(
+            url, correlation_id=correlation_id
+        )
+
+        return request_data
+
+    def _pre_delete_conversation(
+        self,
+        conversation_id: str,
+        correlation_id: Optional[str] = None,
+        api_version: str = ApiVersion.V1.value,
+    ):
+        """
+        Prepare request data for deleting a conversation by ID.
+
+        This internal method constructs the URL for conversation deletion
+        requests using the provided conversation identifier.
+
+        Args:
+            conversation_id: ID of the conversation to delete
+            correlation_id: Optional correlation ID for tracing
+            api_version: API version to use for the request
+
+        Returns:
+            RequestData: Prepared request data for the conversation deletion endpoint
+
+        Raises:
+            ValueError: If an invalid API version is provided
+        """
+        if api_version not in ApiVersion.as_list():
+            raise ValueError(
+                f"Invalid API version: {api_version}. Valid versions are: {', '.join(ApiVersion.as_list())}"
+            )
+        url = urljoin(
+            self._request_handler.base_url,
+            f"{api_version}/Conversations/{conversation_id}",
+        )
+        request_data = self._request_handler.prepare_request(
+            url, correlation_id=correlation_id
+        )
+
+        return request_data

airia/client/conversations/sync_conversations.py

@@ -0,0 +1,182 @@
+from typing import Any, Dict, Optional
+
+from ...types._api_version import ApiVersion
+from ...types.api.conversations import (
+    CreateConversationResponse,
+    GetConversationResponse,
+)
+from .._request_handler import RequestHandler
+from .base_conversations import BaseConversations
+
+
+class Conversations(BaseConversations):
+    def __init__(self, request_handler: RequestHandler):
+        super().__init__(request_handler)
+
+    def create_conversation(
+        self,
+        user_id: str,
+        title: Optional[str] = None,
+        deployment_id: Optional[str] = None,
+        data_source_files: Dict[str, Any] = {},
+        is_bookmarked: bool = False,
+        correlation_id: Optional[str] = None,
+    ) -> CreateConversationResponse:
+        """
+        Create a new conversation.
+
+        Args:
+            user_id (str): The unique identifier of the user creating the conversation.
+            title (str, optional): The title for the conversation. If not provided,
+                the conversation will be created without a title.
+            deployment_id (str, optional): The unique identifier of the deployment
+                to associate with the conversation. If not provided, the conversation
+                will not be associated with any specific deployment.
+            data_source_files (dict): Configuration for data source files
+                to be associated with the conversation. If not provided, no data
+                source files will be associated.
+            is_bookmarked (bool): Whether the conversation should be bookmarked.
+                Defaults to False.
+            correlation_id (str, optional): A unique identifier for request tracing
+                and logging. If not provided, one will be automatically generated.
+
+        Returns:
+            CreateConversationResponse: A response object containing the created
+                conversation details including its ID, creation timestamp, and
+                all provided parameters.
+
+        Raises:
+            AiriaAPIError: If the API request fails, including cases where:
+                - The user_id doesn't exist (404)
+                - The deployment_id is invalid (404)
+                - Authentication fails (401)
+                - Access is forbidden (403)
+                - Server errors (5xx)
+
+        Example:
+            ```python
+            from airia import AiriaClient
+
+            client = AiriaClient(api_key="your_api_key")
+
+            # Create a basic conversation
+            conversation = client.conversations.create_conversation(
+                user_id="user_123"
+            )
+            print(f"Created conversation: {conversation.id}")
+
+            # Create a conversation with all options
+            conversation = client.conversations.create_conversation(
+                user_id="user_123",
+                title="My Research Session",
+                deployment_id="deployment_456",
+                data_source_files={"documents": ["doc1.pdf", "doc2.txt"]},
+                is_bookmarked=True
+            )
+            print(f"Created bookmarked conversation: {conversation.id}")
+            ```
+
+        Note:
+            The user_id is required and must correspond to a valid user in the system.
+            All other parameters are optional and can be set to None or their default values.
+        """
+        request_data = self._pre_create_conversation(
+            user_id=user_id,
+            title=title,
+            deployment_id=deployment_id,
+            data_source_files=data_source_files,
+            is_bookmarked=is_bookmarked,
+            correlation_id=correlation_id,
+            api_version=ApiVersion.V1.value,
+        )
+        resp = self._request_handler.make_request("POST", request_data)
+
+        return CreateConversationResponse(**resp)
+
+    def get_conversation(
+        self, conversation_id: str, correlation_id: Optional[str] = None
+    ) -> GetConversationResponse:
+        """
+        Retrieve detailed information about a specific conversation by its ID.
+
+        This method fetches comprehensive information about a conversation including
+        all messages, metadata, policy redactions, and execution status.
+
+        Args:
+            conversation_id (str): The unique identifier of the conversation to retrieve.
+            correlation_id (str, optional): A unique identifier for request tracing
+                and logging. If not provided, one will be automatically generated.
+
+        Returns:
+            GetConversationResponse: A response object containing the conversation
+                details including user ID, messages, title, deployment information,
+                data source files, bookmark status, policy redactions, and execution status.
+
+        Raises:
+            AiriaAPIError: If the API request fails, including cases where:
+                - The conversation_id doesn't exist (404)
+                - Authentication fails (401)
+                - Access is forbidden (403)
+                - Server errors (5xx)
+
+        Example:
+            ```python
+            from airia import AiriaClient
+
+            client = AiriaClient(api_key="your_api_key")
+
+            # Get conversation details
+            conversation = client.conversations.get_conversation(
+                conversation_id="conversation_123"
+            )
+
+            print(f"Conversation: {conversation.title}")
+            print(f"User: {conversation.user_id}")
+            print(f"Messages: {len(conversation.messages)}")
+            print(f"Bookmarked: {conversation.is_bookmarked}")
+
+            # Access individual messages
+            for message in conversation.messages:
+                print(f"[{message.role}]: {message.message}")
+            ```
+
+        Note:
+            This method only retrieves conversation information and does not
+            modify or execute any operations on the conversation.
+        """
+        request_data = self._pre_get_conversation(
+            conversation_id=conversation_id,
+            correlation_id=correlation_id,
+            api_version=ApiVersion.V1.value,
+        )
+        resp = self._request_handler.make_request("GET", request_data)
+
+        return GetConversationResponse(**resp)
+
+    def delete_conversation(
+        self,
+        conversation_id: str,
+        correlation_id: Optional[str] = None,
+    ) -> None:
+        """
+        Delete a conversation by its ID.
+
+        This method permanently removes a conversation and all associated data
+        from the Airia platform. This action cannot be undone.
+
+        Args:
+            conversation_id: The unique identifier of the conversation to delete
+            correlation_id: Optional correlation ID for request tracing
+
+        Returns:
+            None: This method returns nothing upon successful deletion
+
+        Raises:
+            AiriaAPIError: If the API request fails or the conversation doesn't exist
+        """
+        request_data = self._pre_delete_conversation(
+            conversation_id=conversation_id,
+            correlation_id=correlation_id,
+            api_version=ApiVersion.V1.value,
+        )
+        self._request_handler.make_request("DELETE", request_data, return_json=False)

airia/client/deployments/__init__.py

@@ -0,0 +1,11 @@
+"""
+Deployment management client modules.
+
+This module provides synchronous and asynchronous client interfaces for
+deployment-related operations in the Airia platform.
+"""
+
+from .async_deployments import AsyncDeployments
+from .sync_deployments import Deployments
+
+__all__ = ["AsyncDeployments", "Deployments"]

airia/client/deployments/async_deployments.py

@@ -0,0 +1,112 @@
+from typing import List, Optional
+
+from ...types._api_version import ApiVersion
+from ...types.api.deployments import GetDeploymentResponse, GetDeploymentsResponse
+from .._request_handler import AsyncRequestHandler
+from .base_deployments import BaseDeployments
+
+
+class AsyncDeployments(BaseDeployments):
+    def __init__(self, request_handler: AsyncRequestHandler):
+        super().__init__(request_handler)
+
+    async def get_deployments(
+        self,
+        tags: Optional[List[str]] = None,
+        is_recommended: Optional[bool] = None,
+        project_id: Optional[str] = None,
+        correlation_id: Optional[str] = None,
+        api_version: str = ApiVersion.V2.value,
+    ) -> GetDeploymentsResponse:
+        """
+        Retrieve a paged list of deployments asynchronously.
+
+        This method fetches deployments from the Airia platform with optional filtering
+        by tags and recommendation status. The response includes detailed information
+        about each deployment including associated pipelines, data sources, and user prompts.
+
+        Args:
+            tags: Optional list of tags to filter deployments by
+            is_recommended: Optional filter by recommended status
+            project_id: Optional filter by project id
+            correlation_id: Optional correlation ID for request tracing
+            api_version: API version to use (defaults to V2)
+
+        Returns:
+            GetDeploymentsResponse: Paged response containing deployment items and total count
+
+        Raises:
+            AiriaAPIError: If the API request fails
+            ValueError: If an invalid API version is provided
+
+        Example:
+            ```python
+            client = AiriaAsyncClient(api_key="your-api-key")
+            deployments = await client.deployments.get_deployments(
+                tags=["production", "nlp"],
+                is_recommended=True
+            )
+            print(f"Found {deployments.total_count} deployments")
+            for deployment in deployments.items:
+                print(f"- {deployment.deployment_name}")
+            ```
+        """
+        request_data = self._pre_get_deployments(
+            tags=tags,
+            is_recommended=is_recommended,
+            correlation_id=correlation_id,
+            api_version=api_version,
+        )
+
+        response = await self._request_handler.make_request("GET", request_data)
+
+        if project_id is not None:
+            response["items"] = [
+                item for item in response["items"] if item["projectId"] == project_id
+            ]
+
+        return GetDeploymentsResponse(**response)
+
+    async def get_deployment(
+        self,
+        deployment_id: str,
+        correlation_id: Optional[str] = None,
+        api_version: str = ApiVersion.V1.value,
+    ) -> GetDeploymentResponse:
+        """
+        Retrieve a single deployment by ID asynchronously.
+
+        This method fetches a specific deployment from the Airia platform using its
+        unique identifier. The response includes complete information about the deployment
+        including associated pipelines, data sources, user prompts, and configuration settings.
+
+        Args:
+            deployment_id: The unique identifier of the deployment to retrieve
+            correlation_id: Optional correlation ID for request tracing
+            api_version: API version to use (defaults to V1)
+
+        Returns:
+            GetDeploymentResponse: Complete deployment information
+
+        Raises:
+            AiriaAPIError: If the API request fails or deployment is not found
+            ValueError: If an invalid API version is provided
+
+        Example:
+            ```python
+            client = AiriaAsyncClient(api_key="your-api-key")
+            deployment = await client.deployments.get_deployment("deployment-id-123")
+            print(f"Deployment: {deployment.deployment_name}")
+            print(f"Description: {deployment.description}")
+            print(f"Project: {deployment.project_id}")
+            ```
+        """
+        request_data = self._pre_get_deployment(
+            deployment_id=deployment_id,
+            correlation_id=correlation_id,
+            api_version=api_version,
+        )
+
+        response = await self._request_handler.make_request("GET", request_data)
+
+        return GetDeploymentResponse(**response)

airia/client/deployments/base_deployments.py

@@ -0,0 +1,95 @@
+from typing import List, Optional, Union
+from urllib.parse import urljoin
+
+from ...types._api_version import ApiVersion
+from .._request_handler import AsyncRequestHandler, RequestHandler
+
+
+class BaseDeployments:
+    def __init__(self, request_handler: Union[RequestHandler, AsyncRequestHandler]):
+        self._request_handler = request_handler
+
+    def _pre_get_deployments(
+        self,
+        tags: Optional[List[str]] = None,
+        is_recommended: Optional[bool] = None,
+        correlation_id: Optional[str] = None,
+        api_version: str = ApiVersion.V2.value,
+    ):
+        """
+        Prepare request data for retrieving deployments.
+
+        This internal method constructs the URL and query parameters for deployment
+        retrieval requests, including optional filtering by tags and recommendation status.
+
+        Args:
+            tags: Optional list of tags to filter deployments by
+            is_recommended: Optional filter by recommended status
+            correlation_id: Optional correlation ID for tracing
+            api_version: API version to use for the request
+
+        Returns:
+            RequestData: Prepared request data for the deployments endpoint
+
+        Raises:
+            ValueError: If an invalid API version is provided
+        """
+        if api_version not in ApiVersion.as_list():
+            raise ValueError(
+                f"Invalid API version: {api_version}. Valid versions are: {', '.join(ApiVersion.as_list())}"
+            )
+
+        url = urljoin(
+            self._request_handler.base_url, f"{api_version}/Deployments/paged"
+        )
+
+        # Build query parameters
+        params = {}
+        if tags is not None:
+            params["tags"] = tags
+        if is_recommended is not None:
+            params["isRecommended"] = is_recommended
+
+        request_data = self._request_handler.prepare_request(
+            url=url, params=params, correlation_id=correlation_id
+        )
+
+        return request_data
+
+    def _pre_get_deployment(
+        self,
+        deployment_id: str,
+        correlation_id: Optional[str] = None,
+        api_version: str = ApiVersion.V1.value,
+    ):
+        """
+        Prepare request data for retrieving a single deployment.
+
+        This internal method constructs the URL for deployment retrieval
+        by ID using the specified API version.
+
+        Args:
+            deployment_id: The unique identifier of the deployment to retrieve
+            correlation_id: Optional correlation ID for tracing
+            api_version: API version to use for the request
+
+        Returns:
+            RequestData: Prepared request data for the deployment endpoint
+
+        Raises:
+            ValueError: If an invalid API version is provided
+        """
+        if api_version not in ApiVersion.as_list():
+            raise ValueError(
+                f"Invalid API version: {api_version}. Valid versions are: {', '.join(ApiVersion.as_list())}"
+            )
+
+        url = urljoin(
+            self._request_handler.base_url, f"{api_version}/Deployments/{deployment_id}"
+        )
+
+        request_data = self._request_handler.prepare_request(
+            url=url, correlation_id=correlation_id
+        )
+
+        return request_data

airia/client/deployments/sync_deployments.py

@@ -0,0 +1,112 @@
+from typing import List, Optional
+
+from ...types._api_version import ApiVersion
+from ...types.api.deployments import GetDeploymentResponse, GetDeploymentsResponse
+from .._request_handler import RequestHandler
+from .base_deployments import BaseDeployments
+
+
+class Deployments(BaseDeployments):
+    def __init__(self, request_handler: RequestHandler):
+        super().__init__(request_handler)
+
+    def get_deployments(
+        self,
+        tags: Optional[List[str]] = None,
+        is_recommended: Optional[bool] = None,
+        project_id: Optional[str] = None,
+        correlation_id: Optional[str] = None,
+        api_version: str = ApiVersion.V2.value,
+    ) -> GetDeploymentsResponse:
+        """
+        Retrieve a paged list of deployments.
+
+        This method fetches deployments from the Airia platform with optional filtering
+        by tags and recommendation status. The response includes detailed information
+        about each deployment including associated pipelines, data sources, and user prompts.
+
+        Args:
+            tags: Optional list of tags to filter deployments by
+            is_recommended: Optional filter by recommended status
+            project_id: Optional filter by project id
+            correlation_id: Optional correlation ID for request tracing
+            api_version: API version to use (defaults to V2)
+
+        Returns:
+            GetDeploymentsResponse: Paged response containing deployment items and total count
+
+        Raises:
+            AiriaAPIError: If the API request fails
+            ValueError: If an invalid API version is provided
+
+        Example:
+            ```python
+            client = AiriaClient(api_key="your-api-key")
+            deployments = client.deployments.get_deployments(
+                tags=["production", "nlp"],
+                is_recommended=True
+            )
+            print(f"Found {deployments.total_count} deployments")
+            for deployment in deployments.items:
+                print(f"- {deployment.deployment_name}")
+            ```
+        """
+        request_data = self._pre_get_deployments(
+            tags=tags,
+            is_recommended=is_recommended,
+            correlation_id=correlation_id,
+            api_version=api_version,
+        )
+
+        response = self._request_handler.make_request("GET", request_data)
+
+        if project_id is not None:
+            response["items"] = [
+                item for item in response["items"] if item["projectId"] == project_id
+            ]
+
+        return GetDeploymentsResponse(**response)
+
+    def get_deployment(
+        self,
+        deployment_id: str,
+        correlation_id: Optional[str] = None,
+        api_version: str = ApiVersion.V1.value,
+    ) -> GetDeploymentResponse:
+        """
+        Retrieve a single deployment by ID.
+
+        This method fetches a specific deployment from the Airia platform using its
+        unique identifier. The response includes complete information about the deployment
+        including associated pipelines, data sources, user prompts, and configuration settings.
+
+        Args:
+            deployment_id: The unique identifier of the deployment to retrieve
+            correlation_id: Optional correlation ID for request tracing
+            api_version: API version to use (defaults to V1)
+
+        Returns:
+            GetDeploymentResponse: Complete deployment information
+
+        Raises:
+            AiriaAPIError: If the API request fails or deployment is not found
+            ValueError: If an invalid API version is provided
+
+        Example:
+            ```python
+            client = AiriaClient(api_key="your-api-key")
+            deployment = client.deployments.get_deployment("deployment-id-123")
+            print(f"Deployment: {deployment.deployment_name}")
+            print(f"Description: {deployment.description}")
+            print(f"Project: {deployment.project_id}")
+            ```
+        """
+        request_data = self._pre_get_deployment(
+            deployment_id=deployment_id,
+            correlation_id=correlation_id,
+            api_version=api_version,
+        )
+
+        response = self._request_handler.make_request("GET", request_data)
+
+        return GetDeploymentResponse(**response)

airia/client/pipeline_execution/__init__.py

@@ -0,0 +1,4 @@
+from .sync_pipeline_execution import PipelineExecution
+from .async_pipeline_execution import AsyncPipelineExecution
+
+__all__ = ["PipelineExecution", "AsyncPipelineExecution"]