singularity-grid 0.11.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.11.0 → singularity_grid-0.13.0}/PKG-INFO +149 -2
  2. {singularity_grid-0.11.0 → singularity_grid-0.13.0}/README.md +148 -1
  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.11.0 → singularity_grid-0.13.0}/pyproject.toml +1 -1
  6. {singularity_grid-0.11.0 → singularity_grid-0.13.0}/singularity_grid/__init__.py +52 -1
  7. {singularity_grid-0.11.0 → singularity_grid-0.13.0}/singularity_grid/client.py +430 -8
  8. {singularity_grid-0.11.0 → singularity_grid-0.13.0}/singularity_grid/e2e.py +72 -0
  9. {singularity_grid-0.11.0 → singularity_grid-0.13.0}/singularity_grid/errors.py +16 -0
  10. {singularity_grid-0.11.0 → singularity_grid-0.13.0}/singularity_grid/models.py +43 -0
  11. {singularity_grid-0.11.0 → singularity_grid-0.13.0}/singularity_grid/pods.py +125 -2
  12. singularity_grid-0.13.0/singularity_grid/transcriptions.py +432 -0
  13. singularity_grid-0.13.0/tests/test_messages_pods.py +172 -0
  14. singularity_grid-0.13.0/tests/test_transcriptions.py +554 -0
  15. {singularity_grid-0.11.0 → singularity_grid-0.13.0}/tests/typecheck_embeddings.py +7 -1
  16. {singularity_grid-0.11.0 → singularity_grid-0.13.0}/.github/workflows/publish.yml +0 -0
  17. {singularity_grid-0.11.0 → singularity_grid-0.13.0}/.gitignore +0 -0
  18. {singularity_grid-0.11.0 → singularity_grid-0.13.0}/LICENSE +0 -0
  19. {singularity_grid-0.11.0 → singularity_grid-0.13.0}/examples/check_capacity.py +0 -0
  20. {singularity_grid-0.11.0 → singularity_grid-0.13.0}/examples/multimodal_embeddings.py +0 -0
  21. {singularity_grid-0.11.0 → singularity_grid-0.13.0}/examples/openai_compatible.py +0 -0
  22. {singularity_grid-0.11.0 → singularity_grid-0.13.0}/examples/quickstart.py +0 -0
  23. {singularity_grid-0.11.0 → singularity_grid-0.13.0}/singularity_grid/embeddings.py +0 -0
  24. {singularity_grid-0.11.0 → singularity_grid-0.13.0}/singularity_grid/openai_compat.py +0 -0
  25. {singularity_grid-0.11.0 → singularity_grid-0.13.0}/singularity_grid/processors.py +0 -0
  26. {singularity_grid-0.11.0 → singularity_grid-0.13.0}/singularity_grid/py.typed +0 -0
  27. {singularity_grid-0.11.0 → singularity_grid-0.13.0}/singularity_grid/vault.py +0 -0
  28. {singularity_grid-0.11.0 → singularity_grid-0.13.0}/tests/test_embeddings.py +0 -0
  29. {singularity_grid-0.11.0 → singularity_grid-0.13.0}/tests/test_pod_webhook.py +0 -0
  30. {singularity_grid-0.11.0 → singularity_grid-0.13.0}/tests/test_processors.py +0 -0
  31. {singularity_grid-0.11.0 → singularity_grid-0.13.0}/tests/test_vault.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: singularity-grid
3
- Version: 0.11.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
@@ -167,7 +167,45 @@ seconds of audio, 32 seconds of video, and 20 MiB of decoded media per request.
167
167
  raises `EmbeddingInputError` with a stable `.code`. API failures raise `SGLAPIError`; its `.code`
168
168
  contains the server's stable error code when present.
169
169
 
