Metadata-Version: 2.5
Name: wandelbots-nova
Version: 5.11.0a2026081400
Summary: Official Python SDK for the Wandelbots Nova
Author: Wandelbots GmbH
Author-email: Christoph Biering <christoph.biering@wandelbots.com>, Mahsum Demir <mahsum.demir@wandelbots.com>, Dirk Sonnemann <dirk.sonnemann@wandelbots.com>, Andreas Langenhagen <andreas.langenhagen@wandelbots.com>, Stefan Wagner <stefan.wagner@wandelbots.com>, André Kühnert <andre.kuhnert@wandelbots.com>
License-File: LICENSE
Requires-Python: <3.13,>=3.11
Requires-Dist: aiostream<0.7,>=0.6.4
Requires-Dist: anyio<5,>=4.8.0
Requires-Dist: asyncstdlib<4,>=3.13.0
Requires-Dist: asyncua<2,>=1.1.5
Requires-Dist: blinker>=1.9.0
Requires-Dist: docstring-parser>=0.16.0
Requires-Dist: exceptiongroup>=1.2.2
Requires-Dist: httpx<0.29,>=0.28.0
Requires-Dist: loguru<0.8,>=0.7.2
Requires-Dist: msgpack>=1.2.1
Requires-Dist: nats-py>=2.11.0
Requires-Dist: numpy>1.1.19
Requires-Dist: pillow>=12.3.0
Requires-Dist: pydantic<3,>=2.11.4
Requires-Dist: python-decouple~=3.8
Requires-Dist: python-statemachine==3.2.0
Requires-Dist: scipy<2,>=1.14.1
Requires-Dist: wandelbots-api-client==26.5.3
Requires-Dist: websockets<15,>=14.1.0
Provides-Extra: benchmark
Requires-Dist: apscheduler>=3.11.0; extra == 'benchmark'
Requires-Dist: pyyaml>5.3; extra == 'benchmark'
Requires-Dist: requests>=2.32.3; extra == 'benchmark'
Requires-Dist: rerun-sdk==0.34.0; extra == 'benchmark'
Requires-Dist: trimesh>=4.5.3; extra == 'benchmark'
Provides-Extra: nova-rerun-bridge
Requires-Dist: apscheduler>=3.11.0; extra == 'nova-rerun-bridge'
Requires-Dist: requests>=2.32.3; extra == 'nova-rerun-bridge'
Requires-Dist: rerun-sdk==0.34.0; extra == 'nova-rerun-bridge'
Requires-Dist: trimesh>=4.5.3; extra == 'nova-rerun-bridge'
Provides-Extra: novapolicy
Requires-Dist: aiortc>=1.14.0; extra == 'novapolicy'
Requires-Dist: msgpack<2,>=1.1.0; extra == 'novapolicy'
Requires-Dist: pillow>=10.0.0; extra == 'novapolicy'
Requires-Dist: pyzmq<27,>=26.0.0; extra == 'novapolicy'
Requires-Dist: requests>=2.33.1; extra == 'novapolicy'
Provides-Extra: novax
Requires-Dist: fastapi>=0.115.6; extra == 'novax'
Requires-Dist: python-decouple>=3.8; extra == 'novax'
Requires-Dist: uvicorn>=0.34.0; extra == 'novax'
Provides-Extra: wandelscript
Requires-Dist: aiostream<0.7,>=0.6.1; extra == 'wandelscript'
Requires-Dist: antlr4-python3-runtime==4.13.2; extra == 'wandelscript'
Requires-Dist: dotenv; extra == 'wandelscript'
Requires-Dist: geometricalgebra<0.2,>=0.1.3; extra == 'wandelscript'
Requires-Dist: numpy>=1.1.19; extra == 'wandelscript'
Requires-Dist: typer<0.20,>=0.12; extra == 'wandelscript'
Description-Content-Type: text/markdown

# wandelbots-nova (Python SDK)

