ms-enclave 0.0.0__py3-none-any.whl → 0.0.2__py3-none-any.whl

ms_enclave-0.0.2.dist-info/METADATA

@@ -0,0 +1,366 @@
+Metadata-Version: 2.4
+Name: ms-enclave
+Version: 0.0.2
+Summary: Modularized and Stable Sandbox runtime environment.
+Author: ModelScope team
+Author-email: contact@modelscope.cn
+License: Apache License 2.0
+Project-URL: Homepage, https://github.com/modelscope/ms-enclave
+Keywords: python,llm,sandbox
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.104.0
+Requires-Dist: uvicorn[standard]>=0.24.0
+Requires-Dist: openai
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: requests>=2.32.4
+Requires-Dist: shortuuid>=1.0.13
+Requires-Dist: aiohttp>=3.8.1
+Requires-Dist: docstring-parser
+Provides-Extra: dev
+Requires-Dist: pytest>=8.3.5; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: pre-commit>=4.2.0; extra == "dev"
+Requires-Dist: jupyter-book>=1.0.4.post1; extra == "dev"
+Requires-Dist: pytest-cov>=6.2.1; extra == "dev"
+Provides-Extra: docker
+Requires-Dist: docker>=7.1.0; extra == "docker"
+Requires-Dist: websocket-client; extra == "docker"
+Dynamic: license-file
+
+<p align="center">
+    <br>
+    <img src="doc/asset/image/logo.png"/>
+    <br>
+<p>
+
+<p align="center">
+  <a href="README_zh.md">中文</a> &nbsp ｜ &nbsp English &nbsp
+</p>
+
+<p align="center">
+<img src="https://img.shields.io/badge/python-%E2%89%A53.10-5be.svg">
+<a href="https://badge.fury.io/py/ms-enclave"><img src="https://badge.fury.io/py/ms-enclave.svg" alt="PyPI version" height="18"></a>
+<a href="https://pypi.org/project/ms-enclave"><img alt="PyPI - Downloads" src="https://static.pepy.tech/badge/ms-enclave"></a>
+<a href="https://github.com/modelscope/ms-enclave/pulls"><img src="https://img.shields.io/badge/PR-welcome-55EB99.svg"></a>
+<p>
+
+## Overview
+
+ms-enclave is a modular and stable agent sandbox runtime environment that provides a secure isolated execution environment for applications. It achieves strong isolation through Docker containers, with accompanying local/HTTP managers and an extensible tool system, enabling you to safely and efficiently execute code in a controlled environment.
+
+- 🔒 Secure Isolation: Full isolation and resource limitation based on Docker
+- 🧩 Modular: Extensible sandbox and tools (registration factory)
+- ⚡ Stable Performance: Simple implementation, fast startup, lifecycle management
+- 🌐 Remote Management: Built-in FastAPI service, supports HTTP management
+- 🔧 Tool System: Standardized tools enabled by sandbox type (OpenAI-style schema)
+
+## System Requirements
+
+- Python >= 3.10
+- Operating System: Linux, macOS, or Windows with Docker support
+- Docker daemon running locally (Notebook sandbox requires port 8888 open)
+
+## Installation
+
+### Install from PyPI
+
+```bash
+pip install ms-enclave
+```
+
+### Install from Source
+
+```bash
+git clone https://github.com/modelscope/ms-enclave.git
+cd ms-enclave
+pip install -e .
+```
+
+## Quick Start: Minimal Example (SandboxFactory)
+
+> Tools need to be explicitly enabled in the tools_config setting, otherwise they won't be registered.
+
+```python
+import asyncio
+from ms_enclave.sandbox.boxes import SandboxFactory
+from ms_enclave.sandbox.model import DockerSandboxConfig, SandboxType
+
+async def main():
+    config = DockerSandboxConfig(
+        image='python:3.11-slim',
+        memory_limit='512m',
+        tools_config={
+            'python_executor': {},
+            'file_operation': {},
+            'shell_executor': {}
+        }
+    )
+
+    async with SandboxFactory.create_sandbox(SandboxType.DOCKER, config) as sandbox:
+        # 1) Write a file
+        await sandbox.execute_tool('file_operation', {
+            'operation': 'write', 'file_path': '/sandbox/hello.txt', 'content': 'hi from enclave'
+        })
+        # 2) Execute Python code
+        result = await sandbox.execute_tool('python_executor', {
+            'code': "print('Hello from sandbox!')\nprint(open('/sandbox/hello.txt').read())"
+        })
+        print(result.output)
+
+asyncio.run(main())
+```
+
+---
+
+## Typical Usage Scenarios and Examples
+
+- Directly using SandboxFactory: Create/destroy sandboxes in a single process—lightweight; suitable for scripts or one-off tasks
+- Using LocalSandboxManager: Manage the lifecycle/cleanup of multiple sandboxes locally; suitable for service-oriented or multi-task parallel scenarios
+- Using HttpSandboxManager: Unified sandbox management through remote HTTP services; suitable for cross-machine/distributed or more isolated deployments
+
+### 1) Direct Sandbox Creation: SandboxFactory (Lightweight, Temporary)
+
+Usage Scenarios:
+
+- Temporarily execute code in scripts or microservices
+- Fine-grained control over sandbox lifecycle (cleanup upon context exit)
+
+Example (Docker Sandbox + Python Execution):
+
+```python
+import asyncio
+from ms_enclave.sandbox.boxes import SandboxFactory
+from ms_enclave.sandbox.model import DockerSandboxConfig, SandboxType
+
+async def main():
+    cfg = DockerSandboxConfig(
+        tools_config={'python_executor': {}}
+    )
+    async with SandboxFactory.create_sandbox(SandboxType.DOCKER, cfg) as sb:
+        r = await sb.execute_tool('python_executor', {
+            'code': 'import platform; print(platform.python_version())'
+        })
+        print(r.output)
+
+asyncio.run(main())
+```
+
+### 2) Local Unified Management: LocalSandboxManager (Multi-Sandbox, Lifecycle Management)
+
+Usage Scenarios:
+
+- Create/manage multiple sandboxes within the same process (creation, query, stop, periodic cleanup)
+- Unified view for monitoring stats and health
+
+Example:
+
+```python
+import asyncio
+from ms_enclave.sandbox.manager import LocalSandboxManager
+from ms_enclave.sandbox.model import DockerSandboxConfig, SandboxType
+
+async def main():
+    async with LocalSandboxManager() as manager:
+        cfg = DockerSandboxConfig(tools_config={'shell_executor': {}})
+        sandbox_id = await manager.create_sandbox(SandboxType.DOCKER, cfg)
+
+        # Execute command
+        res = await manager.execute_tool(sandbox_id, 'shell_executor', {'command': 'echo hello'})
+        print(res.output.strip())  # hello
+
+        # View list
+        infos = await manager.list_sandboxes()
+        print([i.id for i in infos])
+
+        # Stop and delete
+        await manager.stop_sandbox(sandbox_id)
+        await manager.delete_sandbox(sandbox_id)
+
+asyncio.run(main())
+```
+
+### 3) Remote Unified Management: HttpSandboxManager (Cross-Machine/Isolated Deployment)
+
+Usage Scenarios:
+
+- Run sandbox services on dedicated hosts/containers, invoke remotely via HTTP
+- Share a secure controlled sandbox cluster among multiple applications
+
+Start the service (choose one):
+
+```bash
+# Option A: Command line
+ms-enclave server --host 0.0.0.0 --port 8000
+
+# Option B: Python script
+python -c "from ms_enclave.sandbox import create_server; create_server().run(host='0.0.0.0', port=8000)"
+```
+
+Client Example:
+
+```python
+import asyncio
+from ms_enclave.sandbox.manager import HttpSandboxManager
+from ms_enclave.sandbox.model import DockerSandboxConfig, SandboxType
+
+async def main():
+    async with HttpSandboxManager(base_url='http://127.0.0.1:8000') as m:
+        cfg = DockerSandboxConfig(tools_config={'python_executor': {}})
+        sid = await m.create_sandbox(SandboxType.DOCKER, cfg)
+        r = await m.execute_tool(sid, 'python_executor', {'code': 'print("Hello remote")'})
+        print(r.output)
+        await m.delete_sandbox(sid)
+
+asyncio.run(main())
+```
+
+---
+
+## Sandbox Types and Tool Support
+
+Currently Supported Sandbox Types:
+
+- DOCKER (General-purpose container execution)
+  - Supported tools:
+    - python_executor (execute Python code)
+    - shell_executor (execute Shell commands)
+    - file_operation (read/write/delete/list files)
+  - Features: Configurable memory/CPU limits, volume mounts, network toggling, privileged mode, port mapping
+
+- DOCKER_NOTEBOOK (Jupyter Kernel Gateway environment)
+  - Supported tools:
+    - notebook_executor (execute code via Jupyter Kernel, supports context saving)
+  - Note: This type only loads notebook_executor; other DOCKER-specific tools won't be enabled in this sandbox.
+  - Dependencies: Requires port 8888 exposed and network enabled
+
+Tool Loading Rules:
+
+- Tools are initialized and made available only when explicitly declared in `tools_config`.
+- Tools validate `required_sandbox_type`; unmatched types will be ignored automatically.
+
+Example:
+
+```python
+DockerSandboxConfig(tools_config={'python_executor': {}, 'shell_executor': {}, 'file_operation': {}})
+DockerNotebookConfig(tools_config={'notebook_executor': {}})
+```
+
+---
+
+## Common Configuration Options
+
+- `image`: Docker image name (e.g., `python:3.11-slim` or `jupyter-kernel-gateway`)
+- `memory_limit`: Memory limit (e.g., `512m` / `1g`)
+- `cpu_limit`: CPU limit (float > 0)
+- `volumes`: Volume mounts, e.g., `{host_path: {"bind": "/container/path", "mode": "rw"}}`
+- `ports`: Port mappings, e.g., `{ "8888/tcp": ("127.0.0.1", 8888) }`
+- `network_enabled`: Enable network (Notebook sandbox requires True)
+- `remove_on_exit`: Automatically remove container on exit (default True)
+
+**Example of Installing Additional Dependencies in Sandbox**
+
+```python
+async with SandboxFactory.create_sandbox(SandboxType.DOCKER, config) as sandbox:
+    # 1) Write a file
+    requirements_file = '/sandbox/requirements.txt'
+    await sandbox.execute_tool('file_operation', {
+        'operation': 'write', 'file_path': f'{requirements_file}', 'content': 'numpy\npandas\nmodelscope\n'
+    })
+    # 2) Execute Python code
+    result = await sandbox.execute_tool('python_executor', {
+        'code': f"print('Hello from sandbox!')\nprint(open(f'{requirements_file}').read())"
+    })
+    print(result.output)
+
+    # 3) Execute CLI
+    result_cli = await sandbox.execute_command(f'pip install -r {requirements_file}')
+    print(result_cli.stdout, flush=True)
+```
+
+**Example of Reading and Writing Host Files in Sandbox**
+
+```python
+async with LocalSandboxManager() as manager:
+    # Create sandbox
+    config = DockerSandboxConfig(
+        # image='python-sandbox',
+        image='python:3.11-slim',
+        tools_config={'python_executor': {}, 'file_operation': {}},
+        volumes={'~/Code/ms-enclave/output': {'bind': '/sandbox/data', 'mode': 'rw'}}
+    )
+    sandbox_id = await manager.create_sandbox(SandboxType.DOCKER, config)
+
+    # Write file
+    result = await manager.execute_tool(
+        sandbox_id, 'file_operation', {'operation': 'write', 'file_path': '/sandbox/data/hello.txt', 'content': 'Hello, Sandbox!'}
+    )
+    print(result.model_dump())
+```
+---
+
+## Error Handling and Debugging
+
+```python
+result = await sandbox.execute_tool('python_executor', {'code': 'print(1/0)'})
+if result.error:
+    print('Error:', result.error)
+else:
+    print('Output:', result.output)
+```
+
+---
+
+## Development and Testing
+
+```bash
+# Clone the repository
+git clone https://github.com/modelscope/ms-enclave.git
+cd ms-enclave
+
+# Setup virtual environment
+python -m venv venv
+source venv/bin/activate  # Windows: venv\Scripts\activate
+
+# Install dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run examples (provided in the repository)
+python examples/sandbox_usage_examples.py
+python examples/local_manager_example.py
+python examples/server_manager_example.py
+```
+
+---
+
+## Available Tools
+
+- `python_executor`: Execute Python code (DOCKER)
+- `shell_executor`: Execute Shell commands (DOCKER)
+- `file_operation`: Read/Write/Delete/List files (DOCKER)
+- `notebook_executor`: Execute via Jupyter Kernel (DOCKER_NOTEBOOK)
+- You can also register custom tools via the Tool factory (`@register_tool`).
+
+---
+
+## Contribution
+
+We welcome contributions! Please check [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+### Steps to Contribute
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/amazing-feature`
+3. Develop and add tests
+4. Run local tests: `pytest`
+5. Commit changes: `git commit -m 'Add amazing feature'`
+6. Push the branch: `git push origin feature/amazing-feature`
+7. Submit a Pull Request
+
+## License
+
+This project is licensed under the Apache 2.0 License. See [LICENSE](LICENSE) for details.

ms_enclave-0.0.2.dist-info/RECORD

@@ -0,0 +1,40 @@
+ms_enclave/__init__.py,sha256=IKXP5d9APyqXs14IU1mBKSr8tGxAwxeCtCnAWTOGhAU,98
+ms_enclave/version.py,sha256=WqqLptwhThO-50eN9GEdqDPEtMsOV0svfTEXxTezYvE,63
+ms_enclave/cli/__init__.py,sha256=I_ANdxdcIHpkIzIXc1yKOlWwzb4oY0FwTPq1kYtgzQw,50
+ms_enclave/cli/base.py,sha256=m1DFlF16L0Lyrn0YNuFj8ByGjVJIoI0jKzAoodIXjRk,404
+ms_enclave/cli/cli.py,sha256=AoSPw65_7OBMT8qgv5vPz1S3Fo91Y6yluaDGGHbUDj0,693
+ms_enclave/cli/start_server.py,sha256=FPmZ97MhWgsyXkl0y32D4XjhAak5Ogrt0Am3izRdi74,2858
+ms_enclave/sandbox/__init__.py,sha256=OPU_W5fZE98IQ8_pAaYkN66R8TZw435Co8uw9oAyZo4,783
+ms_enclave/sandbox/boxes/__init__.py,sha256=it3KgV8cAU4a1TQbiRz-kg7GgI5xA0nqhEAwEgUnpnQ,356
+ms_enclave/sandbox/boxes/base.py,sha256=lLjktdh4YQABr7X-lTLne2VN2Uv6Rcc5TN5LYx_NLxc,8532
+ms_enclave/sandbox/boxes/docker_notebook.py,sha256=-6O54MRNpiGAaQTiI9_1LCl0zzvB2se2_M1Bi8FuZ3s,7989
+ms_enclave/sandbox/boxes/docker_sandbox.py,sha256=ouFPtJyoSeZrQKD61Qyhq13QSuZl1Ut2gD1KgBbKPUs,11755
+ms_enclave/sandbox/manager/__init__.py,sha256=juYJsmpRoCThcILPemx6VGU-brpNF4cbu1FPV-d-tNc,255
+ms_enclave/sandbox/manager/base.py,sha256=nXznN8Yysgkgk8i-yfL29gAh2gBi3sdxPlQciTXnN9g,3848
+ms_enclave/sandbox/manager/http_manager.py,sha256=heVehKDi_VMJ5g9BllzmK5o68c2WIagsl8e231SKWtc,15731
+ms_enclave/sandbox/manager/local_manager.py,sha256=lv7vF9sNOThOPnCz9RzNTcD0pZHoNTVldVanfF7c5Io,9402
+ms_enclave/sandbox/model/__init__.py,sha256=3Sbj5Id77MWOZ1IXHGbu2q5U_p5KMLKvwZEr1QwjUqg,550
+ms_enclave/sandbox/model/base.py,sha256=1X5PaCUC5B5GXVCTzQMybqF7t0QEhWUkYFC-DyYXdhY,709
+ms_enclave/sandbox/model/config.py,sha256=afiSu5QcaZsd36lSoWMDmzz6o6kxTGebHzAqgLQOG_w,4616
+ms_enclave/sandbox/model/requests.py,sha256=JDcANsACotKscWrLs0H_-J8BKEhALUNgmJnoy6_JZuA,2336
+ms_enclave/sandbox/model/responses.py,sha256=AZ_BspRHzlqIP7xjI9XnoeQasIzJqMV8Qmdw23-KAwA,2502
+ms_enclave/sandbox/server/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ms_enclave/sandbox/server/server.py,sha256=SrSxl_C-4IudD5fXbi_cJ9EUv6A0EqxGmW9Opw4lsQE,7029
+ms_enclave/sandbox/tools/__init__.py,sha256=McNOuC9E9Xsckp7vOAxv9TP5q6XEIUAsLbnme3kSvJI,167
+ms_enclave/sandbox/tools/base.py,sha256=vLTJMFOQnfKyTyMMcgeq5f7KBFEFV5y7PFZmb4Ss0KE,2555
+ms_enclave/sandbox/tools/sandbox_tool.py,sha256=iATkvNax7aae53ZnmMwmQDuDb5qcXEUI-aPXD5eVfzo,1370
+ms_enclave/sandbox/tools/tool_info.py,sha256=A3RZLETWG9834J7r2KZfG6_JdV4UWnrFKSrEBfeCLHE,5223
+ms_enclave/sandbox/tools/sandbox_tools/__init__.py,sha256=Mtm2jQTrztLbRVDBiitogIB3GdIrwF3Hwk5KlruyntQ,176
+ms_enclave/sandbox/tools/sandbox_tools/file_operation.py,sha256=3yqkMdx_yrHUM4oyhd5WQm_tSV3o1-JwmBeVoIwaLfE,13348
+ms_enclave/sandbox/tools/sandbox_tools/notebook_executor.py,sha256=kZf9QA0yk-aFOJjtAbzYdKfNwjcoBSrscT9mWsv906w,6029
+ms_enclave/sandbox/tools/sandbox_tools/python_executor.py,sha256=SlhenlO09B_eVfcnrqSZAVYC_JCMws0eXj-caR2BTmw,3259
+ms_enclave/sandbox/tools/sandbox_tools/shell_executor.py,sha256=d5qPv6O1K1V91fsGAf9MiArcRuLtjFWEthi4iwtmAEE,2263
+ms_enclave/utils/__init__.py,sha256=KYWYfti4m8TcWzjOfmollEfEArTgTasq2Zuaz9AkzZI,31
+ms_enclave/utils/json_schema.py,sha256=hBhdMilb9_7JZaFZBb_THPrq8N4m_rJPD43mfwnTx14,7431
+ms_enclave/utils/logger.py,sha256=Hg_iVhgUX39LlWiQsvCyDx9NwQt3wQUukbOSCiLYEQU,5974
+ms_enclave-0.0.2.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+ms_enclave-0.0.2.dist-info/METADATA,sha256=Pqe2xTBcURL8-edgOc9wBSo7SAUb8L2gjcURrqqYvyU,12016
+ms_enclave-0.0.2.dist-info/WHEEL,sha256=SmOxYU7pzNKBqASvQJ7DjX3XGUF92lrGhMb3R6_iiqI,91
+ms_enclave-0.0.2.dist-info/entry_points.txt,sha256=Av3oIAE91Jj-742sTPA90ktrrq8lDowFC2RfXLwM8JM,58
+ms_enclave-0.0.2.dist-info/top_level.txt,sha256=V_Q9rBOF-RGwACDP9ppukoyjaOtpjdht7dhe7StS86A,11
+ms_enclave-0.0.2.dist-info/RECORD,,

{ms_enclave-0.0.0.dist-info → ms_enclave-0.0.2.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (79.0.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

ms_enclave-0.0.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ms-enclave = ms_enclave.cli.cli:run_cmd

ms_enclave/run_server.py

@@ -1,21 +0,0 @@
-"""Server startup script."""
-
-from ms_enclave.sandbox import create_server
-from ms_enclave.utils import get_logger
-
-logger = get_logger()
-
-
-def main():
-    """Run the sandbox server."""
-    server = create_server(cleanup_interval=300)  # 5 minutes
-
-    logger.info('Starting Sandbox Server...')
-    logger.info('API docs: http://localhost:8000/docs')
-    logger.info('Health check: http://localhost:8000/health')
-
-    server.run(host='0.0.0.0', port=8000, log_level='info')
-
-
-if __name__ == '__main__':
-    main()