Metadata-Version: 2.5
Name: nodeshift-ai
Version: 0.1.1
Summary: Official Python client for the NodeShift AI API: chat completions and the Responses API with streaming and tool calls, files, projects, Agent Skills, prompts, agents, workflows and document recognition, with typed answers and errors.
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: chat-completions,llm,nodeshift,nodeshift-ai,openai-compatible,responses-api,sdk,workflows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: anyio<5,>=3.5
Requires-Dist: httpx<1,>=0.25
Provides-Extra: dev
Requires-Dist: mypy<2,>=1.10; extra == 'dev'
Requires-Dist: pytest-cov<8,>=5; extra == 'dev'
Requires-Dist: pytest<10,>=8; extra == 'dev'
Requires-Dist: ruff<1,>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# 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.

```sh
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:

```sh
export NSAI_BASE_URL="https://<your-nsai-host>/api/v1"
export NSAI_API_KEY="nsai_..."
```

```python
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:

```python
from nodeshift_ai import AsyncNodeShift

async with AsyncNodeShift() as client:
    completion = await client.chat.completions.create(model="gpt-4o", messages=messages)
```

## Streaming

```python
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

```python
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`](./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`):

```python
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:

```python
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.                          |

```python
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](https://semver.org). Changes are listed in [CHANGELOG.md](./CHANGELOG.md).

## License

Apache License 2.0. See the `LICENSE` file in this package.
