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 APICopy Anchor Link

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 and construction keyword arguments. Import so101_nexus.mujoco or so101_nexus.warp to register the corresponding backend.
• 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 policyCopy Anchor Link

• Patch (the third version number): 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.

Before 1.0.0, minor releases can change the public API. For reproducible installations, pin an exact package version and lock its dependencies. The changelog records release changes.

Deprecation processCopy Anchor Link

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.

A name whose only safe behavior would be a breaking change, for example a path that executes remote code, may be removed immediately in a minor release. The removal is recorded in the changelog as breaking, with the replacement named.

Supported platformsCopy Anchor Link

The MuJoCo backend is stable. The MuJoCo Warp backend is experimental, and its API and physics can change between minor releases. Installation lists supported Python versions, operating systems, and GPU requirements.

DeterminismCopy Anchor Link

MuJoCo reset and rollout behavior is deterministic for a given seed on a fixed dependency set. Golden-value regression tests check reward and state-observation trajectories for every MuJoCo environment.

Warp GPU contact physics can produce different trajectories with identical seeds. See Training reproducibility for dataset revisions, deterministic Torch execution, and checkpoint limits.