singularity-grid
Python SDK for the SGL Network confidential compute grid. Submit inference jobs to TEE-verified nodes, check grid capacity, and use the OpenAI-compatible chat completions endpoint -- all from a single package.
Installation
pip install singularity-grid
To use the OpenAI compatibility helper:
pip install singularity-grid[openai]
Quick start
1. OpenAI-compatible usage (simplest)
The SGL Network orchestrator exposes an OpenAI-compatible /v1/chat/completions endpoint. You can use the standard openai package with no wrapper:
from openai import OpenAI
client = OpenAI(
base_url="https://grid.x402compute.cc/v1",
api_key="scg_your_api_key",
)
response = client.chat.completions.create(
model="gemma-4-26b",
messages=[{"role": "user", "content": "Hello"}],
)
print(response.choices[0].message.content)
2. Helper function
If you prefer not to copy the URL, use the built-in helper:
from singularity_grid import create_openai_client
client = create_openai_client(api_key="scg_your_api_key")
response = client.chat.completions.create(
model="gemma-4-26b",
messages=[{"role": "user", "content": "Hello"}],
)
print(response.choices[0].message.content)
3. GridClient (full grid features)
For grid-specific features like job submission, TEE attestation, capacity checks, and pricing:
from singularity_grid import GridClient
# Public endpoints -- no auth required
grid = GridClient()
capacity = grid.capacity()
models = grid.models()
pricing = grid.pricing()
print(f"Active nodes: {capacity.active_nodes}/{capacity.total_nodes}")
for m in models:
print(f" {m.id} -- {m.sgl_node_count} nodes")
# Authenticated endpoints
grid = GridClient(api_key="scg_your_api_key")
job = grid.submit_job(
model="gemma-4-26b",
input_payload={
"messages": [{"role": "user", "content": "Analyze this data"}]
},
submitter_wallet="0xYourWallet",
submitter_chain="base",
)
print(f"Job {job.job_id}: {job.status}")
# Retrieve result and attestation
result = grid.get_job(job.job_id)
attestation = grid.get_attestation(job.job_id)
print(f"TEE verified: {attestation.verified}")
4. System One (typed decisions)
System One models such as Laya return typed answers to your questions about a JSON state. They do not generate text. There are three answer types:
choicepicks one option fromcriteria.scoregives a numeric score against a list of criteria.noulgives a single string, number or boolean.
You pay for input tokens only. You must supply api_key, because the Python client uses credits
and does not sign x402 payments.
from singularity_grid import GridClient
grid = GridClient(api_key="scg_your_api_key")
grid.systemone.models() # GET /v1/models?type=systemone
res = grid.systemone.create(
model="convaiinnovations/laya", # the alias "laya" also works
state={"ticket": "I was charged twice this month"},
questions={
"route": {"type": "choice", "instructions": "Which queue?",
"criteria": {"billing": "Money problems", "tech": "Bugs"}},
"urgency": {"type": "score", "instructions": "How urgent is this?",
"criteria": ["The customer is blocked"]},
"lang": {"type": "noul", "instructions": "ISO language code of the ticket"},
},
tier="standard", # optional: "standard" | "confidential"
)
res.answers["route"].choice # "billing"
res.answers["urgency"].score # 0.7
res.answers["lang"].value # "en"
res.usage.cost_usd
Questions can also be SystemOneChoiceQuestion, SystemOneScoreQuestion or
SystemOneNoulQuestion models. create() also accepts task, lang and user.
- A 402 error of type
payment_requiredmeans that you did not supplyapi_key. - Other 402 errors keep the message from the server, for example
insufficient_creditsandpod_cap_reached. create()raisesSGLNotFoundErrorandmodels()returns[]while System One is off on the orchestrator.- The client does not seal the state. It goes to the orchestrator over TLS.
API reference
GridClient
| Method | Auth | Description |
|---|---|---|
capacity() |
No | Grid-wide capacity summary |
models() |
No | Available models with pricing and TEE info |
pricing() |
No | Pricing table for all models |
submit_job(model, input_payload, ...) |
Yes | Submit a compute job |
get_job(job_id) |
Yes | Get job status and result |
get_attestation(job_id) |
Yes | Get TEE attestation proof |
systemone.models() |
No | System One models (GET /v1/models?type=systemone) |
systemone.create(model, state, questions, ...) |
Yes | Typed System One answers (POST /v1/systemone) |
Exceptions
| Exception | When |
|---|---|
SGLError |
Base class for all SDK errors |
SGLAPIError |
Non-2xx response from the API |
SGLAuthError |
401 or 403 response |
SGLNotFoundError |
404 response |
SGLConnectionError |
Orchestrator unreachable or timeout |
Configuration
| Parameter | Default | Description |
|---|---|---|
api_key |
None |
Bearer token for authenticated endpoints |
base_url |
orchestrator URL | Override the orchestrator URL |
timeout |
60.0 |
Request timeout in seconds |
License
MIT
Processors
Processors are served by processors.x402compute.cc, not the grid, so they have their own client.
from singularity_grid import ProcessorsClient
p = ProcessorsClient(api_key=os.environ["SGL_API_KEY"])
p.catalogue() # public, no credential
p.list() # yours (processors:read)
p.deploy(manifest, code) # returns the invoke token ONCE
p.update("my-processor", code=code)
p.set_listing("my-processor", True)
p.run("my-processor", {"name": "world"}, invoke_token)
processors:writeis full control of processors owned by that key's wallet — delete and secrets included, the same as a Cloudflare API token. Mintprocessors:readif you want a credential that cannot change anything. Note that compute keys do not expire, there is no audit log, and delete is permanent: the code is wiped and the slug is burned forever.
run() takes the invoke token from deploy(), not the API key — the run route is the only one
with both a money path and an anonymous buyer lane, so it does not read a key as an ownership
claim. Buyers use run_with_payment() with an x402 header instead.
Upgrading from 0.8.x
The six processor methods on GridClient (deploy_processor, invoke_processor,
list_processors, get_processor, delete_processor, get_processor_logs) are removed, along
with the Processor* models. They pointed at /grid/processors, which has never existed — every
call returned 404 — and their models described an older design that was never shipped. Use
ProcessorsClient. Nothing else changed: chat, embeddings, jobs, models, capacity, pricing,
reserve and the vault are untouched.
Metadata
Release files for singularity-grid 0.10.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| singularity_grid-0.10.0.tar.gz | 37.8 kB | With provenance | Details for singularity_grid-0.10.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| singularity_grid-0.10.0-py3-none-any.whl | Python 3 | none | any | Details for singularity_grid-0.10.0-py3-none-any.whl |
Total release size: 74.9 kB
Release files / singularity_grid-0.10.0.tar.gz
| Download URL | singularity_grid-0.10.0.tar.gz |
|---|---|
| Size | 37.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b4f3fe57d7774fad7ddfe4ea0396a24af2b5e71c826108214709347213ea822e
|
|
BLAKE2b-256 checksum How to use checksums |
e31480d26dc53bf35894a3c66990185f96759e6b25794aa91da32e9f8a965935
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 23, 2026.
Transparency logRelease files / singularity_grid-0.10.0-py3-none-any.whl
| Download URL | singularity_grid-0.10.0-py3-none-any.whl |
|---|---|
| Size | 37.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
aba67bd53af3ba90e0fbffc737d041b1a78b0911f7d7e88299355e37eb9c7150
|
|
BLAKE2b-256 checksum How to use checksums |
ab79b525391724125451fc4b4fc08a07583113a1d7f1a6a31eb9eadc9cea5fd1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 23, 2026.
Transparency logSecurity for singularity-grid 0.10.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for singularity_grid-0.10.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 23, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.