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

airia/client/async_client.py

@@ -16,6 +16,7 @@ from ..types._api_version import ApiVersion
 from ..types._request_data import RequestData
 from ..types.api import (
     CreateConversationResponse,
+    GetConversationResponse,
     GetPipelineConfigResponse,
     PipelineExecutionAsyncStreamedResponse,
     PipelineExecutionDebugResponse,
@@ -219,8 +220,8 @@ class AiriaAsyncClient(AiriaBaseClient):
         raise AiriaAPIError(status_code=e.status, message=sanitized_message) from e
 
     async def _make_request(
-        self, method: str, request_data: RequestData
-    ) -> Dict[str, Any]:
+        self, method: str, request_data: RequestData, return_json: bool = True
+    ) -> Optional[Dict[str, Any]]:
         """
         Makes an asynchronous HTTP request to the Airia API.
 
@@ -231,6 +232,7 @@ class AiriaAsyncClient(AiriaBaseClient):
                 - headers: HTTP headers to include in the request
                 - payload: The JSON payload/body for the request
                 - correlation_id: Unique identifier for request tracing
+            return_json (bool): Whether to return the response as JSON. Default is True.
 
         Returns:
             resp ([Dict[str, Any]): The JSON response from the API as a dictionary.
@@ -265,7 +267,8 @@ class AiriaAsyncClient(AiriaBaseClient):
                 response.raise_for_status()
 
                 # Return the response as a dictionary
-                return await response.json()
+                if return_json:
+                    return await response.json()
 
         except aiohttp.ClientResponseError as e:
             self._handle_exception(e, request_data.url, request_data.correlation_id)
@@ -737,3 +740,94 @@ class AiriaAsyncClient(AiriaBaseClient):
         resp = await self._make_request("POST", request_data)
 
         return CreateConversationResponse(**resp)
+
+    async 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 AiriaAsyncClient
+
+            async def main():
+                client = AiriaAsyncClient(api_key="your_api_key")
+
+                # Get conversation details
+                conversation = await client.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}")
+
+            asyncio.run(main())
+            ```
+
+        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 = await self._make_request("GET", request_data)
+
+        return GetConversationResponse(**resp)
+
+    async 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,
+        )
+        await self._make_request("DELETE", request_data, return_json=False)

airia/client/base_client.py

@@ -97,6 +97,21 @@ class AiriaBaseClient:
         params: Optional[Dict[str, Any]] = None,
         correlation_id: Optional[str] = None,
     ):
+        """
+        Prepare request data including headers, authentication, and logging.
+        
+        This method sets up all the necessary components for an API request including
+        correlation ID, authentication headers, and sanitized logging.
+        
+        Args:
+            url: The target URL for the request
+            payload: Optional JSON payload for the request body
+            params: Optional query parameters for the request
+            correlation_id: Optional correlation ID for request tracing
+            
+        Returns:
+            RequestData: A data structure containing all prepared request components
+        """
         # Set correlation ID if provided or generate a new one
         correlation_id = set_correlation_id(correlation_id)
 
@@ -170,6 +185,38 @@ class AiriaBaseClient:
         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())}"
@@ -205,6 +252,19 @@ class AiriaBaseClient:
         correlation_id: Optional[str] = None,
         api_version: str = ApiVersion.V1.value,
     ):
+        """
+        Prepare request data for getting projects endpoint.
+        
+        Args:
+            correlation_id: Optional correlation ID for tracing
+            api_version: API version to use for the request
+            
+        Returns:
+            RequestData: Prepared request data for the projects 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())}"
@@ -220,6 +280,20 @@ class AiriaBaseClient:
         correlation_id: Optional[str] = None,
         api_version: str = ApiVersion.V1.value,
     ):
+        """
+        Prepare request data for getting active pipelines IDs.
+        
+        Args:
+            project_id: ID of the project to get configuration for
+            correlation_id: Optional correlation ID for tracing
+            api_version: API version to use for the request
+            
+        Returns:
+            RequestData: Prepared request data for the pipeline config 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())}"
@@ -238,6 +312,20 @@ class AiriaBaseClient:
         correlation_id: Optional[str] = None,
         api_version: str = ApiVersion.V1.value,
     ):
+        """
+        Prepare request data for getting pipeline configuration endpoint.
+        
+        Args:
+            pipeline_id: ID of the pipeline to get configuration for
+            correlation_id: Optional correlation ID for tracing
+            api_version: API version to use for the request
+            
+        Returns:
+            RequestData: Prepared request data for the pipeline config 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())}"
@@ -259,6 +347,27 @@ class AiriaBaseClient:
         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())}"
