Stability and versioning

SO101-Nexus follows Semantic Versioning. This page defines what "the API" means, what you can rely on, and how changes are communicated.

Public API

The public, supported surface is:

• Every name exported from the top-level package, so101_nexus.__all__ (configs, rewards, observation components, scene objects, asset helpers, and the LeRobot adapter helpers).
• The documented Gymnasium environment IDs registered by import so101_nexus.mujoco (MuJoCoTouch-v1, MuJoCoLookAt-v1, MuJoCoMove-v1, MuJoCoPickLift-v1, MuJoCoPickAndPlace-v1) and their documented gym.make keyword arguments.
• so101_nexus.__version__.

The following are internal and may change at any time without a major version bump:

• Any name prefixed with an underscore.
• Backend submodule internals (so101_nexus.mujoco.*, so101_nexus.warp.*) beyond environment registration and names re-exported from the top level.
• The so101_nexus.testing helpers and the teleoperation application internals.

Import public objects from so101_nexus, not from backend submodules.

Versioning policy

• Patch (0.4.x): bug fixes and additive, backward-compatible changes only.
• Minor (0.x.0): new features. While the project is pre-1.0, a minor release may include a documented breaking change to the public API.
• Major (x.0.0, from 1.0.0 onward): reserved for breaking changes to the public API.

Until 1.0.0 the public API is still stabilizing, so pin a version range (for example so101-nexus~=0.4) if you need reproducible behavior. Every change is recorded in the changelog.

Deprecation process

Before a public name or behavior is removed:

1. It is marked deprecated in the changelog and, where practical, raises a DeprecationWarning that names the replacement.
2. It is kept for at least one subsequent minor release.
3. It is removed only in a release whose version bump reflects the break.

Supported platforms

• Python: 3.12 and 3.13, verified in continuous integration.
• Operating systems: Linux and macOS are exercised in continuous integration for the MuJoCo backend.
• Backends: the MuJoCo backend is stable. The MuJoCo Warp backend (so101-nexus[warp]) is experimental; its API and physics may change between minor releases, and it requires an NVIDIA GPU with CUDA >= 12.4 for GPU execution.

Determinism

Reset and rollout behavior is deterministic for a given seed on a fixed dependency set. Golden-value regression tests pin the reward and state-observation trajectories of every MuJoCo environment, so a dependency upgrade that changes physics or reward output is caught before release rather than silently altering trained-policy behavior.