airia 0.1.13__py3-none-any.whl → 0.1.14__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/pipeline_execution/__init__.py

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

airia/client/pipeline_execution/async_pipeline_execution.py

@@ -0,0 +1,178 @@
+from typing import Any, Dict, List, Literal, Optional, Union, overload
+
+from ...types._api_version import ApiVersion
+from ...types.api.pipeline_execution import (
+    PipelineExecutionAsyncStreamedResponse,
+    PipelineExecutionDebugResponse,
+    PipelineExecutionResponse,
+)
+from .._request_handler import AsyncRequestHandler
+from .base_pipeline_execution import BasePipelineExecution
+
+
+class AsyncPipelineExecution(BasePipelineExecution):
+    def __init__(self, request_handler: AsyncRequestHandler):
+        super().__init__(request_handler)
+
+    @overload
+    async def execute_pipeline(
+        self,
+        pipeline_id: str,
+        user_input: str,
+        debug: Literal[False] = False,
+        user_id: Optional[str] = None,
+        conversation_id: Optional[str] = None,
+        async_output: Literal[False] = False,
+        include_tools_response: bool = False,
+        images: Optional[List[str]] = None,
+        files: Optional[List[str]] = None,
+        data_source_folders: Optional[Dict[str, Any]] = None,
+        data_source_files: Optional[Dict[str, Any]] = None,
+        in_memory_messages: Optional[List[Dict[str, str]]] = None,
+        current_date_time: Optional[str] = None,
+        save_history: bool = True,
+        additional_info: Optional[List[Any]] = None,
+        prompt_variables: Optional[Dict[str, Any]] = None,
+        correlation_id: Optional[str] = None,
+    ) -> PipelineExecutionResponse: ...
+
+    @overload
+    async def execute_pipeline(
+        self,
+        pipeline_id: str,
+        user_input: str,
+        debug: Literal[True] = True,
+        user_id: Optional[str] = None,
+        conversation_id: Optional[str] = None,
+        async_output: Literal[False] = False,
+        include_tools_response: bool = False,
+        images: Optional[List[str]] = None,
+        files: Optional[List[str]] = None,
+        data_source_folders: Optional[Dict[str, Any]] = None,
+        data_source_files: Optional[Dict[str, Any]] = None,
+        in_memory_messages: Optional[List[Dict[str, str]]] = None,
+        current_date_time: Optional[str] = None,
+        save_history: bool = True,
+        additional_info: Optional[List[Any]] = None,
+        prompt_variables: Optional[Dict[str, Any]] = None,
+        correlation_id: Optional[str] = None,
+    ) -> PipelineExecutionDebugResponse: ...
+
+    @overload
+    async def execute_pipeline(
+        self,
+        pipeline_id: str,
+        user_input: str,
+        debug: bool = False,
+        user_id: Optional[str] = None,
+        conversation_id: Optional[str] = None,
+        async_output: Literal[True] = True,
+        include_tools_response: bool = False,
+        images: Optional[List[str]] = None,
+        files: Optional[List[str]] = None,
+        data_source_folders: Optional[Dict[str, Any]] = None,
+        data_source_files: Optional[Dict[str, Any]] = None,
+        in_memory_messages: Optional[List[Dict[str, str]]] = None,
+        current_date_time: Optional[str] = None,
+        save_history: bool = True,
+        additional_info: Optional[List[Any]] = None,
+        prompt_variables: Optional[Dict[str, Any]] = None,
+        correlation_id: Optional[str] = None,
+    ) -> PipelineExecutionAsyncStreamedResponse: ...
+
+    async def execute_pipeline(
+        self,
+        pipeline_id: str,
+        user_input: str,
+        debug: bool = False,
+        user_id: Optional[str] = None,
+        conversation_id: Optional[str] = None,
+        async_output: bool = False,
+        include_tools_response: bool = False,
+        images: Optional[List[str]] = None,
+        files: Optional[List[str]] = None,
+        data_source_folders: Optional[Dict[str, Any]] = None,
+        data_source_files: Optional[Dict[str, Any]] = None,
+        in_memory_messages: Optional[List[Dict[str, str]]] = None,
+        current_date_time: Optional[str] = None,
+        save_history: bool = True,
+        additional_info: Optional[List[Any]] = None,
+        prompt_variables: Optional[Dict[str, Any]] = None,
+        correlation_id: Optional[str] = None,
+    ) -> Union[
+        PipelineExecutionDebugResponse,
+        PipelineExecutionResponse,
+        PipelineExecutionAsyncStreamedResponse,
+    ]:
+        """
+        Execute a pipeline with the provided input asynchronously.
+
+        Args:
+            pipeline_id: The ID of the pipeline to execute.
+            user_input: input text to process.
+            debug: Whether debug mode execution is enabled. Default is False.
+            user_id: Optional ID of the user making the request (guid).
+            conversation_id: Optional conversation ID (guid).
+            async_output: Whether to stream the response. Default is False.
+            include_tools_response: Whether to return the initial LLM tool result. Default is False.
+            images: Optional list of images formatted as base64 strings.
+            files: Optional list of files formatted as base64 strings.
+            data_source_folders: Optional data source folders information.
+            data_source_files: Optional data source files information.
+            in_memory_messages: Optional list of in-memory messages, each with a role and message.
+            current_date_time: Optional current date and time in ISO format.
+            save_history: Whether to save the userInput and output to conversation history. Default is True.
+            additional_info: Optional additional information.
+            prompt_variables: Optional variables to be used in the prompt.
+            correlation_id: Optional correlation ID for request tracing. If not provided,
+                        one will be generated automatically.
+
+        Returns:
+            Response containing the result of the execution.
+
+        Raises:
+            AiriaAPIError: If the API request fails with details about the error.
+            aiohttp.ClientError: For other request-related errors.
+
+        Example:
+            ```python
+            client = AiriaAsyncClient(api_key="your_api_key")
+            response = await client.pipeline_execution.execute_pipeline(
+                pipeline_id="pipeline_123",
+                user_input="Tell me about quantum computing"
+            )
+            print(response.result)
+            ```
+        """
+        request_data = self._pre_execute_pipeline(
+            pipeline_id=pipeline_id,
+            user_input=user_input,
+            debug=debug,
+            user_id=user_id,
+            conversation_id=conversation_id,
+            async_output=async_output,
+            include_tools_response=include_tools_response,
+            images=images,
+            files=files,
+            data_source_folders=data_source_folders,
+            data_source_files=data_source_files,
+            in_memory_messages=in_memory_messages,
+            current_date_time=current_date_time,
+            save_history=save_history,
+            additional_info=additional_info,
+            prompt_variables=prompt_variables,
+            correlation_id=correlation_id,
+            api_version=ApiVersion.V2.value,
+        )
+        resp = (
+            self._request_handler.make_request_stream("POST", request_data)
+            if async_output
+            else await self._request_handler.make_request("POST", request_data)
+        )
+
+        if not async_output:
+            if not debug:
+                return PipelineExecutionResponse(**resp)
+            return PipelineExecutionDebugResponse(**resp)
+
+        return PipelineExecutionAsyncStreamedResponse(stream=resp)

