simplai-sdk 0.1.0__py3-none-any.whl

core/workflows/scheduling/client.py

@@ -0,0 +1,128 @@
+"""Public SDK interface for scheduled workflow execution."""
+
+from typing import Dict, List, Optional, Union
+
+from .api import schedule_run_api, cancel_schedule_run_api
+
+
+async def schedule_run(
+    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,
+) -> Dict[str, str]:
+    """
+    Schedule a workflow run (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": "number_1", "file_input_field": "A"}]
+                      For MANUAL: [{"app_input_field": "interview_id", "value": "0148eee6-a867-4c7a-8d42-f039a5ef6adf"}]
+        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:
+        Dictionary with unique_id, job_master_id, trace_id, and status:
+        {
+            "unique_id": str,
+            "job_master_id": str,
+            "trace_id": str,
+            "status": str
+        }
+        
+    Example - BULK scheduled run:
+        await schedule_run(
+            workflow_id="695cafaffa8b738fc69146aa",
+            scheduled_run_type="BULK",
+            cron_expression="47 22 11 2 1 ?",
+            time_zone="Asia/Kolkata",
+            input_mapping=[
+                {"app_input_field": "number_1", "file_input_field": "A"},
+                {"app_input_field": "number_2", "file_input_field": "B"}
+            ],
+            api_key="your_api_key",
+            file_url="s3://media-simplai/2025-10-03T16:04:23.490089839-bulk_test.csv",
+            batch_size=1,
+        )
+        
+    Example - MANUAL scheduled run:
+        await schedule_run(
+            workflow_id="6915a7785ac679cd4de1d4d5",
+            scheduled_run_type="MANUAL",
+            cron_expression="47 22 11 2 1 *",
+            time_zone="Asia/Kolkata",
+            input_mapping=[
+                {"app_input_field": "interview_id", "value": "0148eee6-a867-4c7a-8d42-f039a5ef6adf"}
+            ],
+            api_key="your_api_key",
+        )
+    """
+    response = await schedule_run_api(
+        workflow_id=workflow_id,
+        scheduled_run_type=scheduled_run_type,
+        cron_expression=cron_expression,
+        time_zone=time_zone,
+        input_mapping=input_mapping,
+        api_key=api_key,
+        file_url=file_url,
+        batch_size=batch_size,
+    )
+    
+    result: Dict[str, str] = {
+        "status": response.status,
+    }
+    
+    if response.result:
+        result["unique_id"] = response.result.unique_id
+        result["job_master_id"] = response.result.job_master_id
+    
+    if response.trace_id:
+        result["trace_id"] = response.trace_id
+    
+    return result
+
+
+async def cancel_schedule_run(
+    job_master_id: Union[int, str],
+    unique_id: str,
+    api_key: str,
+) -> Dict[str, str]:
+    """
+    Cancel a scheduled run by job_master_id and unique_id.
+    
+    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:
+        Dictionary with status and trace_id:
+        {
+            "status": str,
+            "trace_id": str
+        }
+    """
+    response = await cancel_schedule_run_api(
+        job_master_id=job_master_id,
+        unique_id=unique_id,
+        api_key=api_key,
+    )
+    
+    result: Dict[str, str] = {
+        "status": response.status,
+    }
+    
+    if response.trace_id:
+        result["trace_id"] = response.trace_id
+    
+    return result
+

core/workflows/scheduling/schema.py

