NodeShift AI Python SDK
The official Python client for the NodeShift AI API: chat completions and the Responses API with streaming and tool calls, images, files, projects, Agent Skills, the prompt library, scheduled agents, workflows and document recognition, all with typed answers and typed errors — sync and async. It depends only on httpx and supports Python 3.9 and later.
pip install nodeshift-ai
Quickstart
Create an API key in NodeShift AI under Settings → API Keys, then point the client at your NodeShift AI host:
export NSAI_BASE_URL="https://<your-nsai-host>/api/v1"
export NSAI_API_KEY="nsai_..."
from nodeshift_ai import NodeShift
client = NodeShift() # reads NSAI_API_KEY and NSAI_BASE_URL
completion = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "What is an API key?"}],
)
print(completion.choices[0].message.content)
You can pass both settings instead: NodeShift(api_key=..., base_url=...). There is no default host — the client refuses to start without a base URL, so a key is never sent to a server you did not name.
client.models.list() returns the model ids your key can use. Matching ignores case and separators (Claude Opus 4.8 reaches claude-opus-4-8), and "auto" is listed when your organization has Auto mode on.
The async client has the same surface:
from nodeshift_ai import AsyncNodeShift
async with AsyncNodeShift() as client:
completion = await client.chat.completions.create(model="gpt-4o", messages=messages)
Streaming
with client.chat.completions.create(
model="gpt-4o",
stream=True,
stream_options={"include_usage": True},
messages=[{"role": "user", "content": "Write a haiku about the sea."}],
) as stream:
for chunk in stream:
if chunk.choices:
print(chunk.choices[0].delta.content or "", end="", flush=True)
completion = stream.final_completion() # whole message, finish reason, usage
A stream ends in one of three ways, and never silently:
| How it ended | What you get |
|---|---|
| The server finished the answer | The loop ends; final_completion() returns. |
| The server reported an error, or the stream stopped mid-answer (closed, broken, or silent past the timeout) | The loop raises APIError or StreamInterruptedError. error.partial_completion holds what arrived — it is incomplete. |
You stopped it: close(), leaving the with block, or break |
The connection is closed; final_completion() raises APIUserAbortError. |
A stream can be iterated once. Calling final_completion() without a loop reads the whole stream for you. Use with (or async with) so the connection is closed however the block ends. With the async client this matters more: breaking out of async for alone closes the connection only when the event loop finalizes the stream, so leave it with async with or await stream.aclose(). A close() / aclose() from another thread or task makes a loop still reading the stream raise APIUserAbortError.
Tool calling
import json
completion = client.chat.completions.create(
model="gpt-4o",
messages=messages,
tools=[
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Current temperature in a city.",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
},
},
}
],
)
for call in completion.choices[0].message.tool_calls or []:
arguments = json.loads(call.function.arguments) # model output: validate it
# run your function, then send back {"role": "tool", "tool_call_id": call.id, "content": ...}
tool_choice takes "auto", "none", "required" or {"type": "function", "function": {"name": ...}}. A full loop is in examples/tools.py.
NodeShift fields
Besides the OpenAI-compatible fields, create() takes:
| Argument | Effect |
|---|---|
type="assistant" |
Route through a project: model is then the project's id from NodeShift AI. |
knowledge=False |
Skip the knowledge-base passages NodeShift AI otherwise adds for the model. |
skill_ids=[...] |
Load these Agent Skills (ids from GET /api/v1/skills) before the model answers. |
skills="auto" |
Let the model pick and load a matching skill itself. Not together with skill_ids. |
Images go in a user message as {"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}} — the API reads images from the request only, not from a remote URL. Documents go as {"type": "file", "file": {"file_id": ...}} or {"type": "file", "file": {"file_data": "data:application/pdf;base64,...", "filename": ...}}.
Everything the client covers
| Attribute | Methods | What for |
|---|---|---|
client.chat.completions |
create() |
Chat completions, whole or streamed. |
client.responses |
create() |
The Responses API, whole or as typed events, with function calls and code_interpreter. |
client.images |
generate() |
Images from a prompt. |
client.models |
list() |
The models the key can use. |
client.files |
create(), list(), list_all(), retrieve(), content(), delete() |
Upload a document once, then send its file_id. |
client.containers.files |
list(), retrieve(), content() |
The files code_interpreter wrote. |
client.assistants |
list(), list_all(), retrieve(), create(), update(), delete() |
Projects. |
client.skills |
list(), list_all(), retrieve() |
Agent Skills. |
client.prompts, client.prompt_folders |
list(), list_all() (prompts), retrieve(), create(), update(), delete() |
The prompt library. |
client.agents |
list(), list_all(); runs.create(), runs.retrieve(), runs.poll() |
Scheduled agents: start a run now and wait for its result. |
client.workflows |
list(), retrieve(), create(), update(), delete(); runs.create(), list(), retrieve(), poll(), approve(), reject() |
Workflows and their runs, approval gates included. |
client.doc_recognition.documents |
list(), list_all() |
Documents that document recognition completed. |
Every method takes keyword arguments with the API's own snake_case names. list_all() walks every page of a list for you, fetching the next page only when your loop gets there (with AsyncNodeShift, iterate it with async for):
for project in client.assistants.list_all(type="owned"):
print(project.id, project.name)
Runs and their callbacks
runs.poll() reads a run every two seconds until it ends, or, for a workflow, until it waits for approval. A workflow run can also call your server when it pauses or ends; check each delivery before you trust it:
import os
from nodeshift_ai import (
WorkflowRunStatus,
callback_signing_secret,
parse_callback_event,
verify_callback_signature,
)
workflow_id = "5b1c2d3e-4f50-4172-8394-a5b6c7d8e9f0"
started = client.workflows.runs.create(
workflow_id=workflow_id,
input={"lead_email": "jane@example.com"},
callback_url="https://hooks.example.com/nodeshift/runs",
)
run = client.workflows.runs.poll(
workflow_id=workflow_id, run_id=started.id, max_wait_seconds=600
)
if run.status == WorkflowRunStatus.AWAITING_APPROVAL:
client.workflows.runs.approve(workflow_id=workflow_id, run_id=started.id)
# On the server at callback_url, with the request body exactly as it arrived:
secret = callback_signing_secret(os.environ["NSAI_API_KEY"])
def handle_callback(raw_body: bytes, headers: dict[str, str]) -> None:
is_genuine = verify_callback_signature(
secret=secret,
body=raw_body,
timestamp=headers.get("X-NSAI-Timestamp"),
signature=headers.get("X-NSAI-Signature"),
)
if is_genuine:
event = parse_callback_event(raw_body)
print(event.type, event.data.status)
Errors
Every error the SDK raises is a NodeShiftError:
| Error | When |
|---|---|
APIError |
The API answered with an error. Read status_code, code, type, and for limits retry_after_seconds, error_code and token_budget. |
APIConnectionError |
No HTTP answer at all; code holds the socket error (ECONNREFUSED, …) when known. |
APITimeoutError |
The API sent nothing for longer than the timeout. |
APIUserAbortError |
You closed a stream before the end of the answer. |
StreamInterruptedError |
A stream stopped before the end of the answer; partial_completion has what arrived. |
ResponseInterruptedError |
A Responses stream stopped before response.completed or response.failed; partial_response has what arrived. |
from nodeshift_ai import APIError
try:
client.chat.completions.create(model="gpt-4o", messages=messages)
except APIError as error:
if error.status_code == 429:
print(f"Rate limited ({error.code}); retry in {error.retry_after_seconds}s")
Retries, timeouts and options
- Retries. A request the API refused before doing any work —
429(a rate, token budget or concurrency limit) or503(a model in maintenance, a server restarting) — is retried up tomax_retriestimes (default 2), after theRetry-Afterthe API sent or an exponential backoff. So is a connection the server never accepted. Nothing else is retried: a chat completion is not idempotent, and retrying after the server started generating would answer, and bill, the same request twice. ARetry-Afterlonger than a minute (an exhausted token budget names its reset) is not waited out; the error is raised at once withretry_after_seconds. - Timeouts.
timeout(seconds, default 600) is the longest the client waits for the API to send something: the response, or the next part of a streamed answer. An answer that keeps arriving is never cut however long it runs. A stream that goes silent mid-answer raisesStreamInterruptedErrorwith the partial answer and anAPITimeoutErroras its__cause__. - Per request:
timeout,max_retries,extra_headersandextra_body(fields this SDK version does not type yet). - Your own httpx client:
NodeShift(http_client=httpx.Client(...))for proxies, mTLS or custom transports. A client built with a timeout of its own keeps it unless you passtimeout; one left at httpx's default (five seconds) gets the SDK's ten minutes instead. Closing the NodeShift client leaves yours open.
Security
repr()of a client shows its base URL, never its key.default_headersandextra_headerscannot replace theAuthorizationheader the client sets from its key.
Versioning
The package follows semantic versioning. Changes are listed in CHANGELOG.md.
License
Apache License 2.0. See the LICENSE file in this package.
Metadata
Release files for nodeshift-ai 0.1.1
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 |
|---|---|---|---|---|
| nodeshift_ai-0.1.1.tar.gz | 62.2 kB | Without provenance | Details for nodeshift_ai-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| nodeshift_ai-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for nodeshift_ai-0.1.1-py3-none-any.whl |
Total release size: 133.9 kB
Release files / nodeshift_ai-0.1.1.tar.gz
| Download URL | nodeshift_ai-0.1.1.tar.gz |
|---|---|
| Size | 62.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c9c1b03703add29143e345b5ab8bd2d95b5d5cebd2613330750ae9cbdc88f345
|
|
BLAKE2b-256 checksum How to use checksums |
84164e54e6f2ea5997ccb1dd54b219acf09478ac2a953c9de9870b274c514ae5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / nodeshift_ai-0.1.1-py3-none-any.whl
| Download URL | nodeshift_ai-0.1.1-py3-none-any.whl |
|---|---|
| Size | 71.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
551fd2693c3e58f578bf2a2a7336919855c8700fa403aec9ad17e0b816e08f14
|
|
BLAKE2b-256 checksum How to use checksums |
182c73af3ee111c65e539f8fe259ba793edfb081bd1234082db40be802a1f1cd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Security for nodeshift-ai 0.1.1
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A 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.