[![PyPI version](https://badge.fury.io/py/wandelbots-nova.svg)](https://badge.fury.io/py/wandelbots-nova)
[![License](https://img.shields.io/github/license/wandelbotsgmbh/wandelbots-nova.svg)](https://github.com/wandelbotsgmbh/wandelbots-nova/blob/main/LICENSE)
[![Build status](https://github.com/wandelbotsgmbh/wandelbots-nova/actions/workflows/nova-release.yaml/badge.svg)](https://github.com/wandelbotsgmbh/wandelbots-nova/actions/workflows/nova-release.yaml)
[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/wandelbotsgmbh/wandelbots-nova)

> **📚 New to the SDK?** Explore the [DeepWiki documentation](https://deepwiki.com/wandelbotsgmbh/wandelbots-nova) for architecture guides and tutorials. You can also **chat with it** to get code examples, detailed explanations, and answers to your questions.

This library provides an SDK for the Wandelbots NOVA API.

The SDK will help you to build your own apps and services using Python on top of Wandelbots NOVA and makes programming a robot as easy as possible.

[417768496-f6157e4b-eea8-4b96-b302-1f3864ae44a9.webm](https://github.com/user-attachments/assets/ca7de6ba-c78d-414f-ae8f-f76d0890caf3)

## Table of Contents

- [wandelbots-nova (Python SDK)](#wandelbots-nova-python-sdk)
  - [Table of Contents](#table-of-contents)
  - [Overview](#overview)
  - [Prerequisites](#prerequisites)
  - [Quickstart](#quickstart)
  - [Installation](#installation)
    - [Install with pip](#install-with-pip)
    - [Install with uv and rerun visualization](#install-with-uv-and-rerun-visualization)
    - [Configure Environment Variables](#configure-environment-variables)
  - [Using the SDK](#using-the-sdk)
    - [API essentials](#api-essentials)
    - [Example gallery](#example-gallery)
  - [NOVAx](#novax)
    - [Registering programs](#registering-programs)
  - [Development](#development)
    - [Formatting](#formatting)
    - [Yaml linting](#yaml-linting)
    - [Branch versions for testing](#branch-versions-for-testing)
  - [Release process](#release-process)
    - [Branch behaviour overview](#branch-behaviour-overview)
    - [Stable releases from `main`](#stable-releases-from-main)
    - [LTS releases from `release/\*`](#lts-releases-from-release)
    - [Create a dev build (manual)](#create-a-dev-build-manual)
  - [Additional resources](#additional-resources)

## Overview

[Wandelbots NOVA OS](https://www.wandelbots.com/) is a robot-agnostic operating system that enables developers to plan, program, control, and operate fleets of six-axis industrial robots through a unified API, across all major robot brands. It integrates modern development tools like Python and JavaScript APIs with AI-based control and motion planning, allowing developers to build automation tasks such as gluing, grinding, welding, and palletizing without needing to account for hardware differences. The software offers a powerful set of tools that support the creation of custom automation solutions throughout the entire automation lifecycle.

## Prerequisites

- A running NOVA instance (Get a Wandelbots NOVA account on [wandelbots.com](https://www.wandelbots.com/contact))
- Valid NOVA API credentials
- Python >=3.11

## Quickstart

1. Install the SDK using `pip` or set up a local `uv` project with extras for visualization. Refer to the [Installation](#installation) section for both options.
2. Copy `.env.template` to `.env` and fill in the base URL and access token for your NOVA deployment. Details are covered in [Configure environment variables](#configure-environment-variables).
3. Run an example to validate the setup, e.g. `uv run python examples/start_here.py`. Install the rerun extras and execute `uv run download-models` if you want interactive 3D visualization out of the box.

## Installation

### Install with pip

Install the library using pip:

```bash
pip install wandelbots-nova
```

### Install with uv and rerun visualization

Install [uv](https://docs.astral.sh/uv/getting-started/installation/) on your system.

Initialize a new uv project with the following command.

```bash
uv init
```

Install the library with the `nova-rerun-bridge` extra to use the visualization tool [rerun](https://rerun.io/).
See [extension README.md](nova_rerun_bridge/README.md) for further details.

```bash
uv add wandelbots-nova --extra nova-rerun-bridge
```

Download the robot models to visualize them in the rerun viewer.

```bash
uv run download-models
```

### Configure Environment Variables

Copy the provided `.env.template` file and rename it to `.env`:

```bash
cp .env.template .env
```

Open the `.env` file in a text editor and fill in the values. Here's what each variable does:

| Variable            | Description                                                                      | Required | Default | Example                                          |
| ------------------- | -------------------------------------------------------------------------------- | -------- | ------- | ------------------------------------------------ |
| `NOVA_API`          | Base URL or hostname of the Wandelbots NOVA server instance                      | Yes      | None    | `https://nova.example.com` or `http://172.0.0.1` |
| `NOVA_ACCESS_TOKEN` | Pre-obtained access token for Wandelbots NOVA (cloud or self-hosted deployments) | Yes\*    | None    | `eyJhbGciOi...`                                  |

> **Note:**
>
> - `NOVA_API` is mandatory in every deployment. Always point it to the NOVA base URL you are targeting.
> - `NOVA_ACCESS_TOKEN` is the supported authentication mechanism. It is mandatory for the Wandelbots Cloud environment; for self-hosted deployments generate and supply a token with the required permissions.
> - Username/password authentication (`NOVA_USERNAME`/`NOVA_PASSWORD`) is deprecated and no longer supported.

## Using the SDK

### API essentials

Import the library in your code to get started.

```python
from nova import Nova
```

You can access the automatically generated NOVA API client using the `api` module.

```python
from nova import api
```

### Example gallery

Curated examples in this repository showcase typical SDK workflows:

1. **Basic usage**: [start_here.py](https://github.com/wandelbotsgmbh/wandelbots-nova/tree/main/examples/start_here.py)
2. **Robot movement and I/O control**: [plan_and_execute.py](https://github.com/wandelbotsgmbh/wandelbots-nova/tree/main/examples/plan_and_execute.py)
3. **Collision-free movement**: [collision_setup.py](https://github.com/wandelbotsgmbh/wandelbots-nova/tree/main/examples/collision_setup.py)

<img width="100%" alt="collision_free" src="https://github.com/user-attachments/assets/0416151f-1304-46e2-a4ab-485fcda766fc" />

4. **Multiple robot coordination**: [move_multiple_robots.py](https://github.com/wandelbotsgmbh/wandelbots-nova/tree/main/examples/move_multiple_robots.py)
5. **3D visualization with rerun**: [welding.py](https://github.com/wandelbotsgmbh/wandelbots-nova/tree/main/examples/welding.py)

> **Note**: Install [rerun extras](#install-with-uv-and-rerun-visualization) to enable visualization

<img width="1242" alt="pointcloud" src="https://github.com/user-attachments/assets/8e981f09-81ae-4e71-9851-42611f6b1843" />

6. **Custom TCPs (Tool Center Points)**: [visualize_tool.py](https://github.com/wandelbotsgmbh/wandelbots-nova/tree/main/examples/visualize_tool.py)

<img width="100%" alt="trajectory" src="https://github.com/user-attachments/assets/649de0b7-d90a-4095-ad51-d38d3ac2e716" />

7. **Custom mounting with multiple robots**: [robocore.py](https://github.com/wandelbotsgmbh/wandelbots-nova/tree/main/examples/robocore.py)

<img width="100%" alt="thumbnail" src="https://github.com/user-attachments/assets/6f0c441e-b133-4a3a-bf0e-0e947d3efad4" />

8. **Merge trajectories with blending**: [merge_trajectories.py](https://github.com/wandelbotsgmbh/wandelbots-nova/tree/main/examples/merge_trajectories.py)

9. **Kinematic configuration**: [kinematic_configuration.py](https://github.com/wandelbotsgmbh/wandelbots-nova/tree/main/examples/kinematic_configuration.py)

## NOVAx

NOVAx is an app framework for building server applications on top of Wandelbots NOVA.
It provides common core concepts like the handling of programs and their execution.

You can create a new NOVAx app using the [NOVA CLI](https://github.com/wandelbotsgmbh/nova-cli) generator:

```bash
nova app create "your-nova-app" -g python_app
```

For more information on using NOVAx see the [README](https://github.com/wandelbotsgmbh/wandelbots-nova/tree/main/examples/your-nova-app/README.md). Explore [this example](https://github.com/wandelbotsgmbh/wandelbots-nova/tree/main/examples/your-nova-app/app/register_programs.py) to use the NOVAx entry point.

> **Important:** A `@nova.program` function is registered once the module that defines it is imported. NOVAx handles this for you when you enable directory scanning via `programs_dir` — see [Registering programs](#registering-programs) below.

### Registering programs

Programs register themselves with a global registry when decorated with `@nova.program`, so NOVAx just needs the modules that define them to be imported. There are three ways to get them registered, and they can be combined:

- **Directory scanning:** when you pass `programs_dir`, NOVAx scans that directory and imports every `.py` file under it (recursively), so dropping a new file in is enough — no manual import needed. Files whose name starts with `_` (e.g. `__init__.py`) are skipped, and a missing directory is ignored. It is off by default; configure it via the constructor:

  ```python
  from nova import Novax

  Novax(app)  # no scanning (default)
  Novax(app, programs_dir="my_pkg/robot_programs")  # scan a directory
  Novax(app, programs_dir=None)  # explicit: no scanning
  ```

- **Plain import:** any program imported elsewhere (inside or outside `programs/`) is still registered.

  ```python
  import my_pkg.special_program  # noqa: F401  (registers on import)
  ```

- **Explicit:** `novax.register_module("my_pkg.programs")` imports a module/file and registers its programs on demand.

For local development you can serve everything from a short script without any FastAPI boilerplate:

```python
from nova import Novax

Novax(programs_dir="programs").serve(port=3000)  # scan ./programs and serve
```

## Development

To install development dependencies, run

```bash
uv sync --extra "nova-rerun-bridge"
```

### Formatting

```bash
uv run ruff format
uv run ruff check --select I --fix
```

### Yaml linting

```bash
docker run --rm -it -v $(pwd):/data cytopia/yamllint -d .yamllint .
```

### Branch versions for testing

When working with feature branches or forks, it can be helpful to test the library as a dependency in other projects before merging.
You can specify custom sources in your pyproject.toml to pull the library from a specific branch:

Using PEP 621-style table syntax:

```toml
wandelbots-nova = { git = "https://github.com/wandelbotsgmbh/wandelbots-nova.git", branch = "fix/http-prefix" }
```

Using PEP 508 direct URL syntax:

```toml
wandelbots-nova @ git+https://github.com/wandelbotsgmbh/wandelbots-nova.git@fix/http-prefix
```

## Release process

### Branch behaviour overview

| Branch      | Purpose                                                | Published to                           | Example version      |
| ----------- | ------------------------------------------------------ | -------------------------------------- | -------------------- |
| `main`      | Stable releases (semantic versioning vX.Y.Z)           | PyPI (`pip install wandelbots-nova`)   | `v1.13.0`            |
| `release/*` | LTS-releases, pre-releases or hotfixes for older lines | PyPI (labeled with release suffix)     | `v1.8.7-release-1.x` |
| any other   | Development builds                                     | GitHub actions (not published to PyPI) | `e4c8af0647839...`   |

### Stable releases from `main`

Releases are managed by [release-please](https://github.com/googleapis/release-please):

1. On every push to `main`, release-please opens/updates a **release PR** that bumps the version (derived from Conventional Commits) and updates the changelog.
2. Merging that release PR tags the release, then a source distribution and wheel are built and uploaded to PyPI.
3. A GitHub release is created with the release assets.

### LTS releases from `release/\*`

If you're on older major versions or under a special LTS contract:

1. Use (or create) a branch like `release/1.x`, `release/customer-foo`, etc.
2. Every commit to these branches triggers the release-branch build workflow, which publishes an alpha build to PyPI.
3. Versions include a date/commit suffix to prevent collisions, e.g. `v1.8.7.a2026072803`

### Create a dev build (manual)

Need a temporary test build? Use GitHub actions:

1. Go to the [actions tab](https://github.com/wandelbotsgmbh/wandelbots-nova/actions).
2. Find **Nova SDK: Build dev wheel** and click `Run workflow`.
3. Select a branch and trigger the job.
4. After completion, open the [Installation step](#installation) to copy the ready-to-use `pip install` command:

   ```bash
       pip install "wandelbots-nova @ git+https://github.com/wandelbotsgmbh/wandelbots-nova.git@<commit>"
   ```

Alternatively, trigger the same workflow from your terminal and wait for the
install string. This requires the authenticated [GitHub CLI](https://cli.github.com/)
(`gh auth login`) and a pushed feature branch (not `main` or `release/*`):

```bash
uv run dev-wheel
```

It dispatches the workflow for the current branch, watches the run to
completion, and prints the ready-to-use `pip install` command pinned to the
built commit.

## Additional resources

- [Examples](https://github.com/wandelbotsgmbh/wandelbots-nova/tree/main/examples) covering basic to advanced SDK scenarios
- [Technical wiki](https://deepwiki.com/wandelbotsgmbh/wandelbots-nova) with architecture notes and troubleshooting tips
- [Official documentation](https://docs.wandelbots.io/) for platform concepts and API guides
- [Code documentation](https://wandelbotsgmbh.github.io/wandelbots-nova/) generated from the latest SDK build
