simplai-sdk 0.1.0__py3-none-any.whl

core/workflows/bulk/api.py

@@ -0,0 +1,202 @@
+"""Low-level HTTP API layer for bulk workflow execution."""
+
+from typing import Any, Dict, List
+import httpx
+
+from .schema import (
+    BulkRunRequest,
+    BulkRunResponse,
+    InputFieldMapping,
+    BulkRunStatusResponse,
+    BulkRunCancelResponse,
+)
+from exceptions import APIException
+
+
+from constants import WORKFLOW_BASE_URL as BASE_URL
+
+
+
+async def trigger_bulk_run_api(
+    workflow_id: str,
+    file_link: str,
+    batch_size: int,
+    input_mapping: List[Dict[str, str]],
+    api_key: str,
+) -> BulkRunResponse:
+    """
+    Trigger a bulk workflow run via the REST API.
+    
+    Args:
+        workflow_id: The workflow ID to execute
+        file_link: URL/link to the input file
+        batch_size: Number of records to process per batch
+        input_mapping: List of dictionaries mapping app_input_field to file_input_field
+                      Example: [{"app_input_field": "num_1", "file_input_field": "A"}]
+        api_key: API key for authentication
+        
+    Returns:
+        BulkRunResponse with execution_id and status
+        
+    Raises:
+        APIException: If the API request fails
+    """
+    url = f"{BASE_URL}/bulk/run"
+    headers = {
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+        "PIM-SID": api_key,
+    }
+    
+    # Convert input_mapping to InputFieldMapping objects
+    input_fields_mapping = [
+        InputFieldMapping(
+            app_input_field=mapping["app_input_field"],
+            file_input_field=mapping["file_input_field"]
+        )
+        for mapping in input_mapping
+    ]
+    
+    request_body = BulkRunRequest(
+        file_url=file_link,
+        tool_id=workflow_id,
+        batch_size=batch_size,
+        input_fields_mapping=input_fields_mapping,
+    )
+    
+    async with httpx.AsyncClient() as client:
+        try:
+            response = await client.post(
+                url,
+                headers=headers,
+                json=request_body.model_dump(),
+                timeout=30.0,
+            )
+            response.raise_for_status()
+            data = response.json()
+            
+            return BulkRunResponse(
+                execution_id=data.get("execution_id", ""),
+                status=data.get("status", ""),
+            )
+        except httpx.HTTPStatusError as e:
+            raise APIException(
+                f"API request failed with status {e.response.status_code}: {e.response.text}",
+                status_code=e.response.status_code,
+            )
+        except httpx.RequestError as e:
+            raise APIException(f"Request failed: {str(e)}")
+
+
+async def get_bulk_run_status_api(
+    bulk_run_id: str,
+    api_key: str,
+) -> BulkRunStatusResponse:
+    """
+    Get the bulk run status by bulk run ID.
+    """
+    # NOTE: Endpoint path uses singular 'run' (not 'runs'), e.g.:
+    # /bulk/run/{execution_id}/status
+    url = f"{BASE_URL}/bulk/run/{bulk_run_id}/status"
+    headers = {
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+        "PIM-SID": api_key,
+    }
+
+    async with httpx.AsyncClient() as client:
+        try:
+            response = await client.get(
+                url,
+                headers=headers,
+                timeout=30.0,
+            )
+            response.raise_for_status()
+
+            data = response.json()
+
+            return BulkRunStatusResponse(
+                execution_id=data.get("execution_id", ""),
+                status=data.get("status", ""),
+                batch_completed=data.get("batch_completed", 0),
+                total_batches=data.get("total_batches", 0),
+                trace_id=data.get("trace_id"),
+            )
+        except httpx.HTTPStatusError as e:
+            raise APIException(
+                f"API request failed with status {e.response.status_code}: {e.response.text}",
+                status_code=e.response.status_code,
+            )
+        except httpx.RequestError as e:
+            raise APIException(f"Request failed: {str(e)}")
+
+
+async def cancel_bulk_run_api(
+    bulk_run_id: str,
+    api_key: str,
+) -> BulkRunCancelResponse:
+    """
+    Cancel a bulk run via the REST API.
+    """
+    url = f"{BASE_URL}/bulk/execution/{bulk_run_id}/cancel"
+    headers = {
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+        "PIM-SID": api_key,
+    }
+
+    async with httpx.AsyncClient() as client:
+        try:
+            response = await client.put(
+                url,
+                headers=headers,
+                timeout=30.0,
+            )
+            response.raise_for_status()
+            data = response.json()
+
+            return BulkRunCancelResponse(
+                execution_id=data.get("execution_id", ""),
+                status=data.get("status", ""),
+                trace_id=data.get("trace_id"),
+            )
+        except httpx.HTTPStatusError as e:
+            raise APIException(
+                f"API request failed with status {e.response.status_code}: {e.response.text}",
+                status_code=e.response.status_code,
+            )
+        except httpx.RequestError as e:
+            raise APIException(f"Request failed: {str(e)}")
+
+
+async def download_bulk_run_result_api(
+    bulk_run_id: str,
+    api_key: str,
+) -> str:
+    """
+    Download the bulk run result as raw CSV text.
+    """
+    url = f"{BASE_URL}/bulk/run/{bulk_run_id}/download"
+    headers = {
+        "Accept": "text/csv",
+        "Content-Type": "application/json",
+        "PIM-SID": api_key,
+    }
+
+    async with httpx.AsyncClient() as client:
+        try:
+            response = await client.get(
+                url,
+                headers=headers,
+                timeout=60.0,
+            )
+            response.raise_for_status()
+            # The API returns raw CSV (text/csv)
+            return response.text
+        except httpx.HTTPStatusError as e:
+            raise APIException(
+                f"API request failed with status {e.response.status_code}: {e.response.text}",
+                status_code=e.response.status_code,
+            )
+        except httpx.RequestError as e:
+            raise APIException(f"Request failed: {str(e)}")