@@ -0,0 +1,74 @@
+"""Pydantic schemas for scheduled workflow execution API requests and responses."""
+
+from typing import Any, Dict, List, Optional, Union
+from pydantic import BaseModel, Field
+
+
+class BulkInputFieldMapping(BaseModel):
+    """Schema for bulk input field mapping (file-based)."""
+    app_input_field: str = Field(..., description="The workflow input field name")
+    file_input_field: str = Field(..., description="The file column/field name")
+
+
+class ManualInputFieldMapping(BaseModel):
+    """Schema for manual input field mapping (value-based)."""
+    app_input_field: str = Field(..., description="The workflow input field name")
+    value: str = Field(..., description="The static value for the input field")
+
+
+class ScheduleRunRequest(BaseModel):
+    """Request schema for scheduling a workflow run (supports both BULK and MANUAL)."""
+    tool_id: str = Field(..., description="The workflow ID")
+    scheduled_run_type: str = Field(..., description="Type of scheduled run: 'BULK' or 'MANUAL'")
+    cron_expression: str = Field(..., description="Cron expression for scheduling")
+    time_zone: str = Field(..., description="Time zone for the schedule (e.g., 'Asia/Kolkata')")
+    
+    # BULK-specific fields (optional, required when scheduled_run_type is 'BULK')
+    file_url: Optional[str] = Field(None, description="URL/link to the input file (required for BULK)")
+    batch_size: Optional[int] = Field(None, description="Number of records to process per batch (required for BULK)")
+    
+    # Input field mappings - can be either bulk or manual format
+    input_fields_mapping: List[Dict[str, str]] = Field(
+        ..., 
+        description="List of input field mappings. For BULK: [{'app_input_field': 'x', 'file_input_field': 'A'}]. For MANUAL: [{'app_input_field': 'x', 'value': 'y'}]"
+    )
+
+    class Config:
+        populate_by_name = True
+
+
+class ScheduleRunResult(BaseModel):
+    """Nested result object in schedule run response."""
+    unique_id: str = Field(..., description="Unique identifier for the scheduled run")
+    job_master_id: str = Field(..., description="Job master identifier")
+
+
+class ScheduleRunResponse(BaseModel):
+    """Response schema from schedule run API."""
+    app_id: str = Field(..., alias="app_id", description="The workflow/app ID")
+    status: str = Field(..., description="Execution status (e.g., ACCEPTED)")
+    execution_mode: Optional[str] = Field(None, description="Execution mode (e.g., ASYNC)")
+    result: Optional[ScheduleRunResult] = Field(None, description="Result object with unique_id and job_master_id")
+    trace_id: Optional[str] = Field(None, description="Trace identifier for the scheduled run")
+
+    class Config:
+        populate_by_name = True
+
+
+class ScheduleCancelRequest(BaseModel):
+    """Request schema for canceling a scheduled run."""
+    job_master_id: Union[int, str] = Field(..., description="Job master identifier")
+    unique_id: str = Field(..., description="Unique identifier for the scheduled run")
+
+    class Config:
+        populate_by_name = True
+
+
+class ScheduleCancelResponse(BaseModel):
+    """Response schema from schedule cancel API."""
+    status: str = Field(..., description="Cancellation status (e.g., CANCELLED)")
+    trace_id: Optional[str] = Field(None, description="Trace identifier for the cancelled run")
+
+    class Config:
+        populate_by_name = True
+

core/workflows/tool_execution/__init__.py

@@ -0,0 +1,16 @@
+"""Public SDK interface for workflow execution."""
+
+from .client import (
+    execute_workflow,
+    get_tool_result,
+    execute_and_wait_workflow,
+    cancel_execution,
+)
+
+__all__ = [
+    "execute_workflow",
+    "get_tool_result",
+    "execute_and_wait_workflow",
+    "cancel_execution",
+]
+

core/workflows/tool_execution/api.py

@@ -0,0 +1,172 @@
+"""Low-level HTTP API layer for workflow execution."""
+
+import json
+from typing import Any, Dict, Optional
+import httpx
+
+from .schema import (
+    ExecuteWorkflowRequest,
+    ExecuteWorkflowResponse,
+    ExecutionStatusResponse,
+    CancelExecutionResponse,
+)
+from exceptions import APIException
+
+
+from constants import WORKFLOW_BASE_URL as BASE_URL
+
+async def execute_workflow_api(
+    workflow_id: str,
+    inputs: Dict[str, Any],
+    api_key: str,
+) -> ExecuteWorkflowResponse:
+    """
+    Execute a workflow via the REST API.
+    
+    Args:
+        workflow_id: The workflow ID to execute
+        inputs: Input parameters for the workflow
+        api_key: API key for authentication
+        
+    Returns:
+        ExecuteWorkflowResponse with execution_id and status
+        
+    Raises:
+        APIException: If the API request fails
+    """
+    url = f"{BASE_URL}/execute"
+    headers = {
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+        "PIM-SID": api_key,
+    }
+    
+    request_body = ExecuteWorkflowRequest(
+        app_id=workflow_id,
+        inputs=inputs,
+    )
+
+
+    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 ExecuteWorkflowResponse(
+                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_execution_status_api(
+    execution_id: str,
+    api_key: str,
+) -> ExecutionStatusResponse:
+    """
+    Get the execution status and result via the REST API.
+    
+    Args:
+        execution_id: The execution ID to check
+        api_key: API key for authentication
+        
+    Returns:
+        ExecutionStatusResponse with executionId, traceId, status, and parsed result
+        
+    Raises:
+        APIException: If the API request fails
+    """
+    url = f"{BASE_URL}/executions/{execution_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()
+            
+            # Extract and parse result from raw_response.api_response.result
+            raw_response = data.get("raw_response", {})
+            api_response = raw_response.get("api_response") if raw_response else None
+            
+            return ExecutionStatusResponse(
+                executionId=data.get("executionId", ""),
+                traceId=data.get("traceId"),
+                status=data.get("status", ""),
+                api_response=api_response,
+            )
+        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_execution_api(
+    execution_id: str,
+    api_key: str,
+) -> CancelExecutionResponse:
+    """
+    Cancel an execution via the REST API.
+    
+    Args:
+        execution_id: The execution ID to cancel
+        api_key: API key for authentication
+        
+    Returns:
+        CancelExecutionResponse with execution_id and status
+        
+    Raises:
+        APIException: If the API request fails
+    """
+    url = f"{BASE_URL}/executions/{execution_id}/cancel"
+    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,
+                timeout=30.0,
+            )
+            response.raise_for_status()
+            data = response.json()
+            
+            return CancelExecutionResponse(
+                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)}")
+

