nepher 0.1.0__tar.gz

nepher-0.1.0/LICENSE

@@ -0,0 +1,97 @@
+BUSINESS SOURCE LICENSE 1.1
+
+Parameters
+
+Licensor:                 Nepher AI
+Licensed Work:            EnvHub - Universal Isaac Lab Environments Platform
+                          (Nepher: Universal Isaac Lab Environments Platform)
+Change Date:              2030-02-07
+Change License:           Apache License, Version 2.0
+Additional Use Grant:     You may use the Licensed Work for the specific purposes
+                          detailed in the "Isaac Lab Ecosystem Grant" section below.
+
+-------------------------------------------------------------------------
+
+TERMS AND CONDITIONS
+
+1. Definitions
+
+"Licensor" means the copyright owner or entity authorized by the copyright
+owner that is granting the License.
+
+"Licensed Work" means the subject Software and related content governed by
+this License.
+
+"Change Date" means the date when the Licensed Work becomes available under
+the Change License.
+
+"Change License" means the Open Source license that the Licensed Work
+will revert to on the Change Date.
+
+"Production Environment" means any deployment of the Licensed Work where
+it is used for operational purposes, including but not limited to hosting
+environment platforms, providing environment management services, or operating
+environment distribution infrastructure.
+
+2. License Grant
+
+Subject to the terms of this License, the Licensor grants you a non-exclusive,
+worldwide, non-transferable, royalty-free license to copy, modify, create
+derivative works, and redistribute the Licensed Work.
+
+3. Limitations (The "Source Available" Restriction)
+
+The License Grant above is subject to the following strict limitations:
+
+(a) Production Use Restriction: You may NOT use the Licensed Work in a
+    Production Environment unless your use falls specifically under the
+    "Additional Use Grant" defined in the Parameters above or the
+    "Isaac Lab Ecosystem Grant" defined below.
+
+(b) Competitive Restriction: You may NOT use the Licensed Work, in whole or
+    in part, to establish, operate, or provide a competing environment
+    management platform, environment distribution service, or environment
+    marketplace that competes with the Licensor's EnvHub platform, nor may
+    you use the Licensed Work to create a competing environment discovery,
+    management, or distribution system.
+
+4. Isaac Lab Ecosystem Grant (The "Research and Development Exception")
+
+The Licensor hereby grants specific permission for the following uses:
+
+(a) Research and Development: You are permitted to use, copy, modify, and
+    run the Licensed Work for the purpose of research, development, and
+    testing of Isaac Lab environments, including but not limited to:
+    - Creating and managing Isaac Lab environments for personal or
+      organizational use
+    - Developing and testing environment configurations
+    - Contributing environments to the EnvHub platform
+    - Using the Licensed Work as a client to access the EnvHub platform
+
+(b) Integration: You are permitted to integrate the Licensed Work into
+    software applications that interface with the Licensor's EnvHub platform,
+    provided such software does not attempt to replicate the core platform
+    functionality for the purpose of launching a competing service.
+
+(c) Auditing: You are permitted to use the Licensed Work for the purpose of
+    security research, code auditing, and transparency verification.
+
+5. Change License Conversion
+
+On the Change Date, or the fourth anniversary of the first availability of
+the Licensed Work, whichever comes first, the Licensor grants you a license
+under the terms of the Change License (Apache License, Version 2.0).
+
+6. Disclaimer
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

