forgevm 0.1.0__tar.gz

forgevm-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: forgevm
+Version: 0.1.0
+Summary: Python SDK for ForgeVM — self-hosted microVM sandboxes for LLMs
+Author: DohaerisAI
+License: MIT
+Project-URL: Homepage, https://github.com/DohaerisAI/forgevm
+Project-URL: Repository, https://github.com/DohaerisAI/forgevm
+Project-URL: Documentation, https://github.com/DohaerisAI/forgevm#use-with-python
+Project-URL: Issues, https://github.com/DohaerisAI/forgevm/issues
+Keywords: forgevm,sandbox,microvm,llm,code-execution,firecracker,ai-agent
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+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: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Emulators
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-httpx>=0.30.0; extra == "dev"
+
+# ForgeVM Python SDK
+
+Python client for [ForgeVM](https://github.com/DohaerisAI/forgevm) -- self-hosted compute sandboxes for LLMs.
+
+## Install
+
+```bash
+pip install forgevm
+```
+
+## Quick Start
+
+```python
+from forgevm import Client
+
+client = Client("http://localhost:7423")
+
+# Spawn a sandbox
+sandbox = client.spawn(image="alpine:latest")
+
+# Execute commands
+result = sandbox.exec("echo hello")
+print(result.stdout)  # "hello\n"
+
+# File operations
+sandbox.write_file("/tmp/hello.txt", "Hello, world!")
+content = sandbox.read_file("/tmp/hello.txt")
+
+# Extend TTL
+sandbox.extend_ttl("30m")
+
+# Auto-cleanup with context manager
+with client.spawn(image="python:3.12") as sb:
+    sb.exec("python3 -c 'print(1+1)'")
+# sandbox destroyed automatically
+
+# Streaming output
+for chunk in sandbox.exec_stream("ping -c 3 localhost"):
+    print(chunk.data, end="")
+
+sandbox.destroy()
+```
+
+## Async Support
+
+```python
+from forgevm import AsyncClient
+
+async with AsyncClient("http://localhost:7423") as client:
+    sandbox = await client.spawn(image="alpine:latest")
+    result = await sandbox.exec("echo hello")
+    await sandbox.destroy()
+```
+
+## License
+
+MIT

forgevm-0.1.0/README.md

@@ -0,0 +1,57 @@
+# ForgeVM Python SDK
+
+Python client for [ForgeVM](https://github.com/DohaerisAI/forgevm) -- self-hosted compute sandboxes for LLMs.
+
+## Install
+
+```bash
+pip install forgevm
+```
+
+## Quick Start
+
+```python
+from forgevm import Client
+
+client = Client("http://localhost:7423")
+
+# Spawn a sandbox
+sandbox = client.spawn(image="alpine:latest")
+
+# Execute commands
+result = sandbox.exec("echo hello")
+print(result.stdout)  # "hello\n"
+
+# File operations
+sandbox.write_file("/tmp/hello.txt", "Hello, world!")
+content = sandbox.read_file("/tmp/hello.txt")
+
+# Extend TTL
+sandbox.extend_ttl("30m")
+
+# Auto-cleanup with context manager
+with client.spawn(image="python:3.12") as sb:
+    sb.exec("python3 -c 'print(1+1)'")
+# sandbox destroyed automatically
+
+# Streaming output
+for chunk in sandbox.exec_stream("ping -c 3 localhost"):
+    print(chunk.data, end="")
+
+sandbox.destroy()
+```
+
+## Async Support
+
+```python
+from forgevm import AsyncClient
+
+async with AsyncClient("http://localhost:7423") as client:
+    sandbox = await client.spawn(image="alpine:latest")
+    result = await sandbox.exec("echo hello")
+    await sandbox.destroy()
+```
+
+## License
+
+MIT

forgevm-0.1.0/forgevm/__init__.py

@@ -0,0 +1,28 @@
+"""ForgeVM Python SDK — client for the ForgeVM sandbox orchestrator."""
+
+from forgevm.client import Client
+from forgevm.sandbox import Sandbox
+from forgevm.async_client import AsyncClient
+from forgevm.async_sandbox import AsyncSandbox
+from forgevm.models import ExecResult, SandboxInfo, Template
+from forgevm.exceptions import (
+    ForgevmError,
+    SandboxNotFound,
+    ProviderError,
+    ConnectionError,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "Client",
+    "Sandbox",
+    "AsyncClient",
+    "AsyncSandbox",
+    "ExecResult",
+    "SandboxInfo",
+    "Template",
+    "ForgevmError",
+    "SandboxNotFound",
+    "ProviderError",
+    "ConnectionError",
+]

forgevm-0.1.0/forgevm/async_client.py

@@ -0,0 +1,139 @@
+"""ForgeVM Async Client — async variant using httpx.AsyncClient."""
+
+from __future__ import annotations
+
+import httpx
+
+from forgevm.async_sandbox import AsyncSandbox
+from forgevm.exceptions import ConnectionError, handle_response
+from forgevm.models import SandboxInfo
+
+
+class AsyncClient:
+    """Async client for the ForgeVM API server.
+
+    Usage:
+        async with AsyncClient("http://localhost:7423") as client:
+            sandbox = await client.spawn(image="alpine:latest")
+            result = await sandbox.exec("echo hello")
+            print(result.stdout)
+            await sandbox.destroy()
+    """
+
+    def __init__(
+        self,
+        base_url: str = "http://localhost:7423",
+        api_key: str | None = None,
+        user_id: str | None = None,
+        timeout: float = 30.0,
+    ):
+        headers = {}
+        if api_key:
+            headers["X-API-Key"] = api_key
+        if user_id:
+            headers["X-User-ID"] = user_id
+
+        self._http = httpx.AsyncClient(
+            base_url=base_url,
+            headers=headers,
+            timeout=timeout,
+        )
+
+    async def spawn(
+        self,
+        image: str = "alpine:latest",
+        provider: str | None = None,
+        memory_mb: int | None = None,
+        vcpus: int | None = None,
+        ttl: str | None = None,
+        template: str | None = None,
+        metadata: dict[str, str] | None = None,
+    ) -> AsyncSandbox:
+        """Spawn a new sandbox."""
+        body: dict = {"image": image}
+        if provider:
+            body["provider"] = provider
+        if memory_mb:
+            body["memory_mb"] = memory_mb
+        if vcpus:
+            body["vcpus"] = vcpus
+        if ttl:
+            body["ttl"] = ttl
+        if template:
+            body["template"] = template
+        if metadata:
+            body["metadata"] = metadata
+
+        try:
+            resp = await self._http.post("/api/v1/sandboxes", json=body)
+        except httpx.ConnectError as e:
+            raise ConnectionError(f"Cannot connect to ForgeVM server: {e}")
+
+        handle_response(resp)
+        data = resp.json()
+        return AsyncSandbox(self._http, data["id"], info=data)
+
+    async def spawn_template(self, template_name: str) -> AsyncSandbox:
+        """Spawn a sandbox from a saved template."""
+        try:
+            resp = await self._http.post(f"/api/v1/templates/{template_name}/spawn")
+        except httpx.ConnectError as e:
+            raise ConnectionError(f"Cannot connect to ForgeVM server: {e}")
+
+        handle_response(resp)
+        data = resp.json()
+        return AsyncSandbox(self._http, data["id"], info=data)
+
+    async def get(self, sandbox_id: str) -> AsyncSandbox:
+        """Get an existing sandbox by ID."""
+        resp = await self._http.get(f"/api/v1/sandboxes/{sandbox_id}")
+        handle_response(resp)
+        data = resp.json()
+        return AsyncSandbox(self._http, data["id"], info=data)
+
+    async def list(self) -> list[SandboxInfo]:
+        """List all active sandboxes."""
+        resp = await self._http.get("/api/v1/sandboxes")
+        handle_response(resp)
+        return [
+            SandboxInfo(
+                id=s["id"],
+                state=s["state"],
+                provider=s["provider"],
+                image=s["image"],
+                memory_mb=s.get("memory_mb", 512),
+                vcpus=s.get("vcpus", 1),
+                created_at=s.get("created_at", ""),
+                expires_at=s.get("expires_at", ""),
+                metadata=s.get("metadata", {}),
+            )
+            for s in resp.json()
+        ]
+
+    async def prune(self) -> int:
+        """Prune expired sandboxes. Returns count pruned."""
+        resp = await self._http.delete("/api/v1/sandboxes")
+        handle_response(resp)
+        return resp.json().get("pruned", 0)
+
+    async def pool_status(self) -> dict:
+        """Get VM pool status."""
+        resp = await self._http.get("/api/v1/pool/status")
+        handle_response(resp)
+        return resp.json()
+
+    async def health(self) -> dict:
+        """Check server health."""
+        resp = await self._http.get("/api/v1/health")
+        handle_response(resp)
+        return resp.json()
+
+    async def close(self) -> None:
+        """Close the HTTP client."""
+        await self._http.aclose()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *args):
+        await self.close()

forgevm-0.1.0/forgevm/async_sandbox.py

@@ -0,0 +1,171 @@
+"""ForgeVM AsyncSandbox — async variant of Sandbox."""
+
+from __future__ import annotations
+
+from typing import AsyncIterator
+
+import httpx
+
+from forgevm.exceptions import handle_response
+from forgevm.models import ExecResult
+from forgevm.streaming import StreamChunk
+
+
+class AsyncSandbox:
+    """An async ForgeVM sandbox instance. Supports async context manager for auto-cleanup."""
+
+    def __init__(self, http: httpx.AsyncClient, sandbox_id: str, info: dict | None = None):
+        self._http = http
+        self.id = sandbox_id
+        self._info = info or {}
+
+    @property
+    def state(self) -> str:
+        return self._info.get("state", "unknown")
+
+    @property
+    def provider(self) -> str:
+        return self._info.get("provider", "")
+
+    @property
+    def image(self) -> str:
+        return self._info.get("image", "")
+
+    async def exec(
+        self,
+        command: str,
+        args: list[str] | None = None,
+        env: dict[str, str] | None = None,
+        workdir: str | None = None,
+    ) -> ExecResult:
+        """Execute a command in the sandbox."""
+        body: dict = {"command": command}
+        if args:
+            body["args"] = args
+        if env:
+            body["env"] = env
+        if workdir:
+            body["workdir"] = workdir
+
+        resp = await self._http.post(f"/api/v1/sandboxes/{self.id}/exec", json=body)
+        handle_response(resp)
+        data = resp.json()
+        return ExecResult(
+            exit_code=data["exit_code"],
+            stdout=data["stdout"],
+            stderr=data["stderr"],
+            duration=data.get("duration", ""),
+        )
+
+    async def exec_stream(
+        self,
+        command: str,
+        args: list[str] | None = None,
+        env: dict[str, str] | None = None,
+        workdir: str | None = None,
+    ) -> AsyncIterator[StreamChunk]:
+        """Execute a command and stream output chunks asynchronously."""
+        import json as jsonlib
+
+        body: dict = {"command": command, "stream": True}
+        if args:
+            body["args"] = args
+        if env:
+            body["env"] = env
+        if workdir:
+            body["workdir"] = workdir
+
+        async with self._http.stream("POST", f"/api/v1/sandboxes/{self.id}/exec", json=body) as resp:
+            handle_response(resp)
+            async for line in resp.aiter_lines():
+                line = line.strip()
+                if not line:
+                    continue
+                data = jsonlib.loads(line)
+                yield StreamChunk(
+                    stream=data.get("stream", "stdout"),
+                    data=data.get("data", ""),
+                )
+
+    async def write_file(self, path: str, content: str, mode: str | None = None) -> None:
+        """Write a file to the sandbox."""
+        body: dict = {"path": path, "content": content}
+        if mode:
+            body["mode"] = mode
+        resp = await self._http.post(f"/api/v1/sandboxes/{self.id}/files", json=body)
+        handle_response(resp)
+
+    async def read_file(self, path: str) -> str:
+        """Read a file from the sandbox."""
+        resp = await self._http.get(f"/api/v1/sandboxes/{self.id}/files", params={"path": path})
+        handle_response(resp)
+        return resp.text
+
+    async def list_files(self, path: str = "/") -> list[dict]:
+        """List files in a sandbox directory."""
+        resp = await self._http.get(f"/api/v1/sandboxes/{self.id}/files/list", params={"path": path})
+        handle_response(resp)
+        return resp.json()
+
+    async def delete_file(self, path: str, recursive: bool = False) -> None:
+        """Delete a file or directory from the sandbox."""
+        params = {"path": path}
+        if recursive:
+            params["recursive"] = "true"
+        resp = await self._http.delete(f"/api/v1/sandboxes/{self.id}/files", params=params)
+        handle_response(resp)
+
+    async def move_file(self, old_path: str, new_path: str) -> None:
+        """Move/rename a file in the sandbox."""
+        resp = await self._http.post(
+            f"/api/v1/sandboxes/{self.id}/files/move",
+            json={"old_path": old_path, "new_path": new_path},
+        )
+        handle_response(resp)
+
+    async def chmod_file(self, path: str, mode: str) -> None:
+        """Change file permissions in the sandbox."""
+        resp = await self._http.post(
+            f"/api/v1/sandboxes/{self.id}/files/chmod",
+            json={"path": path, "mode": mode},
+        )
+        handle_response(resp)
+
+    async def stat_file(self, path: str) -> dict:
+        """Get file info for a single file in the sandbox."""
+        resp = await self._http.get(
+            f"/api/v1/sandboxes/{self.id}/files/stat", params={"path": path}
+        )
+        handle_response(resp)
+        return resp.json()
+
+    async def glob_files(self, pattern: str) -> list[str]:
+        """Return paths matching a glob pattern in the sandbox."""
+        resp = await self._http.get(
+            f"/api/v1/sandboxes/{self.id}/files/glob", params={"pattern": pattern}
+        )
+        handle_response(resp)
+        return resp.json()
+
+    async def destroy(self) -> None:
+        """Destroy this sandbox."""
+        resp = await self._http.delete(f"/api/v1/sandboxes/{self.id}")
+        handle_response(resp)
+
+    async def refresh(self) -> None:
+        """Refresh sandbox info from the server."""
+        resp = await self._http.get(f"/api/v1/sandboxes/{self.id}")
+        handle_response(resp)
+        self._info = resp.json()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *args):
+        try:
+            await self.destroy()
+        except Exception:
+            pass
+
+    def __repr__(self) -> str:
+        return f"AsyncSandbox(id={self.id!r}, state={self.state!r})"