core/workflows/bulk/client.py

@@ -0,0 +1,115 @@
+"""Public SDK interface for bulk workflow execution."""
+
+from typing import Dict, List
+
+from .api import trigger_bulk_run_api
+from .api import get_bulk_run_status_api
+from .api import cancel_bulk_run_api
+from .api import download_bulk_run_result_api
+
+
+async def trigger_bulk_run(
+    workflow_id: str,
+    file_link: str,
+    batch_size: int,
+    input_mapping: List[Dict[str, str]],
+    api_key: str,
+) -> Dict[str, str]:
+    """
+    Trigger a bulk run of workflows.
+    
+    Args:
+        workflow_id: The workflow ID to execute
+        file_link: URL/link to the input file containing the data
+        batch_size: Number of records to process per batch
+        input_mapping: List of dictionaries mapping workflow input fields to file columns.
+                      Each dictionary should have:
+                      - "app_input_field": The workflow input field name
+                      - "file_input_field": The file column/field name
+                      Example: [
+                          {"app_input_field": "num_1", "file_input_field": "A"},
+                          {"app_input_field": "num_2", "file_input_field": "B"}
+                      ]
+        api_key: API key for authentication
+        
+    Returns:
+        Dictionary with bulk_run_id and status:
+        {
+            "bulk_run_id": str,
+            "status": str
+        }
+    """
+    response = await trigger_bulk_run_api(
+        workflow_id=workflow_id,
+        file_link=file_link,
+        batch_size=batch_size,
+        input_mapping=input_mapping,
+        api_key=api_key,
+    )
+    
+    return {
+        "bulk_run_id": response.execution_id,
+        "status": response.status,
+    }
+
+
+async def get_bulk_run_status(
+    bulk_run_id: str,
+    api_key: str,
+) -> Dict[str, str]:
+    """
+    Get the bulk run result by bulk run ID.
+    
+    Args:
+        bulk_run_id: The bulk run ID to check
+        api_key: API key for authentication
+    """
+    response = await get_bulk_run_status_api(
+        bulk_run_id=bulk_run_id,
+        api_key=api_key,
+    )
+    
+    return {
+        "bulk_run_id": response.execution_id,
+        "status": response.status,
+        "batch_completed": response.batch_completed,
+        "total_batches": response.total_batches,
+        "trace_id": response.trace_id,
+    }
+
+
+async def cancel_bulk_run(
+    bulk_run_id: str,
+    api_key: str,
+) -> Dict[str, str]:
+    """
+    Cancel a bulk run by bulk run ID.
+    """
+    response = await cancel_bulk_run_api(
+        bulk_run_id=bulk_run_id,
+        api_key=api_key,
+    )
+
+    result: Dict[str, str] = {
+        "bulk_run_id": response.execution_id,
+        "status": response.status,
+    }
+
+    if response.trace_id:
+        result["trace_id"] = response.trace_id
+
+    return result
+
+
+async def download_bulk_run_result(
+    bulk_run_id: str,
+    api_key: str,
+) -> str:
+    """
+    Download the bulk run result as CSV text for the given bulk_run_id.
+    """
+    return await download_bulk_run_result_api(
+        bulk_run_id=bulk_run_id,
+        api_key=api_key,
+    )
+

core/workflows/bulk/schema.py