170
- ### 5. System One / Laya
170
+ ### 5. Confidential transcription (private v1)
171
+
172
+ `transcribe_pcm` accepts one raw, headerless PCM utterance. Bytes must already be mono, 16 kHz,
173
+ signed 16-bit little-endian PCM. The SDK rejects empty, partial-sample, and over-60-second inputs
174
+ before network access, reserves an eligible node using metadata only, and seals the audio directly
175
+ to that node's verified X25519 key. It verifies the node signature before decrypting the result.
176
+
177
+ ```python
178
+ from singularity_grid import GridClient
179
+
180
+ grid = GridClient(api_key="x402c_your_api_key")
181
+ result = grid.transcribe_pcm_file("utterance.pcm", language="en") # or "auto"
182
+
183
+ print(result["text"])
184
+ print(result["segments"])
185
+ ```
186
+
187
+ Use `transcribe_pcm(pcm_bytes, ...)` when audio is already in memory. This private v1 route is
188
+ client-sealed JSON; it is not multipart, streaming, or OpenAI wire-compatible. It does not accept
189
+ WAV/MP3 containers or remote URLs. The route can remain unavailable while Grid transcription is
190
+ dark. A submit is never retried automatically because a timeout can leave paid settlement in an
191
+ ambiguous state; retain the logical `request_id` when reconciling a request.
192
+
193
+ Billable duration is exact `sample_count / 16000`, including fractional seconds. The pinned
194
+ rate is $0.0001 per audio second, with a $0.0001 minimum charge and rounding up to whole
195
+ micro-USDC. The SDK recomputes both quote and final charge; `job_id` must equal the original
196
+ request UUID. After a timeout or `outcome_unknown`, reconcile that UUID before any explicit retry.
197
+ The SDK does not sign x402 wallet payments; use API-key credits for this client.
198
+
199
+ Request IDs must be canonical lowercase UUIDv4 values; the SDK generates one when omitted.
200
+ Silent audio can return an empty transcript with no segments. Segment text has a combined
201
+ 64 KiB UTF-8 limit, and timestamp starts/ends must be nondecreasing, allowing at most 50 ms overlap.
202
+
203
+ The package exports the exact model commit and SHA-256, protocol, audio format, and limits.
204
+ Local input failures raise `TranscriptionInputError`. Substituted reservations, bad node key
205
+ bindings/signatures, unsupported envelopes, and result binding mismatches raise
206
+ `TranscriptionResponseError`. Neither exception includes audio or transcript data.
207
+
208
+ ### 6. System One / Laya
171
209
 
172
210
  Laya is served as a typed-decision model, not as chat completions.
173
211
 
