airia 0.1.26__py3-none-any.whl → 0.1.28__py3-none-any.whl

airia/client/tools/base_tools.py

@@ -0,0 +1,153 @@
+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 BaseTools:
+    def __init__(self, request_handler: Union[RequestHandler, AsyncRequestHandler]):
+        self._request_handler = request_handler
+
+    def _pre_create_tool(
+        self,
+        name: str,
+        description: str,
+        api_endpoint: str,
+        method_type: str,
+        purpose: str,
+        body_type: str,
+        category: str,
+        provider: str,
+        tool_type: str,
+        body: str,
+        headers: List[Dict[str, str]],
+        parameters: List[Dict[str, Any]],
+        request_timeout: int,
+        route_through_acc: bool,
+        should_redirect: bool,
+        tool_credentials: Dict[str, Any],
+        acc_group: Optional[str] = None,
+        documentation: Optional[str] = None,
+        project_id: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+        tool_metadata: Optional[List[Dict[str, Any]]] = None,
+        correlation_id: Optional[str] = None,
+        api_version: str = ApiVersion.V1.value,
+    ):
+        """
+        Prepare request data for creating a new tool.
+
+        This internal method constructs the URL and payload for tool creation
+        requests, including all tool configuration and metadata.
+
+        Args:
+            name: Name of the tool
+            description: Brief description of what the tool does
+            api_endpoint: Web API endpoint where the tool sends its requests
+            method_type: HTTP method type (Get, Post, Put, Delete)
+            purpose: When and why to use this tool
+            body_type: Type of the request body (Json, XFormUrlEncoded, None)
+            category: Category of the tool (Action, Airia, Mcp)
+            provider: Provider of the tool
+            tool_type: Type of the tool (Custom, Calculator, MCP, etc.)
+            body: Body of the request that the tool sends to the API
+            headers: List of headers required when making the API request
+            parameters: Collection of parameters required by the tool
+            request_timeout: Request timeout in seconds for tool execution
+            route_through_acc: Flag indicating whether the tool should route through the ACC
+            should_redirect: Flag indicating whether the tool should redirect with authorization header
+            tool_credentials: Tool credentials
+            acc_group: Optional ACC specific group name
+            documentation: Optional documentation for the tool
+            project_id: Optional unique identifier of the project to which the tool is associated
+            tags: Optional list of tags for the tool
+            tool_metadata: Optional user provided metadata for the tool definition
+            correlation_id: Optional correlation ID for tracing
+            api_version: API version to use for the request
+
+        Returns:
+            RequestData: Prepared request data for the tool 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}/Tools")
+
+        payload: Dict[str, Any] = {
+            "name": name,
+            "description": description,
+            "apiEndpoint": api_endpoint,
+            "methodType": method_type,
+            "purpose": purpose,
+            "bodyType": body_type,
+            "category": category,
+            "provider": provider,
+            "toolType": tool_type,
+            "body": body,
+            "headers": headers,
+            "parameters": parameters,
+            "requestTimeout": request_timeout,
+            "routeThroughACC": route_through_acc,
+            "shouldRedirect": should_redirect,
+            "toolCredentials": tool_credentials,
+        }
+
+        # Add optional fields only if they are provided
+        if acc_group is not None:
+            payload["accGroup"] = acc_group
+        if documentation is not None:
+            payload["documentation"] = documentation
+        if project_id is not None:
+            payload["projectId"] = project_id
+        if tags is not None:
+            payload["tags"] = tags
+        if tool_metadata is not None:
+            payload["toolMetadata"] = tool_metadata
+
+        request_data = self._request_handler.prepare_request(
+            url=url, payload=payload, correlation_id=correlation_id
+        )
+
+        return request_data
+
+    def _pre_delete_tool(
+        self,
+        tool_id: str,
+        correlation_id: Optional[str] = None,
+        api_version: str = ApiVersion.V1.value,
+    ):
+        """
+        Prepare request data for deleting a tool by ID.
+
+        This internal method constructs the URL for tool deletion
+        requests using the provided tool identifier.
+
+        Args:
+            tool_id: ID of the tool 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 tool 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}/Tools/{tool_id}",
+        )
+        request_data = self._request_handler.prepare_request(
+            url, correlation_id=correlation_id
+        )
+
+        return request_data

airia/client/tools/sync_tools.py