forgevm-0.1.0/forgevm/client.py

@@ -0,0 +1,125 @@
+"""ForgeVM Client — main entry point for the SDK."""
+
+from __future__ import annotations
+
+import httpx
+
+from forgevm.exceptions import ConnectionError, handle_response
+from forgevm.models import SandboxInfo
+from forgevm.sandbox import Sandbox
+
+
+class Client:
+    """Client for the ForgeVM API server.
+
+    Usage:
+        with Client("http://localhost:7423") as client:
+            sandbox = client.spawn(image="alpine:latest")
+            result = sandbox.exec("echo hello")
+            print(result.stdout)
+            sandbox.destroy()
+    """
+
+    def __init__(
+        self,
+        base_url: str = "http://localhost:7423",
+        api_key: str | None = None,
+        user_id: str | None = None,
+        timeout: float = 30.0,
+    ):
+        headers = {}
+        if api_key:
+            headers["X-API-Key"] = api_key
+        if user_id:
+            headers["X-User-ID"] = user_id
+
+        self._http = httpx.Client(
+            base_url=base_url,
+            headers=headers,
+            timeout=timeout,
+        )
+
+    def spawn(
+        self,
+        image: str = "alpine:latest",
+        provider: str | None = None,
+        memory_mb: int | None = None,
+        vcpus: int | None = None,
+        ttl: str | None = None,
+        metadata: dict[str, str] | None = None,
+    ) -> Sandbox:
+        """Spawn a new sandbox."""
+        body: dict = {"image": image}
+        if provider:
+            body["provider"] = provider
+        if memory_mb:
+            body["memory_mb"] = memory_mb
+        if vcpus:
+            body["vcpus"] = vcpus
+        if ttl:
+            body["ttl"] = ttl
+        if metadata:
+            body["metadata"] = metadata
+
+        try:
+            resp = self._http.post("/api/v1/sandboxes", json=body)
+        except httpx.ConnectError as e:
+            raise ConnectionError(f"Cannot connect to ForgeVM server: {e}")
+
+        handle_response(resp)
+        data = resp.json()
+        return Sandbox(self._http, data["id"], info=data)
+
+    def get(self, sandbox_id: str) -> Sandbox:
+        """Get an existing sandbox by ID."""
+        resp = self._http.get(f"/api/v1/sandboxes/{sandbox_id}")
+        handle_response(resp)
+        data = resp.json()
+        return Sandbox(self._http, data["id"], info=data)
+
+    def list(self) -> list[SandboxInfo]:
+        """List all active sandboxes."""
+        resp = self._http.get("/api/v1/sandboxes")
+        handle_response(resp)
+        return [
+            SandboxInfo(
+                id=s["id"],
+                state=s["state"],
+                provider=s["provider"],
+                image=s["image"],
+                memory_mb=s.get("memory_mb", 512),
+                vcpus=s.get("vcpus", 1),
+                created_at=s.get("created_at", ""),
+                expires_at=s.get("expires_at", ""),
+                metadata=s.get("metadata", {}),
+            )
+            for s in resp.json()
+        ]
+
+    def prune(self) -> int:
+        """Prune expired sandboxes. Returns count pruned."""
+        resp = self._http.delete("/api/v1/sandboxes")
+        handle_response(resp)
+        return resp.json().get("pruned", 0)
+
+    def pool_status(self) -> dict:
+        """Get VM pool status."""
+        resp = self._http.get("/api/v1/pool/status")
+        handle_response(resp)
+        return resp.json()
+
+    def health(self) -> dict:
+        """Check server health."""
+        resp = self._http.get("/api/v1/health")
+        handle_response(resp)
+        return resp.json()
+
+    def close(self) -> None:
+        """Close the HTTP client."""
+        self._http.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()