core/workflows/tool_execution/client.py

@@ -0,0 +1,195 @@
+"""Public SDK interface for workflow execution."""
+
+import asyncio
+import time
+from typing import Any, Dict, Optional
+
+from constants import TERMINAL_STATES
+
+from .api import execute_workflow_api, get_execution_status_api, cancel_execution_api
+from exceptions import TimeoutException
+
+
+
+async def execute_workflow(
+    workflow_id: str,
+    inputs: Dict[str, Any],
+    api_key: str,
+) -> Dict[str, str]:
+    """
+    Execute a workflow and return the execution ID.
+    
+    Args:
+        workflow_id: The workflow ID to execute
+        inputs: Input parameters for the workflow
+        api_key: API key for authentication
+        
+    Returns:
+        Dictionary with execution_id and status:
+        {
+            "execution_id": str,
+            "status": str
+        }
+    """
+    response = await execute_workflow_api(
+        workflow_id=workflow_id,
+        inputs=inputs,
+        api_key=api_key,
+    )
+    
+    return {
+        "execution_id": response.execution_id,
+        "status": response.status,
+    }
+
+
+async def get_tool_result(
+    execution_id: str,
+    api_key: str,
+) -> Dict[str, Any]:
+    """
+    Get the execution result by execution ID.
+    
+    Args:
+        execution_id: The execution ID to check
+        api_key: API key for authentication
+        
+    Returns:
+        Dictionary with executionId, traceId, status, and result:
+        {
+            "executionId": str,
+            "traceId": str (optional),
+            "status": str,
+            "result": Any (parsed JSON if possible)
+        }
+    """
+    response = await get_execution_status_api(
+        execution_id=execution_id,
+        api_key=api_key,
+    )
+    
+    result = {
+        "executionId": response.executionId,
+        "status": response.status,
+    }
+    
+    if response.traceId:
+        result["traceId"] = response.traceId
+    
+    if response.api_response is not None:
+        result["api_response"] = response.api_response
+    
+    return result
+
+
+async def execute_and_wait_workflow(
+    workflow_id: str,
+    inputs: Dict[str, Any],
+    api_key: str,
+    timeout: float = 60.0,
+    poll_interval: float = 2.0,
+) -> Dict[str, Any]:
+    """
+    Execute a workflow and wait for completion with polling.
+    
+    Args:
+        workflow_id: The workflow ID to execute
+        inputs: Input parameters for the workflow
+        api_key: API key for authentication
+        timeout: Maximum time to wait in seconds (default: 60.0)
+        poll_interval: Time between polls in seconds (default: 2.0)
+        
+    Returns:
+        Dictionary with executionId, traceId, status, and result:
+        {
+            "executionId": str,
+            "traceId": str (optional),
+            "status": str,
+            "result": Any (parsed JSON if possible)
+        }
+        
+    Raises:
+        TimeoutException: If the execution doesn't complete within the timeout
+    """
+    # Step 1: Execute the workflow
+    execution_info = await execute_workflow(
+        workflow_id=workflow_id,
+        inputs=inputs,
+        api_key=api_key,
+    )
+    
+    execution_id = execution_info["execution_id"]
+    start_time = time.time()
+    
+    # Step 2: Poll for completion
+    while True:
+        elapsed_time = time.time() - start_time
+        
+        # Check timeout
+        if elapsed_time >= timeout:
+            raise TimeoutException(
+                f"Workflow execution timed out after {timeout} seconds. "
+                f"Execution ID: {execution_id}"
+            )
+        
+        # Get execution status
+        result = await get_tool_result(
+            execution_id=execution_id,
+            api_key=api_key,
+        )
+        
+        status = result.get("status", "").upper()
+        
+        # Check if we've reached a terminal state
+        if status in TERMINAL_STATES:
+            return result
+        
+        # If still pending, wait before next poll
+        if status == "PENDING":
+            # Calculate remaining time and sleep for poll_interval or remaining time, whichever is smaller
+            remaining_time = timeout - elapsed_time
+            sleep_time = min(poll_interval, remaining_time)
+            if sleep_time > 0:
+                await asyncio.sleep(sleep_time)
+            else:
+                # No time left, will timeout on next iteration
+                continue
+        
+        # For any other non-terminal state, continue polling
+        remaining_time = timeout - elapsed_time
+        sleep_time = min(poll_interval, remaining_time)
+        if sleep_time > 0:
+            await asyncio.sleep(sleep_time)
+        else:
+            # No time left, will timeout on next iteration
+            continue
+
+
+async def cancel_execution(
+    execution_id: str,
+    api_key: str,
+) -> Dict[str, str]:
+    """
+    Cancel an execution by execution ID.
+    
+    Args:
+        execution_id: The execution ID to cancel
+        api_key: API key for authentication
+        
+    Returns:
+        Dictionary with execution_id and status:
+        {
+            "execution_id": str,
+            "status": str
+        }
+    """
+    response = await cancel_execution_api(
+        execution_id=execution_id,
+        api_key=api_key,
+    )
+    
+    return {
+        "execution_id": response.execution_id,
+        "status": response.status,
+    }
+