@@ -0,0 +1,245 @@
+from typing import Any, Dict, List, Optional, Literal
+
+from ...types._api_version import ApiVersion
+from ...types.api.tools import CreateToolResponse
+from .._request_handler import RequestHandler
+from .base_tools import BaseTools
+
+
+class Tools(BaseTools):
+    def __init__(self, request_handler: RequestHandler):
+        super().__init__(request_handler)
+
+    def create_tool(
+        self,
+        name: str,
+        description: str,
+        purpose: str,
+        api_endpoint: str,
+        method_type: str,
+        body: str,
+        tool_credentials: Dict[str, Any],
+        headers: List[Dict[str, str]] = [],
+        parameters: List[Dict[str, Any]] = [],
+        request_timeout: int = 100,
+        body_type: Literal["Json", "XFormUrlEncoded", "None"] = "Json",
+        category: Literal["Action", "Airia", "Mcp"] = "Airia",
+        tool_type: str = "Custom",
+        provider: str = "Custom",
+        route_through_acc: bool = False,
+        should_redirect: bool = True,
+        acc_group: Optional[str] = None,
+        documentation: Optional[str] = None,
+        project_id: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+        tool_metadata: Optional[List[Dict[str, Any]]] = None,
+        correlation_id: Optional[str] = None,
+    ) -> CreateToolResponse:
+        """
+        Create a new tool in the Airia platform.
+
+        Args:
+            name (str): Name of the tool.
+            description (str): Brief description of what the tool does.
+                Example: "Use this tool to get the current weather in a given location."
+            purpose (str): When and why to use this tool.
+                Example: "When a user asks about the weather, including current conditions,
+                forecasts, or specific weather events."
+            api_endpoint (str): Web API endpoint where the tool sends its requests to
+                perform its task.
+            method_type (str): HTTP method type. Valid values: "Get", "Post", "Put", "Delete".
+            body_type (str): Type of the request body. Valid values: "Json", "XFormUrlEncoded", "None".
+            category (str): Category of the tool. Valid values: "Action", "Airia", "Mcp".
+            provider (str): Provider of the tool.
+            tool_type (str): Type of the tool. Valid values: "Custom", "Calculator", "MCP",
+                "LoadMemory", "StoreMemory", etc.
+            body (str): Body of the request that the tool sends to the API.
+            headers (list[dict]): List of headers required when making the API request.
+                Each header should be a dictionary with "key" and "value" fields.
+                Example: [{"key": "Content-Type", "value": "application/json"}]
+            parameters (list[dict]): Collection of parameters required by the tool
+                to execute its function.
+            request_timeout (int): Request timeout in seconds for tool execution.
+            route_through_acc (bool): Flag indicating whether the tool should route
+                through the ACC.
+            should_redirect (bool): Flag indicating whether the tool should redirect
+                with authorization header attached.
+            tool_credentials (dict): Tool credentials model.
+            acc_group (str, optional): ACC specific group name. If provided, the tool will
+                route through this ACC group.
+            documentation (str, optional): Documentation for the tool.
+            project_id (str, optional): Unique identifier of the project to which the tool
+                is associated.
+            tags (list[str], optional): List of tags for the tool.
+            tool_metadata (list[dict], optional): User provided metadata for the tool definition.
+            correlation_id (str, optional): A unique identifier for request tracing
+                and logging. If not provided, one will be automatically generated.
+
+        Returns:
+            CreateToolResponse: A response object containing the created tool details
+                including its ID, creation timestamp, configuration, credentials,
+                parameters, and all provided metadata.
+
+        Raises:
+            AiriaAPIError: If the API request fails, including cases where:
+                - Invalid parameters are provided (400)
+                - 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 weather tool with all required parameters
+            tool = client.tools.create_tool(
+                name="get_weather",
+                description="Use this tool to get the current weather in a given location.",
+                api_endpoint="https://api.weather.com/v1/current",
+                method_type="Get",
+                purpose="When a user asks about the weather, including current conditions.",
+                body_type="None",
+                category="Action",
+                provider="WeatherAPI",
+                tool_type="Custom",
+                body="",
+                headers=[],
+                parameters=[],
+                request_timeout=100,
+                route_through_acc=False,
+                should_redirect=False,
+                tool_credentials={}
+            )
+            print(f"Created tool: {tool.id}")
+
+            # Create an email tool with headers and optional parameters
+            tool = client.tools.create_tool(
+                name="send_email",
+                description="Send an email to a recipient.",
+                api_endpoint="https://api.email-service.com/v1/send",
+                method_type="Post",
+                purpose="When a user wants to send an email message.",
+                body_type="Json",
+                category="Action",
+                provider="EmailService",
+                tool_type="Custom",
+                body='{"to": "{{recipient}}", "subject": "{{subject}}", "body": "{{message}}"}',
+                headers=[
+                    {"key": "Content-Type", "value": "application/json"},
+                    {"key": "Authorization", "value": "Bearer {{api_key}}"}
+                ],
+                parameters=[
+                    {"name": "recipient", "type": "string", "required": True},
+                    {"name": "subject", "type": "string", "required": True},
+                    {"name": "message", "type": "string", "required": True}
+                ],
+                request_timeout=120,
+                route_through_acc=False,
+                should_redirect=False,
+                tool_credentials={},
+                documentation="This tool sends emails using the Email Service API.",
+                tags=["email", "communication"]
+            )
+            print(f"Created email tool: {tool.id}")
+            ```
+
+        Note:
+            - Required parameters: name, description, api_endpoint, method_type, purpose,
+              body_type, category, provider, tool_type, body, headers, parameters,
+              request_timeout, route_through_acc, should_redirect, and tool_credentials.
+            - Optional parameters: acc_group, documentation, project_id, tags, and tool_metadata.
+            - The method_type must be one of: "Get", "Post", "Put", "Delete"
+            - The body_type must be one of: "Json", "XFormUrlEncoded", "None"
+            - The category must be one of: "Action", "Airia", "Mcp"
+            - The tool_type must be one of: "Custom", "Calculator", "MCP", "LoadMemory",
+              "StoreMemory", etc.
+        """
+        request_data = self._pre_create_tool(
+            name=name,
+            description=description,
+            api_endpoint=api_endpoint,
+            method_type=method_type,
+            purpose=purpose,
+            body_type=body_type,
+            category=category,
+            provider=provider,
+            tool_type=tool_type,
+            body=body,
+            headers=headers,
+            parameters=parameters,
+            request_timeout=request_timeout,
+            route_through_acc=route_through_acc,
+            should_redirect=should_redirect,
+            tool_credentials=tool_credentials,
+            acc_group=acc_group,
+            documentation=documentation,
+            project_id=project_id,
+            tags=tags,
+            tool_metadata=tool_metadata,
+            correlation_id=correlation_id,
+            api_version=ApiVersion.V1.value,
+        )
+        resp = self._request_handler.make_request("POST", request_data)
+
+        return CreateToolResponse(**resp)
+
+    def delete_tool(
+        self,
+        tool_id: str,
+        correlation_id: Optional[str] = None,
+    ) -> None:
+        """
+        Delete a tool by its ID.
+
+        This method permanently removes a tool from the Airia platform.
+        This action cannot be undone.
+
+        Args:
+            tool_id (str): The unique identifier of the tool to delete.
+            correlation_id (str, optional): A unique identifier for request tracing
+                and logging. If not provided, one will be automatically generated.
+
+        Returns:
+            None: This method returns nothing upon successful deletion.
+
+        Raises:
+            AiriaAPIError: If the API request fails, including cases where:
+                - The tool_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")
+
+            # Delete a tool
+            client.tools.delete_tool(tool_id="tool_123")
+            print("Tool deleted successfully")
+
+            # Handle deletion errors
+            from airia.exceptions import AiriaAPIError
+
+            try:
+                client.tools.delete_tool(tool_id="nonexistent_id")
+            except AiriaAPIError as e:
+                if e.status_code == 404:
+                    print("Tool not found")
+                else:
+                    print(f"Error deleting tool: {e.message}")
+            ```
+
+        Note:
+            This operation is permanent and cannot be undone. Make sure you have
+            the correct tool_id before calling this method.
+        """
+        request_data = self._pre_delete_tool(
+            tool_id=tool_id,
+            correlation_id=correlation_id,
+            api_version=ApiVersion.V1.value,
+        )
+        self._request_handler.make_request("DELETE", request_data, return_json=False)