airia/client/pipeline_execution/base_pipeline_execution.py

@@ -0,0 +1,96 @@
+from typing import Any, Dict, List, Optional, Union
+from urllib.parse import urljoin
+
+from ...types._api_version import ApiVersion
+from .._request_handler import AsyncRequestHandler, RequestHandler
+
+
+class BasePipelineExecution:
+    def __init__(self, request_handler: Union[RequestHandler, AsyncRequestHandler]):
+        self._request_handler = request_handler
+
+    def _pre_execute_pipeline(
+        self,
+        pipeline_id: str,
+        user_input: str,
+        debug: bool = False,
+        user_id: Optional[str] = None,
+        conversation_id: Optional[str] = None,
+        async_output: bool = False,
+        include_tools_response: bool = False,
+        images: Optional[List[str]] = None,
+        files: Optional[List[str]] = None,
+        data_source_folders: Optional[Dict[str, Any]] = None,
+        data_source_files: Optional[Dict[str, Any]] = None,
+        in_memory_messages: Optional[List[Dict[str, str]]] = None,
+        current_date_time: Optional[str] = None,
+        save_history: bool = True,
+        additional_info: Optional[List[Any]] = None,
+        prompt_variables: Optional[Dict[str, Any]] = None,
+        correlation_id: Optional[str] = None,
+        api_version: str = ApiVersion.V2.value,
+    ):
+        """
+        Prepare request data for pipeline execution endpoint.
+
+        This internal method constructs the URL and payload for pipeline execution
+        requests, validating the API version and preparing all request components.
+
+        Args:
+            pipeline_id: ID of the pipeline to execute
+            user_input: Input text to process
+            debug: Whether to enable debug mode
+            user_id: Optional user identifier
+            conversation_id: Optional conversation identifier
+            async_output: Whether to enable streaming output
+            include_tools_response: Whether to include tool responses
+            images: Optional list of base64-encoded images
+            files: Optional list of base64-encoded files
+            data_source_folders: Optional data source folder configuration
+            data_source_files: Optional data source files configuration
+            in_memory_messages: Optional list of in-memory messages
+            current_date_time: Optional current date/time in ISO format
+            save_history: Whether to save to conversation history
+            additional_info: Optional additional information
+            prompt_variables: Optional prompt variables
+            correlation_id: Optional correlation ID for tracing
+            api_version: API version to use for the request
+
+        Returns:
+            RequestData: Prepared request data for the pipeline execution 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}/PipelineExecution/{pipeline_id}",
+        )
+
+        payload = {
+            "userInput": user_input,
+            "debug": debug,
+            "userId": user_id,
+            "conversationId": conversation_id,
+            "asyncOutput": async_output,
+            "includeToolsResponse": include_tools_response,
+            "images": images,
+            "files": files,
+            "dataSourceFolders": data_source_folders,
+            "dataSourceFiles": data_source_files,
+            "inMemoryMessages": in_memory_messages,
+            "currentDateTime": current_date_time,
+            "saveHistory": save_history,
+            "additionalInfo": additional_info,
+            "promptVariables": prompt_variables,
+        }
+
+        request_data = self._request_handler.prepare_request(
+            url=url, payload=payload, correlation_id=correlation_id
+        )
+
+        return request_data