simplai-sdk 0.1.0__py3-none-any.whl

core/agents/models.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+
+class AgentStatus(str, Enum):
+    """Known agent response status values returned by the Simplai agent API.
+    
+    The API returns messageStatus as an integer:
+    - 0 or None = PENDING/PROCESSING
+    - 1 = PROCESSING
+    - 2 = COMPLETED
+    - Other values = FAILED/ERROR
+    """
+
+    PENDING = "PENDING"
+    PROCESSING = "PROCESSING"
+    COMPLETED = "COMPLETED"
+    FAILED = "FAILED"
+    TIMEOUT = "TIMEOUT"
+    UNKNOWN = "UNKNOWN"
+
+    @classmethod
+    def from_raw(cls, value: Any) -> "AgentStatus":
+        """Convert a raw status value from the API into an AgentStatus.
+        
+        Handles both integer messageStatus and string status values.
+        """
+        # Handle integer messageStatus (0, 1, 2, etc.)
+        if isinstance(value, int):
+            if value == 0:
+                return cls.PROCESSING  # 0 typically means processing
+            elif value == 1:
+                return cls.PROCESSING
+            elif value == 2:
+                return cls.COMPLETED
+            else:
+                return cls.FAILED
+        
+        # Handle None/empty
+        if value is None:
+            return cls.PROCESSING
+        
+        # Handle string values
+        if isinstance(value, str):
+            upper = value.upper()
+            for member in cls:
+                if member.value == upper:
+                    return member
+        
+        return cls.UNKNOWN
+
+
+@dataclass
+class AgentMessage:
+    """Represents a message in agent conversation."""
+
+    role: str  # "user" or "assistant"
+    content: str
+    message_id: Optional[str] = None
+
+
+@dataclass
+class AgentResult:
+    """Final result of an agent conversation."""
+
+    conversation_id: str
+    message_id: str
+    status: AgentStatus
+    response: str
+    payload: Dict[str, Any]  # Full response from API
+    trace_id: Optional[str] = None  # Trace ID for tracing (from response)
+    node_id: Optional[str] = None  # Node ID for tracing (from response)
+
+    @property
+    def succeeded(self) -> bool:
+        """True if the agent conversation completed successfully."""
+        return self.status == AgentStatus.COMPLETED
+
+
+@dataclass
+class AgentStreamChunk:
+    """Represents a chunk in streaming agent response."""
+
+    content: str
+    conversation_id: Optional[str] = None
+    message_id: Optional[str] = None
+    is_complete: bool = False
+    metadata: Optional[Dict[str, Any]] = None
+    trace_id: Optional[str] = None  # Trace ID from first chunk (for request-level traces)
+    node_id: Optional[str] = None  # Node ID from first chunk (for tree-based traces)
+    tree_id: Optional[str] = None  # Tree ID from first chunk (for tree-based traces)
+
+
+class AgentExecutionError(Exception):
+    """Raised when an agent conversation fails, times out, or cannot be executed."""
+

core/workflows/WORKFLOW_ARCHITECTURE.md