@@ -200,6 +238,53 @@ decision = grid.system_one(
200
238
  print(decision["answers"])
201
239
  ```
202
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
+
203
288
  ## API reference
204
289
 
205
290
  ### GridClient
@@ -213,10 +298,15 @@ print(decision["answers"])
213
298
  | `pricing()` | No | Pricing table for all models |
214
299
  | `embeddings(model, input, ...)` | Yes | Typed text or ordered multimodal embeddings |
215
300
  | `embed(model, input, ...)` | Yes | Embedding vectors only, ordered like the input |
301
+ | `transcribe_pcm(pcm, ...)` | Yes | Validate, client-seal, and transcribe raw 16 kHz mono s16 PCM |
302
+ | `transcribe_pcm_file(path, ...)` | Yes | Bounded raw-PCM file helper |
216
303
  | `system_one(state, questions, ...)` | Yes | Call `/v1/systemone` for typed decisions |
217
304
  | `submit_job(model, input_payload, ...)` | Yes | Submit a compute job |
218
305
  | `get_job(job_id)` | Yes | Get job status and result |
219
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` |
220
310
 
221
311
  ### Exceptions
222
312
 
@@ -228,6 +318,8 @@ print(decision["answers"])
228
318
  | `SGLNotFoundError` | 404 response |
229
319
  | `SGLConnectionError` | Orchestrator unreachable or timeout |
230
320
  | `EmbeddingInputError` | Local media, input, dimension, or limit validation failure; inspect `.code` |
321
+ | `TranscriptionInputError` | Local PCM, language, request ID, or limit validation failure; inspect `.code` |
322
+ | `TranscriptionResponseError` | Reservation key binding, signed envelope, or result binding failed |
231
323
 
232
324
  ### Configuration
233
325
 
@@ -236,6 +328,8 @@ print(decision["answers"])
236
328
  | `api_key` | `None` | Bearer token for authenticated endpoints |
237
329
  | `base_url` | orchestrator URL | Override the orchestrator URL |
238
330
  | `timeout` | `60.0` | Request timeout in seconds |
331
+ | `transcription_timeout` | `120.0` | STT-only reserve/submit timeout in seconds |
332
+ | `transcription_canary_token` | `None` | Private token sent only to STT reserve/submit routes |
239
333
 
240
334
  ## License
241
335
 
@@ -275,3 +369,56 @@ with the `Processor*` models. They pointed at `/grid/processors`, which has neve
275
369
  call returned 404 — and their models described an older design that was never shipped. Use
276
370
  `ProcessorsClient`. Nothing else changed: chat, embeddings, jobs, models, capacity, pricing,
277
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`.
@@ -136,7 +136,45 @@ seconds of audio, 32 seconds of video, and 20 MiB of decoded media per request.
136
136
  raises `EmbeddingInputError` with a stable `.code`. API failures raise `SGLAPIError`; its `.code`
137
137
  contains the server's stable error code when present.
138
138
 
139
- ### 5. System One / Laya
139
+ ### 5. Confidential transcription (private v1)
140
+
141
+ `transcribe_pcm` accepts one raw, headerless PCM utterance. Bytes must already be mono, 16 kHz,
142
+ signed 16-bit little-endian PCM. The SDK rejects empty, partial-sample, and over-60-second inputs
143
+ before network access, reserves an eligible node using metadata only, and seals the audio directly
144
+ to that node's verified X25519 key. It verifies the node signature before decrypting the result.
145
+
146
+ ```python
147
+ from singularity_grid import GridClient
148
+
149
+ grid = GridClient(api_key="x402c_your_api_key")
150
+ result = grid.transcribe_pcm_file("utterance.pcm", language="en") # or "auto"
151
+
152
+ print(result["text"])
153
+ print(result["segments"])
154
+ ```
155
+
156
+ Use `transcribe_pcm(pcm_bytes, ...)` when audio is already in memory. This private v1 route is
157
+ client-sealed JSON; it is not multipart, streaming, or OpenAI wire-compatible. It does not accept
158
+ WAV/MP3 containers or remote URLs. The route can remain unavailable while Grid transcription is
159
+ dark. A submit is never retried automatically because a timeout can leave paid settlement in an
160
+ ambiguous state; retain the logical `request_id` when reconciling a request.
161
+
162
+ Billable duration is exact `sample_count / 16000`, including fractional seconds. The pinned
163
+ rate is $0.0001 per audio second, with a $0.0001 minimum charge and rounding up to whole
164
+ micro-USDC. The SDK recomputes both quote and final charge; `job_id` must equal the original
165
+ request UUID. After a timeout or `outcome_unknown`, reconcile that UUID before any explicit retry.
166
+ The SDK does not sign x402 wallet payments; use API-key credits for this client.
167
+
168
+ Request IDs must be canonical lowercase UUIDv4 values; the SDK generates one when omitted.
169
+ Silent audio can return an empty transcript with no segments. Segment text has a combined
170
+ 64 KiB UTF-8 limit, and timestamp starts/ends must be nondecreasing, allowing at most 50 ms overlap.
171
+
172
+ The package exports the exact model commit and SHA-256, protocol, audio format, and limits.
173
+ Local input failures raise `TranscriptionInputError`. Substituted reservations, bad node key
174
+ bindings/signatures, unsupported envelopes, and result binding mismatches raise
175
+ `TranscriptionResponseError`. Neither exception includes audio or transcript data.
176
+
177
+ ### 6. System One / Laya
140
178
 
141
179
  Laya is served as a typed-decision model, not as chat completions.
142
180
 
@@ -169,6 +207,53 @@ decision = grid.system_one(
169
207
  print(decision["answers"])
170
208
  ```
171
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
+
172
257
  ## API reference
173
258
 
174
259
  ### GridClient
@@ -182,10 +267,15 @@ print(decision["answers"])
182
267
  | `pricing()` | No | Pricing table for all models |
183
268
  | `embeddings(model, input, ...)` | Yes | Typed text or ordered multimodal embeddings |
184
269
  | `embed(model, input, ...)` | Yes | Embedding vectors only, ordered like the input |
270
+ | `transcribe_pcm(pcm, ...)` | Yes | Validate, client-seal, and transcribe raw 16 kHz mono s16 PCM |
271
+ | `transcribe_pcm_file(path, ...)` | Yes | Bounded raw-PCM file helper |
185
272
  | `system_one(state, questions, ...)` | Yes | Call `/v1/systemone` for typed decisions |
186
273
  | `submit_job(model, input_payload, ...)` | Yes | Submit a compute job |
187
274
  | `get_job(job_id)` | Yes | Get job status and result |
188
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` |
189
279
 
190
280
  ### Exceptions
191
281
 
@@ -197,6 +287,8 @@ print(decision["answers"])
197
287
  | `SGLNotFoundError` | 404 response |
198
288
  | `SGLConnectionError` | Orchestrator unreachable or timeout |
199
289
  | `EmbeddingInputError` | Local media, input, dimension, or limit validation failure; inspect `.code` |
290
+ | `TranscriptionInputError` | Local PCM, language, request ID, or limit validation failure; inspect `.code` |
291
+ | `TranscriptionResponseError` | Reservation key binding, signed envelope, or result binding failed |
200
292
 
201
293
  ### Configuration
202
294
 
@@ -205,6 +297,8 @@ print(decision["answers"])
205
297
  | `api_key` | `None` | Bearer token for authenticated endpoints |
206
298
  | `base_url` | orchestrator URL | Override the orchestrator URL |
207
299
  | `timeout` | `60.0` | Request timeout in seconds |
300
+ | `transcription_timeout` | `120.0` | STT-only reserve/submit timeout in seconds |
301
+ | `transcription_canary_token` | `None` | Private token sent only to STT reserve/submit routes |
208
302
 
209
303
  ## License
210
304
 
@@ -244,3 +338,56 @@ with the `Processor*` models. They pointed at `/grid/processors`, which has neve
244
338
  call returned 404 — and their models described an older design that was never shipped. Use
245
339
  `ProcessorsClient`. Nothing else changed: chat, embeddings, jobs, models, capacity, pricing,
246
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.11.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"
@@ -7,6 +7,8 @@ from .client import (
7
7
  )
8
8
  from .errors import (
9
9
  EmbeddingInputError,
10
+ TranscriptionInputError,
11
+ TranscriptionResponseError,
10
12
  SGLAPIError,
11
13
  SGLAuthError,
12
14
  SGLConnectionError,
@@ -49,6 +51,10 @@ from .models import (
49
51
  PricingResponse,
50
52
  TeeCapacity,
51
53
  MultimodalEmbeddingItem,
54
+ TranscriptionAttestation,
55
+ TranscriptionResponse,
56
+ TranscriptionSegment,
57
+ TranscriptionUsage,
52
58
  )
53
59
  from .embeddings import (
54
60
  EMBEDDINGGEMMA2_DIMENSIONS,
@@ -66,8 +72,28 @@ from .embeddings import (
66
72
  video_part,
67
73
  )
68
74
  from .openai_compat import create_openai_client
75
+ from .client import ANTHROPIC_VERSION
76
+ from .transcriptions import (
77
+ TRANSCRIPTION_AUDIO_FORMAT,
78
+ TRANSCRIPTION_BITS_PER_SAMPLE,
79
+ TRANSCRIPTION_CHANNELS,
80
+ TRANSCRIPTION_MAX_DURATION_SECONDS,
81
+ TRANSCRIPTION_MAX_PCM_BYTES,
82
+ TRANSCRIPTION_MAX_RESULT_ENVELOPE_BYTES,
83
+ TRANSCRIPTION_MAX_SAMPLES,
84
+ TRANSCRIPTION_MAX_SEGMENTS,
85
+ TRANSCRIPTION_MAX_TEXT_BYTES,
86
+ TRANSCRIPTION_RATE_USD_PER_SECOND,
87
+ TRANSCRIPTION_MINIMUM_CHARGE_USD,
88
+ TRANSCRIPTION_MODEL,
89
+ TRANSCRIPTION_MODEL_REVISION,
90
+ TRANSCRIPTION_MODEL_SHA256,
91
+ TRANSCRIPTION_PROTOCOL,
92
+ TRANSCRIPTION_SAMPLE_RATE,
93
+ validate_transcription_pcm,
94
+ )
69
95
 
70
- __version__ = "0.11.0"
96
+ __version__ = "0.13.0"
71
97
 
72
98
  __all__ = [
73
99
  # Processors — a SEPARATE client on processors.x402compute.cc. Until 0.9.0 these methods
@@ -80,6 +106,7 @@ __all__ = [
80
106
  "verify_pod_webhook",
81
107
  # Client
82
108
  "GridClient",
109
+ "ANTHROPIC_VERSION",
83
110
  "create_openai_client",
84
111
  "DEFAULT_BASE_URL",
85
112
  # Exceptions
@@ -89,6 +116,8 @@ __all__ = [
89
116
  "SGLConnectionError",
90
117
  "SGLNotFoundError",
91
118
  "EmbeddingInputError",
119
+ "TranscriptionInputError",
120
+ "TranscriptionResponseError",
92
121
  # EmbeddingGemma 2 constants + safe media/input helpers
93
122
  "EMBEDDINGGEMMA2_MODEL",
94
123
  "EMBEDDINGGEMMA2_DIMENSIONS",
@@ -103,6 +132,24 @@ __all__ = [
103
132
  "audio_part",
104
133
  "video_part",
105
134
  "multimodal_item",
135
+ # Transcription v1 constants + validation
136
+ "TRANSCRIPTION_MODEL",
137
+ "TRANSCRIPTION_MODEL_REVISION",
138
+ "TRANSCRIPTION_MODEL_SHA256",
139
+ "TRANSCRIPTION_PROTOCOL",
140
+ "TRANSCRIPTION_AUDIO_FORMAT",
141
+ "TRANSCRIPTION_SAMPLE_RATE",
142
+ "TRANSCRIPTION_CHANNELS",
143
+ "TRANSCRIPTION_BITS_PER_SAMPLE",
144
+ "TRANSCRIPTION_MAX_DURATION_SECONDS",
145
+ "TRANSCRIPTION_MAX_SAMPLES",
146
+ "TRANSCRIPTION_MAX_PCM_BYTES",
147
+ "TRANSCRIPTION_MAX_RESULT_ENVELOPE_BYTES",
148
+ "TRANSCRIPTION_MAX_TEXT_BYTES",
149
+ "TRANSCRIPTION_RATE_USD_PER_SECOND",
150
+ "TRANSCRIPTION_MINIMUM_CHARGE_USD",
151
+ "TRANSCRIPTION_MAX_SEGMENTS",
152
+ "validate_transcription_pcm",
106
153
  # Models — Grid
107
154
  "AttestationProof",
108
155
  "CapacityResponse",
@@ -134,5 +181,9 @@ __all__ = [
134
181
  "PricingInfo",
135
182
  "PricingResponse",
136
183
  "TeeCapacity",
184
+ "TranscriptionAttestation",
185
+ "TranscriptionResponse",
186
+ "TranscriptionSegment",
187
+ "TranscriptionUsage",
137
188
  ]
138
189
  from .vault import VaultClient, VaultError, encrypt_envelope, decrypt_envelope