simplex 1.0.0__py3-none-any.whl → 1.0.8__py3-none-any.whl

simplex/resources/workflow_session.py

@@ -0,0 +1,333 @@
+"""
+WorkflowSession class for managing Simplex workflow sessions.
+
+This module provides the WorkflowSession class which represents an active
+workflow session and provides methods for interacting with it.
+"""
+
+from typing import Any, Dict, List, Optional
+
+from simplex.errors import SimplexError, WorkflowError
+from simplex.http_client import HttpClient
+from simplex.types import AgenticResponse, RunAgentResponse
+
+
+class WorkflowSession:
+    """
+    Represents an active workflow session.
+    
+    A WorkflowSession provides methods for interacting with a running workflow,
+    including navigation, agent execution, and session management. It can be used
+    as a context manager for automatic cleanup.
+    
+    Example:
+        >>> with client.create_workflow_session(name="test", url="https://example.com") as session:
+        ...     session.goto("https://example.com/login")
+        ...     session.run_agent("Login Agent", variables={"username": "user"})
+        ...     # Session automatically closed when exiting the with block
+    
+    Attributes:
+        session_id: Unique identifier for this session
+        workflow_id: ID of the workflow
+        livestream_url: URL to view the live browser session
+        connect_url: URL to connect to the session
+        vnc_url: URL for VNC access
+    """
+    
+    def __init__(
+        self,
+        http_client: HttpClient,
+        session_data: Dict[str, str]
+    ):
+        """
+        Initialize a WorkflowSession.
+        
+        Args:
+            http_client: HTTP client for making API requests
+            session_data: Dictionary containing session information
+        """
+        self._http_client = http_client
+        self.session_id = session_data['sessionId']
+        self.workflow_id = session_data['workflowId']
+        self.livestream_url = session_data['livestreamUrl']
+        self.connect_url = session_data['connectUrl']
+        self.vnc_url = session_data['vncUrl']
+        self._closed = False
+    
+    def __enter__(self) -> 'WorkflowSession':
+        """
+        Enter the context manager.
+        
+        Returns:
+            This session instance
+        """
+        return self
+    
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """
+        Exit the context manager and close the session.
+        
+        Args:
+            exc_type: Exception type if an exception occurred
+            exc_val: Exception value if an exception occurred
+            exc_tb: Exception traceback if an exception occurred
+        """
+        self.close()
+    
+    def goto(self, url: str) -> Dict[str, Any]:
+        """
+        Navigate to a specific URL within the session.
+        
+        Args:
+            url: The URL to navigate to
+            
+        Returns:
+            Response from the navigation action
+            
+        Raises:
+            WorkflowError: If navigation fails
+        """
+        if self._closed:
+            raise WorkflowError("Cannot navigate - session is closed", session_id=self.session_id)
+        
+        try:
+            response = self._http_client.post(
+                '/agentic',
+                data={
+                    'task': f'Navigate to {url}',
+                    'session_id': self.session_id,
+                    'max_steps': 1
+                }
+            )
+            
+            if not response.get('succeeded'):
+                raise WorkflowError(
+                    f"Failed to navigate to {url}: {response.get('error', 'Unknown error')}",
+                    session_id=self.session_id
+                )
+            
+            return response
+        except SimplexError:
+            raise
+        except Exception as e:
+            raise WorkflowError(
+                f"Failed to navigate to {url}: {str(e)}",
+                session_id=self.session_id
+            )
+    
+    def agentic(
+        self,
+        task: str,
+        max_steps: Optional[int] = None,
+        actions_to_exclude: Optional[List[str]] = None,
+        variables: Optional[Dict[str, Any]] = None
+    ) -> AgenticResponse:
+        """
+        Execute an agentic task within this session.
+        
+        This method allows you to give natural language instructions to an agent
+        that will execute them within the browser session.
+        
+        Args:
+            task: Natural language description of what to do
+            max_steps: Maximum number of steps the agent can take (optional)
+            actions_to_exclude: List of action types to exclude (optional)
+            variables: Dictionary of variables to use in the task (optional)
+            
+        Returns:
+            Response containing task results
+            
+        Raises:
+            WorkflowError: If the task fails
+            
+        Example:
+            >>> session.agentic("Click the login button and enter credentials")
+        """
+        if self._closed:
+            raise WorkflowError("Cannot execute task - session is closed", session_id=self.session_id)
+        
+        import json
+        
+        request_data = {
+            'task': task,
+            'session_id': self.session_id
+        }
+        
+        if max_steps is not None:
+            request_data['max_steps'] = max_steps
+        
+        if actions_to_exclude:
+            request_data['actions_to_exclude'] = actions_to_exclude
+        
+        if variables:
+            request_data['variables'] = json.dumps(variables)
+        
+        try:
+            response = self._http_client.post('/agentic', data=request_data)
+            
+            if not response.get('succeeded') and response.get('error'):
+                raise SimplexError(
+                    f"Agent task failed: {response['error']}",
+                    status_code=500,
+                    data={'session_id': self.session_id, 'task': task}
+                )
+            
+            return response
+        except SimplexError:
+            raise
+        except Exception as e:
+            raise SimplexError(
+                f"Failed to run agent task: {str(e)}",
+                status_code=500,
+                data={'session_id': self.session_id, 'task': task}
+            )
+    
+    def run_agent(
+        self,
+        agent_name: str,
+        variables: Optional[Dict[str, Any]] = None
+    ) -> RunAgentResponse:
+        """
+        Run a named agent within this session.
+        
+        Named agents are pre-configured agents that can be executed by name.
+        
+        Args:
+            agent_name: Name of the agent to run
+            variables: Dictionary of variables to pass to the agent (optional)
+            
+        Returns:
+            Response containing agent execution results
+            
+        Raises:
+            SimplexError: If the agent execution fails
+            
+        Example:
+            >>> session.run_agent("Login Agent", variables={"username": "user@example.com"})
+        """
+        if self._closed:
+            raise WorkflowError("Cannot run agent - session is closed", session_id=self.session_id)
+        
+        request_data = {
+            'agent_name': agent_name,
+            'session_id': self.session_id
+        }
+        
+        if variables:
+            request_data['variables'] = variables
+        
+        try:
+            response = self._http_client.post('/run_agent', data=request_data)
+            
+            if not response.get('succeeded'):
+                raise SimplexError(
+                    f"Agent run failed for {agent_name}",
+                    status_code=500,
+                    data={'agent_name': agent_name, 'session_id': self.session_id}
+                )
+            
+            return response
+        except SimplexError:
+            raise
+        except Exception as e:
+            raise SimplexError(
+                f"Failed to run agent: {str(e)}",
+                status_code=500,
+                data={'agent_name': agent_name, 'session_id': self.session_id}
+            )
+    
+    def start_capture(self) -> Dict[str, bool]:
+        """
+        Start capture mode for this session.
+        
+        Capture mode records browser actions for later playback.
+        
+        Returns:
+            Response indicating success
+            
+        Raises:
+            WorkflowError: If starting capture mode fails
+        """
+        if self._closed:
+            raise WorkflowError("Cannot start capture - session is closed", session_id=self.session_id)
+        
+        try:
+            response = self._http_client.post(
+                '/start_capture_mode',
+                data={'session_id': self.session_id}
+            )
+            return response
+        except Exception as e:
+            raise WorkflowError(
+                f"Failed to start capture mode: {str(e)}",
+                session_id=self.session_id
+            )
+    
+    def stop_capture(self) -> Dict[str, bool]:
+        """
+        Stop capture mode for this session.
+        
+        Returns:
+            Response indicating success
+            
+        Raises:
+            WorkflowError: If stopping capture mode fails
+        """
+        if self._closed:
+            raise WorkflowError("Cannot stop capture - session is closed", session_id=self.session_id)
+        
+        try:
+            response = self._http_client.post(
+                '/stop_capture_mode',
+                data={'session_id': self.session_id}
+            )
+            return response
+        except Exception as e:
+            raise WorkflowError(
+                f"Failed to stop capture mode: {str(e)}",
+                session_id=self.session_id
+            )
+    
+    def close(self) -> Dict[str, Any]:
+        """
+        Close this workflow session.
+        
+        This releases resources associated with the session. Once closed,
+        the session cannot be used for further operations.
+        
+        Returns:
+            Response from closing the session
+            
+        Raises:
+            WorkflowError: If closing the session fails
+        """
+        if self._closed:
+            return {'succeeded': True, 'message': 'Session already closed'}
+        
+        try:
+            response = self._http_client.post(
+                '/close_workflow_session',
+                data={'session_id': self.session_id}
+            )
+            self._closed = True
+            return response
+        except Exception as e:
+            raise WorkflowError(
+                f"Failed to close workflow session: {str(e)}",
+                session_id=self.session_id
+            )
+    
+    @property
+    def is_closed(self) -> bool:
+        """
+        Check if the session is closed.
+        
+        Returns:
+            True if the session is closed, False otherwise
+        """
+        return self._closed
+    
+    def __repr__(self) -> str:
+        """Return a string representation of the session."""
+        status = "closed" if self._closed else "open"
+        return f"WorkflowSession(session_id='{self.session_id}', status='{status}')"