nepher-0.1.0/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: nepher
+Version: 0.1.0
+Summary: Universal Isaac Lab Environments Platform
+Author: Nepher Contributors
+License: BUSL-1.1
+Project-URL: Homepage, https://github.com/nepher-ai/envhub
+Project-URL: Documentation, https://github.com/nepher-ai/envhub#readme
+Project-URL: Repository, https://github.com/nepher-ai/envhub
+Project-URL: Issues, https://github.com/nepher-ai/envhub/issues
+Keywords: isaac-lab,robotics,environments,simulation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: tomli>=2.0.0
+Requires-Dist: tomli-w>=1.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: click>=8.0.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Provides-Extra: keyring
+Requires-Dist: keyring>=23.0; extra == "keyring"
+Provides-Extra: isaaclab
+Requires-Dist: isaaclab; extra == "isaaclab"
+Dynamic: license-file
+
+# Nepher: Universal Isaac Lab Environments Platform
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-BUSL--1.1-blue.svg)](LICENSE)
+
+**Nepher** is a unified, category-agnostic Python package for managing Isaac Lab environments across all categories (navigation, manipulation, humanoid, locomotion, etc.). It provides a professional command-line interface and Python API for discovering, downloading, uploading, and managing environment bundles for Isaac Lab/Isaac Sim.
+
+## Why EnvHub is Needed
+
+Isaac Lab researchers and developers frequently need to work with diverse simulation environments across multiple categories (navigation, manipulation, humanoid, etc.). Managing these environments manually leads to several challenges:
+
+- **Fragmented Environment Management**: Without a centralized platform, environments are scattered across repositories, making discovery and sharing difficult
+- **Inconsistent Structure**: Different environment formats and structures make integration into research workflows cumbersome
+- **Limited Discoverability**: Researchers struggle to find and evaluate suitable environments for their tasks
+- **Version Control Issues**: Managing environment versions, dependencies, and updates becomes complex at scale
+- **Repetitive Setup**: Setting up environments requires manual downloads, configuration, and path management
+
+EnvHub addresses these challenges by providing a unified platform for environment discovery, management, and integration with Isaac Lab. It standardizes environment structures, enables easy sharing and collaboration, and simplifies the workflow from environment discovery to integration in research code.
+
+## What is an Environment?
+
+An **Environment** (or **env**) is a bundle containing one or more simulation scenes organized under a common theme or purpose. Each environment has:
+
+- **Unique Identifier**: An environment ID that uniquely identifies the bundle
+- **Category**: The type of environment (navigation, manipulation, humanoid, locomotion, etc.)
+- **Type**: Either `usd` (USD-based scenes) or `preset` (programmatically generated scenes)
+- **Metadata**: Description, version, author, and other metadata
+- **Scenes**: A collection of related scenes that share the same environment context
+
+Environments serve as containers that group related simulation scenes together, making it easier to organize, discover, and manage simulation assets.
+
+## What is a Scene?
+
+A **Scene** represents a single, specific simulation configuration within an environment. Each scene defines:
+
+- **Scene Identifier**: A unique name within the environment
+- **Type-Specific Configuration**: 
+  - For USD scenes: A USD file path plus optional occupancy maps and metadata
+  - For preset scenes: A Python configuration file that generates the scene programmatically
+- **Scene-Specific Settings**: Spawn areas, exclusion zones, waypoints, and other scene-specific parameters
+
+Scenes are the actual simulation configurations that get loaded into Isaac Lab for training or evaluation. A single environment can contain multiple scenes, allowing researchers to work with variations of similar environments.
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install nepher
+```
+
+### From Source
+
+Clone the repository and install in editable mode:
+
+```bash
+git clone https://github.com/nepher-ai/envhub.git
+cd envhub
+pip install -e .
+```
+
+#### Optional Dependencies
+
+Install with optional extras as needed:
+
+```bash
+# Development tools (pytest, black, ruff, mypy)
+pip install -e ".[dev]"
+
+# Keyring support for secure credential storage
+pip install -e ".[keyring]"
+
+# Isaac Lab integration
+pip install -e ".[isaaclab]"
+
+# All optional dependencies
+pip install -e ".[dev,keyring,isaaclab]"
+```
+
+## Environment and Scene Definitions
+
+### Environment Structure
+
+Environments are defined using a `manifest.yaml` file that describes the environment bundle:
+
+**Example: USD Environment**
+```yaml
+id: digital-twin-warehouse-v1
+type: usd
+version: 1.0.0
+description: Digital twin of a small warehouse environment for navigation training
+category: navigation
+
+scenes:
+  - scene_id: small_warehouse
+    description: Small warehouse digital twin with realistic layout and obstacles
+    usd: small_warehouse_digital_twin.usd
+    omap_image: digital_twin_omap/map.png
+    omap_meta: digital_twin_omap/map.yaml
+```
+
+**Example: Preset Environment**
+```yaml
+id: indoor-environments-v1
+type: preset
+version: 1.0.0
+description: Indoor navigation environments including hospital corridors and warehouse
+category: navigation
+
+preset_scenes:
+  - scene_id: hospital
+    description: Hospital corridor environment for indoor navigation
+    preset: hospital_preset.py
+  - scene_id: warehouse
+    description: Warehouse with shelves and bounding walls
+    preset: warehouse_preset.py
+```
+
+### Usage Example
+
+Here's how to load and use environments and scenes in your Isaac Lab code:
+
+```python
+from nepher import load_env, load_scene
+
+# Load an environment
+env = load_env("indoor-environments-v1", category="navigation")
+
+# List all scenes in the environment
+print("Available scenes:", [s.name for s in env.get_all_scenes()])
+# Output: Available scenes: ['hospital', 'warehouse']
+
+# Load a specific scene configuration
+scene_cfg = load_scene(env, scene="hospital", category="navigation")
+
+# Use the scene configuration in Isaac Lab
+from isaaclab.envs import ManagerBasedRLEnv
+# ... configure your environment with scene_cfg
+```
+
+**USD Scene in Isaac Sim**
+![USD Scene Example](assets/usd_example.png)
+
+**Preset Scene in Isaac Sim**
+![Preset Scene Example](assets/preset_example.png)
+
+## Quick Start
+
+```bash
+# Authenticate with your API key
+nepher login <api_key>
+
+# Check current authentication status
+nepher whoami
+
+# Logout and clear credentials
+nepher logout
+
+# List available environments
+nepher list --category navigation
+
+# List evaluation benchmarks (evaluators only - for tournaments)
+nepher list --eval-benchmarks
+
+# Download an environment
+nepher download <env_id> --category navigation
+
+# List cached environments
+nepher cache list
+
+# View an environment in Isaac Sim
+nepher view <env_id> --category navigation
+
+# View a specific scene
+nepher view <env_id> --category navigation --scene <scene_name>
+
+# Upload your own environment (contributors or evaluators only)
+nepher upload ./my-env --category manipulation --thumbnail ./thumbnail.png
+```
+
+## Features
+
+- **Universal Category Support**: Works with any environment category (navigation, manipulation, humanoid, locomotion, etc.)
+- **Professional CLI**: Intuitive command-line interface for all operations
+- **Seamless Integration**: Direct integration with `envhub-backend` API
+- **Flexible Configuration**: User-configurable cache directories and settings
+
+
+## License
+
+Business Source License 1.1 (BUSL-1.1) - see [LICENSE](LICENSE) for details.
+

nepher-0.1.0/README.md

@@ -0,0 +1,192 @@
+# Nepher: Universal Isaac Lab Environments Platform
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License](https://img.shields.io/badge/license-BUSL--1.1-blue.svg)](LICENSE)
+
+**Nepher** is a unified, category-agnostic Python package for managing Isaac Lab environments across all categories (navigation, manipulation, humanoid, locomotion, etc.). It provides a professional command-line interface and Python API for discovering, downloading, uploading, and managing environment bundles for Isaac Lab/Isaac Sim.
+
+## Why EnvHub is Needed
+
+Isaac Lab researchers and developers frequently need to work with diverse simulation environments across multiple categories (navigation, manipulation, humanoid, etc.). Managing these environments manually leads to several challenges:
+
+- **Fragmented Environment Management**: Without a centralized platform, environments are scattered across repositories, making discovery and sharing difficult
+- **Inconsistent Structure**: Different environment formats and structures make integration into research workflows cumbersome
+- **Limited Discoverability**: Researchers struggle to find and evaluate suitable environments for their tasks
+- **Version Control Issues**: Managing environment versions, dependencies, and updates becomes complex at scale
+- **Repetitive Setup**: Setting up environments requires manual downloads, configuration, and path management
+
+EnvHub addresses these challenges by providing a unified platform for environment discovery, management, and integration with Isaac Lab. It standardizes environment structures, enables easy sharing and collaboration, and simplifies the workflow from environment discovery to integration in research code.
+
+## What is an Environment?
+
+An **Environment** (or **env**) is a bundle containing one or more simulation scenes organized under a common theme or purpose. Each environment has:
+
+- **Unique Identifier**: An environment ID that uniquely identifies the bundle
+- **Category**: The type of environment (navigation, manipulation, humanoid, locomotion, etc.)
+- **Type**: Either `usd` (USD-based scenes) or `preset` (programmatically generated scenes)
+- **Metadata**: Description, version, author, and other metadata
+- **Scenes**: A collection of related scenes that share the same environment context
+
+Environments serve as containers that group related simulation scenes together, making it easier to organize, discover, and manage simulation assets.
+
+## What is a Scene?
+
+A **Scene** represents a single, specific simulation configuration within an environment. Each scene defines:
+
+- **Scene Identifier**: A unique name within the environment
+- **Type-Specific Configuration**: 
+  - For USD scenes: A USD file path plus optional occupancy maps and metadata
+  - For preset scenes: A Python configuration file that generates the scene programmatically
+- **Scene-Specific Settings**: Spawn areas, exclusion zones, waypoints, and other scene-specific parameters
+
+Scenes are the actual simulation configurations that get loaded into Isaac Lab for training or evaluation. A single environment can contain multiple scenes, allowing researchers to work with variations of similar environments.
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install nepher
+```
+
+### From Source
+
+Clone the repository and install in editable mode:
+
+```bash
+git clone https://github.com/nepher-ai/envhub.git
+cd envhub
+pip install -e .
+```
+
+#### Optional Dependencies
+
+Install with optional extras as needed:
+
+```bash
+# Development tools (pytest, black, ruff, mypy)
+pip install -e ".[dev]"
+
+# Keyring support for secure credential storage
+pip install -e ".[keyring]"
+
+# Isaac Lab integration
+pip install -e ".[isaaclab]"
+
+# All optional dependencies
+pip install -e ".[dev,keyring,isaaclab]"
+```
+
+## Environment and Scene Definitions
+
+### Environment Structure
+
+Environments are defined using a `manifest.yaml` file that describes the environment bundle:
+
+**Example: USD Environment**
+```yaml
+id: digital-twin-warehouse-v1
+type: usd
+version: 1.0.0
+description: Digital twin of a small warehouse environment for navigation training
+category: navigation
+
+scenes:
+  - scene_id: small_warehouse
+    description: Small warehouse digital twin with realistic layout and obstacles
+    usd: small_warehouse_digital_twin.usd
+    omap_image: digital_twin_omap/map.png
+    omap_meta: digital_twin_omap/map.yaml
+```
+
+**Example: Preset Environment**
+```yaml
+id: indoor-environments-v1
+type: preset
+version: 1.0.0
+description: Indoor navigation environments including hospital corridors and warehouse
+category: navigation
+
+preset_scenes:
+  - scene_id: hospital
+    description: Hospital corridor environment for indoor navigation
+    preset: hospital_preset.py
+  - scene_id: warehouse
+    description: Warehouse with shelves and bounding walls
+    preset: warehouse_preset.py
+```
+
+### Usage Example
+
+Here's how to load and use environments and scenes in your Isaac Lab code:
+
+```python
+from nepher import load_env, load_scene
+
+# Load an environment
+env = load_env("indoor-environments-v1", category="navigation")
+
+# List all scenes in the environment
+print("Available scenes:", [s.name for s in env.get_all_scenes()])
+# Output: Available scenes: ['hospital', 'warehouse']
+
+# Load a specific scene configuration
+scene_cfg = load_scene(env, scene="hospital", category="navigation")
+
+# Use the scene configuration in Isaac Lab
+from isaaclab.envs import ManagerBasedRLEnv
+# ... configure your environment with scene_cfg
+```
+
+**USD Scene in Isaac Sim**
+![USD Scene Example](assets/usd_example.png)
+
+**Preset Scene in Isaac Sim**
+![Preset Scene Example](assets/preset_example.png)
+
+## Quick Start
+
+```bash
+# Authenticate with your API key
+nepher login <api_key>
+
+# Check current authentication status
+nepher whoami
+
+# Logout and clear credentials
+nepher logout
+
+# List available environments
+nepher list --category navigation
+
+# List evaluation benchmarks (evaluators only - for tournaments)
+nepher list --eval-benchmarks
+
+# Download an environment
+nepher download <env_id> --category navigation
+
+# List cached environments
+nepher cache list
+
+# View an environment in Isaac Sim
+nepher view <env_id> --category navigation
+
+# View a specific scene
+nepher view <env_id> --category navigation --scene <scene_name>
+
+# Upload your own environment (contributors or evaluators only)
+nepher upload ./my-env --category manipulation --thumbnail ./thumbnail.png
+```
+
+## Features
+
+- **Universal Category Support**: Works with any environment category (navigation, manipulation, humanoid, locomotion, etc.)
+- **Professional CLI**: Intuitive command-line interface for all operations
+- **Seamless Integration**: Direct integration with `envhub-backend` API
+- **Flexible Configuration**: User-configurable cache directories and settings
+
+
+## License
+
+Business Source License 1.1 (BUSL-1.1) - see [LICENSE](LICENSE) for details.
+

nepher-0.1.0/nepher/__init__.py

@@ -0,0 +1,36 @@
+"""
+Nepher: Universal Isaac Lab Environments Platform
+
+A unified, category-agnostic Python package for managing Isaac Lab environments.
+"""
+
+__version__ = "0.1.0"
+
+from nepher.config import get_config, set_config
+from nepher.auth import login, logout, whoami, get_api_key
+from nepher.api.client import get_client, APIClient
+from nepher.core import Environment, Scene
+from nepher.loader import load_env, load_scene
+
+__all__ = [
+    # Version
+    "__version__",
+    # Configuration
+    "get_config",
+    "set_config",
+    # Authentication
+    "login",
+    "logout",
+    "whoami",
+    "get_api_key",
+    # API Client
+    "get_client",
+    "APIClient",
+    # Core types
+    "Environment",
+    "Scene",
+    # Loaders
+    "load_env",
+    "load_scene",
+]
+

nepher-0.1.0/nepher/api/__init__.py

@@ -0,0 +1,6 @@
+"""API client for envhub-backend."""
+
+from nepher.api.client import APIClient, get_client
+
+__all__ = ["APIClient", "get_client"]
+