Metadata-Version: 2.4
Name: motrix-env-core
Version: 0.4.0
Summary: Backend-neutral framework APIs and runtime facilities for building reinforcement learning environments.
Keywords: reinforcement-learning,robotics,simulation,environment
Author: Motphys
Author-email: Motphys <developers@motphys.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Dist: array-api-compat==1.15.0
Requires-Dist: gymnasium==1.1.1
Requires-Dist: numpy>=1.26
Requires-Dist: omegaconf>=2.3,<2.4
Requires-Dist: typing-extensions>=4.1
Requires-Dist: motrix-env-core[numba,video] ; extra == 'all'
Requires-Dist: numba==0.61.2 ; extra == 'numba'
Requires-Dist: scipy==1.15.3 ; extra == 'numba'
Requires-Dist: tbb==2021.13.0 ; extra == 'tbb'
Requires-Dist: imageio>=2.30 ; extra == 'video'
Requires-Dist: imageio-ffmpeg>=0.5 ; extra == 'video'
Requires-Python: >=3.10, <3.14
Project-URL: Homepage, https://github.com/Motphys/MotrixLab
Project-URL: Repository, https://github.com/Motphys/MotrixLab
Project-URL: Issues, https://github.com/Motphys/MotrixLab/issues
Project-URL: Changelog, https://github.com/Motphys/MotrixLab/releases
Provides-Extra: all
Provides-Extra: numba
Provides-Extra: tbb
Provides-Extra: video
Description-Content-Type: text/markdown

# Motrix Environment Core

`motrix-env-core` provides the backend-neutral framework APIs used to build reinforcement learning
environments:

- environment base classes and configuration protocols;
- environment registry and registration decorators;
- backend-independent scene configuration and the simulator boundary (`motrix_env_core.sim`);
- NumPy environment runtime and rendering;
- framework-level math and reward utilities.

It intentionally contains no built-in tasks, robot models, meshes, textures, or motion data, and no
simulator: importing `motrix_env_core` never imports MotrixSim or MuJoCo. Install `motrix-envs` when
the built-in MotrixLab environments are required.

```python
from motrix_env_core import EnvCfg, SceneCfg, configclass, registry
```

## Environment discovery

Registry queries automatically discover installed environment providers through the
`motrix_env_core.envs` entry-point group. Each package supplies a registration callback that uses the
existing environment decorators; applications need no registration imports. Environment discovery
is independent of training and Hydra Task configuration.

The first query loads all installed providers, not just the provider for the requested Env ID.
Provider dependency and registration errors are reported to the caller.

See [Environment registration](../docs/source/en/user_guide/tutorial/building_envs/direct_env.md#environment-registration)
for the package declaration and registration example shared by direct and manager environments.

## Simulator backends

Simulator bindings live in their own distributions and register through the
`motrix_env.sim_backends` entry-point group:

- [`motrix-env-motrixsim`](../motrix_env_motrixsim) — the MotrixSim backend (live simulation,
  rendering, and the torch-tensor frontend); registered as the default simulator;
- [`motrix-env-mujoco`](../motrix_env_mujoco) — a compile-only MuJoCo backend that lowers
  `SceneCfg` into `mujoco.MjModel` (sim2sim, preview, conversion tools).

Installing a backend package registers it; the registry discovers entry points lazily on first use
and never imports a native simulator until a backend is actually constructed.

Compile-only consumers (viewers, converters, previews) import the backend's scene compiler directly,
for example `from motrix_env_mujoco.compiler import MuJoCoSceneCompiler`.

Requesting a backend whose package is not installed fails loudly with an installation hint, and the
other registered backends remain usable.