airia/types/api/__init__.py

@@ -1,3 +1,4 @@
 from . import attachments as attachments
 from . import models as models
 from . import pipeline_import as pipeline_import
+from . import tools as tools

airia/types/api/tools/__init__.py

@@ -0,0 +1,7 @@
+from ._tools import CreateToolResponse, ToolHeader, ToolParameter
+
+__all__ = [
+    "CreateToolResponse",
+    "ToolHeader",
+    "ToolParameter",
+]

airia/types/api/tools/_tools.py

@@ -0,0 +1,245 @@
+"""
+Pydantic models for tool management API responses.
+
+This module defines data structures for tool operations including
+creation and configuration within the Airia platform.
+"""
+
+from typing import Optional, List
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+
+class ToolHeader(BaseModel):
+    """Key-value pair header for a tool definition.
+
+    Attributes:
+        key: The key of the header
+        value: The value of the header
+    """
+
+    key: str
+    value: str
+
+
+class ToolParameter(BaseModel):
+    """Parameter definition for a tool.
+
+    Attributes:
+        name: Name of the parameter
+        type: Type of the parameter
+        description: Description of what the parameter does
+        default: Default value for the parameter
+        valid_options: List of valid options for the parameter
+        array_item_type: Type of items if this parameter is an array
+        parameters: Nested parameters for complex types
+        requirement: Whether the parameter is required or optional
+    """
+
+    name: str
+    type: str
+    description: str
+    default: Optional[str] = None
+    valid_options: Optional[List[str]] = Field(None, alias="validOptions")
+    array_item_type: Optional[str] = Field(None, alias="arrayItemType")
+    parameters: Optional[List["ToolParameter"]] = None
+    requirement: str
+
+
+class ToolCredentialSettings(BaseModel):
+    """Settings for tool credentials.
+
+    Attributes:
+        available_credential_types: List of available credential types
+        default_value: Default credential value
+        platform_supported_oauth_types: List of OAuth types supported by the platform
+    """
+
+    available_credential_types: List[str] = Field(alias="availableCredentialTypes")
+    default_value: Optional[str] = Field(None, alias="defaultValue")
+    platform_supported_oauth_types: List[str] = Field(
+        alias="platformSupportedOAuthTypes"
+    )
+
+
+class CredentialEntry(BaseModel):
+    """Represents a deserialized object for each entry of a credential.
+
+    Attributes:
+        key: The property name of the API Key for credentials data
+        value: The value of the credential
+    """
+
+    key: str
+    value: str
+
+
+class ToolCredential(BaseModel):
+    """Tool credential information.
+
+    Attributes:
+        id: Unique identifier for the credential
+        name: Name of the credential
+        display_identifier_name: Display name for the credential identifier
+        created_at: When the credential was created
+        project_id: ID of the project this credential belongs to
+        type: Type of credential
+        expired: Whether the credential has expired
+        expires_on: When the credential expires
+        administrative_scope: Scope of the credential (e.g., "Tenant")
+        user_id: ID of the user who owns the credential
+        credential_data: List of credential entries
+        custom_credentials: Custom credentials data
+        custom_credentials_id: ID of custom credentials
+        tenant_id: ID of the tenant this credential belongs to
+        origin: Origin of the credential (Platform or Chat)
+    """
+
+    id: str
+    name: Optional[str] = None
+    display_identifier_name: Optional[str] = Field(None, alias="displayIdentifierName")
+    created_at: Optional[datetime] = Field(None, alias="createdAt")
+    project_id: Optional[str] = Field(None, alias="projectId")
+    type: str
+    expired: Optional[bool] = None
+    expires_on: Optional[datetime] = Field(None, alias="expiresOn")
+    administrative_scope: str = Field(alias="administrativeScope")
+    user_id: Optional[str] = Field(None, alias="userId")
+    credential_data: List[CredentialEntry] = Field(default_factory=list, alias="credentialData")
+    custom_credentials: Optional[dict] = Field(None, alias="customCredentials")
+    custom_credentials_id: Optional[str] = Field(None, alias="customCredentialsId")
+    tenant_id: Optional[str] = Field(None, alias="tenantId")
+    origin: str
+
+
+class ToolCredentials(BaseModel):
+    """Credentials configuration for a tool.
+
+    Attributes:
+        tool_credential_settings: Settings for tool credentials
+        tool_credentials: The actual credential object
+        tool_credentials_id: ID of the tool credentials
+        auth_required: Whether authentication is required
+        use_user_credentials: Whether to use user credentials
+        user_credential_connector_id: ID of the user credential connector
+        use_user_credentials_type: Type of user credentials to use
+        credentials_source_type: Source type of the credentials
+        use_airia_key_support: Whether Airia key support is enabled
+    """
+
+    tool_credential_settings: ToolCredentialSettings = Field(
+        alias="toolCredentialSettings"
+    )
+    tool_credentials: Optional[ToolCredential] = Field(None, alias="toolCredentials")
+    tool_credentials_id: Optional[str] = Field(None, alias="toolCredentialsId")
+    auth_required: bool = Field(alias="authRequired")
+    use_user_credentials: bool = Field(alias="useUserCredentials")
+    user_credential_connector_id: Optional[str] = Field(
+        None, alias="userCredentialConnectorId"
+    )
+    use_user_credentials_type: str = Field(alias="useUserCredentialsType")
+    credentials_source_type: str = Field(alias="credentialsSourceType")
+    use_airia_key_support: bool = Field(alias="useAiriaKeySupport")
+
+
+class ProjectReference(BaseModel):
+    """Reference to a project.
+
+    Attributes:
+        id: Project ID
+        name: Project name
+    """
+
+    id: str
+    name: str
+
+
+class ToolMetadata(BaseModel):
+    """Metadata key-value pair for a tool.
+
+    Attributes:
+        key: The metadata key
+        value: The metadata value
+    """
+
+    key: str
+    value: str
+
+
+class CreateToolResponse(BaseModel):
+    """Response data for tool creation and retrieval operations.
+
+    This response contains complete information about a tool including
+    its configuration, credentials, parameters, and metadata.
+
+    Attributes:
+        id: Unique identifier for the tool
+        created_at: Timestamp when the tool was created
+        updated_at: Timestamp when the tool was last updated
+        tool_type: Type of the tool (e.g., "custom")
+        name: Name of the tool
+        standardized_name: Standardized version of the tool name
+        display_name: Display name of the tool (includes provider suffix for gateway tools)
+        origin: Origin of the tool
+        description: Brief description of what the tool does
+        method_type: HTTP method type (Get, Post, Put, Delete)
+        purpose: When and why to use this tool
+        api_endpoint: Web API endpoint where the tool sends requests
+        provider: Provider of the tool
+        tool_credentials: Credentials configuration for the tool
+        headers: Headers required when making API requests
+        body: Body of the request that the tool sends to the API
+        body_type: Type of the request body (Json, XFormUrlEncoded, None)
+        parameters: List of parameters the tool accepts
+        project_id: ID of the project this tool belongs to
+        project_name: Name of the project this tool belongs to
+        project: Project reference object
+        children: Child tool definitions
+        route_through_acc: Whether the tool should route through an ACC specific group
+        should_redirect: Whether the tool should redirect
+        acc_group: ACC specific group name
+        documentation: Documentation for the tool
+        tags: List of tags associated with the tool
+        tool_metadata: List of metadata key-value pairs
+        supports_pagination: Whether the tool supports pagination
+        category: Category of the tool (Action, Airia, Mcp)
+        request_timeout: Request timeout in seconds
+    """
+
+    id: str
+    created_at: datetime = Field(alias="createdAt")
+    updated_at: datetime = Field(alias="updatedAt")
+    tool_type: str = Field(alias="toolType")
+    name: str
+    standardized_name: str = Field(alias="standardizedName")
+    display_name: Optional[str] = Field(None, alias="displayName")
+    origin: Optional[str] = None
+    description: str
+    method_type: str = Field(alias="methodType")
+    purpose: str
+    api_endpoint: str = Field(alias="apiEndpoint")
+    provider: str
+    tool_credentials: ToolCredentials = Field(alias="toolCredentials")
+    headers: List[ToolHeader]
+    body: str
+    body_type: str = Field(alias="bodyType")
+    parameters: List[ToolParameter]
+    project_id: Optional[str] = Field(None, alias="projectId")
+    project_name: Optional[str] = Field(None, alias="projectName")
+    project: Optional[ProjectReference] = None
+    children: Optional[List["CreateToolResponse"]] = None
+    route_through_acc: bool = Field(alias="routeThroughACC")
+    should_redirect: bool = Field(alias="shouldRedirect")
+    acc_group: Optional[str] = Field(None, alias="accGroup")
+    documentation: Optional[str] = None
+    tags: Optional[List[str]] = None
+    tool_metadata: Optional[List[ToolMetadata]] = Field(None, alias="toolMetadata")
+    supports_pagination: Optional[bool] = Field(None, alias="supportsPagination")
+    category: str
+    request_timeout: int = Field(alias="requestTimeout")
+
+
+# Update forward references
+ToolParameter.model_rebuild()
+CreateToolResponse.model_rebuild()

{airia-0.1.26.dist-info → airia-0.1.28.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: airia
-Version: 0.1.26
+Version: 0.1.28
 Summary: Python SDK for Airia API
 Author-email: Airia LLC <support@airia.com>
 License: MIT