wandelbotsgmbh/wandelbots-nova / .agents/skills/nova-api-v2
nova-api-v2
VerifiedAuthoritative reference for working with the released Wandelbots NOVA API v2 in the wandelbots-nova Python SDK. Use whenever a task touches the NOVA API, the generated `wandelbots_api_client` models (`nova.api.models.*`), motion planning requests (`plan_trajectory`, `MotionGroupSetup`, `LimitSet`, `LimitsOverride`), robot limits, or torque/velocity/acceleration/jerk limits. Reach for this skill before guessing field names or assuming a field exists — the installed client reflects the RELEASED API, while nightly specs may contain unreleased fields. Especially relevant for controller-reported limits (e.g. KUKA torque) and any "does field X exist / how is it forwarded to the planner?" question.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.0 KB |
SKILL.md
View on GitHub---
name: nova-api-v2
description: >-
Authoritative reference for working with the released Wandelbots NOVA API v2 in the
wandelbots-nova Python SDK. Use whenever a task touches the NOVA API, the generated
`wandelbots_api_client` models (`nova.api.models.*`), motion planning requests
(`plan_trajectory`, `MotionGroupSetup`, `LimitSet`, `LimitsOverride`), robot limits, or
torque/velocity/acceleration/jerk limits. Reach for this skill before guessing field names
or assuming a field exists — the installed client reflects the RELEASED API, while nightly
specs may contain unreleased fields. Especially relevant for controller-reported limits
(e.g. KUKA torque) and any "does field X exist / how is it forwarded to the planner?" question.
---
# NOVA API v2
Domain knowledge for the **released** Wandelbots NOVA API v2 as used by the `wandelbots-nova`
SDK. The goal is to keep you from guessing field names or inventing fields that only exist in
unreleased/nightly specs.
## Source of truth (in priority order)
1. **The installed client** `wandelbots_api_client` (pinned in `pyproject.toml`, e.g.
`wandelbots_api_client~=26.4.0`). `nova.api` lazily re-exports
`wandelbots_api_client.v2_pydantic`; all models live in a single generated file
`wandelbots_api_client/v2_pydantic/models/models.py`. This matches the released API exactly.
2. **Docs UI:** https://portal.wandelbots.io/docs/api/v2/ui/ — base URL `/api/v2`. Shows the
API version (e.g. `v2.4.0`).
Prefer the installed models over any nightly/internal spec. A nightly spec may advertise fields
that are **not yet released** and therefore are not in the client the SDK ships with.
### How to verify a field exists (do this instead of guessing)
```bash
# Confirm versions
./.venv/bin/python -c "import wandelbots_api_client as c; print(c.__version__)"
# Inspect a model's fields directly
./.venv/bin/python -c "from nova import api; print(api.models.JointLimits.model_fields.keys())"
```
You can also grep the generated models file:
```bash
grep -n "^class JointLimits" .venv/lib/python*/site-packages/wandelbots_api_client/v2_pydantic/models/models.py
```
If a field is not in the installed model, treat it as **not available** in the released API,
regardless of what a spec or ticket claims.
## Limits & torque (motion planning)
This is the most common source of confusion. The released v2 API distinguishes **global**
motion-group limits from **per-segment** limit overrides, and they do NOT carry the same fields.
- The controller reports limits in `MotionGroupDescription.operation_limits`
(`auto_limits` / `manual_limits` / `manual_t1_limits` / `manual_t2_limits`), each a `LimitSet`.
- Per-joint limits live in `LimitSet.joints[i]` (`JointLimits`):
`position`, `velocity`, `acceleration`, `jerk`, `torque`.
- **`torque` is a global per-joint limit only.** There is no per-segment torque field.
- `MotionGroupSetup.global_limits` (sent to `plan_trajectory`) is built from `auto_limits` in
`nova/utils/collision_setup.py::motion_group_setup_from_motion_group_description`. So any
controller-reported `joints[i].torque` (e.g. from a KUKA controller) is **already forwarded to
the planner unchanged** via `global_limits` — no SDK change is needed for forwarding.
- Per-segment `MotionCommand.limits_override` (`LimitsOverride`) has **no torque field** — only
velocity / acceleration / jerk for joints and TCP. Therefore torque **cannot be overridden per
motion**; it is exclusively a motion-group-global limit.
### Consequence for `MotionSettings`
`nova.types.motion_settings.MotionSettings` is **per-motion**. Because the API only supports
torque as a global limit, exposing a per-motion torque setting would be a footgun: it could only
take effect on the collision-free planning path (which folds settings into
`global_limits` via `update_motion_group_setup_with_motion_settings`) and would be **silently
ignored on the standard collision-checked path** (which uses `LimitsOverride`). Do not add
per-motion torque unless the released API gains a per-segment torque field.
## Planning data flow (where to look)
- Setup is built in `nova/utils/collision_setup.py::motion_group_setup_from_motion_group_description`.
- Collision-checked planning: `MotionGroup._plan_with_collision_check` → `plan_trajectory`
(uses `LimitsOverride` per `MotionCommand`, plus `global_limits`).
- Collision-free planning: `MotionGroup._plan_collision_free` → `plan_collision_free`
(folds `MotionSettings` into `global_limits`, not via `LimitsOverride`).
- Per-segment overrides are capped to the global maxima before planning by
`nova/utils/motion_group_settings.py::clamp_motion_commands_to_global_limits` (this prevents the
planner from producing a trajectory the hardware down-scales at execution time).
## Verifying behavior with a quick experiment
When unsure whether a value survives setup-building and serialization, construct the models and
serialize the request rather than reasoning about it:
```python
from nova import api
from nova.utils.collision_setup import motion_group_setup_from_motion_group_description as build
desc = api.models.MotionGroupDescription(
motion_group_model=api.models.MotionGroupModel("UniversalRobots_UR5e"),
operation_limits=api.models.OperationLimits(
auto_limits=api.models.LimitSet(
joints=[api.models.JointLimits(velocity=3.0, acceleration=10.0, torque=150.0)],
tcp=api.models.CartesianLimits(velocity=250.0),
)
),
)
setup = build(desc)
print(setup.global_limits.joints[0].torque) # -> 150.0, i.e. forwarded
```
## Pitfalls
- Don't trust a ticket/spec that says a field exists until you've confirmed it in the installed
model. Released ≠ nightly.
- `global_limits` (request input) vs `operation_limits` (controller-reported description) are
different objects — the setup builder copies `auto_limits` into `global_limits`.
- Physical limit enforcement happens at execution time (the motion player time-scales the path);
the planner treats `limits_override` as a per-segment replacement, not a clamp.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |