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 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"]])