@@ -279,16 +388,66 @@ class AiriaBaseClient:
 
         return request_data
 
-    def _pre_get_projects(
+    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.base_url, f"{api_version}/Project/paginated")
+        url = urljoin(self.base_url, f"{api_version}/Conversations/{conversation_id}")
+        request_data = self._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.base_url, f"{api_version}/Conversations/{conversation_id}")
         request_data = self._prepare_request(url, correlation_id=correlation_id)
 
         return request_data

airia/client/sync_client.py

@@ -14,6 +14,7 @@ from ..types._api_version import ApiVersion
 from ..types._request_data import RequestData
 from ..types.api import (
     CreateConversationResponse,
+    GetConversationResponse,
     GetPipelineConfigResponse,
     PipelineExecutionDebugResponse,
     PipelineExecutionResponse,
@@ -202,7 +203,9 @@ class AiriaClient(AiriaBaseClient):
             status_code=e.response.status_code, message=sanitized_message
         ) from e
 
-    def _make_request(self, method: str, request_data: RequestData) -> Dict[str, Any]:
+    def _make_request(
+        self, method: str, request_data: RequestData, return_json: bool = True
+    ) -> Dict[str, Any]:
         """
         Makes a synchronous HTTP request to the Airia API.
 
@@ -213,6 +216,7 @@ class AiriaClient(AiriaBaseClient):
                 - headers: HTTP headers to include in the request
                 - payload: The JSON payload/body for the request
                 - correlation_id: Unique identifier for request tracing
+            return_json (bool): Whether to return the response as JSON. Default is True.
 
         Returns:
             resp (Dict[str, Any]): The JSON response from the API as a dictionary.
@@ -248,7 +252,8 @@ class AiriaClient(AiriaBaseClient):
             response.raise_for_status()
 
             # Returns the JSON response
-            return response.json()
+            if return_json:
+                return response.json()
 
         except requests.HTTPError as e:
             self._handle_exception(e, request_data.url, request_data.correlation_id)
@@ -716,3 +721,91 @@ class AiriaClient(AiriaBaseClient):
         resp = self._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.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._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._make_request("DELETE", request_data, return_json=False)

airia/constants.py

@@ -1,9 +1,20 @@
-"""Constants used throughout the Airia SDK."""
+"""
+Constants used throughout the Airia SDK.
+
+This module defines default values for API endpoints, timeouts, and other
+configuration parameters used by the SDK clients.
+"""
 
 # Default API endpoints
 DEFAULT_BASE_URL = "https://api.airia.ai/"
+"""Default base URL for the main Airia API endpoints."""
+
 DEFAULT_OPENAI_GATEWAY_URL = "https://gateway.airia.ai/openai/v1"
+"""Default base URL for the Airia OpenAI Gateway API."""
+
 DEFAULT_ANTHROPIC_GATEWAY_URL = "https://gateway.airia.ai/anthropic"
+"""Default base URL for the Airia Anthropic Gateway API."""
 
 # Default timeouts
-DEFAULT_TIMEOUT = 30.0
+DEFAULT_TIMEOUT = 30.0
+"""Default timeout in seconds for API requests."""

airia/logs.py

@@ -2,7 +2,7 @@ import os
 import sys
 import uuid
 from contextvars import ContextVar
-from typing import BinaryIO, Optional, TextIO, Union, overload
+from typing import BinaryIO, Optional, TextIO, Union
 
 import loguru
 from loguru import logger
@@ -48,28 +48,6 @@ def correlation_id_filter(record):
     return record
 
 
-@overload
-def configure_logging(
-    format_string: str = "<green>{time:YYYY-MM-DD HH:mm:ss.SSS}</green> | <level>{level: <8}</level> | <cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - <level>{message}</level>",
-    level: str = "INFO",
-    sink: Union[TextIO, BinaryIO] = ...,
-    rotation: None = None,
-    retention: None = None,
-    include_correlation_id: bool = True,
-) -> "loguru.Logger": ...
-
-
-@overload
-def configure_logging(
-    format_string: str = "<green>{time:YYYY-MM-DD HH:mm:ss.SSS}</green> | <level>{level: <8}</level> | <cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - <level>{message}</level>",
-    level: str = "INFO",
-    sink: Union[str, os.PathLike[str]] = ...,
-    rotation: Optional[str] = None,
-    retention: Optional[str] = None,
-    include_correlation_id: bool = True,
-) -> "loguru.Logger": ...
-
-
 def configure_logging(
     format_string: str = "<green>{time:YYYY-MM-DD HH:mm:ss.SSS}</green> | <level>{level: <8}</level> | <cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> - <level>{message}</level>",
     level: str = "INFO",

airia/types/_request_data.py

@@ -1,9 +1,29 @@
+"""
+Internal data structures for HTTP request preparation.
+
+This module defines the data models used internally by the SDK clients
+to organize and pass request information between methods.
+"""
 from typing import Any, Dict, Optional
 
 from pydantic import BaseModel
 
 
 class RequestData(BaseModel):
+    """
+    Structured container for HTTP request components.
+    
+    This internal data structure organizes all the components needed to make
+    an HTTP request, including the URL, headers, payload, query parameters,
+    and correlation ID for tracing.
+    
+    Attributes:
+        url: The complete URL for the HTTP request
+        payload: Optional JSON payload for the request body
+        params: Optional query parameters to append to the URL
+        headers: HTTP headers including authentication and content-type
+        correlation_id: Unique identifier for request tracing and logging
+    """
     url: str
     payload: Optional[Dict[str, Any]]
     params: Optional[Dict[str, Any]]

airia/types/api/__init__.py

@@ -1,3 +1,10 @@
+"""
+API response models for the Airia SDK.
+
+This package contains Pydantic models that define the structure of responses
+from various Airia API endpoints, including pipeline execution, project management,
+conversation handling, and configuration retrieval.
+"""
 from .get_projects import ProjectItem
 from .get_pipeline_config import GetPipelineConfigResponse
 from .pipeline_execution import (
@@ -6,7 +13,7 @@ from .pipeline_execution import (
     PipelineExecutionAsyncStreamedResponse,
     PipelineExecutionStreamedResponse,
 )
-from .conversations import CreateConversationResponse
+from .conversations import CreateConversationResponse, GetConversationResponse
 
 __all__ = [
     "PipelineExecutionDebugResponse",
@@ -16,4 +23,5 @@ __all__ = [
     "GetPipelineConfigResponse",
     "ProjectItem",
     "CreateConversationResponse",
+    "GetConversationResponse",
 ]

airia/types/api/conversations.py

@@ -1,9 +1,73 @@
-from typing import Optional
+"""
+Pydantic models for conversation management API responses.
+
+This module defines data structures for conversation operations including
+creation, retrieval, and message management within the Airia platform.
+"""
+from typing import Optional, List, Dict
+from datetime import datetime
 
 from pydantic import BaseModel, Field
 
 
+class PolicyRedaction(BaseModel):
+    """
+    Information about content that was redacted due to policy violations.
+    
+    When content in a conversation violates platform policies, this model
+    tracks what was redacted and where it occurred.
+    """
+    violating_text: str = Field(alias="violatingText")
+    violating_message_index: int = Field(alias="violatingMessageIndex")
+
+
+class ConversationMessage(BaseModel):
+    """
+    Individual message within a conversation.
+    
+    Represents a single message exchange in a conversation, which can be
+    from a user, assistant, or system. Messages may include text content
+    and optional image attachments.
+    """
+    id: str
+    conversation_id: str = Field(alias="conversationId")
+    message: Optional[str] = None
+    created_at: datetime = Field(alias="createdAt")
+    updated_at: datetime = Field(alias="updatedAt")
+    role: str
+    images: Optional[List[str]] = None
+
+
+class GetConversationResponse(BaseModel):
+    """
+    Complete conversation data including messages and metadata.
+    
+    This response contains all information about a conversation including
+    its message history, associated files, execution status, and any
+    content moderation actions that have been applied.
+    """
+    user_id: str = Field(alias="userId")
+    conversation_id: str = Field(alias="conversationId")
+    messages: List[ConversationMessage]
+    title: Optional[str] = None
+    websocket_url: Optional[str] = Field(None, alias="websocketUrl")
+    deployment_id: Optional[str] = Field(None, alias="deploymentId")
+    data_source_files: Dict[str, List[str]] = Field(alias="dataSourceFiles")
+    is_bookmarked: bool = Field(alias="isBookmarked")
+    policy_redactions: Optional[Dict[str, PolicyRedaction]] = Field(
+        None, alias="policyRedactions"
+    )
+    last_execution_status: Optional[str] = Field(None, alias="lastExecutionStatus")
+    last_execution_id: Optional[str] = Field(None, alias="lastExecutionId")
+
+
 class CreateConversationResponse(BaseModel):
+    """
+    Response data for newly created conversations.
+    
+    Contains the essential information needed to begin interacting with
+    a new conversation, including connection details and visual metadata.
+    """
     user_id: str = Field(alias="userId")
     conversation_id: str = Field(alias="conversationId")
     websocket_url: str = Field(alias="websocketUrl")