microcld 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- microcld/__init__.py +62 -0
- microcld/_api.py +237 -0
- microcld/_types.py +147 -0
- microcld/aio.py +307 -0
- microcld/cli.py +509 -0
- microcld/client.py +365 -0
- microcld/errors.py +73 -0
- microcld/hosting.py +267 -0
- microcld/tools.py +285 -0
- microcld-0.1.0.dist-info/METADATA +207 -0
- microcld-0.1.0.dist-info/RECORD +14 -0
- microcld-0.1.0.dist-info/WHEEL +4 -0
- microcld-0.1.0.dist-info/entry_points.txt +2 -0
- microcld-0.1.0.dist-info/licenses/LICENSE +21 -0
microcld/__init__.py
ADDED
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
"""Python SDK and CLI for microcloud: hosting (apps, databases, buckets) and AI-agent sandboxes (`microcld`).
|
|
2
|
+
|
|
3
|
+
from microcld import Sandbox
|
|
4
|
+
|
|
5
|
+
with Sandbox.create(template="python") as sb:
|
|
6
|
+
sb.files.write("/tmp/data.csv", "a,b\\n1,2\\n")
|
|
7
|
+
print(sb.exec("python3 -c 'import sys; print(sys.version)'").check().stdout)
|
|
8
|
+
|
|
9
|
+
Hosting: `Client().apps`, `.databases`, `.buckets` (see `microcld.hosting`).
|
|
10
|
+
|
|
11
|
+
API key and URL: arguments or `SANDBOX_API_KEY` / `SANDBOX_API_URL`.
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
from . import tools
|
|
15
|
+
from ._types import CodeError, CodeResult, CommandError, ExecResult, OutputChunk, SandboxInfo, Usage, UsageReport
|
|
16
|
+
from .aio import AsyncClient, AsyncSandbox
|
|
17
|
+
from .client import Client, Sandbox
|
|
18
|
+
from .errors import (
|
|
19
|
+
AuthError,
|
|
20
|
+
BadRequestError,
|
|
21
|
+
CapacityError,
|
|
22
|
+
ConflictError,
|
|
23
|
+
InterpreterError,
|
|
24
|
+
NotFoundError,
|
|
25
|
+
QuotaError,
|
|
26
|
+
SandboxError,
|
|
27
|
+
ServerError,
|
|
28
|
+
TimeoutError,
|
|
29
|
+
)
|
|
30
|
+
from .hosting import Account, Apps, Buckets, Databases
|
|
31
|
+
|
|
32
|
+
__version__ = "0.1.0"
|
|
33
|
+
|
|
34
|
+
__all__ = [
|
|
35
|
+
"tools",
|
|
36
|
+
"Apps",
|
|
37
|
+
"Databases",
|
|
38
|
+
"Buckets",
|
|
39
|
+
"Account",
|
|
40
|
+
"Sandbox",
|
|
41
|
+
"AsyncSandbox",
|
|
42
|
+
"Client",
|
|
43
|
+
"AsyncClient",
|
|
44
|
+
"ExecResult",
|
|
45
|
+
"OutputChunk",
|
|
46
|
+
"CommandError",
|
|
47
|
+
"CodeResult",
|
|
48
|
+
"CodeError",
|
|
49
|
+
"InterpreterError",
|
|
50
|
+
"SandboxInfo",
|
|
51
|
+
"Usage",
|
|
52
|
+
"UsageReport",
|
|
53
|
+
"SandboxError",
|
|
54
|
+
"AuthError",
|
|
55
|
+
"BadRequestError",
|
|
56
|
+
"CapacityError",
|
|
57
|
+
"ConflictError",
|
|
58
|
+
"NotFoundError",
|
|
59
|
+
"QuotaError",
|
|
60
|
+
"ServerError",
|
|
61
|
+
"TimeoutError",
|
|
62
|
+
]
|
microcld/_api.py
ADDED
|
@@ -0,0 +1,237 @@
|
|
|
1
|
+
"""Request descriptions for the API - shared by the sync and async clients.
|
|
2
|
+
|
|
3
|
+
Each function returns a `Req`; `Client` and `AsyncClient` execute it.
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
from __future__ import annotations
|
|
7
|
+
|
|
8
|
+
import os
|
|
9
|
+
from dataclasses import dataclass
|
|
10
|
+
from typing import Any, Mapping, Sequence, Union
|
|
11
|
+
|
|
12
|
+
DEFAULT_URL = "http://127.0.0.1:7900"
|
|
13
|
+
ENV_URL = "SANDBOX_API_URL"
|
|
14
|
+
ENV_KEY = "SANDBOX_API_KEY"
|
|
15
|
+
|
|
16
|
+
#: Slack on top of the command timeout: queueing and output transfer.
|
|
17
|
+
EXEC_SLACK = 30.0
|
|
18
|
+
|
|
19
|
+
# Egress policy: "internet" | "none" | ["1.1.1.1:53", ...] (allowlist) |
|
|
20
|
+
# {"mode": ..., "allow": [...]}.
|
|
21
|
+
Egress = Union[str, Sequence[str], Mapping[str, Any]]
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
@dataclass(frozen=True)
|
|
25
|
+
class Req:
|
|
26
|
+
method: str
|
|
27
|
+
path: str
|
|
28
|
+
json: Any = None
|
|
29
|
+
params: dict[str, str] | None = None
|
|
30
|
+
content: bytes | None = None
|
|
31
|
+
timeout: float | None = None
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def config(api_key: str | None, base_url: str | None) -> tuple[str, str]:
|
|
35
|
+
"""Key and URL: arguments, otherwise the environment."""
|
|
36
|
+
key = api_key or os.environ.get(ENV_KEY)
|
|
37
|
+
if not key:
|
|
38
|
+
raise ValueError(f"an API key is required: pass api_key or set {ENV_KEY}")
|
|
39
|
+
url = (base_url or os.environ.get(ENV_URL) or DEFAULT_URL).rstrip("/")
|
|
40
|
+
return key, url
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def egress_json(egress: Egress | None) -> dict[str, Any] | None:
|
|
44
|
+
if egress is None:
|
|
45
|
+
return None
|
|
46
|
+
if isinstance(egress, str):
|
|
47
|
+
return {"mode": egress}
|
|
48
|
+
if isinstance(egress, Mapping):
|
|
49
|
+
return dict(egress)
|
|
50
|
+
return {"mode": "allowlist", "allow": list(egress)}
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def create(
|
|
54
|
+
template: str | None,
|
|
55
|
+
cpus: int | None,
|
|
56
|
+
memory_mb: int | None,
|
|
57
|
+
disk_gb: int | None,
|
|
58
|
+
idle_timeout_secs: int | None,
|
|
59
|
+
port: int | None,
|
|
60
|
+
egress: Egress | None,
|
|
61
|
+
ttl_secs: int | None = None,
|
|
62
|
+
bucket: str | None = None,
|
|
63
|
+
bucket_mode: str | None = None,
|
|
64
|
+
) -> Req:
|
|
65
|
+
body = {
|
|
66
|
+
k: v
|
|
67
|
+
for k, v in {
|
|
68
|
+
"template": template,
|
|
69
|
+
"cpus": cpus,
|
|
70
|
+
"memory_mb": memory_mb,
|
|
71
|
+
"disk_gb": disk_gb,
|
|
72
|
+
"idle_timeout_secs": idle_timeout_secs,
|
|
73
|
+
"port": port,
|
|
74
|
+
"ttl_secs": ttl_secs,
|
|
75
|
+
"egress": egress_json(egress),
|
|
76
|
+
"bucket": bucket,
|
|
77
|
+
"bucket_mode": bucket_mode,
|
|
78
|
+
}.items()
|
|
79
|
+
if v is not None
|
|
80
|
+
}
|
|
81
|
+
return Req("POST", "/v1/sandboxes", json=body, timeout=120)
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
def get(id: str) -> Req:
|
|
85
|
+
return Req("GET", f"/v1/sandboxes/{id}")
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
def list_() -> Req:
|
|
89
|
+
return Req("GET", "/v1/sandboxes")
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def delete(id: str) -> Req:
|
|
93
|
+
return Req("DELETE", f"/v1/sandboxes/{id}", timeout=90)
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
def lifecycle(id: str, op: str) -> Req:
|
|
97
|
+
return Req("POST", f"/v1/sandboxes/{id}/{op}", timeout=120)
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
def exec_(
|
|
101
|
+
id: str,
|
|
102
|
+
cmd: str | Sequence[str],
|
|
103
|
+
env: Mapping[str, str] | None,
|
|
104
|
+
cwd: str | None,
|
|
105
|
+
timeout: float,
|
|
106
|
+
stdin: str | None,
|
|
107
|
+
) -> Req:
|
|
108
|
+
argv = ["sh", "-c", cmd] if isinstance(cmd, str) else list(cmd)
|
|
109
|
+
body: dict[str, Any] = {"cmd": argv, "timeout_secs": max(1, int(timeout))}
|
|
110
|
+
if env:
|
|
111
|
+
body["env"] = dict(env)
|
|
112
|
+
if cwd:
|
|
113
|
+
body["cwd"] = cwd
|
|
114
|
+
if stdin is not None:
|
|
115
|
+
body["stdin"] = stdin
|
|
116
|
+
return Req("POST", f"/v1/sandboxes/{id}/exec", json=body, timeout=timeout + EXEC_SLACK)
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
def exec_stream(
|
|
120
|
+
id: str,
|
|
121
|
+
cmd: str | Sequence[str],
|
|
122
|
+
env: Mapping[str, str] | None,
|
|
123
|
+
cwd: str | None,
|
|
124
|
+
timeout: float,
|
|
125
|
+
stdin: str | None,
|
|
126
|
+
) -> Req:
|
|
127
|
+
r = exec_(id, cmd, env, cwd, timeout, stdin)
|
|
128
|
+
return Req("POST", f"/v1/sandboxes/{id}/exec/stream", json=r.json, timeout=r.timeout)
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
class StreamAcc:
|
|
132
|
+
"""Parser for streamed-exec NDJSON: output chunks one by one, then
|
|
133
|
+
an `ExecResult` (all output). No exit event means the stream was cut off."""
|
|
134
|
+
|
|
135
|
+
def __init__(self) -> None:
|
|
136
|
+
self.out: list[str] = []
|
|
137
|
+
self.err: list[str] = []
|
|
138
|
+
self.exit: dict[str, Any] | None = None
|
|
139
|
+
|
|
140
|
+
def feed(self, line: str):
|
|
141
|
+
import json
|
|
142
|
+
|
|
143
|
+
from ._types import OutputChunk
|
|
144
|
+
from .errors import ServerError
|
|
145
|
+
|
|
146
|
+
ev = json.loads(line)
|
|
147
|
+
kind = ev.get("type")
|
|
148
|
+
if kind in ("stdout", "stderr"):
|
|
149
|
+
(self.out if kind == "stdout" else self.err).append(ev["data"])
|
|
150
|
+
return OutputChunk(kind, ev["data"])
|
|
151
|
+
if kind == "exit":
|
|
152
|
+
self.exit = ev
|
|
153
|
+
return None
|
|
154
|
+
if kind == "error":
|
|
155
|
+
raise ServerError(f"exec aborted: {ev.get('error')}")
|
|
156
|
+
return None
|
|
157
|
+
|
|
158
|
+
def finish(self):
|
|
159
|
+
from ._types import ExecResult
|
|
160
|
+
from .errors import ServerError
|
|
161
|
+
|
|
162
|
+
if self.exit is None:
|
|
163
|
+
raise ServerError("exec aborted: the stream ended without an exit code")
|
|
164
|
+
return ExecResult(
|
|
165
|
+
exit_code=self.exit.get("exit_code"),
|
|
166
|
+
stdout="".join(self.out),
|
|
167
|
+
stderr="".join(self.err),
|
|
168
|
+
timed_out=bool(self.exit.get("timed_out")),
|
|
169
|
+
)
|
|
170
|
+
|
|
171
|
+
|
|
172
|
+
def read_file(id: str, path: str) -> Req:
|
|
173
|
+
return Req("GET", f"/v1/sandboxes/{id}/files", params={"path": path}, timeout=120)
|
|
174
|
+
|
|
175
|
+
|
|
176
|
+
def write_file(id: str, path: str, data: bytes, mode: int | None) -> Req:
|
|
177
|
+
params = {"path": path}
|
|
178
|
+
if mode is not None:
|
|
179
|
+
params["mode"] = f"{mode:o}"
|
|
180
|
+
return Req("PUT", f"/v1/sandboxes/{id}/files", params=params, content=data, timeout=120)
|
|
181
|
+
|
|
182
|
+
|
|
183
|
+
def fork(id: str, snapshot: str | None, ttl_secs: int | None = None) -> Req:
|
|
184
|
+
body = {k: v for k, v in {"snapshot": snapshot, "ttl_secs": ttl_secs}.items() if v is not None}
|
|
185
|
+
return Req("POST", f"/v1/sandboxes/{id}/fork", json=body, timeout=150)
|
|
186
|
+
|
|
187
|
+
|
|
188
|
+
def update(id: str, body: dict[str, Any]) -> Req:
|
|
189
|
+
return Req("PATCH", f"/v1/sandboxes/{id}", json=body)
|
|
190
|
+
|
|
191
|
+
|
|
192
|
+
def set_ttl(id: str, ttl_secs: int | None) -> Req:
|
|
193
|
+
return Req("PUT", f"/v1/sandboxes/{id}/ttl", json={"ttl_secs": ttl_secs})
|
|
194
|
+
|
|
195
|
+
|
|
196
|
+
def snapshot(id: str, name: str) -> Req:
|
|
197
|
+
return Req("POST", f"/v1/sandboxes/{id}/snapshots", json={"name": name}, timeout=150)
|
|
198
|
+
|
|
199
|
+
|
|
200
|
+
def set_egress(id: str, egress: Egress) -> Req:
|
|
201
|
+
return Req("PUT", f"/v1/sandboxes/{id}/egress", json=egress_json(egress))
|
|
202
|
+
|
|
203
|
+
|
|
204
|
+
def usage(start: str | None, end: str | None) -> Req:
|
|
205
|
+
params = {k: v for k, v in {"from": start, "to": end}.items() if v}
|
|
206
|
+
return Req("GET", "/v1/usage", params=params or None)
|
|
207
|
+
|
|
208
|
+
|
|
209
|
+
#: Interpreter client in the `python` template.
|
|
210
|
+
INTERPRETER = ["python3", "/opt/mcinterp/mcinterp.py", "run"]
|
|
211
|
+
#: Slack for starting the client and returning the reply, on top of the code timeout.
|
|
212
|
+
INTERPRETER_SLACK = 15.0
|
|
213
|
+
|
|
214
|
+
|
|
215
|
+
def interpreter_request(code: str | None, timeout: float, reset: bool = False) -> str:
|
|
216
|
+
import json
|
|
217
|
+
|
|
218
|
+
return json.dumps({"reset": True} if reset else {"code": code, "timeout": timeout}, ensure_ascii=False)
|
|
219
|
+
|
|
220
|
+
|
|
221
|
+
def parse_interpreter(exit_code: int | None, stdout: str, stderr: str) -> dict[str, Any]:
|
|
222
|
+
"""The interpreter client reply, or `InterpreterError`."""
|
|
223
|
+
import json
|
|
224
|
+
|
|
225
|
+
from .errors import InterpreterError
|
|
226
|
+
|
|
227
|
+
if exit_code != 0:
|
|
228
|
+
hint = " (the python template is required)" if exit_code == 127 or "No such file" in stderr else ""
|
|
229
|
+
raise InterpreterError(f"interpreter unavailable{hint}: {(stderr or stdout).strip()[-500:]}")
|
|
230
|
+
try:
|
|
231
|
+
return json.loads(stdout)
|
|
232
|
+
except ValueError as e:
|
|
233
|
+
raise InterpreterError(f"interpreter replied with non-JSON: {e}") from e
|
|
234
|
+
|
|
235
|
+
|
|
236
|
+
def as_bytes(data: bytes | str) -> bytes:
|
|
237
|
+
return data.encode() if isinstance(data, str) else data
|
microcld/_types.py
ADDED
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
"""API response data."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from dataclasses import dataclass, field
|
|
6
|
+
from typing import Any
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
@dataclass(frozen=True)
|
|
10
|
+
class SandboxInfo:
|
|
11
|
+
id: str
|
|
12
|
+
template: str
|
|
13
|
+
state: str
|
|
14
|
+
cpus: int
|
|
15
|
+
memory_mb: int
|
|
16
|
+
created_at: str
|
|
17
|
+
forked_from: str | None = None
|
|
18
|
+
#: When the sandbox will be deleted (RFC 3339); None - no expiry.
|
|
19
|
+
expires_at: str | None = None
|
|
20
|
+
#: Organization bucket (S3_*/AWS_* in command env) and key mode: "read" / "write".
|
|
21
|
+
bucket: str | None = None
|
|
22
|
+
bucket_mode: str | None = None
|
|
23
|
+
|
|
24
|
+
@classmethod
|
|
25
|
+
def from_json(cls, d: dict[str, Any]) -> "SandboxInfo":
|
|
26
|
+
return cls(
|
|
27
|
+
id=d["id"],
|
|
28
|
+
template=d.get("template", ""),
|
|
29
|
+
state=d.get("state", "unknown"),
|
|
30
|
+
cpus=d.get("cpus", 0),
|
|
31
|
+
memory_mb=d.get("memory_mb", 0),
|
|
32
|
+
created_at=d.get("created_at", ""),
|
|
33
|
+
forked_from=d.get("forked_from"),
|
|
34
|
+
expires_at=d.get("expires_at"),
|
|
35
|
+
bucket=d.get("bucket"),
|
|
36
|
+
bucket_mode=d.get("bucket_mode"),
|
|
37
|
+
)
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
@dataclass(frozen=True)
|
|
41
|
+
class OutputChunk:
|
|
42
|
+
"""A chunk of streamed exec output: `stream` is "stdout" or "stderr"."""
|
|
43
|
+
|
|
44
|
+
stream: str
|
|
45
|
+
data: str
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
class CommandError(Exception):
|
|
49
|
+
"""The command exited with a non-zero code (`ExecResult.check()`)."""
|
|
50
|
+
|
|
51
|
+
def __init__(self, result: "ExecResult"):
|
|
52
|
+
tail = (result.stderr or result.stdout).strip()[-500:]
|
|
53
|
+
super().__init__(f"exit code {result.exit_code}{' (timed out)' if result.timed_out else ''}: {tail}")
|
|
54
|
+
self.result = result
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
@dataclass(frozen=True)
|
|
58
|
+
class ExecResult:
|
|
59
|
+
"""Command result. `exit_code` is None if the process was killed (including timeout)."""
|
|
60
|
+
|
|
61
|
+
exit_code: int | None
|
|
62
|
+
stdout: str
|
|
63
|
+
stderr: str
|
|
64
|
+
timed_out: bool = False
|
|
65
|
+
truncated: bool = False
|
|
66
|
+
|
|
67
|
+
@property
|
|
68
|
+
def ok(self) -> bool:
|
|
69
|
+
return self.exit_code == 0
|
|
70
|
+
|
|
71
|
+
def check(self) -> "ExecResult":
|
|
72
|
+
"""Return self, or raise `CommandError` if the exit code is not 0."""
|
|
73
|
+
if not self.ok:
|
|
74
|
+
raise CommandError(self)
|
|
75
|
+
return self
|
|
76
|
+
|
|
77
|
+
@classmethod
|
|
78
|
+
def from_json(cls, d: dict[str, Any]) -> "ExecResult":
|
|
79
|
+
return cls(
|
|
80
|
+
exit_code=d.get("exit_code"),
|
|
81
|
+
stdout=d.get("stdout", ""),
|
|
82
|
+
stderr=d.get("stderr", ""),
|
|
83
|
+
timed_out=d.get("timed_out", False),
|
|
84
|
+
truncated=d.get("truncated", False),
|
|
85
|
+
)
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
@dataclass(frozen=True)
|
|
89
|
+
class CodeError:
|
|
90
|
+
"""An exception raised in `run_code` code."""
|
|
91
|
+
|
|
92
|
+
name: str
|
|
93
|
+
value: str
|
|
94
|
+
traceback: str
|
|
95
|
+
|
|
96
|
+
def __str__(self) -> str:
|
|
97
|
+
return self.traceback or f"{self.name}: {self.value}"
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
@dataclass(frozen=True)
|
|
101
|
+
class CodeResult:
|
|
102
|
+
"""Result of `run_code`. `result` is the repr of the last expression (as in Jupyter),
|
|
103
|
+
`images` are matplotlib figures as PNG bytes."""
|
|
104
|
+
|
|
105
|
+
stdout: str
|
|
106
|
+
stderr: str
|
|
107
|
+
result: str | None
|
|
108
|
+
error: CodeError | None
|
|
109
|
+
images: list[bytes] = field(default_factory=list)
|
|
110
|
+
duration_ms: int = 0
|
|
111
|
+
|
|
112
|
+
@property
|
|
113
|
+
def ok(self) -> bool:
|
|
114
|
+
return self.error is None
|
|
115
|
+
|
|
116
|
+
@property
|
|
117
|
+
def text(self) -> str:
|
|
118
|
+
"""All text together - handy to hand to a model as a tool result."""
|
|
119
|
+
parts = [self.stdout.rstrip("\n"), self.stderr.rstrip("\n")]
|
|
120
|
+
if self.result is not None:
|
|
121
|
+
parts.append(self.result)
|
|
122
|
+
if self.error is not None:
|
|
123
|
+
parts.append(str(self.error).rstrip("\n"))
|
|
124
|
+
return "\n".join(p for p in parts if p)
|
|
125
|
+
|
|
126
|
+
|
|
127
|
+
@dataclass(frozen=True)
|
|
128
|
+
class Usage:
|
|
129
|
+
running_seconds: float
|
|
130
|
+
vcpu_seconds: float
|
|
131
|
+
memory_mb_seconds: float
|
|
132
|
+
id: str | None = None
|
|
133
|
+
|
|
134
|
+
|
|
135
|
+
@dataclass(frozen=True)
|
|
136
|
+
class UsageReport:
|
|
137
|
+
start: str
|
|
138
|
+
end: str
|
|
139
|
+
total: Usage
|
|
140
|
+
sandboxes: list[Usage] = field(default_factory=list)
|
|
141
|
+
|
|
142
|
+
@classmethod
|
|
143
|
+
def from_json(cls, d: dict[str, Any]) -> "UsageReport":
|
|
144
|
+
def u(x: dict[str, Any]) -> Usage:
|
|
145
|
+
return Usage(x["running_seconds"], x["vcpu_seconds"], x["memory_mb_seconds"], x.get("id"))
|
|
146
|
+
|
|
147
|
+
return cls(start=d["from"], end=d["to"], total=u(d["total"]), sandboxes=[u(s) for s in d["sandboxes"]])
|