simplex/types.py

@@ -0,0 +1,276 @@
+"""
+Type definitions for the Simplex SDK.
+
+This module contains TypedDict classes and type aliases used throughout the SDK
+for type hinting and documentation purposes.
+"""
+
+from typing import Any, Dict, List, Optional, TypedDict
+
+
+class SimplexClientOptions(TypedDict, total=False):
+    """
+    Configuration options for the SimplexClient.
+    
+    Attributes:
+        api_key: Your Simplex API key (required)
+        timeout: Request timeout in seconds (default: 30)
+        max_retries: Maximum number of retry attempts (default: 3)
+        retry_delay: Delay between retries in seconds (default: 1)
+    """
+    api_key: str
+    timeout: int
+    max_retries: int
+    retry_delay: int
+
+
+# Type alias for workflow variables
+WorkflowVariables = Dict[str, Any]
+
+
+class RunWorkflowRequest(TypedDict, total=False):
+    """
+    Request parameters for running a workflow.
+    
+    Attributes:
+        workflow_id: The ID of the workflow to run (required)
+        metadata: Optional metadata string to attach to the workflow run
+        webhook_url: Optional webhook URL for status updates
+        variables: Dictionary of variables to pass to the workflow
+    """
+    workflow_id: str
+    metadata: str
+    webhook_url: str
+    variables: WorkflowVariables
+
+
+class RunWorkflowResponse(TypedDict):
+    """
+    Response from running a workflow.
+    
+    Attributes:
+        succeeded: Whether the workflow started successfully
+        message: Human-readable status message
+        session_id: Unique identifier for this workflow session
+        vnc_url: URL for VNC access to the workflow session
+    """
+    succeeded: bool
+    message: str
+    session_id: str
+    vnc_url: str
+
+
+class WorkflowAction(TypedDict):
+    """
+    Represents a single action taken during workflow execution.
+    
+    Attributes:
+        action: The type of action performed
+        params: Parameters passed to the action
+        result: Result returned by the action
+        timestamp: ISO 8601 timestamp when the action occurred
+    """
+    action: str
+    params: Any
+    result: Any
+    timestamp: str
+
+
+class WorkflowStatusResponse(TypedDict):
+    """
+    Response from checking workflow status.
+    
+    Attributes:
+        succeeded: Whether the status check succeeded
+        completed: Whether the workflow has completed execution
+        results: List of actions taken during workflow execution
+        total_actions: Total number of actions performed
+        session_id: The session ID being checked
+        completed_at: ISO 8601 timestamp of completion (if completed)
+    """
+    succeeded: bool
+    completed: bool
+    results: List[WorkflowAction]
+    total_actions: int
+    session_id: str
+    completed_at: Optional[str]
+
+
+class CreateWorkflowSessionRequest(TypedDict, total=False):
+    """
+    Request parameters for creating a workflow session.
+    
+    Attributes:
+        workflow_name: Name for the workflow (required)
+        url: Starting URL for the workflow (required)
+        proxies: Whether to use proxies (default: False)
+        session_data: Optional JSON string of session data
+    """
+    workflow_name: str
+    url: str
+    proxies: bool
+    session_data: str
+
+
+class CreateWorkflowSessionResponse(TypedDict):
+    """
+    Response from creating a workflow session.
+    
+    Attributes:
+        session_id: Unique identifier for the session
+        workflow_id: ID of the created workflow
+        livestream_url: URL to view the live browser session
+        connect_url: URL to connect to the session
+        vnc_url: URL for VNC access
+    """
+    session_id: str
+    workflow_id: str
+    livestream_url: str
+    connect_url: str
+    vnc_url: str
+
+
+class AgenticRequest(TypedDict, total=False):
+    """
+    Request parameters for running an agentic task.
+    
+    Attributes:
+        task: Natural language description of the task (required)
+        session_id: Session to run the task in (required)
+        max_steps: Maximum number of steps to take (optional)
+        actions_to_exclude: List of action types to exclude (optional)
+        variables: JSON string of variables for the task (optional)
+    """
+    task: str
+    session_id: str
+    max_steps: int
+    actions_to_exclude: List[str]
+    variables: str
+
+
+class AgenticResponse(TypedDict):
+    """
+    Response from running an agentic task.
+    
+    Attributes:
+        succeeded: Whether the task completed successfully
+        result: Result data from the task
+        error: Error message if the task failed
+    """
+    succeeded: bool
+    result: Any
+    error: Optional[str]
+
+
+class RunAgentRequest(TypedDict, total=False):
+    """
+    Request parameters for running a named agent.
+    
+    Attributes:
+        agent_name: Name of the agent to run (required)
+        session_id: Session to run the agent in (required)
+        variables: Dictionary of variables to pass to the agent
+    """
+    agent_name: str
+    session_id: str
+    variables: Dict[str, Any]
+
+
+class RunAgentResponse(TypedDict):
+    """
+    Response from running a named agent.
+    
+    Attributes:
+        succeeded: Whether the agent completed successfully
+        session_id: The session ID where the agent ran
+        agent_name: Name of the agent that ran
+        result: Result data from the agent
+    """
+    succeeded: bool
+    session_id: str
+    agent_name: str
+    result: Any
+
+
+class GetSessionStoreResponse(TypedDict):
+    """
+    Response from getting session store data.
+    
+    Attributes:
+        succeeded: Whether the request succeeded
+        session_store: Dictionary containing session data
+        error: Error message if the request failed
+    """
+    succeeded: bool
+    session_store: Optional[Dict[str, Any]]
+    error: Optional[str]
+
+
+class DownloadSessionFilesRequest(TypedDict, total=False):
+    """
+    Request parameters for downloading session files.
+    
+    Attributes:
+        session_id: Session to download files from (required)
+        filename: Optional specific filename to download
+    """
+    session_id: str
+    filename: str
+
+
+class DownloadSessionFilesErrorResponse(TypedDict):
+    """
+    Error response from downloading session files.
+    
+    Attributes:
+        succeeded: Always False for error responses
+        error: Error message describing what went wrong
+    """
+    succeeded: bool
+    error: str
+
+
+class TwoFactorConfig(TypedDict, total=False):
+    """
+    Configuration for 2FA authentication.
+    
+    Attributes:
+        seed: The 2FA seed/secret (required)
+        name: Optional name for this 2FA config
+        partial_url: Optional partial URL to match for auto-detection
+    """
+    seed: str
+    name: str
+    partial_url: str
+
+
+class Add2FAConfigRequest(TypedDict, total=False):
+    """
+    Request parameters for adding a 2FA configuration.
+    
+    Attributes:
+        seed: The 2FA seed/secret (required)
+        name: Optional name for this 2FA config
+        partial_url: Optional partial URL to match for auto-detection
+    """
+    seed: str
+    name: str
+    partial_url: str
+
+
+class Add2FAConfigResponse(TypedDict):
+    """
+    Response from adding a 2FA configuration.
+    
+    Attributes:
+        succeeded: Whether the config was added successfully
+        added_config: The configuration that was added
+        total_configs: Total number of 2FA configs after adding
+        all_configs: List of all 2FA configurations
+        error: Error message if the request failed
+    """
+    succeeded: bool
+    added_config: Optional[Any]
+    total_configs: Optional[int]
+    all_configs: Optional[List[Any]]
+    error: Optional[str]