nodus-sdk

Unified platform SDK for Nodus AI systems.

Single-package installation story for the Nodus ecosystem. Auto-wires available packages via create_runtime(**kwargs), provides 9 bridge modules for external integrations, and exposes a FastAPI control-plane router.

Status: v0.2.0 — published on PyPI.

create_runtime(auth=True) now requires a configured SECRET_KEY and raises without one — it used to attach nothing and report success. See CHANGELOG.md.

Install

pip install nodus-sdk                            # core only
pip install "nodus-sdk[agent,sql,fastapi]"       # agent + SQLAlchemy + FastAPI
pip install "nodus-sdk[full]"                    # everything

Quick start

from nodus_sdk import create_runtime

rt = create_runtime(memory=True, trace_id="req-001", timeout_ms=None)
result = rt.run_source('print("hello from sdk")')

create_runtime()

from nodus_sdk import create_runtime, NodusSDKRuntime

rt = create_runtime(
    memory=True,          # the runtime's own std:memory store; or pass a MemoryStore
    events=True,          # True = auto-configure; or pass EventBusConfig
    extensions=True,      # attach ExtensionRegistry
    auth=True,            # KeyRing from $SECRET_KEY; or pass your own ring
    observability=True,   # or pass service name string
    trace_id="tid-001",   # injected into every emitted event
    timeout_ms=None,      # None = unlimited (required for long-lived services)
    max_steps=None,
    # Confinement matches a bare NodusRuntime: the filesystem is jailed to the
    # working directory unless allowed_paths is given (None = no jail), and
    # subprocess / network / env are denied unless granted:
    allowed_paths=["/data"],
    allow_network=True,
    project_root=None,
)

rt.memory_store is the store the guest's memory_get / memory_put read and write — the same object create_nodus_router(rt)'s /memory/{key} routes use.

create_runtime returns a NodusSDKRuntime — a NodusRuntime subclass with fluent attach_* bridge methods. All capability kwargs accept True (default config) or a config/store object.

auth=True needs a configured SECRET_KEY

auth=True builds a nodus_auth.KeyRing from AuthSettings().SECRET_KEY, so set that environment variable to a random secret of at least 32 bytes (nodus_auth.generate_key() makes one). It raises rather than falling back, because the two obvious fallbacks are both worse than an error:

• a random secret per runtime would stop tokens verifying across a restart, across two runtimes in one process, and across the replicas of any real deployment — while passing every single-process test;
• nodus-auth's dev default SECRET_KEY is a published constant, so a ring built on it is forgeable by anyone who has read the package.

auth=my_key_ring skips all of that and uses the ring you pass. Requires nodus-auth>=0.2.0; 0.1.x signs through python-jose, which carries an unfixed critical advisory (CVE-2026-85394).

rt.auth_key_ring is the ring, and rt.event_bus the bus — both None if the matching optional package is not installed, in which case the bridge is not listed in rt.attached_bridges() either.

NodusSDKRuntime fluent API

from nodus_sdk import NodusSDKRuntime
from nodus_sdk.bridges.sql import SqlBridge
from nodus_sdk.bridges.webhook import WebhookBridge

rt = (
    NodusSDKRuntime(timeout_ms=None)
    .attach_sql(SqlBridge("postgresql://..."))
    .attach_webhook(WebhookBridge(secret="my-secret"))
)

All attach_* methods are idempotent and return self.

Bridges

Bridge return type note: Bridge host functions return Python maps (dicts), not Records. Use index access in .nd code: r["status"], not r.status.

FastAPI integration

from fastapi import FastAPI
from nodus_sdk import create_runtime
from nodus_sdk.bridges.api import create_nodus_router, NodusTraceMiddleware

rt = create_runtime(timeout_ms=None)
app = FastAPI()
app.add_middleware(NodusTraceMiddleware, runtime=rt)
app.include_router(create_nodus_router(rt))
# Routes: POST /run, GET /health, GET /syscalls, GET|POST|DELETE /memory/{key}

detect_available()

from nodus_sdk import detect_available

avail = detect_available()
# {"memory": True, "extension": False, "events": True, ...}

Development

pip install -e ".[dev]"
PYTHONPATH="C:/dev/Coding Language/src" pytest tests/ -q

Tests require nodus-lang source on PYTHONPATH.

License

MIT — see LICENSE.