forgevm-0.1.0/forgevm/exceptions.py

@@ -0,0 +1,56 @@
+"""ForgeVM SDK exceptions."""
+
+from __future__ import annotations
+
+import httpx
+
+
+class ForgevmError(Exception):
+    """Base exception for ForgeVM SDK."""
+
+    def __init__(self, message: str, code: str | None = None):
+        super().__init__(message)
+        self.code = code
+
+
+class SandboxNotFound(ForgevmError):
+    """Raised when a sandbox is not found."""
+
+    def __init__(self, sandbox_id: str):
+        super().__init__(f"Sandbox {sandbox_id!r} not found", code="NOT_FOUND")
+        self.sandbox_id = sandbox_id
+
+
+class ProviderError(ForgevmError):
+    """Raised when a provider operation fails."""
+
+    pass
+
+
+class ConnectionError(ForgevmError):
+    """Raised when the connection to the ForgeVM server fails."""
+
+    pass
+
+
+def handle_response(response: httpx.Response) -> None:
+    """Check response status and raise appropriate exceptions."""
+    if response.is_success:
+        return
+
+    try:
+        data = response.json()
+        code = data.get("code", "")
+        message = data.get("message", response.text)
+    except Exception:
+        code = ""
+        message = response.text
+
+    if response.status_code == 404:
+        raise SandboxNotFound(message)
+    if response.status_code == 401:
+        raise ForgevmError(message, code="UNAUTHORIZED")
+    if response.status_code >= 500:
+        raise ProviderError(message, code=code)
+
+    raise ForgevmError(message, code=code)