Skip to main content

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) or 503 (a model in maintenance, a server restarting) — is retried up to max_retries times (default 2), after the Retry-After the 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. A Retry-After longer than a minute (an exhausted token budget names its reset) is not waited out; the error is raised at once with retry_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 raises StreamInterruptedError with the partial answer and an APITimeoutError as its __cause__.
  • Per request: timeout, max_retries, extra_headers and extra_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 pass timeout; 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_headers and extra_headers cannot replace the Authorization header 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)

Source distribution for nodeshift-ai 0.1.1
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)

Table of built distributions (wheels) for nodeshift-ai 0.1.1
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page