---
title: Core Package
description: Public API surface of so101_nexus.
---

# Core Package

`so101_nexus` provides shared types, configuration classes, scene objects, observation components, asset helpers, and the environment registry. The MuJoCo backend lives under `so101_nexus.mujoco` and is registered by importing it.

```python
import so101_nexus
```

## Exports by Category

### Type Aliases

| Name | Definition |
|------|------------|
| `ColorName` | `Literal["red", "orange", "yellow", "green", "blue", "purple", "black", "white", "gray"]` |
| `ColorConfig` | `ColorName \| list[ColorName]` |
| `ControlMode` | `Literal["pd_joint_pos", "pd_joint_delta_pos", "pd_joint_target_delta_pos"]` |
| `ObsMode` | `Literal["state", "visual"]` |
| `MoveDirection` | `Literal["up", "down", "left", "right", "forward", "backward"]` |
| `YcbModelId` | Literal union of 10 YCB object IDs (see [Assets and Geometry](/docs/api/assets-and-geometry)) |

### Constants

| Name | Type | Description |
|------|------|-------------|
| `SO101_JOINT_NAMES` | `tuple[str, ...]` | Ordered joint names for the SO-101 arm |
| `DIRECTION_VECTORS` | `dict[MoveDirection, tuple]` | Maps direction names to unit vectors |
| `COLOR_MAP` | `dict[str, list[float]]` | Maps color names to RGBA values |
| `YCB_OBJECTS` | `dict[str, str]` | Maps YCB model IDs to human-readable names |
| `ROBOT_CAMERA_PRESETS` | `dict[str, RobotCameraPreset]` | Named camera mounting presets for SO-100 and SO-101 |
| `ASSETS_DIR` | `Path` | Root directory for bundled assets |
| `SO101_DIR` | `Path` | Asset directory for the SO-101 arm (URDF/XML retained for teleop calibration; the MuJoCo backend loads the menagerie MJCF) |

### Configuration Classes

All configuration classes have sensible defaults. See [Configuration Classes](/docs/api/configs) for full reference.

| Class | Purpose |
|-------|---------|
| `RenderConfig` | Render camera resolution (visualization only, not observations) |
| `RobotConfig` | Rest pose, grasp force threshold, velocity threshold |
| `RobotCameraPreset` | Named preset combining camera mounting parameters |
| `RewardConfig` | Reward component weights with a `compute()` method |
| `EnvironmentConfig` | Base environment parameters (spawn region, obs mode, episode length) |
| `PickConfig` | Extends `EnvironmentConfig` for pick/lift tasks |
| `PickAndPlaceConfig` | Extends `EnvironmentConfig` for pick-and-place tasks |
| `TouchConfig` | Extends PickConfig for touch-an-object tasks |
| `LookAtConfig` | Extends `EnvironmentConfig` for look-at tasks |
| `MoveConfig` | Extends `EnvironmentConfig` for directional move tasks |

### Observation Components

See [Observations](/docs/concepts/observations-and-camera-modes) for conceptual overview and [Configuration Classes](/docs/api/configs) for full parameter reference.

| Class | Type | Description |
|-------|------|-------------|
| `Observation` | Abstract base | Base class for all observation components |
| `JointPositions` | State (6-dim) | Current joint angles |
| `EndEffectorPose` | State (7-dim) | TCP position + quaternion orientation |
| `TargetOffset` | State (3-dim) | Vector from gripper to goal |
| `GazeDirection` | State (3-dim) | Unit vector toward target |
| `GraspState` | State (1-dim) | Binary grasp flag |
| `ObjectPose` | State (7-dim) | Object position + quaternion orientation |
| `ObjectOffset` | State (3-dim) | Vector from gripper to object |
| `TargetPosition` | State (3-dim) | Absolute goal position |
| `WristCamera` | Camera | RGB image from wrist-mounted camera |
| `OverheadCamera` | Camera | RGB image from stationary overhead camera |
| `CameraObservation` | Camera (abstract) | Base class for camera observation components (`WristCamera`, `OverheadCamera`) |

### Scene Objects

See [Scene Objects](/docs/api/objects) for full reference.

| Class | Description |
|-------|-------------|
| `SceneObject` | Abstract base for all scene objects |
| `CubeObject` | A colored cube with configurable size and mass |
| `YCBObject` | A YCB benchmark object loaded from mesh assets |
| `MeshObject` | A custom mesh object (MuJoCo only) |

### Functions

#### Color

| Function | Signature | Description |
|----------|-----------|-------------|
| `sample_color` | `(colors: ColorConfig, rng: Generator \| None = None) -> list[float]` | Resolve a ColorConfig to an RGBA list, sampling uniformly if given a list of colors |

#### Reward and observation helpers

| Function | Signature | Description |
|----------|-----------|-------------|
| `privileged_state_feature_names` | `(observations: Sequence[Observation] | None) -> list[str]` | Per-dimension names for the non-camera state observation vector |
| `reach_progress` | `(distance, *, scale) -> float \| ndarray \| tensor` | Tanh-shaped progress in [0, 1]: 1 at distance 0, decaying toward 0 |
| `orientation_progress` | `(cos_similarity) -> float \| ndarray \| tensor` | Maps cosine similarity in [-1, 1] to a reward in [0, 1] |
| `lift_progress` | `(height, *, scale, grasped) -> float \| ndarray \| tensor` | Tanh-shaped lift progress in [0, 1], zero unless grasped |
| `simple_reward` | `(*, progress, completion_bonus, success) -> float \| ndarray \| tensor` | Single-objective task reward; shaping fills [0, 1 - completion_bonus] via `progress` |
#### Asset Paths

| Function | Returns | Description |
|----------|---------|-------------|
| `get_so101_simulation_dir()` | `Path` | Path to SO-101 `SO101/` assets (URDF/XML, retained for teleop calibration) |
| `get_so101_mujoco_model_dir()` | `Path` | Directory of the vendored menagerie MJCF (loaded by the MuJoCo backend) |
| `get_so101_mujoco_model_path()` | `Path` | Path to the menagerie `so101.xml` (loaded by the MuJoCo backend) |

#### YCB Asset Management

See [Assets and Geometry](/docs/api/assets-and-geometry) for full reference.

| Function | Description |
|----------|-------------|
| `ensure_ycb_assets(model_id)` | Download and cache YCB assets, return cache path |
| `get_ycb_mesh_dir(model_id)` | Path to mesh directory for a YCB model |
| `get_ycb_collision_mesh(model_id)` | Path to `collision.obj` |
| `get_ycb_visual_mesh(model_id)` | Path to `visual.obj` |
| `get_mujoco_ycb_rest_pose(verts)` | Rest orientation and spawn height for MuJoCo |

#### Environment Registry

| Function | Description |
|----------|-------------|
| `all_registered_env_ids()` | Returns all registered Gymnasium environment IDs |

See [Environment Registry](/docs/api/environment-registry) for details on how registration works.

### Processor APIs

The optional `so101_nexus.processors` subpackage provides LeRobot-style action and observation processor steps and a Gym wrapper that emits LeRobot-shaped observations. It requires the `teleop` extra (`pip install so101-nexus[teleop]`). See [LeRobot Processors](/docs/api/lerobot-processors) for the full reference.
