singularity-grid 0.12.0__tar.gz → 0.13.0__tar.gz

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.
Files changed (31) hide show
  1. {singularity_grid-0.12.0 → singularity_grid-0.13.0}/PKG-INFO +104 -1
  2. {singularity_grid-0.12.0 → singularity_grid-0.13.0}/README.md +103 -0
  3. singularity_grid-0.13.0/examples/anthropic_messages.py +41 -0
  4. singularity_grid-0.13.0/examples/pods_sandbox.py +27 -0
  5. {singularity_grid-0.12.0 → singularity_grid-0.13.0}/pyproject.toml +1 -1
  6. {singularity_grid-0.12.0 → singularity_grid-0.13.0}/singularity_grid/__init__.py +3 -1
  7. {singularity_grid-0.12.0 → singularity_grid-0.13.0}/singularity_grid/client.py +168 -6
  8. {singularity_grid-0.12.0 → singularity_grid-0.13.0}/singularity_grid/pods.py +125 -2
  9. singularity_grid-0.13.0/tests/test_messages_pods.py +172 -0
  10. {singularity_grid-0.12.0 → singularity_grid-0.13.0}/.github/workflows/publish.yml +0 -0
  11. {singularity_grid-0.12.0 → singularity_grid-0.13.0}/.gitignore +0 -0
  12. {singularity_grid-0.12.0 → singularity_grid-0.13.0}/LICENSE +0 -0
  13. {singularity_grid-0.12.0 → singularity_grid-0.13.0}/examples/check_capacity.py +0 -0
  14. {singularity_grid-0.12.0 → singularity_grid-0.13.0}/examples/multimodal_embeddings.py +0 -0
  15. {singularity_grid-0.12.0 → singularity_grid-0.13.0}/examples/openai_compatible.py +0 -0
  16. {singularity_grid-0.12.0 → singularity_grid-0.13.0}/examples/quickstart.py +0 -0
  17. {singularity_grid-0.12.0 → singularity_grid-0.13.0}/singularity_grid/e2e.py +0 -0
  18. {singularity_grid-0.12.0 → singularity_grid-0.13.0}/singularity_grid/embeddings.py +0 -0
  19. {singularity_grid-0.12.0 → singularity_grid-0.13.0}/singularity_grid/errors.py +0 -0
  20. {singularity_grid-0.12.0 → singularity_grid-0.13.0}/singularity_grid/models.py +0 -0
  21. {singularity_grid-0.12.0 → singularity_grid-0.13.0}/singularity_grid/openai_compat.py +0 -0
  22. {singularity_grid-0.12.0 → singularity_grid-0.13.0}/singularity_grid/processors.py +0 -0
  23. {singularity_grid-0.12.0 → singularity_grid-0.13.0}/singularity_grid/py.typed +0 -0
  24. {singularity_grid-0.12.0 → singularity_grid-0.13.0}/singularity_grid/transcriptions.py +0 -0
  25. {singularity_grid-0.12.0 → singularity_grid-0.13.0}/singularity_grid/vault.py +0 -0
  26. {singularity_grid-0.12.0 → singularity_grid-0.13.0}/tests/test_embeddings.py +0 -0
  27. {singularity_grid-0.12.0 → singularity_grid-0.13.0}/tests/test_pod_webhook.py +0 -0
  28. {singularity_grid-0.12.0 → singularity_grid-0.13.0}/tests/test_processors.py +0 -0
  29. {singularity_grid-0.12.0 → singularity_grid-0.13.0}/tests/test_transcriptions.py +0 -0
  30. {singularity_grid-0.12.0 → singularity_grid-0.13.0}/tests/test_vault.py +0 -0
  31. {singularity_grid-0.12.0 → singularity_grid-0.13.0}/tests/typecheck_embeddings.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: singularity-grid
3
- Version: 0.12.0
3
+ Version: 0.13.0
4
4
  Summary: Python SDK for the SGL Network confidential compute grid (end-to-end encrypted + streaming)
5
5
  Project-URL: Homepage, https://singularitylayer.xyz
6
6
  Project-URL: Repository, https://github.com/Singularity-Layer/sgl-network-sdk
