simplex 0.2.3__tar.gz → 1.0.6__tar.gz

simplex-1.0.6/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Simplex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

simplex-1.0.6/MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md
+include LICENSE
+include requirements.txt
+recursive-include simplex *.py
+recursive-exclude tests *
+recursive-exclude examples *

simplex-1.0.6/PKG-INFO

@@ -0,0 +1,423 @@
+Metadata-Version: 2.4
+Name: simplex
+Version: 1.0.6
+Summary: Official Python SDK for the Simplex API
+Home-page: https://github.com/yourusername/simplex-python-sdk
+Author: Simplex
+Author-email: Simplex <support@simplex.sh>
+License: MIT
+Project-URL: Homepage, https://github.com/yourusername/simplex-python-sdk
+Project-URL: Documentation, https://docs.simplex.sh
+Project-URL: Repository, https://github.com/yourusername/simplex-python-sdk
+Project-URL: Bug Tracker, https://github.com/yourusername/simplex-python-sdk/issues
+Keywords: simplex,api,sdk,workflow,automation,browser
+Classifier: Development Status :: 4 - Beta
+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.8
+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: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25.0
+Requires-Dist: urllib3>=1.26.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
+Requires-Dist: black>=22.0.0; extra == "dev"
+Requires-Dist: flake8>=4.0.0; extra == "dev"
+Requires-Dist: mypy>=0.950; extra == "dev"
+Requires-Dist: python-dotenv>=0.19.0; extra == "dev"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# Simplex Python SDK
+
+Official Python SDK for the [Simplex API](https://simplex.sh) - A powerful workflow automation platform for browser-based tasks.
+
+[![Python Version](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- 🚀 Simple and intuitive API
+- 🔄 Automatic retry logic with exponential backoff
+- 🎯 Type hints for better IDE support
+- 🔐 Built-in error handling
+- 📦 Context manager support for automatic cleanup
+- 🤖 Support for agentic workflows and named agents
+- 📁 File download capabilities
+- 🔑 2FA configuration management
+
+## Installation
+
+Install the Simplex SDK using pip:
+
+```bash
+pip install simplex-sdk
+```
+
+Or install from source:
+
+```bash
+git clone https://github.com/yourusername/simplex-python-sdk.git
+cd simplex-python-sdk/python
+pip install -e .
+```
+
+## Quick Start
+
+```python
+from simplex import SimplexClient
+
+# Initialize the client
+client = SimplexClient(api_key='your-api-key')
+
+# Run a workflow with variables
+result = client.workflows.run(
+    'workflow-id',
+    variables={'username': 'user@example.com'}
+)
+
+print(f"Workflow started: {result['session_id']}")
+```
+
+## Usage Examples
+
+### Creating a Workflow Session
+
+Use workflow sessions for more control over browser automation:
+
+```python
+from simplex import SimplexClient
+
+client = SimplexClient(api_key='your-api-key')
+
+# Using context manager for automatic cleanup
+with client.create_workflow_session(
+    name='my-workflow',
+    url='https://example.com'
+) as session:
+    print(f'Session ID: {session.session_id}')
+    print(f'Livestream URL: {session.livestream_url}')
+    
+    # Navigate to a page
+    session.goto('https://example.com/login')
+    
+    # Run a named agent
+    session.run_agent('Login Agent', variables={
+        'username': 'user@example.com',
+        'password': 'secret'
+    })
+    
+    # Execute an agentic task
+    session.agentic('Click the submit button and wait for confirmation')
+    
+    # Session automatically closes when exiting the with block
+```
+
+### Running a Workflow
+
+Execute pre-built workflows with variables:
+
+```python
+from simplex import SimplexClient, WorkflowError
+
+client = SimplexClient(api_key='your-api-key')
+
+try:
+    # Run workflow with variables
+    result = client.workflows.run(
+        'workflow-id',
+        variables={
+            'email': 'user@example.com',
+            'product_id': '12345'
+        },
+        metadata='Order processing workflow'
+    )
+    
+    print(f"Success: {result['succeeded']}")
+    print(f"Session ID: {result['session_id']}")
+    
+    # Check workflow status
+    status = client.workflows.get_status(result['session_id'])
+    print(f"Completed: {status['completed']}")
+    print(f"Total actions: {status['total_actions']}")
+    
+except WorkflowError as e:
+    print(f"Workflow failed: {e.message}")
+```
+
+### Using Agentic Tasks
+
+Execute natural language instructions:
+
+```python
+# Within a workflow session
+session.agentic(
+    'Navigate to the invoices page and download the latest invoice',
+    max_steps=10
+)
+
+# Or using the workflows resource
+client.workflows.agentic(
+    task='Find and click the login button',
+    session_id='session-id',
+    max_steps=5
+)
+```
+
+### Downloading Session Files
+
+Download files created during workflow execution:
+
+```python
+from simplex import SimplexClient
+
+client = SimplexClient(api_key='your-api-key')
+
+# Download all files as a zip
+zip_data = client.download_session_files('session-id')
+with open('session_files.zip', 'wb') as f:
+    f.write(zip_data)
+
+# Download a specific file
+file_data = client.download_session_files('session-id', filename='report.pdf')
+with open('report.pdf', 'wb') as f:
+    f.write(file_data)
+```
+
+### Adding 2FA Configuration
+
+Configure automatic 2FA handling:
+
+```python
+from simplex import SimplexClient
+
+client = SimplexClient(api_key='your-api-key')
+
+result = client.add_2fa_config(
+    seed='JBSWY3DPEHPK3PXP',
+    name='My Service',
+    partial_url='example.com'
+)
+
+print(f"Total configs: {result['total_configs']}")
+```
+
+### Error Handling
+
+The SDK provides specific exception types for different error scenarios:
+
+```python
+from simplex import (
+    SimplexClient,
+    SimplexError,
+    WorkflowError,
+    AuthenticationError,
+    RateLimitError,
+    NetworkError
+)
+
+client = SimplexClient(api_key='your-api-key')
+
+try:
+    result = client.workflows.run('workflow-id')
+except AuthenticationError as e:
+    print(f"Authentication failed: {e.message}")
+except RateLimitError as e:
+    print(f"Rate limit exceeded. Retry after {e.retry_after} seconds")
+except WorkflowError as e:
+    print(f"Workflow error: {e.message}")
+    print(f"Workflow ID: {e.workflow_id}")
+    print(f"Session ID: {e.session_id}")
+except NetworkError as e:
+    print(f"Network error: {e.message}")
+except SimplexError as e:
+    print(f"General error: {e.message}")
+```
+
+## Configuration
+
+### Environment Variables
+
+You can use environment variables for configuration:
+
+```python
+import os
+from simplex import SimplexClient
+
+api_key = os.getenv('SIMPLEX_API_KEY')
+client = SimplexClient(api_key=api_key)
+```
+
+Example `.env` file:
+
+```bash
+SIMPLEX_API_KEY=your-api-key
+WORKFLOW_ID=your-workflow-id
+```
+
+### Client Options
+
+Customize client behavior with initialization parameters:
+
+```python
+from simplex import SimplexClient
+
+client = SimplexClient(
+    api_key='your-api-key',
+    timeout=60,           # Request timeout in seconds
+    max_retries=5,        # Maximum retry attempts
+    retry_delay=2,        # Delay between retries in seconds
+    base_url='https://api.simplex.sh'  # API base URL
+)
+```
+
+## API Reference
+
+### SimplexClient
+
+Main client class for interacting with the Simplex API.
+
+**Methods:**
+- `create_workflow_session(name, url, proxies=False, session_data=None)` - Create a new workflow session
+- `get_session_store(session_id)` - Retrieve session store data
+- `download_session_files(session_id, filename=None)` - Download files from a session
+- `add_2fa_config(seed, name=None, partial_url=None)` - Add 2FA configuration
+- `update_api_key(api_key)` - Update the API key
+- `set_custom_header(key, value)` - Set a custom header
+- `remove_custom_header(key)` - Remove a custom header
+
+### Workflow Resource
+
+Access via `client.workflows`
+
+**Methods:**
+- `run(workflow_id, variables=None, metadata=None, webhook_url=None)` - Execute a workflow
+- `get_status(session_id)` - Get workflow execution status
+- `create_workflow_session(workflow_name, url, proxies=False, session_data=None)` - Create a session
+- `agentic(task, session_id, max_steps=None, actions_to_exclude=None, variables=None)` - Run agentic task
+- `run_agent(agent_name, session_id, variables=None)` - Run a named agent
+- `start_segment(workflow_id, segment_name)` - Start a workflow segment
+- `finish_segment(workflow_id)` - Finish the current segment
+- `start_capture(session_id)` - Start capture mode
+- `stop_capture(session_id)` - Stop capture mode
+- `close_workflow_session(session_id)` - Close a session
+
+### WorkflowSession
+
+Created via `client.create_workflow_session()`. Supports context manager protocol.
+
+**Properties:**
+- `session_id` - Unique session identifier
+- `workflow_id` - Associated workflow ID
+- `livestream_url` - URL to view live browser session
+- `connect_url` - Connection URL
+- `vnc_url` - VNC access URL
+- `is_closed` - Whether the session is closed
+
+**Methods:**
+- `goto(url)` - Navigate to a URL
+- `agentic(task, max_steps=None, actions_to_exclude=None, variables=None)` - Execute agentic task
+- `run_agent(agent_name, variables=None)` - Run a named agent
+- `start_capture()` - Start capture mode
+- `stop_capture()` - Stop capture mode
+- `close()` - Close the session
+
+## Development
+
+### Setup Development Environment
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/simplex-python-sdk.git
+cd simplex-python-sdk/python
+
+# Create a virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+
+# Install development dependencies
+pip install -r requirements-dev.txt
+
+# Install the package in editable mode
+pip install -e .
+```
+
+### Running Tests
+
+```bash
+pytest tests/
+```
+
+### Code Formatting
+
+```bash
+black simplex/
+flake8 simplex/
+mypy simplex/
+```
+
+## Examples
+
+Check out the [examples](./examples) directory for more usage examples:
+
+- `login_example.py` - Basic login workflow
+- `create_workflow.py` - Creating and controlling sessions
+- `run_workflow.py` - Running workflows with variables
+- `download_file.py` - Downloading session files
+- `add_2fa_config.py` - Adding 2FA configuration
+
+## Requirements
+
+- Python 3.8 or higher
+- `requests>=2.25.0`
+- `urllib3>=1.26.0`
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Support
+
+- Documentation: [https://docs.simplex.sh](https://docs.simplex.sh)
+- Email: support@simplex.sh
+- GitHub Issues: [https://github.com/yourusername/simplex-python-sdk/issues](https://github.com/yourusername/simplex-python-sdk/issues)
+
+## Changelog
+
+### Version 1.0.0 (2024)
+
+- Initial release
+- Full feature parity with TypeScript SDK
+- Support for workflow execution and session management
+- Agentic task execution
+- Named agent support
+- File download capabilities
+- 2FA configuration management
+- Comprehensive error handling
+- Type hints throughout
+- Context manager support
+
+---
+
+Made with ❤️ by [Simplex](https://simplex.sh)