@@ -0,0 +1,58 @@
+"""Pydantic schemas for bulk workflow execution API requests and responses."""
+
+from typing import Any, Dict, List, Optional
+from pydantic import BaseModel, Field
+
+
+class InputFieldMapping(BaseModel):
+    """Schema for input field mapping."""
+    app_input_field: str = Field(..., description="The workflow input field name")
+    file_input_field: str = Field(..., description="The file column/field name")
+
+
+class BulkRunRequest(BaseModel):
+    """Request schema for triggering a bulk workflow run."""
+    file_url: str = Field(..., description="URL/link to the input file")
+    tool_id: str = Field(..., description="The workflow ID")
+    batch_size: int = Field(..., description="Number of records to process per batch")
+    input_fields_mapping: List[InputFieldMapping] = Field(
+        ..., 
+        description="Mapping between workflow input fields and file columns"
+    )
+
+
+class BulkRunResponse(BaseModel):
+    """Response schema from bulk run API."""
+    execution_id: str = Field(..., alias="execution_id", description="The bulk run execution ID")
+    status: str = Field(..., description="Execution status (e.g., ACCEPTED)")
+
+    class Config:
+        populate_by_name = True
+
+class BulkRunStatusRequest(BaseModel):
+    """Request schema for getting the bulk run status."""
+    execution_id: str = Field(..., description="The bulk run ID")
+
+    class Config:
+        populate_by_name = True
+
+class BulkRunStatusResponse(BaseModel):
+    """Response schema from bulk run client."""
+    execution_id: str = Field(..., alias="execution_id", description="The bulk run execution ID")
+    status: str = Field(..., description="Execution status (e.g., ACCEPTED, COMPLETED, FAILED, CANCELLED)")
+    batch_completed: int = Field(..., description="Number of completed batches")
+    total_batches: int = Field(..., description="Total number of batches")
+    trace_id: Optional[str] = Field(None, description="Trace identifier for the bulk run")
+
+    class Config:
+        populate_by_name = True
+
+
+class BulkRunCancelResponse(BaseModel):
+    """Response schema from bulk run cancel API."""
+    execution_id: str = Field(..., alias="execution_id", description="The bulk run execution ID")
+    status: str = Field(..., description="Execution status after cancel (e.g., CANCELLED)")
+    trace_id: Optional[str] = Field(None, description="Trace identifier for the bulk run")
+
+    class Config:
+        populate_by_name = True

core/workflows/models.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Dict
+
+
+class ExecutionStatus(str, Enum):
+    """Known execution status values returned by the Simplai workflow API."""
+
+    PENDING = "PENDING"
+    RUNNING = "RUNNING"
+    SUCCEEDED = "SUCCEEDED"
+    FAILED = "FAILED"
+    CANCELED = "CANCELED"
+    TIMEOUT = "TIMEOUT"
+    UNKNOWN = "UNKNOWN"
+
+    @classmethod
+    def from_raw(cls, value: Any) -> "ExecutionStatus":
+        """Convert a raw status value from the API into an ExecutionStatus."""
+        if not isinstance(value, str):
+            return cls.UNKNOWN
+        upper = value.upper()
+        for member in cls:
+            if member.value == upper:
+                return member
+        return cls.UNKNOWN
+
+
+@dataclass
+class WorkflowResult:
+    """Final result of a workflow execution in synchronous mode."""
+
+    execution_id: str
+    status: ExecutionStatus
+    payload: Dict[str, Any]
+
+    @property
+    def succeeded(self) -> bool:
+        """True if the workflow completed successfully."""
+        return self.status == ExecutionStatus.SUCCEEDED
+
+
+class WorkflowExecutionError(Exception):
+    """Raised when a workflow fails, times out, or cannot be executed."""
+
+
+

core/workflows/scheduling/__init__.py

@@ -0,0 +1,9 @@
+"""Public SDK interface for scheduled workflow execution."""
+
+from .client import schedule_run, cancel_schedule_run
+
+__all__ = [
+    "schedule_run",
+    "cancel_schedule_run",
+]
+

core/workflows/scheduling/api.py