@@ -238,6 +238,53 @@ decision = grid.system_one(
238
238
  print(decision["answers"])
239
239
  ```
240
240
 
241
+ ### 7. Anthropic Messages API (and Claude Code)
242
+
243
+ The Grid also speaks the Anthropic Messages format at `POST /v1/messages`, next to the
244
+ OpenAI one. Same auth, same credits, same nodes. Use a Grid model id, not a Claude id.
245
+
246
+ ```python
247
+ import os
248
+ from singularity_grid import GridClient
249
+
250
+ grid = GridClient(api_key=os.environ["SGL_API_KEY"])
251
+
252
+ msg = grid.messages(
253
+ "qwen-2.5-32b",
254
+ [{"role": "user", "content": "What is a TEE?"}],
255
+ max_tokens=512,
256
+ system="Answer in one sentence.",
257
+ )
258
+ print(msg["content"][0]["text"])
259
+
260
+ # Streaming: Anthropic events as dicts (message_start, content_block_delta, ..., message_stop)
261
+ for ev in grid.messages_stream("qwen-2.5-32b", [{"role": "user", "content": "Count to 5"}], max_tokens=256):
262
+ if ev["type"] == "content_block_delta" and ev["delta"]["type"] == "text_delta":
263
+ print(ev["delta"]["text"], end="", flush=True)
264
+
265
+ # Free input-token estimate
266
+ print(grid.count_tokens("qwen-2.5-32b", [{"role": "user", "content": "hi"}])["input_tokens"])
267
+ ```
268
+
269
+ The official Anthropic SDK works too:
270
+ `anthropic.Anthropic(api_key="x402c_...", base_url="https://grid.x402compute.cc")`.
271
+
272
+ **Claude Code on the Grid.** Point Claude Code at the Grid with your Singularity Layer compute key:
273
+
274
+ ```bash
275
+ export ANTHROPIC_BASE_URL=https://grid.x402compute.cc
276
+ export ANTHROPIC_API_KEY=x402c_... # your compute API key
277
+ claude --model qwen-2.5-32b
278
+ ```
279
+
280
+ Claude Code's own system prompt and tools are about 13k tokens, so only large-context models
281
+ fit. Today that is `qwen-2.5-32b` (32k context). Check `max_input_tokens` in `GET /v1/models`
282
+ (send an `anthropic-version` header to get the Anthropic shape) before picking another one.
283
+
284
+ Not supported (clean 400): extended thinking with a budget, structured outputs, server tools
285
+ such as web search, documents and citations, `top_p` / `top_k`, and assistant prefill. Images
286
+ work on vision models only, as base64, non-streaming.
287
+
241
288
  ## API reference
242
289
 
243
290
  ### GridClient
@@ -257,6 +304,9 @@ print(decision["answers"])
257
304
  | `submit_job(model, input_payload, ...)` | Yes | Submit a compute job |
258
305
  | `get_job(job_id)` | Yes | Get job status and result |
259
306
  | `get_attestation(job_id)` | Yes | Get TEE attestation proof |
307
+ | `messages(model, messages, max_tokens=...)` | Yes | Anthropic-format chat via `/v1/messages` |
308
+ | `messages_stream(model, messages, max_tokens=...)` | Yes | Streaming `/v1/messages`, yields Anthropic events |
309
+ | `count_tokens(model, messages)` | No | Free input-token estimate via `/v1/messages/count_tokens` |
260
310
 
261
311
  ### Exceptions
262
312
 
@@ -319,3 +369,56 @@ with the `Processor*` models. They pointed at `/grid/processors`, which has neve
319
369
  call returned 404 — and their models described an older design that was never shipped. Use
320
370
  `ProcessorsClient`. Nothing else changed: chat, embeddings, jobs, models, capacity, pricing,
321
371
  reserve and the vault are untouched.
372
+
373
+ ## Agent Pods
374
+
375
+ `PodsClient` creates and drives hosted agents on `compute.x402layer.cc` with a compute API key.
376
+
377
+ ```python
378
+ import os
379
+ from singularity_grid import PodsClient
380
+
381
+ pods = PodsClient(api_key=os.environ["SGL_API_KEY"])
382
+
383
+ # engine: "clawpod" (OpenClaw, default), "hermpod" (Hermes) or "pipod" (the Pi coding agent)
384
+ pod = pods.create_pod(tier="starter", ai={"mode": "managed"}, engine="pipod", max_total_usd=5)
385
+ pods.wait_for_online(pod["id"])
386
+ ```
387
+
388
+ **Bring your own key, with fallbacks.** Presets fix the provider URL: `openrouter`, `openai`,
389
+ `venice`, `0g`, or `custom` with your own `base_url`. Fallbacks are tried in order when the
390
+ primary fails. `managed_models` also allows Singularity Layer models, paid per call from your
391
+ credits (fallbacks and our models are ClawPod only for now).
392
+
393
+ ```python
394
+ pods.create_pod(
395
+ engine="clawpod",
396
+ ai={
397
+ "mode": "byok",
398
+ "preset": "venice",
399
+ "api_key": os.environ["VENICE_API_KEY"],
400
+ "fallbacks": [
401
+ {"preset": "openrouter", "model": "meta-llama/llama-3.3-70b-instruct", "api_key": os.environ["OPENROUTER_API_KEY"]},
402
+ {"preset": "singularity", "model": "z-ai/glm-5.3"},
403
+ ],
404
+ "managed_models": True,
405
+ },
406
+ )
407
+ ```
408
+
409
+ **Sandbox.** Run commands, edit files, give a port a URL, and clone a pod from its Agent Vault
410
+ backup. Needs an API key with the `pods:control:write` scope; a pod's own key cannot use these.
411
+
412
+ ```python
413
+ run = pods.exec(pod["id"], "python3 --version", timeout_seconds=30)
414
+ pods.write_file(pod["id"], "hello.txt", "hi")
415
+ print(pods.read_file(pod["id"], "hello.txt")["content"])
416
+
417
+ port = pods.open_port(pod["id"], 8080, "public")["port"] # port["url"] is shown once
418
+ pods.close_port(pod["id"], 8080)
419
+
420
+ clone = pods.clone_pod(pod["id"], os.environ["VAULT_PASSPHRASE"])
421
+ print(pods.clone_status(clone["pod"]["id"]))
422
+ ```
423
+
424
+ See `examples/pods_sandbox.py`.
@@ -207,6 +207,53 @@ decision = grid.system_one(
207
207
  print(decision["answers"])
208
208
  ```
209
209
 
210
+ ### 7. Anthropic Messages API (and Claude Code)
211
+
212
+ The Grid also speaks the Anthropic Messages format at `POST /v1/messages`, next to the
213
+ OpenAI one. Same auth, same credits, same nodes. Use a Grid model id, not a Claude id.
214
+
215
+ ```python
216
+ import os
217
+ from singularity_grid import GridClient
218
+
219
+ grid = GridClient(api_key=os.environ["SGL_API_KEY"])
220
+
221
+ msg = grid.messages(
222
+ "qwen-2.5-32b",
223
+ [{"role": "user", "content": "What is a TEE?"}],
224
+ max_tokens=512,
225
+ system="Answer in one sentence.",
226
+ )
227
+ print(msg["content"][0]["text"])
228
+
229
+ # Streaming: Anthropic events as dicts (message_start, content_block_delta, ..., message_stop)
230
+ for ev in grid.messages_stream("qwen-2.5-32b", [{"role": "user", "content": "Count to 5"}], max_tokens=256):
231
+ if ev["type"] == "content_block_delta" and ev["delta"]["type"] == "text_delta":
232
+ print(ev["delta"]["text"], end="", flush=True)
233
+
234
+ # Free input-token estimate
235
+ print(grid.count_tokens("qwen-2.5-32b", [{"role": "user", "content": "hi"}])["input_tokens"])
236
+ ```
237
+
238
+ The official Anthropic SDK works too:
239
+ `anthropic.Anthropic(api_key="x402c_...", base_url="https://grid.x402compute.cc")`.
240
+
241
+ **Claude Code on the Grid.** Point Claude Code at the Grid with your Singularity Layer compute key:
242
+
243
+ ```bash
244
+ export ANTHROPIC_BASE_URL=https://grid.x402compute.cc
245
+ export ANTHROPIC_API_KEY=x402c_... # your compute API key
246
+ claude --model qwen-2.5-32b
247
+ ```
248
+
249
+ Claude Code's own system prompt and tools are about 13k tokens, so only large-context models
250
+ fit. Today that is `qwen-2.5-32b` (32k context). Check `max_input_tokens` in `GET /v1/models`
251
+ (send an `anthropic-version` header to get the Anthropic shape) before picking another one.
252
+
253
+ Not supported (clean 400): extended thinking with a budget, structured outputs, server tools
254
+ such as web search, documents and citations, `top_p` / `top_k`, and assistant prefill. Images
255
+ work on vision models only, as base64, non-streaming.
256
+
210
257
  ## API reference
211
258
 
212
259
  ### GridClient
@@ -226,6 +273,9 @@ print(decision["answers"])
226
273
  | `submit_job(model, input_payload, ...)` | Yes | Submit a compute job |
227
274
  | `get_job(job_id)` | Yes | Get job status and result |
228
275
  | `get_attestation(job_id)` | Yes | Get TEE attestation proof |
276
+ | `messages(model, messages, max_tokens=...)` | Yes | Anthropic-format chat via `/v1/messages` |
277
+ | `messages_stream(model, messages, max_tokens=...)` | Yes | Streaming `/v1/messages`, yields Anthropic events |
278
+ | `count_tokens(model, messages)` | No | Free input-token estimate via `/v1/messages/count_tokens` |
229
279
 
230
280
  ### Exceptions
231
281
 
@@ -288,3 +338,56 @@ with the `Processor*` models. They pointed at `/grid/processors`, which has neve
288
338
  call returned 404 — and their models described an older design that was never shipped. Use
289
339
  `ProcessorsClient`. Nothing else changed: chat, embeddings, jobs, models, capacity, pricing,
290
340
  reserve and the vault are untouched.
341
+
342
+ ## Agent Pods
343
+
344
+ `PodsClient` creates and drives hosted agents on `compute.x402layer.cc` with a compute API key.
345
+
346
+ ```python
347
+ import os
348
+ from singularity_grid import PodsClient
349
+
350
+ pods = PodsClient(api_key=os.environ["SGL_API_KEY"])
351
+
352
+ # engine: "clawpod" (OpenClaw, default), "hermpod" (Hermes) or "pipod" (the Pi coding agent)
353
+ pod = pods.create_pod(tier="starter", ai={"mode": "managed"}, engine="pipod", max_total_usd=5)
354
+ pods.wait_for_online(pod["id"])
355
+ ```
356
+
357
+ **Bring your own key, with fallbacks.** Presets fix the provider URL: `openrouter`, `openai`,
358
+ `venice`, `0g`, or `custom` with your own `base_url`. Fallbacks are tried in order when the
359
+ primary fails. `managed_models` also allows Singularity Layer models, paid per call from your
360
+ credits (fallbacks and our models are ClawPod only for now).
361
+
362
+ ```python
363
+ pods.create_pod(
364
+ engine="clawpod",
365
+ ai={
366
+ "mode": "byok",
367
+ "preset": "venice",
368
+ "api_key": os.environ["VENICE_API_KEY"],
369
+ "fallbacks": [
370
+ {"preset": "openrouter", "model": "meta-llama/llama-3.3-70b-instruct", "api_key": os.environ["OPENROUTER_API_KEY"]},
371
+ {"preset": "singularity", "model": "z-ai/glm-5.3"},
372
+ ],
373
+ "managed_models": True,
374
+ },
375
+ )
376
+ ```
377
+
378
+ **Sandbox.** Run commands, edit files, give a port a URL, and clone a pod from its Agent Vault
379
+ backup. Needs an API key with the `pods:control:write` scope; a pod's own key cannot use these.
380
+
381
+ ```python
382
+ run = pods.exec(pod["id"], "python3 --version", timeout_seconds=30)
383
+ pods.write_file(pod["id"], "hello.txt", "hi")
384
+ print(pods.read_file(pod["id"], "hello.txt")["content"])
385
+
386
+ port = pods.open_port(pod["id"], 8080, "public")["port"] # port["url"] is shown once
387
+ pods.close_port(pod["id"], 8080)
388
+
389
+ clone = pods.clone_pod(pod["id"], os.environ["VAULT_PASSPHRASE"])
390
+ print(pods.clone_status(clone["pod"]["id"]))
391
+ ```
392
+
393
+ See `examples/pods_sandbox.py`.
@@ -0,0 +1,41 @@
1
+ """Anthropic Messages API on the Singularity Layer Grid.
2
+
3
+ SGL_API_KEY=x402c_... python examples/anthropic_messages.py
4
+
5
+ Model ids are Grid model ids. Claude Code users: set ANTHROPIC_BASE_URL=https://grid.x402compute.cc
6
+ and ANTHROPIC_API_KEY to your compute key, and pick a large-context model (Claude Code's own
7
+ prompt is about 13k tokens; today qwen-2.5-32b at 32k fits).
8
+ """
9
+
10
+ import os
11
+
12
+ from singularity_grid import GridClient
13
+
14
+ MODEL = os.environ.get("SGL_MODEL", "qwen-2.5-32b")
15
+ QUESTION = [{"role": "user", "content": "Name three uses of a trusted execution environment."}]
16
+
17
+ with GridClient(api_key=os.environ["SGL_API_KEY"]) as grid:
18
+ print("estimated input tokens:", grid.count_tokens(MODEL, QUESTION)["input_tokens"])
19
+
20
+ msg = grid.messages(MODEL, QUESTION, max_tokens=256, system="Be brief.")
21
+ for block in msg["content"]:
22
+ if block["type"] == "text":
23
+ print(block["text"])
24
+ print("stop:", msg["stop_reason"], "usage:", msg["usage"])
25
+
26
+ # Tools: the model answers with a tool_use block you run yourself.
27
+ weather_tool = {
28
+ "name": "get_weather",
29
+ "description": "Current weather for a city",
30
+ "input_schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]},
31
+ }
32
+ with_tool = grid.messages(
33
+ MODEL, [{"role": "user", "content": "What is the weather in Paris?"}], max_tokens=256, tools=[weather_tool]
34
+ )
35
+ print(with_tool["stop_reason"], with_tool["content"])
36
+
37
+ # Streaming
38
+ for ev in grid.messages_stream(MODEL, [{"role": "user", "content": "Count from 1 to 5."}], max_tokens=256):
39
+ if ev["type"] == "content_block_delta" and ev["delta"].get("type") == "text_delta":
40
+ print(ev["delta"]["text"], end="", flush=True)
41
+ print()
@@ -0,0 +1,27 @@
1
+ """Agent Pods sandbox: run a command, edit a file, serve a port, clean up.
2
+
3
+ SGL_API_KEY=x402c_... POD_ID=<an online pod you own> python examples/pods_sandbox.py
4
+
5
+ The key needs the pods:control:write scope. Nothing here creates or pays for a pod.
6
+ """
7
+
8
+ import os
9
+
10
+ from singularity_grid import PodsClient
11
+
12
+ pod_id = os.environ["POD_ID"]
13
+
14
+ with PodsClient(api_key=os.environ["SGL_API_KEY"]) as pods:
15
+ run = pods.exec(pod_id, "uname -a && whoami", timeout_seconds=30)
16
+ print("exit", run["exit_code"], run["stdout"])
17
+
18
+ pods.write_file(pod_id, "index.html", "<h1>Hello from my pod</h1>")
19
+ print(pods.read_file(pod_id, "index.html")["content"])
20
+
21
+ # Serve the workspace on 8080 and give it a public URL (shown once).
22
+ pods.exec(pod_id, "nohup python3 -m http.server 8080 >/dev/null 2>&1 &", timeout_seconds=10)
23
+ port = pods.open_port(pod_id, 8080, "public")["port"]
24
+ print("open", port["url"])
25
+
26
+ print(pods.list_ports(pod_id))
27
+ pods.close_port(pod_id, 8080)
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "singularity-grid"
7
- version = "0.12.0"
7
+ version = "0.13.0"
8
8
  description = "Python SDK for the SGL Network confidential compute grid (end-to-end encrypted + streaming)"
9
9
  readme = "README.md"
10
10
  license = "MIT"
@@ -72,6 +72,7 @@ from .embeddings import (
72
72
  video_part,
73
73
  )
74
74
  from .openai_compat import create_openai_client
75
+ from .client import ANTHROPIC_VERSION
75
76
  from .transcriptions import (
76
77
  TRANSCRIPTION_AUDIO_FORMAT,
77
78
  TRANSCRIPTION_BITS_PER_SAMPLE,
@@ -92,7 +93,7 @@ from .transcriptions import (
92
93
  validate_transcription_pcm,
93
94
  )
94
95
 
95
- __version__ = "0.12.0"
96
+ __version__ = "0.13.0"
96
97
 
97
98
  __all__ = [
98
99
  # Processors — a SEPARATE client on processors.x402compute.cc. Until 0.9.0 these methods
@@ -105,6 +106,7 @@ __all__ = [
105
106
  "verify_pod_webhook",
106
107
  # Client
107
108
  "GridClient",
109
+ "ANTHROPIC_VERSION",
108
110
  "create_openai_client",
109
111
  "DEFAULT_BASE_URL",
110
112
  # Exceptions
@@ -77,6 +77,48 @@ def _count_images(messages: List[Dict[str, Any]]) -> int:
77
77
  # Client
78
78
  # ---------------------------------------------------------------------------
79
79
 
80
+ ANTHROPIC_VERSION = "2023-06-01"
81
+ _ANTHROPIC_HEADERS = {"anthropic-version": ANTHROPIC_VERSION}
82
+
83
+
84
+ def _messages_body(
85
+ model: str,
86
+ messages: List[Dict[str, Any]],
87
+ max_tokens: int,
88
+ system: Optional[Any],
89
+ tools: Optional[List[Dict[str, Any]]],
90
+ tool_choice: Optional[Dict[str, Any]],
91
+ stop_sequences: Optional[List[str]],
92
+ temperature: Optional[float],
93
+ extra: Dict[str, Any],
94
+ ) -> Dict[str, Any]:
95
+ body: Dict[str, Any] = {"model": model, "messages": messages, "max_tokens": max_tokens}
96
+ if system is not None:
97
+ body["system"] = system
98
+ if tools is not None:
99
+ body["tools"] = tools
100
+ if tool_choice is not None:
101
+ body["tool_choice"] = tool_choice
102
+ if stop_sequences is not None:
103
+ body["stop_sequences"] = stop_sequences
104
+ if temperature is not None:
105
+ body["temperature"] = temperature
106
+ body.update(extra)
107
+ body.pop("stream", None)
108
+ return body
109
+
110
+
111
+ def _parse_stream_event(data_lines: List[str]) -> Dict[str, Any]:
112
+ try:
113
+ event = _json.loads("\n".join(data_lines))
114
+ except _json.JSONDecodeError as exc:
115
+ raise SGLAPIError(502, "malformed stream event") from exc
116
+ if event.get("type") == "error":
117
+ err = event.get("error") or {}
118
+ raise SGLAPIError(502, str(err.get("message") or "stream aborted by server"), event)
119
+ return event # type: ignore[no-any-return]
120
+
121
+
80
122
  class GridClient:
81
123
  """Client for the SGL Network orchestrator API.
82
124
 
@@ -334,7 +376,7 @@ class GridClient:
334
376
  data = self._request("POST", "/v1/chat/completions", json=body)
335
377
  except SGLAPIError as err:
336
378
  if err.status_code == 402:
337
- raise SGLAPIError(402, "Payment required — pass api_key (credits); the Python GridClient does not sign x402 payments.") from err
379
+ raise SGLAPIError(402, "Payment required: pass api_key (credits); the Python GridClient does not sign x402 payments.") from err
338
380
  raise
339
381
 
340
382
  sealed = data.get("sealed_result")
@@ -420,7 +462,7 @@ class GridClient:
420
462
  if err.status_code == 402:
421
463
  raise SGLAPIError(
422
464
  402,
423
- "Payment required — pass api_key (credits); the Python "
465
+ "Payment required: pass api_key (credits); the Python "
424
466
  "GridClient does not sign x402 payments.",
425
467
  err.body,
426
468
  ) from err
@@ -497,7 +539,7 @@ class GridClient:
497
539
  if err.status_code == 402:
498
540
  raise SGLAPIError(
499
541
  402,
500
- "Payment required — pass api_key (credits); the Python "
542
+ "Payment required: pass api_key (credits); the Python "
501
543
  "GridClient does not sign x402 payments.",
502
544
  err.body,
503
545
  ) from err
@@ -668,7 +710,7 @@ class GridClient:
668
710
  return self._request("POST", "/v1/embeddings", json=body)
669
711
  except SGLAPIError as err:
670
712
  if err.status_code == 402:
671
- raise SGLAPIError(402, "Payment required — pass api_key (credits); the Python GridClient does not sign x402 payments.", err.body) from err
713
+ raise SGLAPIError(402, "Payment required: pass api_key (credits); the Python GridClient does not sign x402 payments.", err.body) from err
672
714
  raise
673
715
 
674
716
  def system_one(
@@ -702,7 +744,7 @@ class GridClient:
702
744
  return self._request("POST", "/v1/systemone", json=body)
703
745
  except SGLAPIError as err:
704
746
  if err.status_code == 402:
705
- raise SGLAPIError(402, "Payment required — pass api_key (credits); the Python GridClient does not sign x402 payments.") from err
747
+ raise SGLAPIError(402, "Payment required: pass api_key (credits); the Python GridClient does not sign x402 payments.") from err
706
748
  raise
707
749
 
708
750
  def systemone(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
@@ -754,7 +796,7 @@ class GridClient:
754
796
  if resp.status_code != 200:
755
797
  resp.read()
756
798
  if resp.status_code == 402:
757
- raise SGLAPIError(402, "Payment required — pass api_key (credits); the Python GridClient does not sign x402 payments.")
799
+ raise SGLAPIError(402, "Payment required: pass api_key (credits); the Python GridClient does not sign x402 payments.")
758
800
  msg = resp.text
759
801
  try:
760
802
  err = resp.json().get("error")
@@ -840,6 +882,126 @@ class GridClient:
840
882
 
841
883
  # -- lifecycle ----------------------------------------------------------
842
884
 
885
+ # -- Anthropic Messages API -----------------------------------------------
886
+
887
+ def messages(
888
+ self,
889
+ model: str,
890
+ messages: List[Dict[str, Any]],
891
+ *,
892
+ max_tokens: int,
893
+ system: Optional[Any] = None,
894
+ tools: Optional[List[Dict[str, Any]]] = None,
895
+ tool_choice: Optional[Dict[str, Any]] = None,
896
+ stop_sequences: Optional[List[str]] = None,
897
+ temperature: Optional[float] = None,
898
+ **extra: Any,
899
+ ) -> Dict[str, Any]:
900
+ """Anthropic-format chat via ``POST /v1/messages`` (non-streaming).
901
+
902
+ Same request and response shape as the Anthropic Messages API, served by
903
+ Grid models. Use a Grid model id (for example ``qwen-2.5-32b``), not a
904
+ Claude id. Requires ``api_key`` (credits); this client does not sign x402
905
+ payments. The orchestrator seals the prompt to the node, so this is not
906
+ client-side end-to-end encrypted like :meth:`chat_completions`.
907
+
908
+ For long replies prefer :meth:`messages_stream`: a non-streaming reply that
909
+ runs past the Grid's sync window returns 504 with a ``job_id``. Do not
910
+ retry that, it would start a second paid job.
911
+ """
912
+ body = _messages_body(model, messages, max_tokens, system, tools, tool_choice, stop_sequences, temperature, extra)
913
+ try:
914
+ return self._request("POST", "/v1/messages", json=body, headers=_ANTHROPIC_HEADERS)
915
+ except SGLAPIError as err:
916
+ if err.status_code == 402:
917
+ raise SGLAPIError(402, "Payment required: pass api_key (credits); the Python GridClient does not sign x402 payments.", err.body) from err
918
+ raise
919
+
920
+ def messages_stream(
921
+ self,
922
+ model: str,
923
+ messages: List[Dict[str, Any]],
924
+ *,
925
+ max_tokens: int,
926
+ system: Optional[Any] = None,
927
+ tools: Optional[List[Dict[str, Any]]] = None,
928
+ tool_choice: Optional[Dict[str, Any]] = None,
929
+ stop_sequences: Optional[List[str]] = None,
930
+ temperature: Optional[float] = None,
931
+ **extra: Any,
932
+ ) -> Iterator[Dict[str, Any]]:
933
+ """Streaming Anthropic-format chat via ``POST /v1/messages`` with ``stream: true``.
934
+
935
+ Yields each server-sent event as a dict, in Anthropic order
936
+ (``message_start``, ``content_block_start``, ``content_block_delta``, ...,
937
+ ``message_stop``). ``ping`` events are yielded too. An ``error`` event after
938
+ the stream started raises :class:`SGLAPIError`. Text arrives in
939
+ ``content_block_delta`` events whose ``delta["type"]`` is ``text_delta``.
940
+ """
941
+ body = _messages_body(model, messages, max_tokens, system, tools, tool_choice, stop_sequences, temperature, extra)
942
+ body["stream"] = True
943
+ headers = dict(_ANTHROPIC_HEADERS)
944
+ headers["Accept"] = "text/event-stream"
945
+ try:
946
+ yield from self._messages_events(body, headers)
947
+ except httpx.ConnectError as exc:
948
+ raise SGLConnectionError(f"Could not connect to {self._base_url}: {exc}") from exc
949
+ except httpx.TimeoutException as exc:
950
+ raise SGLConnectionError(f"Stream from {self._base_url}/v1/messages timed out: {exc}") from exc
951
+
952
+ def _messages_events(self, body: Dict[str, Any], headers: Dict[str, str]) -> Iterator[Dict[str, Any]]:
953
+ with self._client.stream("POST", "/v1/messages", json=body, headers=headers) as resp:
954
+ if resp.status_code != 200:
955
+ resp.read()
956
+ err_body: Optional[Dict[str, Any]] = None
957
+ msg: Any = resp.text
958
+ try:
959
+ err_body = resp.json()
960
+ err = err_body.get("error") if isinstance(err_body, dict) else None
961
+ msg = err.get("message", msg) if isinstance(err, dict) else (err or msg)
962
+ except Exception:
963
+ pass
964
+ if resp.status_code == 402:
965
+ raise SGLAPIError(402, "Payment required: pass api_key (credits); the Python GridClient does not sign x402 payments.", err_body)
966
+ if resp.status_code in (401, 403):
967
+ raise SGLAuthError(resp.status_code, str(msg), err_body)
968
+ if resp.status_code == 404:
969
+ raise SGLNotFoundError(resp.status_code, str(msg), err_body)
970
+ raise SGLAPIError(resp.status_code, str(msg), err_body)
971
+ data_lines: List[str] = []
972
+ for raw in resp.iter_lines():
973
+ line = raw.rstrip("\r")
974
+ if line.startswith("data:"):
975
+ data_lines.append(line[5:].strip())
976
+ continue
977
+ if line != "" or not data_lines:
978
+ continue
979
+ event = _parse_stream_event(data_lines)
980
+ data_lines = []
981
+ yield event
982
+ if event.get("type") == "message_stop":
983
+ return
984
+ if data_lines:
985
+ yield _parse_stream_event(data_lines)
986
+
987
+ def count_tokens(
988
+ self,
989
+ model: str,
990
+ messages: List[Dict[str, Any]],
991
+ *,
992
+ system: Optional[Any] = None,
993
+ tools: Optional[List[Dict[str, Any]]] = None,
994
+ ) -> Dict[str, Any]:
995
+ """Estimate input tokens for a Messages request via
996
+ ``POST /v1/messages/count_tokens``. Free. An estimate from the Grid's own
997
+ estimator, not a model tokenizer count. Returns ``{"input_tokens": N}``."""
998
+ body: Dict[str, Any] = {"model": model, "messages": messages}
999
+ if system is not None:
1000
+ body["system"] = system
1001
+ if tools is not None:
1002
+ body["tools"] = tools
1003
+ return self._request("POST", "/v1/messages/count_tokens", json=body, headers=_ANTHROPIC_HEADERS)
1004
+
843
1005
  def close(self) -> None:
844
1006
  """Close the underlying HTTP client."""
845
1007
  self._client.close()
@@ -27,6 +27,7 @@ import re
27
27
  import time
28
28
  import uuid
29
29
  from typing import Any, Dict, List, Optional
30
+ from urllib.parse import quote
30
31
 
31
32
  import httpx
32
33
 
@@ -119,11 +120,35 @@ class PodsClient:
119
120
  region: Optional[str] = None,
120
121
  term_hours: Optional[int] = None,
121
122
  capabilities: Optional[Dict[str, bool]] = None,
122
- ai: Optional[Dict[str, str]] = None,
123
+ ai: Optional[Dict[str, Any]] = None,
123
124
  idempotency_key: Optional[str] = None,
125
+ *,
126
+ engine: Optional[str] = None,
127
+ template: Optional[str] = None,
128
+ template_config: Optional[Dict[str, Any]] = None,
129
+ channels: Optional[Dict[str, Any]] = None,
130
+ max_total_usd: Optional[float] = None,
131
+ agent_instructions: Optional[str] = None,
132
+ agent_identity: Optional[str] = None,
133
+ heartbeat_prompt: Optional[str] = None,
134
+ agent_heartbeat_minutes: Optional[int] = None,
124
135
  ) -> Dict[str, Any]:
125
136
  """Create a pod. Provisions a machine and charges for it.
126
137
 
138
+ ``engine`` picks the agent: ``"clawpod"`` (OpenClaw, the default), ``"hermpod"``
139
+ (Hermes) or ``"pipod"`` (the Pi coding agent).
140
+
141
+ ``ai`` is ``{"mode": "managed"}`` (our models, billed from credits) or a bring-your-own-key
142
+ block: ``{"mode": "byok", "preset": "venice", "api_key": ..., "fallbacks": [...],
143
+ "managed_models": True}``. Presets: ``openrouter``, ``openai``, ``venice``, ``0g``,
144
+ ``custom`` (``custom`` also needs ``base_url`` and optionally ``api``). ``fallbacks``
145
+ is an ordered list of at most 3 providers of the same shape (each with ``model`` and
146
+ ``api_key``), plus optionally one ``{"preset": "singularity", "model": ...}`` entry for a
147
+ Singularity Layer model paid from credits. ``managed_models`` turns those models on
148
+ (default on for a BYOK ClawPod; fallbacks and our models are ClawPod only for now).
149
+
150
+ ``max_total_usd`` refuses the create, before any charge, if the price is higher.
151
+
127
152
  Returns as soon as the order exists, with ``status == "provisioning"``; the machine
128
153
  takes a few minutes to boot. Use :meth:`wait_for_online` if you need to wait.
129
154
 
@@ -136,6 +161,10 @@ class PodsClient:
136
161
  ("name", name), ("external_ref", external_ref), ("model", model),
137
162
  ("system_prompt", system_prompt), ("region", region),
138
163
  ("term_hours", term_hours), ("capabilities", capabilities), ("ai", ai),
164
+ ("engine", engine), ("template", template), ("template_config", template_config),
165
+ ("channels", channels), ("max_total_usd", max_total_usd),
166
+ ("agent_instructions", agent_instructions), ("agent_identity", agent_identity),
167
+ ("heartbeat_prompt", heartbeat_prompt), ("agent_heartbeat_minutes", agent_heartbeat_minutes),
139
168
  ):
140
169
  if value is not None:
141
170
  body[key] = value
@@ -165,7 +194,14 @@ class PodsClient:
165
194
  return self._request("GET", f"/pods{query}")
166
195
 
167
196
  def update_pod(self, pod_id: str, **patch: Any) -> Dict[str, Any]:
168
- """Change ``name``, ``model``, ``slug`` or ``auto_renew``."""
197
+ """Change ``name``, ``model``, ``slug``, ``auto_renew``, ``agent_instructions``,
198
+ ``agent_identity``, ``heartbeat_prompt`` or ``agent_heartbeat_minutes``.
199
+
200
+ Bring-your-own-key pods can also pass ``ai={...}``: ``api_key``, ``base_url``, ``api``
201
+ for the primary, ``managed_models`` (Singularity Layer models on or off), or
202
+ ``providers`` (the WHOLE ordered list, primary first; an entry without ``api_key``
203
+ keeps its stored key).
204
+ """
169
205
  return self._request("PATCH", f"/pods/{pod_id}", patch)["pod"]
170
206
 
171
207
  def delete_pod(self, pod_id: str) -> Dict[str, Any]:
@@ -405,6 +441,93 @@ class PodsClient:
405
441
  def get_backups(self, pod_id: str) -> Dict[str, Any]:
406
442
  return self._request("GET", f"/pods/{pod_id}/backups")["backups"]
407
443
 
444
+
445
+ # ── sandbox: commands, files, ports, clone ─────────────────────────────────────────
446
+ #
447
+ # Owner only: an API key with the ``pods:control:write`` scope (or a signed-in session).
448
+ # A pod's own key cannot use these, so an agent cannot get a shell on itself. The pod must
449
+ # be online; right after it first comes online the sandbox may answer 409 for about a minute.
450
+
451
+ def exec(self, pod_id: str, command: str, timeout_seconds: Optional[int] = None) -> Dict[str, Any]:
452
+ """Run a shell command in the pod's workspace as the unprivileged ``pod`` user.
453
+
454
+ ``timeout_seconds`` is 1 to 300 (default 60). Returns ``exit_code``, ``timed_out``,
455
+ ``duration_ms``, ``stdout``, ``stderr``, ``truncated`` (a stream passed 1 MB) and ``cwd``.
456
+ """
457
+ body: Dict[str, Any] = {"command": command}
458
+ if timeout_seconds is not None:
459
+ body["timeout_seconds"] = timeout_seconds
460
+ return self._request("POST", f"/pods/{pod_id}/exec", body)["exec"]
461
+
462
+ def list_files(self, pod_id: str) -> Dict[str, Any]:
463
+ """List the files in the pod's workspace: ``{"files": [...], "root": ...}``."""
464
+ return self._request("GET", f"/pods/{pod_id}/files")
465
+
466
+ def read_file(self, pod_id: str, path: str) -> Dict[str, Any]:
467
+ """Read one file: ``{"path", "content", "modified", "managed"}``."""
468
+ return self._request("GET", f"/pods/{pod_id}/files?path={quote(path, safe='')}")["file"]
469
+
470
+ def write_file(self, pod_id: str, path: str, content: str) -> Dict[str, Any]:
471
+ """Create or replace a text file in the pod."""
472
+ return self._request("PUT", f"/pods/{pod_id}/files", {"path": path, "content": content})["file"]
473
+
474
+ def open_port(self, pod_id: str, port: int, visibility: str = "public") -> Dict[str, Any]:
475
+ """Give a port on the pod a URL. Returns ``{"port": {...}, "rotated": bool}``.
476
+
477
+ The URL (and, for ``private`` ports, the token and the header to send it in) are
478
+ returned ONCE; opening the same port again rotates them. Ports below 1024 and the
479
+ ports the platform uses on the pod are refused. At most 5 open at a time.
480
+ """
481
+ return self._request("POST", f"/pods/{pod_id}/ports", {"port": port, "visibility": visibility})
482
+
483
+ def list_ports(self, pod_id: str) -> Dict[str, Any]:
484
+ """The pod's open ports (never their URLs or tokens) and the limit."""
485
+ return self._request("GET", f"/pods/{pod_id}/ports")
486
+
487
+ def close_port(self, pod_id: str, port: int) -> Dict[str, Any]:
488
+ return self._request("DELETE", f"/pods/{pod_id}/ports/{int(port)}")
489
+
490
+ def clone_pod(
491
+ self,
492
+ source_pod_id: str,
493
+ passphrase: str,
494
+ *,
495
+ backup_id: Optional[str] = None,
496
+ name: Optional[str] = None,
497
+ term_hours: Optional[int] = None,
498
+ region: Optional[str] = None,
499
+ max_total_usd: Optional[float] = None,
500
+ channels: Optional[Dict[str, Any]] = None,
501
+ ai: Optional[Dict[str, Any]] = None,
502
+ external_ref: Optional[str] = None,
503
+ idempotency_key: Optional[str] = None,
504
+ ) -> Dict[str, Any]:
505
+ """Create a NEW pod from the source pod's Agent Vault backup.
506
+
507
+ Billed exactly like :meth:`create_pod` and idempotent the same way (a key is
508
+ generated if you do not pass one). ``passphrase`` is your Vault backup passphrase.
509
+ Channel tokens and BYOK keys are never copied: pass ``channels`` and, for a source
510
+ on your own key, ``ai``. Returns ``{"pod": {...}, "clone": {"source_pod_id",
511
+ "backup_id", "restore": {"status", "message"}}}``; follow the restore with
512
+ :meth:`clone_status` on the NEW pod's id.
513
+ """
514
+ body: Dict[str, Any] = {"passphrase": passphrase}
515
+ for key, value in (
516
+ ("backup_id", backup_id), ("name", name), ("term_hours", term_hours),
517
+ ("region", region), ("max_total_usd", max_total_usd), ("channels", channels),
518
+ ("ai", ai), ("external_ref", external_ref),
519
+ ):
520
+ if value is not None:
521
+ body[key] = value
522
+ return self._request(
523
+ "POST", f"/pods/{source_pod_id}/clone", body,
524
+ {"Idempotency-Key": idempotency_key or f"sdk-{uuid.uuid4()}"},
525
+ )
526
+
527
+ def clone_status(self, pod_id: str) -> Dict[str, Any]:
528
+ """The restore job of a pod that was created as a clone."""
529
+ return self._request("GET", f"/pods/{pod_id}/clone")["clone"]
530
+
408
531
  # ── events and webhooks ────────────────────────────────────────────────────────────
409
532
 
410
533
  def list_events(
@@ -0,0 +1,172 @@
1
+ """Anthropic Messages helpers and the pods Sandbox/clone/BYOK surface.
2
+
3
+ The transport is an httpx.MockTransport, so these pin the wire contract (path, method, headers,
4
+ body) and how errors and stream events come back. No network.
5
+ """
6
+
7
+ import json
8
+
9
+ import httpx
10
+ import pytest
11
+
12
+ from singularity_grid import ANTHROPIC_VERSION, GridClient, PodsClient
13
+ from singularity_grid.errors import SGLAPIError
14
+
15
+ POD = "11111111-2222-3333-4444-555555555555"
16
+
17
+
18
+ def _grid(handler, api_key="x402c_k"):
19
+ client = GridClient(api_key=api_key)
20
+ headers = dict(client._client.headers)
21
+ client._client.close()
22
+ client._client = httpx.Client(base_url="https://grid.test", headers=headers, transport=httpx.MockTransport(handler))
23
+ return client
24
+
25
+
26
+ def _pods(handler):
27
+ client = PodsClient(api_key="x402c_k", base_url="https://compute.test")
28
+ client._client.close()
29
+ client._client = httpx.Client(transport=httpx.MockTransport(handler))
30
+ return client
31
+
32
+
33
+ def test_messages_posts_with_key_and_version():
34
+ seen = {}
35
+
36
+ def handler(req):
37
+ seen["url"] = str(req.url)
38
+ seen["headers"] = req.headers
39
+ seen["body"] = json.loads(req.content)
40
+ return httpx.Response(200, json={"id": "m", "type": "message", "role": "assistant", "content": [{"type": "text", "text": "hi"}], "stop_reason": "end_turn", "usage": {"input_tokens": 3, "output_tokens": 1}})
41
+
42
+ out = _grid(handler).messages("qwen-2.5-32b", [{"role": "user", "content": "hello"}], max_tokens=16, system="be brief")
43
+ assert out["content"][0]["text"] == "hi"
44
+ assert seen["url"] == "https://grid.test/v1/messages"
45
+ assert seen["headers"]["anthropic-version"] == ANTHROPIC_VERSION
46
+ assert seen["headers"]["x-api-key"] == "x402c_k"
47
+ assert seen["body"] == {"model": "qwen-2.5-32b", "messages": [{"role": "user", "content": "hello"}], "max_tokens": 16, "system": "be brief"}
48
+
49
+
50
+ def test_messages_maps_402_and_reads_anthropic_errors():
51
+ c = _grid(lambda req: httpx.Response(402, json={"type": "error", "error": {"type": "billing_error", "message": "pay"}}), api_key=None)
52
+ with pytest.raises(SGLAPIError) as e:
53
+ c.messages("m", [], max_tokens=1)
54
+ assert e.value.status_code == 402 and "api_key" in str(e.value)
55
+ c = _grid(lambda req: httpx.Response(400, json={"type": "error", "error": {"type": "invalid_request_error", "message": "top_p is not supported"}}))
56
+ with pytest.raises(SGLAPIError, match="top_p is not supported"):
57
+ c.messages("m", [], max_tokens=1)
58
+
59
+
60
+ def test_messages_stream_yields_events_until_message_stop():
61
+ sse = (
62
+ 'event: message_start\ndata: {"type":"message_start","message":{"id":"m"}}\n\n'
63
+ 'event: ping\ndata: {"type":"ping"}\n\n'
64
+ 'event: content_block_delta\r\ndata: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hel"}}\r\n\r\n'
65
+ 'event: content_block_delta\ndata: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"lo"}}\n\n'
66
+ 'event: message_stop\ndata: {"type":"message_stop"}\n\n'
67
+ )
68
+ bodies = []
69
+
70
+ def handler(req):
71
+ bodies.append(json.loads(req.content))
72
+ return httpx.Response(200, headers={"content-type": "text/event-stream"}, content=sse.encode())
73
+
74
+ events = list(_grid(handler).messages_stream("m", [{"role": "user", "content": "x"}], max_tokens=8))
75
+ assert [e["type"] for e in events] == ["message_start", "ping", "content_block_delta", "content_block_delta", "message_stop"]
76
+ assert "".join(e["delta"]["text"] for e in events if e["type"] == "content_block_delta") == "Hello"
77
+ assert bodies[0]["stream"] is True
78
+
79
+
80
+ def test_messages_stream_raises_on_error_event():
81
+ sse = 'event: error\ndata: {"type":"error","error":{"type":"api_error","message":"node failed"}}\n\n'
82
+ c = _grid(lambda req: httpx.Response(200, headers={"content-type": "text/event-stream"}, content=sse.encode()))
83
+ with pytest.raises(SGLAPIError, match="node failed"):
84
+ list(c.messages_stream("m", [], max_tokens=8))
85
+
86
+
87
+ def test_count_tokens():
88
+ seen = {}
89
+
90
+ def handler(req):
91
+ seen["path"] = req.url.path
92
+ return httpx.Response(200, json={"input_tokens": 4})
93
+
94
+ assert _grid(handler).count_tokens("m", [{"role": "user", "content": "hello"}])["input_tokens"] == 4
95
+ assert seen["path"] == "/v1/messages/count_tokens"
96
+
97
+
98
+ def test_create_pod_sends_engine_and_byok_fallbacks():
99
+ seen = {}
100
+
101
+ def handler(req):
102
+ seen["body"] = json.loads(req.content)
103
+ seen["idem"] = req.headers.get("idempotency-key")
104
+ return httpx.Response(201, json={"pod": {"id": POD, "status": "provisioning"}})
105
+
106
+ ai = {"mode": "byok", "preset": "venice", "api_key": "vk", "managed_models": True,
107
+ "fallbacks": [{"preset": "openrouter", "model": "x/y", "api_key": "ok"}, {"preset": "singularity", "model": "z-ai/glm-5.3"}]}
108
+ _pods(handler).create_pod(engine="pipod", ai=ai)
109
+ assert seen["body"]["engine"] == "pipod"
110
+ assert seen["body"]["ai"]["fallbacks"][1]["preset"] == "singularity"
111
+ assert seen["idem"]
112
+
113
+
114
+ def test_sandbox_routes():
115
+ calls = []
116
+
117
+ def handler(req):
118
+ calls.append((req.method, str(req.url), json.loads(req.content) if req.content else None))
119
+ u = str(req.url)
120
+ if u.endswith("/exec"):
121
+ return httpx.Response(200, json={"exec": {"exit_code": 0, "timed_out": False, "stdout": "hi\n", "stderr": "", "truncated": False}})
122
+ if "/files?path=" in u:
123
+ return httpx.Response(200, json={"file": {"path": "a b.txt", "content": "x"}})
124
+ if u.endswith("/files") and req.method == "PUT":
125
+ return httpx.Response(200, json={"file": {"path": "a.txt", "size": 1}})
126
+ if u.endswith("/files"):
127
+ return httpx.Response(200, json={"files": [{"path": "a.txt"}], "root": "/opt/pod/workspace"})
128
+ if u.endswith("/ports") and req.method == "POST":
129
+ return httpx.Response(201, json={"port": {"port": 8080, "visibility": "private", "url": "https://u/", "token": "t"}, "rotated": False})
130
+ if u.endswith("/ports"):
131
+ return httpx.Response(200, json={"ports": [], "limit": 5})
132
+ if u.endswith("/ports/8080"):
133
+ return httpx.Response(200, json={"closed": True, "port": 8080})
134
+ return httpx.Response(404, json={"error": {"code": "not_found", "message": "nope"}})
135
+
136
+ c = _pods(handler)
137
+ assert c.exec(POD, "echo hi", timeout_seconds=5)["stdout"] == "hi\n"
138
+ assert calls[0] == ("POST", f"https://compute.test/pods/v1/pods/{POD}/exec", {"command": "echo hi", "timeout_seconds": 5})
139
+ assert c.list_files(POD)["root"] == "/opt/pod/workspace"
140
+ assert c.read_file(POD, "a b.txt")["content"] == "x"
141
+ assert calls[2][1].endswith("path=a%20b.txt")
142
+ assert c.write_file(POD, "a.txt", "x")["size"] == 1
143
+ assert calls[3][2] == {"path": "a.txt", "content": "x"}
144
+ assert c.open_port(POD, 8080, "private")["port"]["token"] == "t"
145
+ assert calls[4][2] == {"port": 8080, "visibility": "private"}
146
+ assert c.list_ports(POD)["limit"] == 5
147
+ assert c.close_port(POD, 8080)["closed"] is True
148
+ assert calls[6][0] == "DELETE"
149
+
150
+
151
+ def test_sandbox_error_keeps_code():
152
+ c = _pods(lambda req: httpx.Response(403, json={"error": {"code": "forbidden", "message": "needs pods:control:write"}}))
153
+ with pytest.raises(SGLAPIError, match="pods:control:write") as e:
154
+ c.exec(POD, "ls")
155
+ assert e.value.body["code"] == "forbidden"
156
+
157
+
158
+ def test_clone_pod_and_status():
159
+ seen = {}
160
+
161
+ def handler(req):
162
+ if req.method == "POST":
163
+ seen["body"] = json.loads(req.content)
164
+ seen["idem"] = req.headers.get("idempotency-key")
165
+ return httpx.Response(201, json={"pod": {"id": "new"}, "clone": {"source_pod_id": POD, "backup_id": "b", "restore": {"status": "pending"}}})
166
+ return httpx.Response(200, json={"clone": {"status": "restored"}})
167
+
168
+ c = _pods(handler)
169
+ out = c.clone_pod(POD, "correct horse", name="copy", idempotency_key="clone-1")
170
+ assert out["clone"]["restore"]["status"] == "pending"
171
+ assert seen == {"body": {"passphrase": "correct horse", "name": "copy"}, "idem": "clone-1"}
172
+ assert c.clone_status("new")["status"] == "restored"