Python SDK reference

Install the SDK with pip install nodus-compute and import it as nodus (Python 3.10 or newer). The pages below are generated from the package’s docstrings and type annotations.

nodus Nodus Python SDK (`pip install nodus-compute`).

nodus.agent Agents: durable runs on the journal engine (resources.md §4.1 to §4.3, ADR-048, ADR-101).

nodus.api Layer 1 of the SDK: the generic resource client over every kind (resources.md §10.3).

nodus.api.models Pydantic v2 models for every kind, generated from `api/openapi` by `make gen` (datamodel-code-generator).

nodus.app `App`: the group of Functions defined in one Python file (resources.md §3.9, ADR-047).

nodus.checkpoint The checkpoint handshake and gang checkpoints (resources.md §8, distributed-training.md §10.3).

nodus.cluster `nodus.cluster.info()`: the gang env contract of distributed-training.md §3.6, as one object.

nodus.envs Helpers for building your own Environment and datasets: `nodus.envs.split`.

nodus.errors Errors raised by the Nodus SDK.

nodus.examples Runnable examples that ship with the SDK: `python -m nodus.examples.rl` trains a model with RL.

nodus.examples.rl Reinforcement learning in one file: teach a small model to spell words backwards.

nodus.functions Functions, FunctionCalls and `@app.cls` classes (resources.md §3.10, §3.11, ADR-047, ADR-110).

nodus.image The Modal-shaped `Image` builder (resources.md §5.3).

nodus.integrations Framework callbacks that report training progress to Nodus from inside a container.

nodus.integrations.lightning `NodusCallback` for a Lightning `Trainer` (ADR-103).

nodus.integrations.transformers `NodusCallback` for the Hugging Face `Trainer` and every TRL trainer built on it (ADR-103).

nodus.job `Job`: a run-to-completion container with checkpoints, recovery and outputs (resources.md §3.1).

nodus.llm OpenAI- and Anthropic-compatible inference (resources.md §4.5, §4.6, ADR-049, ADR-100).

nodus.log Structured telemetry from inside a container: metrics, RL task outcomes, work units and phases.

nodus.outputs `nodus.outputs.verify()`: fail fast inside a Job when its model output would not load (resources.md §10.5).

nodus.process Processes and files inside a running Job, Sandbox or Workspace (resources.md §3.6).

nodus.recipes Training recipes: TrainingJob builders for fine-tuning, pretraining, distillation, preference training and RL.

nodus.recipes.finetune Fine-tuning, preference training, distillation and pretraining recipes on the catalog runtimes.

nodus.recipes.rl Reinforcement learning and evaluation on catalog Environments or your own.

nodus.runtime In-container helpers that speak nodusd's sockets (resources.md §8); each is a no-op outside Nodus.

nodus.sandbox `Sandbox`: an isolated long-running container driven by exec, files and tunnels (resources.md §3.5, ADR-044).

nodus.secret `Secret` references (resources.md §5.2). Values are write-only: nothing the API returns contains them.

nodus.sweep `Sweep`: one Job template run across a matrix of GPUs, regions and parameters (resources.md §3.3, ADR-051).

nodus.volume `Volume`: named storage with Modal's commit and reload semantics for `ReadWriteMany` (resources.md §5.1, ADR-091).

nodus.workspace `Workspace`: a development machine with SSH, VS Code, JupyterLab and a persistent home (resources.md §3.8).