@@ -0,0 +1,179 @@
+"""Low-level HTTP API layer for scheduled workflow execution."""
+
+from math import log
+from typing import Any, Dict, List, Optional, Union
+import httpx
+
+from exceptions import APIException
+
+from .schema import (
+    ScheduleRunRequest,
+    ScheduleRunResponse,
+    ScheduleRunResult,
+    ScheduleCancelRequest,
+    ScheduleCancelResponse,
+    BulkInputFieldMapping,
+    ManualInputFieldMapping,
+)
+
+
+from constants import WORKFLOW_BASE_URL as BASE_URL
+
+
+async def schedule_run_api(
+    workflow_id: str,
+    scheduled_run_type: str,
+    cron_expression: str,
+    time_zone: str,
+    input_mapping: List[Dict[str, str]],
+    api_key: str,
+    file_url: Optional[str] = None,
+    batch_size: Optional[int] = None,
+) -> ScheduleRunResponse:
+    """
+    Schedule a workflow run via the REST API (supports both BULK and MANUAL types).
+    
+    Args:
+        workflow_id: The workflow ID to execute
+        scheduled_run_type: Type of scheduled run - 'BULK' or 'MANUAL'
+        cron_expression: Cron expression for scheduling (e.g., "47 22 11 2 1 ?")
+        time_zone: Time zone for the schedule (e.g., "Asia/Kolkata")
+        input_mapping: List of dictionaries with input field mappings.
+                      For BULK: [{"app_input_field": "x", "file_input_field": "A"}]
+                      For MANUAL: [{"app_input_field": "x", "value": "y"}]
+        api_key: API key for authentication
+        file_url: URL/link to the input file (required for BULK, ignored for MANUAL)
+        batch_size: Number of records to process per batch (required for BULK, optional for MANUAL)
+        
+    Returns:
+        ScheduleRunResponse with execution_id and status
+        
+    Raises:
+        APIException: If the API request fails
+        ValueError: If required fields are missing for the scheduled_run_type
+    """
+    # Validate required fields based on scheduled_run_type
+    scheduled_run_type_upper = scheduled_run_type.upper()
+    if scheduled_run_type_upper not in ["BULK", "MANUAL"]:
+        raise ValueError(f"scheduled_run_type must be 'BULK' or 'MANUAL', got '{scheduled_run_type}'")
+    
+    if scheduled_run_type_upper == "BULK":
+        if not file_url:
+            raise ValueError("file_url is required when scheduled_run_type is 'BULK'")
+
+    
+    # Build the request body
+    request_data: Dict[str, Any] = {
+        "tool_id": workflow_id,
+        "scheduled_run_type": scheduled_run_type_upper,
+        "cron_expression": cron_expression,
+        "time_zone": time_zone,
+        "input_fields_mapping": input_mapping,
+        "batch_size": batch_size,
+    }
+    
+    # Add BULK-specific / shared fields if applicable
+    if scheduled_run_type_upper == "BULK":
+        request_data["file_url"] = file_url
+
+    # batch_size can be used for both BULK and MANUAL if provided
+
+    print(f"request_data : {request_data}")
+    
+    url = f"{BASE_URL}/schedule/run"
+    headers = {
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+        "PIM-SID": api_key,
+    }
+    
+    async with httpx.AsyncClient() as client:
+        try:
+            response = await client.post(
+                url,
+                headers=headers,
+                json=request_data,
+                timeout=30.0,
+            )
+            response.raise_for_status()
+            data = response.json()
+            
+            # Parse nested result object if present
+            result_obj = None
+            if "result" in data and data["result"]:
+                result_data = data["result"]
+                result_obj = ScheduleRunResult(
+                    unique_id=result_data.get("unique_id", ""),
+                    job_master_id=result_data.get("job_master_id", ""),
+                )
+            
+            return ScheduleRunResponse(
+                app_id=data.get("app_id", ""),
+                status=data.get("status", ""),
+                execution_mode=data.get("execution_mode"),
+                result=result_obj,
+                trace_id=data.get("trace_id"),
+            )
+        except httpx.HTTPStatusError as e:
+            raise APIException(
+                f"API request failed with status {e.response.status_code}: {e.response.text}",
+                status_code=e.response.status_code,
+            )
+        except httpx.RequestError as e:
+            raise APIException(f"Request failed: {str(e)}")
+
+
+async def cancel_schedule_run_api(
+    job_master_id: Union[int, str],
+    unique_id: str,
+    api_key: str,
+) -> ScheduleCancelResponse:
+    """
+    Cancel a scheduled run via the REST API.
+    
+    Args:
+        job_master_id: Job master identifier (can be int or str)
+        unique_id: Unique identifier for the scheduled run
+        api_key: API key for authentication
+        
+    Returns:
+        ScheduleCancelResponse with status and trace_id
+        
+    Raises:
+        APIException: If the API request fails
+    """
+    url = f"{BASE_URL}/schedule/cancel"
+    headers = {
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+        "PIM-SID": api_key,
+    }
+    
+    request_data = {
+        "job_master_id": job_master_id,
+        "unique_id": unique_id,
+    }
+    
+    async with httpx.AsyncClient() as client:
+        try:
+            response = await client.put(
+                url,
+                headers=headers,
+                json=request_data,
+                timeout=30.0,
+            )
+            response.raise_for_status()
+            data = response.json()
+            
+            return ScheduleCancelResponse(
+                status=data.get("status", ""),
+                trace_id=data.get("trace_id"),
+            )
+        except httpx.HTTPStatusError as e:
+            raise APIException(
+                f"API request failed with status {e.response.status_code}: {e.response.text}",
+                status_code=e.response.status_code,
+            )
+        except httpx.RequestError as e:
+            raise APIException(f"Request failed: {str(e)}")
+