SDK reference

# Client

Credentials, base URL, pooled HTTP transport: every other SDK object is reached through this synchronous entry point.

>>> nodus.Client(api_key=None, *, base_url=None, timeout=30.0, max_retries=2)

One client per process: the pooled transport amortizes TLS handshakes; per-request clients add one per submission. Thread-safe; the workload handles it returns are not.

A context manager: exit closes the transport, releasing pooled sockets; with-form for short-lived processes, module-level for long-lived services.

>>> import nodus
>>>
# Omitted arguments: read from environment.
>>> client = nodus.Client(
...     api_key="nk_live_…",
...     base_url="https://api.nodus.run",
...     timeout=30.0,
...     max_retries=2,
... )
>>> client.healthz()
{'status': 'ok'}
>>>
# Transport closes on exit.
>>> with nodus.Client() as client:
...     for wl in client.iter_workloads(page_size=100):
...         print(wl.id, wl.status, wl.spend_usd)

# Workload

The handle returned by client.run() and client.get(): one brief's lifecycle state, chosen route, spend, output.

Handles are mutable: refresh() and wait() update the instance in place and return it, so later reads cost nothing. Unsafe to share across threads or tasks; give each its own via client.get().

StageRun carries id, status, continuity_mode, completed_units, total_units, latest_manifest. Progress counts in units the stage defines; a reclaim resuming from the last manifest reads as work retained, not lost.

>>> import nodus
>>>
>>> with nodus.Client() as client:
...     wl = client.run(
...         model="7B fine-tune",
...         command=["python", "train.py", "--epochs", "3"],
...         peak_memory_gb=38,
...         expected_runtime_hours=6,
...         budget=180.00,
...         continuity="checkpointed",
...         interrupt_tolerance="high",
...         data_regions=["us"],
...     )
...     wl.wait(poll_seconds=5.0, timeout_seconds=8 * 3600)
...
...     print(wl.status, wl.succeeded)
...     print(wl.route.sku, wl.route.compute_class)
...     print(f"{wl.spend_usd:.2f} of {wl.budget_usd:.2f} budgeted")
WorkloadStatus.COMPLETED True
nodus:a100-40-us-east accelerator
164.20 of 180.00 budgeted

# Route

The placement decision, in the Nodus catalog alone: None through ACCEPTED and PLANNING, set from RESERVING on.

price_usd_hour × expected_hours plus expected recovery: expected_cost_usd can exceed the naive product. budget is checked against it, never against a plan that only fits if nothing goes wrong.

No supplier field anywhere in the API, Route and Workload included: the product contract. You get a catalog route and an outcome; Nodus picks and moves placement, accountable for deadline and budget.

# AsyncClient

nodus.AsyncClient mirrors Client with the same constructor arguments; run/get/list/cancel/healthz are coroutines, iter_workloads an async iterator, the client an async context manager.

Calls return an AsyncWorkload with the same attributes, types, and in-place mutation as Workload plus awaitable refresh()/wait()/events()/artifacts()/ledger()/cancel() and async for event in wl.stream_events(). wait() yields between polls; thousands of concurrent waits cost a task each, not a thread each.

import asyncio
import nodus


async def sweep(client, lr: float) -> nodus.AsyncWorkload:
    wl = await client.run(
        model=f"7B sweep lr={lr}",
        command=["python", "train.py", "--lr", str(lr)],
        peak_memory_gb=38,
        expected_runtime_hours=4,
        budget=120.00,
        continuity="checkpointed",
    )
    await wl.wait(poll_seconds=5.0)
    return wl


async def main() -> None:
    async with nodus.AsyncClient() as client:
        runs = await asyncio.gather(
            *(sweep(client, lr) for lr in (1e-5, 3e-5, 1e-4)),
        )
        for wl in runs:
            print(wl.id, wl.status, wl.route.sku, f"${wl.spend_usd:.2f}")


asyncio.run(main())

# Types

Enums compare equal to their wire strings, so wl.status == "running" needs no imports; enum fields accept strings too.

ContinuityMode is what must survive an interruption, the brief's most consequential field; it decides what recovery may do.

COMPLETED/FAILED/CANCELLED is exactly the terminal set, where is_terminal is true and wait() returns. Everything else can still change; never read RECOVERING as failure.

The SDK also exports brief models Requirements/Outcome/Continuity/Policy/StageSpec; pass kwargs to run() and never touch them, or construct directly for pre-call validation.

# Errors

One except nodus.NodusError catches everything the SDK raises, and nothing else: every error inherits it. Each carries request_id where the control plane returned one; quote it in support requests.

One distinction matters: can the condition change on its own? Time clears rate limits and capacity; asking for less clears budget caps; authentication and validation never clear.

import time
import nodus


def submit(client, brief: dict, attempts: int = 6) -> nodus.Workload:
    brief = dict(brief)
    for _ in range(attempts):
        try:
            return client.run(**brief)

        except nodus.AuthenticationError:
            raise

        except nodus.ValidationError as exc:
            raise RuntimeError(f"bad brief [{exc.code}] {exc.message}") from exc

        except nodus.RateLimitError as exc:
            time.sleep(exc.retry_after)

        except nodus.BudgetExceededError as exc:
            cap = exc.payload["monthly_spend_cap_usd"]
            spent = exc.payload["month_to_date_usd"]
            needed = exc.payload["estimated_cost_usd"]
            headroom = cap - spent
            if needed > headroom:
                raise
            brief["budget"] = headroom

        except nodus.CapacityUnavailableError:
            brief["interrupt_tolerance"] = "high"
            brief["continuity"] = "checkpointed"
            brief.pop("finish_by", None)
            time.sleep(30)

    raise RuntimeError("no feasible route after widening the brief")

# HTTP surface

The SDK is a thin client over this surface. Tenant-scoped throughout: another tenant’s workload id reads as absent, not forbidden. Submission rules: retries & idempotency.