@@ -0,0 +1,417 @@
+# Workflow Execution Architecture
+
+## Overview
+The workflow execution system is organized in layers, from high-level API functions down to low-level HTTP client methods. Both synchronous and asynchronous execution paths are supported.
+
+## Architecture Layers
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  API Layer (api.py)                                         │
+│  - execute_workflow()      (sync high-level)                │
+│  - aexecute_workflow()     (async high-level)                │
+│  - get_execution_status()  (sync status check)              │
+│  - aget_execution_status() (async status check)             │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│  Client Layer (client.py)                                    │
+│  - SimplaiClient class                                       │
+│    ├─ execute_once() / aexecute_once()                      │
+│    ├─ get_status_once() / aget_status_once()                │
+│    └─ execute_and_wait() / aexecute_and_wait()              │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│  HTTP Layer (httpx)                                          │
+│  - _request_with_retries_sync()                             │
+│  - _request_with_retries_async()                             │
+└──────────────────────────────────────────────────────────────┘
+```
+
+## Module Responsibilities
+
+### 1. **constants.py** - Configuration
+- `DEFAULT_BASE_URL`: Base API endpoint
+- `EXECUTE_PATH`: Endpoint for workflow execution
+- `STATUS_PATH_TEMPLATE`: Endpoint template for status checks
+
+### 2. **models.py** - Data Models
+- `ExecutionStatus`: Enum for workflow states (PENDING, RUNNING, SUCCEEDED, etc.)
+- `WorkflowResult`: Result container with execution_id, status, and payload
+- `WorkflowExecutionError`: Exception for workflow failures
+
+### 3. **client.py** - HTTP Client & Polling Logic
+- `SimplaiClient`: Reusable HTTP client with retry logic
+- Handles both sync and async HTTP requests
+- Implements polling mechanism for waiting on workflow completion
+
+### 4. **api.py** - High-Level API
+- Convenience functions that wrap `SimplaiClient`
+- Supports "sync" and "async" modes
+- Provides simple interface for users
+
+---
+
+## Synchronous Workflow Execution Flow
+
+### Mode: "sync" (Polling until completion)
+
+```
+User calls:
+  execute_workflow(workflow_id, inputs, mode="sync")
+    │
+    ├─► Creates SimplaiClient instance
+    │
+    ├─► Calls client.execute_and_wait()
+    │     │
+    │     ├─► Step 1: Execute workflow
+    │     │     └─► client.execute_once()
+    │     │           └─► POST /interact/api/v2/tool/execute
+    │     │           └─► Returns execution_id
+    │     │
+    │     └─► Step 2: Poll until completion
+    │           │
+    │           ├─► Loop:
+    │           │     ├─► client.get_status_once(execution_id)
+    │           │     │     └─► GET /interact/api/v2/tool/executions/{id}/status
+    │           │     │
+    │           │     ├─► Check if terminal status:
+    │           │     │     - SUCCEEDED → Return WorkflowResult
+    │           │     │     - FAILED/CANCELED/TIMEOUT → Raise WorkflowExecutionError
+    │           │     │     - PENDING/RUNNING → Continue polling
+    │           │     │
+    │           │     └─► time.sleep(poll_interval)  # Wait before next poll
+    │           │
+    │           └─► Return WorkflowResult or raise exception
+    │
+    └─► Returns WorkflowResult to user
+```
+
+### Mode: "async" (Fire and forget)
+
+```
+User calls:
+  execute_workflow(workflow_id, inputs, mode="async")
+    │
+    ├─► Creates SimplaiClient instance
+    │
+    └─► Calls client.execute_once()
+          └─► POST /interact/api/v2/tool/execute
+          └─► Returns execution_id (string)
+    
+    Returns: execution_id (user must poll manually)
+```
+
+---
+
+## Asynchronous Workflow Execution Flow
+
+### Mode: "sync" (Polling until completion)
+
+```
+User calls:
+  await aexecute_workflow(workflow_id, inputs, mode="sync")
+    │
+    ├─► Creates SimplaiClient instance
+    │
+    ├─► Calls await client.aexecute_and_wait()
+    │     │
+    │     ├─► Step 1: Execute workflow
+    │     │     └─► await client.aexecute_once()
+    │     │           └─► POST /interact/api/v2/tool/execute (async)
+    │     │           └─► Returns execution_id
+    │     │
+    │     └─► Step 2: Poll until completion
+    │           │
+    │           ├─► Loop:
+    │           │     ├─► await client.aget_status_once(execution_id)
+    │           │     │     └─► GET /interact/api/v2/tool/executions/{id}/status (async)
+    │           │     │
+    │           │     ├─► Check if terminal status:
+    │           │     │     - SUCCEEDED → Return WorkflowResult
+    │           │     │     - FAILED/CANCELED/TIMEOUT → Raise WorkflowExecutionError
+    │           │     │     - PENDING/RUNNING → Continue polling
+    │           │     │
+    │           │     └─► await asyncio.sleep(poll_interval)  # Non-blocking wait
+    │           │
+    │           └─► Return WorkflowResult or raise exception
+    │
+    └─► Returns WorkflowResult to user
+```
+
+### Mode: "async" (Fire and forget)
+
+```
+User calls:
+  await aexecute_workflow(workflow_id, inputs, mode="async")
+    │
+    ├─► Creates SimplaiClient instance
+    │
+    └─► Calls await client.aexecute_once()
+          └─► POST /interact/api/v2/tool/execute (async)
+          └─► Returns execution_id (string)
+    
+    Returns: execution_id (user must poll manually)
+```
+
+---
+
+## Function Reference
+
+### High-Level API Functions (api.py)
+
+#### `execute_workflow()` - Synchronous
+```python
+def execute_workflow(
+    workflow_id: str,
+    inputs: Dict[str, Any],
+    *,
+    api_key: str,
+    mode: str = "sync",  # "sync" or "async"
+    timeout: Optional[float] = None,
+    poll_interval: float = 2.0,
+    base_url: str = DEFAULT_BASE_URL,
+) -> WorkflowResult | str:
+```
+- **mode="sync"**: Polls until completion, returns `WorkflowResult`
+- **mode="async"**: Returns immediately with `execution_id` (string)
+
+#### `aexecute_workflow()` - Asynchronous
+```python
+async def aexecute_workflow(...) -> WorkflowResult | str:
+```
+- Same as `execute_workflow()` but async/await compatible
+- Uses `await` for non-blocking operations
+
+#### `get_execution_status()` - Synchronous Status Check
+```python
+def get_execution_status(
+    execution_id: str,
+    *,
+    api_key: str,
+    base_url: str = DEFAULT_BASE_URL,
+) -> Dict[str, Any]:
+```
+- One-off status check (doesn't poll)
+- Returns raw status dictionary
+
+#### `aget_execution_status()` - Asynchronous Status Check
+```python
+async def aget_execution_status(...) -> Dict[str, Any]:
+```
+- Async version of `get_execution_status()`
+
+---
+
+### Client Methods (client.py)
+
+#### `SimplaiClient.execute_once()` - Sync Execute
+```python
+def execute_once(
+    self,
+    workflow_id: str,
+    inputs: Dict[str, Any],
+) -> str:
+```
+- Sends POST request to execute workflow
+- Returns `execution_id`
+- Uses `_request_with_retries_sync()` with retry logic
+
+#### `SimplaiClient.aexecute_once()` - Async Execute
+```python
+async def aexecute_once(...) -> str:
+```
+- Async version of `execute_once()`
+- Uses `_request_with_retries_async()`
+
+#### `SimplaiClient.get_status_once()` - Sync Status Check
+```python
+def get_status_once(self, execution_id: str) -> Dict[str, Any]:
+```
+- Sends GET request to check status
+- Returns raw status dictionary
+- Uses `_request_with_retries_sync()`
+
+#### `SimplaiClient.aget_status_once()` - Async Status Check
+```python
+async def aget_status_once(...) -> Dict[str, Any]:
+```
+- Async version of `get_status_once()`
+- Uses `_request_with_retries_async()`
+
+#### `SimplaiClient.execute_and_wait()` - Sync Polling
+```python
+def execute_and_wait(
+    self,
+    workflow_id: str,
+    inputs: Dict[str, Any],
+    *,
+    poll_interval: float = 2.0,
+    timeout: Optional[float] = None,
+) -> WorkflowResult:
+```
+**Flow:**
+1. Calls `execute_once()` to start workflow
+2. Enters polling loop:
+   - Calls `get_status_once()` to check status
+   - Checks if status is terminal (SUCCEEDED, FAILED, CANCELED, TIMEOUT)
+   - If terminal and SUCCEEDED → return `WorkflowResult`
+   - If terminal and not SUCCEEDED → raise `WorkflowExecutionError`
+   - If not terminal → `time.sleep(poll_interval)` and loop again
+3. Respects `timeout` parameter (raises error if exceeded)
+
+#### `SimplaiClient.aexecute_and_wait()` - Async Polling
+```python
+async def aexecute_and_wait(...) -> WorkflowResult:
+```
+- Async version of `execute_and_wait()`
+- Uses `await asyncio.sleep()` instead of `time.sleep()`
+- Non-blocking, allows other coroutines to run
+
+---
+
+## Polling Mechanism Details
+
+### Terminal States
+The polling loop stops when it encounters one of these states:
+- `SUCCEEDED`: Workflow completed successfully → Returns `WorkflowResult`
+- `FAILED`: Workflow failed → Raises `WorkflowExecutionError`
+- `CANCELED`: Workflow was canceled → Raises `WorkflowExecutionError`
+- `TIMEOUT`: Workflow timed out → Raises `WorkflowExecutionError`
+
+### Non-Terminal States
+- `PENDING`: Workflow queued but not started
+- `RUNNING`: Workflow currently executing
+- `UNKNOWN`: Status couldn't be parsed
+
+### Polling Behavior
+- **Default interval**: 2.0 seconds between polls
+- **Timeout**: Optional maximum wait time
+- **Sync**: Uses `time.sleep()` (blocks thread)
+- **Async**: Uses `asyncio.sleep()` (non-blocking, allows concurrency)
+
+---
+
+## Error Handling
+
+### Retry Logic
+Both sync and async request methods implement retry with exponential backoff:
+- **Max retries**: 3 (configurable)
+- **Backoff**: `backoff_factor * (2^attempt)` seconds
+- **Retries on**: 5xx server errors, transport errors
+- **No retry on**: 4xx client errors (immediate error)
+
+### Error Types
+- `WorkflowExecutionError`: Raised for:
+  - Workflow failures (FAILED, CANCELED, TIMEOUT status)
+  - HTTP client errors (4xx)
+  - Timeout exceeded
+  - Invalid JSON responses
+  - Missing execution_id in response
+
+---
+
+## Usage Examples
+
+### Synchronous Execution (Blocking)
+```python
+from simplai_sdk import execute_workflow
+
+# Poll until completion
+result = execute_workflow(
+    workflow_id="my-workflow",
+    inputs={"key": "value"},
+    api_key="my-api-key",
+    mode="sync",
+    timeout=60.0,
+    poll_interval=2.0
+)
+print(result.payload)  # Access result data
+
+# Fire and forget (get execution_id)
+execution_id = execute_workflow(
+    workflow_id="my-workflow",
+    inputs={"key": "value"},
+    api_key="my-api-key",
+    mode="async"
+)
+```
+
+### Asynchronous Execution (Non-blocking)
+```python
+from simplai_sdk import aexecute_workflow
+import asyncio
+
+async def main():
+    # Poll until completion (non-blocking)
+    result = await aexecute_workflow(
+        workflow_id="my-workflow",
+        inputs={"key": "value"},
+        api_key="my-api-key",
+        mode="sync",
+        timeout=60.0,
+        poll_interval=2.0
+    )
+    print(result.payload)
+    
+    # Fire and forget
+    execution_id = await aexecute_workflow(
+        workflow_id="my-workflow",
+        inputs={"key": "value"},
+        api_key="my-api-key",
+        mode="async"
+    )
+
+asyncio.run(main())
+```
+
+### Manual Status Checking
+```python
+from simplai_sdk import get_execution_status, aget_execution_status
+
+# Sync
+status = get_execution_status(
+    execution_id="exec-123",
+    api_key="my-api-key"
+)
+
+# Async
+status = await aget_execution_status(
+    execution_id="exec-123",
+    api_key="my-api-key"
+)
+```
+
+---
+
+## Key Differences: Sync vs Async
+
+| Aspect | Synchronous | Asynchronous |
+|--------|------------|--------------|
+| **Blocking** | Blocks thread during I/O | Non-blocking, allows concurrency |
+| **Sleep** | `time.sleep()` | `asyncio.sleep()` |
+| **HTTP Client** | `httpx.Client` | `httpx.AsyncClient` |
+| **Request Method** | `client.request()` | `await client.request()` |
+| **Use Case** | Simple scripts, blocking operations | Concurrent operations, web servers |
+| **Performance** | One workflow at a time | Can handle multiple workflows concurrently |
+
+---
+
+## Summary
+
+The workflow execution system provides:
+1. **High-level API** (`api.py`) - Simple functions for users
+2. **Client layer** (`client.py`) - Reusable client with polling logic
+3. **Models** (`models.py`) - Type-safe data structures
+4. **Constants** (`constants.py`) - Configuration values
+
+Both sync and async paths follow the same logical flow:
+1. Execute workflow → Get `execution_id`
+2. Poll status → Check for terminal state
+3. Return result or raise error
+
+The async path uses `await` and `asyncio.sleep()` to allow concurrent execution of multiple workflows, while the sync path blocks until completion.
+

core/workflows/__init__.py

@@ -0,0 +1,31 @@
+"""Backwards-compatibility shim for earlier imports.
+
+The implementation has been split into smaller modules for readability:
+- tool_execution: workflow execution APIs
+- bulk: bulk run APIs
+"""
+
+from .tool_execution import (
+    execute_workflow,
+    get_tool_result,
+    execute_and_wait_workflow,
+    cancel_execution,
+)
+
+from .bulk import (
+    trigger_bulk_run,
+    get_bulk_run_status,
+    cancel_bulk_run,
+    download_bulk_run_result,
+)
+
+__all__ = [
+    "execute_workflow",
+    "get_tool_result",
+    "execute_and_wait_workflow",
+    "cancel_execution",
+    "trigger_bulk_run",
+    "get_bulk_run_status",
+    "cancel_bulk_run",
+    "download_bulk_run_result",
+]

core/workflows/bulk/__init__.py

@@ -0,0 +1,14 @@
+"""Public SDK interface for bulk workflow execution."""
+
+from .client import trigger_bulk_run
+from .client import get_bulk_run_status
+from .client import cancel_bulk_run
+from .client import download_bulk_run_result
+__all__ = [
+    "trigger_bulk_run",
+    "get_bulk_run_status",
+    "cancel_bulk_run",
+    "download_bulk_run_result",
+]
+
+