simplex 2.0.5__tar.gz → 3.0.2__tar.gz

simplex-3.0.2/PKG-INFO

@@ -0,0 +1,292 @@
+Metadata-Version: 2.4
+Name: simplex
+Version: 3.0.2
+Summary: Official Python SDK for the Simplex API
+Author-email: Simplex <support@simplex.sh>
+License: MIT
+Project-URL: Homepage, https://simplex.sh
+Project-URL: Documentation, https://docs.simplex.sh
+Project-URL: Repository, https://github.com/simplexlabs/simplex-python
+Keywords: simplex,api,sdk,workflow,automation,browser,scraping
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25.0
+Requires-Dist: typer>=0.9.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: types-requests>=2.25.0; extra == "dev"
+Dynamic: license-file
+
+# Simplex Python SDK & CLI
+
+Official Python SDK and CLI for the [Simplex](https://simplex.sh) browser automation platform.
+
+[![Python Version](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Installation
+
+```bash
+pip install simplex
+```
+
+This installs both the Python SDK (`from simplex import SimplexClient`) and the CLI (`simplex` command).
+
+## Authentication
+
+```bash
+# Option 1: Environment variable
+export SIMPLEX_API_KEY="your-api-key"
+
+# Option 2: Login command (saves to ~/.simplex/credentials)
+simplex login
+```
+
+## Claude Code Plugin
+
+Give Claude Code full knowledge of the Simplex CLI and SDK:
+
+```
+/plugin install simplexlabs/simplex-python
+```
+
+Once installed, Claude Code automatically knows how to use `simplex editor`, `simplex connect`, `simplex run`, and the full Python SDK.
+
+## CLI
+
+### `simplex editor` — Create a workflow and start an interactive session
+
+```bash
+simplex editor --name "My Workflow" --url "https://example.com"
+simplex editor -n "My Workflow" -u "https://example.com" --var key=value
+simplex editor -n "Test" -u "https://example.com" --json
+```
+
+Creates a workflow, starts a browser session, and streams live agent events. Prints session info (session_id, workflow_id, vnc_url) then streams SSE events until Ctrl+C.
+
+### `simplex connect` — Stream events from a running session
+
+```bash
+simplex connect <session_id>
+simplex connect "https://host:port/stream" --json
+```
+
+### `simplex run` — Run an existing workflow
+
+```bash
+simplex run <workflow_id>
+simplex run <workflow_id> --var email=test@test.com --watch
+```
+
+### `simplex send` — Send a message to a running session
+
+```bash
+simplex send <session_id> "Click the login button"
+```
+
+### `simplex pause` / `simplex resume`
+
+```bash
+simplex pause <session_id>
+simplex resume <session_id>
+```
+
+### `simplex workflows list`
+
+```bash
+simplex workflows list --name "search term"
+```
+
+### `simplex sessions`
+
+```bash
+simplex sessions status <session_id>
+simplex sessions logs <session_id>
+simplex sessions download <session_id> --filename report.pdf --output ./report.pdf
+simplex sessions replay <session_id> --output replay.mp4
+```
+
+### `simplex login` / `whoami` / `logout`
+
+```bash
+simplex login       # Prompts for API key
+simplex whoami      # Shows current auth status
+simplex logout      # Removes saved credentials
+```
+
+## Python SDK
+
+### Quick Start
+
+```python
+from simplex import SimplexClient
+
+client = SimplexClient(api_key="your-api-key")
+
+# Start an interactive editor session
+result = client.start_editor_session(
+    name="My Session",
+    url="https://example.com",
+    test_data={"username": "test"},
+)
+print(f"Session: {result['session_id']}")
+print(f"VNC: {result['vnc_url']}")
+
+# Stream live events
+for event in client.stream_session(result["logs_url"]):
+    print(event)
+
+# Send a message to the agent
+client.send_message(result["message_url"], "Click the login button")
+
+# Close the session
+client.close_session(result["session_id"])
+```
+
+### Client
+
+```python
+client = SimplexClient(
+    api_key="your-api-key",
+    base_url="https://api.simplex.sh",  # Optional
+    timeout=30,                          # Request timeout in seconds
+    max_retries=3,                       # Retry attempts
+    retry_delay=1.0,                     # Delay between retries
+)
+```
+
+### Workflow Management
+
+```python
+# Create
+result = client.create_workflow(name="My Workflow", url="https://example.com")
+workflow_id = result["workflow"]["id"]
+
+# Get
+workflow = client.get_workflow(workflow_id)
+
+# Update
+client.update_workflow(workflow_id, name="New Name", url="https://new-url.com")
+
+# Search
+results = client.search_workflows(workflow_name="search term")
+```
+
+### Editor Sessions
+
+```python
+# Start an editor session (creates workflow + browser session)
+# NOTE: Takes 10-15 seconds. Use timeout=120.
+result = client.start_editor_session(
+    name="My Session",
+    url="https://example.com",
+    test_data={"username": "test"},
+)
+# Returns: succeeded, workflow_id, session_id, vnc_url, logs_url, message_url, filesystem_url
+
+# Stream live SSE events
+for event in client.stream_session(result["logs_url"]):
+    event_type = event.get("event") or event.get("type", "")
+    print(f"[{event_type}] {event}")
+
+# Send a message to the agent
+client.send_message(result["message_url"], "Click the login button")
+```
+
+### Run Workflows
+
+```python
+import time
+
+result = client.run_workflow("workflow-id", variables={"key": "value"})
+
+# Poll for completion
+while True:
+    status = client.get_session_status(result["session_id"])
+    if not status["in_progress"]:
+        break
+    time.sleep(2)
+
+if status["success"]:
+    print(status["scraper_outputs"])
+    print(status["structured_output"])
+```
+
+### Session Management
+
+```python
+client.pause(session_id)
+client.resume(session_id)
+client.close_session(session_id)
+client.get_session_status(session_id)
+client.retrieve_session_logs(session_id)
+client.download_session_files(session_id)
+client.retrieve_session_replay(session_id)
+```
+
+## SSE Event Format
+
+Events from `stream_session()` are dicts. The event type is in the `event` key:
+
+| Event | Description |
+|-------|-------------|
+| `RunContent` | Agent text output |
+| `ToolCallStarted` | Tool invocation started |
+| `ToolCallCompleted` | Tool result |
+| `FlowPaused` | Session paused |
+| `FlowResumed` | Session resumed |
+| `RunCompleted` | Agent finished |
+| `RunError` | Error occurred |
+
+## Error Handling
+
+```python
+from simplex import (
+    SimplexError,
+    AuthenticationError,
+    RateLimitError,
+    NetworkError,
+    ValidationError,
+    WorkflowError,
+)
+
+try:
+    result = client.run_workflow("workflow-id")
+except AuthenticationError:
+    print("Invalid API key")
+except RateLimitError as e:
+    print(f"Rate limited. Retry after {e.retry_after}s")
+except WorkflowError as e:
+    print(f"Workflow error: {e.message}, session: {e.session_id}")
+except SimplexError as e:
+    print(f"Error: {e.message}")
+```
+
+## Requirements
+
+- Python 3.9+
+- `requests>=2.25.0`
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Links
+
+- [Simplex](https://simplex.sh)
+- [Documentation](https://docs.simplex.sh)
+- [Support](mailto:support@simplex.sh)

simplex-3.0.2/README.md

@@ -0,0 +1,259 @@
+# Simplex Python SDK & CLI
+
+Official Python SDK and CLI for the [Simplex](https://simplex.sh) browser automation platform.
+
+[![Python Version](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Installation
+
+```bash
+pip install simplex
+```
+
+This installs both the Python SDK (`from simplex import SimplexClient`) and the CLI (`simplex` command).
+
+## Authentication
+
+```bash
+# Option 1: Environment variable
+export SIMPLEX_API_KEY="your-api-key"
+
+# Option 2: Login command (saves to ~/.simplex/credentials)
+simplex login
+```
+
+## Claude Code Plugin
+
+Give Claude Code full knowledge of the Simplex CLI and SDK:
+
+```
+/plugin install simplexlabs/simplex-python
+```
+
+Once installed, Claude Code automatically knows how to use `simplex editor`, `simplex connect`, `simplex run`, and the full Python SDK.
+
+## CLI
+
+### `simplex editor` — Create a workflow and start an interactive session
+
+```bash
+simplex editor --name "My Workflow" --url "https://example.com"
+simplex editor -n "My Workflow" -u "https://example.com" --var key=value
+simplex editor -n "Test" -u "https://example.com" --json
+```
+
+Creates a workflow, starts a browser session, and streams live agent events. Prints session info (session_id, workflow_id, vnc_url) then streams SSE events until Ctrl+C.
+
+### `simplex connect` — Stream events from a running session
+
+```bash
+simplex connect <session_id>
+simplex connect "https://host:port/stream" --json
+```
+
+### `simplex run` — Run an existing workflow
+
+```bash
+simplex run <workflow_id>
+simplex run <workflow_id> --var email=test@test.com --watch
+```
+
+### `simplex send` — Send a message to a running session
+
+```bash
+simplex send <session_id> "Click the login button"
+```
+
+### `simplex pause` / `simplex resume`
+
+```bash
+simplex pause <session_id>
+simplex resume <session_id>
+```
+
+### `simplex workflows list`
+
+```bash
+simplex workflows list --name "search term"
+```
+
+### `simplex sessions`
+
+```bash
+simplex sessions status <session_id>
+simplex sessions logs <session_id>
+simplex sessions download <session_id> --filename report.pdf --output ./report.pdf
+simplex sessions replay <session_id> --output replay.mp4
+```
+
+### `simplex login` / `whoami` / `logout`
+
+```bash
+simplex login       # Prompts for API key
+simplex whoami      # Shows current auth status
+simplex logout      # Removes saved credentials
+```
+
+## Python SDK
+
+### Quick Start
+
+```python
+from simplex import SimplexClient
+
+client = SimplexClient(api_key="your-api-key")
+
+# Start an interactive editor session
+result = client.start_editor_session(
+    name="My Session",
+    url="https://example.com",
+    test_data={"username": "test"},
+)
+print(f"Session: {result['session_id']}")
+print(f"VNC: {result['vnc_url']}")
+
+# Stream live events
+for event in client.stream_session(result["logs_url"]):
+    print(event)
+
+# Send a message to the agent
+client.send_message(result["message_url"], "Click the login button")
+
+# Close the session
+client.close_session(result["session_id"])
+```
+
+### Client
+
+```python
+client = SimplexClient(
+    api_key="your-api-key",
+    base_url="https://api.simplex.sh",  # Optional
+    timeout=30,                          # Request timeout in seconds
+    max_retries=3,                       # Retry attempts
+    retry_delay=1.0,                     # Delay between retries
+)
+```
+
+### Workflow Management
+
+```python
+# Create
+result = client.create_workflow(name="My Workflow", url="https://example.com")
+workflow_id = result["workflow"]["id"]
+
+# Get
+workflow = client.get_workflow(workflow_id)
+
+# Update
+client.update_workflow(workflow_id, name="New Name", url="https://new-url.com")
+
+# Search
+results = client.search_workflows(workflow_name="search term")
+```
+
+### Editor Sessions
+
+```python
+# Start an editor session (creates workflow + browser session)
+# NOTE: Takes 10-15 seconds. Use timeout=120.
+result = client.start_editor_session(
+    name="My Session",
+    url="https://example.com",
+    test_data={"username": "test"},
+)
+# Returns: succeeded, workflow_id, session_id, vnc_url, logs_url, message_url, filesystem_url
+
+# Stream live SSE events
+for event in client.stream_session(result["logs_url"]):
+    event_type = event.get("event") or event.get("type", "")
+    print(f"[{event_type}] {event}")
+
+# Send a message to the agent
+client.send_message(result["message_url"], "Click the login button")
+```
+
+### Run Workflows
+
+```python
+import time
+
+result = client.run_workflow("workflow-id", variables={"key": "value"})
+
+# Poll for completion
+while True:
+    status = client.get_session_status(result["session_id"])
+    if not status["in_progress"]:
+        break
+    time.sleep(2)
+
+if status["success"]:
+    print(status["scraper_outputs"])
+    print(status["structured_output"])
+```
+
+### Session Management
+
+```python
+client.pause(session_id)
+client.resume(session_id)
+client.close_session(session_id)
+client.get_session_status(session_id)
+client.retrieve_session_logs(session_id)
+client.download_session_files(session_id)
+client.retrieve_session_replay(session_id)
+```
+
+## SSE Event Format
+
+Events from `stream_session()` are dicts. The event type is in the `event` key:
+
+| Event | Description |
+|-------|-------------|
+| `RunContent` | Agent text output |
+| `ToolCallStarted` | Tool invocation started |
+| `ToolCallCompleted` | Tool result |
+| `FlowPaused` | Session paused |
+| `FlowResumed` | Session resumed |
+| `RunCompleted` | Agent finished |
+| `RunError` | Error occurred |
+
+## Error Handling
+
+```python
+from simplex import (
+    SimplexError,
+    AuthenticationError,
+    RateLimitError,
+    NetworkError,
+    ValidationError,
+    WorkflowError,
+)
+
+try:
+    result = client.run_workflow("workflow-id")
+except AuthenticationError:
+    print("Invalid API key")
+except RateLimitError as e:
+    print(f"Rate limited. Retry after {e.retry_after}s")
+except WorkflowError as e:
+    print(f"Workflow error: {e.message}, session: {e.session_id}")
+except SimplexError as e:
+    print(f"Error: {e.message}")
+```
+
+## Requirements
+
+- Python 3.9+
+- `requests>=2.25.0`
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+
+## Links
+
+- [Simplex](https://simplex.sh)
+- [Documentation](https://docs.simplex.sh)
+- [Support](mailto:support@simplex.sh)

{simplex-2.0.5 → simplex-3.0.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simplex"
-version = "2.0.5"
+version = "3.0.2"
 description = "Official Python SDK for the Simplex API"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -28,8 +28,13 @@ classifiers = [
 ]
 dependencies = [
     "requests>=2.25.0",
+    "typer>=0.9.0",
+    "rich>=13.0.0",
 ]
 
+[project.scripts]
+simplex = "simplex.cli.main:app"
+
 [project.optional-dependencies]
 dev = [
     "pytest>=7.0.0",
@@ -42,6 +47,9 @@ Homepage = "https://simplex.sh"
 Documentation = "https://docs.simplex.sh"
 Repository = "https://github.com/simplexlabs/simplex-python"
 
+[tool.setuptools.packages.find]
+include = ["simplex*"]
+
 [tool.mypy]
 python_version = "3.9"
 warn_return_any = true

{simplex-2.0.5 → simplex-3.0.2}/simplex/__init__.py

@@ -31,11 +31,19 @@ from simplex.errors import (
 )
 from simplex.types import (
     FileMetadata,
+    PauseSessionResponse,
+    ResumeSessionResponse,
     RunWorkflowResponse,
+    SearchWorkflowItem,
+    SearchWorkflowsResponse,
     SessionStatusResponse,
+    StartEditorSessionResponse,
+    UpdateWorkflowMetadataResponse,
+    WebhookPayload,
 )
+from simplex.webhook import WebhookVerificationError, verify_simplex_webhook
 
-__version__ = "2.0.5"
+__version__ = "3.0.2"
 __all__ = [
     "SimplexClient",
     "SimplexError",
@@ -47,4 +55,13 @@ __all__ = [
     "FileMetadata",
     "SessionStatusResponse",
     "RunWorkflowResponse",
+    "PauseSessionResponse",
+    "ResumeSessionResponse",
+    "SearchWorkflowsResponse",
+    "SearchWorkflowItem",
+    "StartEditorSessionResponse",
+    "UpdateWorkflowMetadataResponse",
+    "WebhookPayload",
+    "verify_simplex_webhook",
+    "WebhookVerificationError",
 ]

{simplex-2.0.5 → simplex-3.0.2}/simplex/_http_client.py

@@ -21,7 +21,7 @@ from simplex.errors import (
     ValidationError,
 )
 
-__version__ = "2.0.5"
+__version__ = "3.0.2"
 
 
 class HttpClient:
@@ -77,6 +77,7 @@ class HttpClient:
         """Convert HTTP errors to appropriate exception types."""
         status_code = response.status_code
 
+        data = None
         try:
             data = response.json()
             if isinstance(data, dict):
@@ -87,7 +88,7 @@ class HttpClient:
             message = response.text or "An error occurred"
 
         if status_code == 400:
-            return ValidationError(message, data=response.json() if response.text else None)
+            return ValidationError(message, data=data)
         elif status_code in [401, 403]:
             return AuthenticationError(message)
         elif status_code == 429:
@@ -95,7 +96,7 @@ class HttpClient:
             retry_after_seconds = int(retry_after) if retry_after and retry_after.isdigit() else None
             return RateLimitError(message, retry_after=retry_after_seconds)
         else:
-            return SimplexError(message, status_code=status_code, data=response.json() if response.text else None)
+            return SimplexError(message, status_code=status_code, data=data)
 
     def _make_request(
         self,
@@ -205,6 +206,48 @@ class HttpClient:
         )
         return response.json()
 
+    def post_json(self, path: str, data: dict | None = None) -> Any:
+        """POST with JSON body."""
+        response = self._make_request("POST", path, json=data)
+        return response.json()
+
+    def patch_json(self, path: str, data: dict | None = None) -> Any:
+        """PATCH with JSON body."""
+        response = self._make_request("PATCH", path, json=data)
+        return response.json()
+
+    def stream_sse(self, url: str) -> Any:
+        """Connect to an SSE endpoint and yield parsed events.
+
+        Uses absolute URL (not base_url) since SSE endpoints are on container tunnels.
+        The generator ends cleanly when the connection closes (e.g. session finished).
+        """
+        import json as json_module
+
+        response = self.session.get(url, stream=True, timeout=None)
+        response.raise_for_status()
+        try:
+            for line in response.iter_lines(decode_unicode=True):
+                if line and line.startswith("data: "):
+                    try:
+                        yield json_module.loads(line[6:])
+                    except json_module.JSONDecodeError:
+                        continue
+        except (requests.exceptions.ChunkedEncodingError, requests.exceptions.ConnectionError):
+            return  # Connection closed — session ended
+
+    def post_to_url(self, url: str, json_data: dict) -> Any:
+        """POST JSON to an absolute URL (not relative to base_url)."""
+        response = self.session.post(url, json=json_data, timeout=self.timeout)
+        response.raise_for_status()
+        return response.json()
+
+    def get_from_url(self, url: str, params: dict | None = None) -> Any:
+        """GET from an absolute URL (not relative to base_url)."""
+        response = self.session.get(url, params=params, timeout=self.timeout)
+        response.raise_for_status()
+        return response.json()
+
     def download_file(self, path: str, params: dict[str, Any] | None = None) -> bytes:
         """
         Download a file from the API.