core/workflows/tool_execution/schema.py

@@ -0,0 +1,40 @@
+"""Pydantic schemas for workflow execution API requests and responses."""
+
+from typing import Any, Dict, Optional
+from pydantic import BaseModel, Field
+
+
+class ExecuteWorkflowRequest(BaseModel):
+    """Request schema for executing a workflow."""
+    app_id: str = Field(..., description="The workflow ID")
+    inputs: Dict[str, Any] = Field(default_factory=dict, description="Input parameters for the workflow")
+
+
+class ExecuteWorkflowResponse(BaseModel):
+    """Response schema from execute workflow API."""
+    execution_id: str = Field(..., alias="execution_id")
+    status: str = Field(..., description="Execution status (e.g., PENDING)")
+
+    class Config:
+        populate_by_name = True
+
+
+class ExecutionStatusResponse(BaseModel):
+    """Response schema from get execution status API."""
+    executionId: str = Field(..., description="The execution ID")
+    traceId: Optional[str] = Field(None, description="The trace ID")
+    status: str = Field(..., description="Execution status (e.g., COMPLETED, FAILED, CANCELLED, PENDING)")
+    api_response: Optional[Dict[str, Any]] = Field(None, description="Raw response from the API")
+
+    class Config:
+        populate_by_name = True
+
+
+class CancelExecutionResponse(BaseModel):
+    """Response schema from cancel execution API."""
+    execution_id: str = Field(..., alias="execution_id", description="The execution ID")
+    status: str = Field(..., description="Execution status (e.g., COMPLETE)")
+
+    class Config:
+        populate_by_name = True
+

exceptions/__init__.py

@@ -0,0 +1,21 @@
+"""Custom exceptions for the SimplAI Python SDK."""
+
+from typing import Optional
+
+
+class SimplAIException(Exception):
+    """Base exception for all SimplAI SDK exceptions."""
+    pass
+
+
+class TimeoutException(SimplAIException):
+    """Raised when a workflow execution times out."""
+    pass
+
+
+class APIException(SimplAIException):
+    """Raised when an API request fails."""
+    def __init__(self, message: str, status_code: Optional[int] = None):
+        super().__init__(message)
+        self.status_code = status_code
+

simplai_sdk/__init__.py

@@ -0,0 +1,7 @@
+from .simplai import SimplAI
+from traces.agents import get_trace_tree
+
+__all__ = [
+    "SimplAI",
+    "get_trace_tree",
+]