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.
- {singularity_grid-0.11.0 → singularity_grid-0.13.0}/PKG-INFO +149 -2
- {singularity_grid-0.11.0 → singularity_grid-0.13.0}/README.md +148 -1
- singularity_grid-0.13.0/examples/anthropic_messages.py +41 -0
- singularity_grid-0.13.0/examples/pods_sandbox.py +27 -0
- {singularity_grid-0.11.0 → singularity_grid-0.13.0}/pyproject.toml +1 -1
- {singularity_grid-0.11.0 → singularity_grid-0.13.0}/singularity_grid/__init__.py +52 -1
- {singularity_grid-0.11.0 → singularity_grid-0.13.0}/singularity_grid/client.py +430 -8
- {singularity_grid-0.11.0 → singularity_grid-0.13.0}/singularity_grid/e2e.py +72 -0
- {singularity_grid-0.11.0 → singularity_grid-0.13.0}/singularity_grid/errors.py +16 -0
- {singularity_grid-0.11.0 → singularity_grid-0.13.0}/singularity_grid/models.py +43 -0
- {singularity_grid-0.11.0 → singularity_grid-0.13.0}/singularity_grid/pods.py +125 -2
- singularity_grid-0.13.0/singularity_grid/transcriptions.py +432 -0
- singularity_grid-0.13.0/tests/test_messages_pods.py +172 -0
- singularity_grid-0.13.0/tests/test_transcriptions.py +554 -0
- {singularity_grid-0.11.0 → singularity_grid-0.13.0}/tests/typecheck_embeddings.py +7 -1
- {singularity_grid-0.11.0 → singularity_grid-0.13.0}/.github/workflows/publish.yml +0 -0
- {singularity_grid-0.11.0 → singularity_grid-0.13.0}/.gitignore +0 -0
- {singularity_grid-0.11.0 → singularity_grid-0.13.0}/LICENSE +0 -0
- {singularity_grid-0.11.0 → singularity_grid-0.13.0}/examples/check_capacity.py +0 -0
- {singularity_grid-0.11.0 → singularity_grid-0.13.0}/examples/multimodal_embeddings.py +0 -0
- {singularity_grid-0.11.0 → singularity_grid-0.13.0}/examples/openai_compatible.py +0 -0
- {singularity_grid-0.11.0 → singularity_grid-0.13.0}/examples/quickstart.py +0 -0
- {singularity_grid-0.11.0 → singularity_grid-0.13.0}/singularity_grid/embeddings.py +0 -0
- {singularity_grid-0.11.0 → singularity_grid-0.13.0}/singularity_grid/openai_compat.py +0 -0
- {singularity_grid-0.11.0 → singularity_grid-0.13.0}/singularity_grid/processors.py +0 -0
- {singularity_grid-0.11.0 → singularity_grid-0.13.0}/singularity_grid/py.typed +0 -0
- {singularity_grid-0.11.0 → singularity_grid-0.13.0}/singularity_grid/vault.py +0 -0
- {singularity_grid-0.11.0 → singularity_grid-0.13.0}/tests/test_embeddings.py +0 -0
- {singularity_grid-0.11.0 → singularity_grid-0.13.0}/tests/test_pod_webhook.py +0 -0
- {singularity_grid-0.11.0 → singularity_grid-0.13.0}/tests/test_processors.py +0 -0
- {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.
|
|
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.
|
|
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.
|
|
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.
|
|
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.
|
|
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
|