Metadata-Version: 2.4
Name: enviscale
Version: 0.1.0
Summary: Official Python SDK & CLI for the EnviScale Robotics Physics & SimReady Pipeline.
Author-email: EnviScale Team <dev@enviscale.com>
License: MIT
Project-URL: Homepage, https://enviscale.com
Project-URL: Documentation, https://enviscale.com/docs
Project-URL: Repository, https://github.com/enviscale/enviscale-sdk
Keywords: robotics,physics,mujoco,isaac-sim,simready,simulation,reinforcement-learning,parallel-axis-theorem,cad
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"

# EnviScale Python SDK & CLI

[![PyPI Version](https://img.shields.io/badge/pypi-v0.1.0-blue.svg)](https://pypi.org/project/enviscale/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-green.svg)](https://www.python.org/)
[![Physics Standard](https://img.shields.io/badge/physics-Parallel--Axis%20Theorem-orange.svg)](https://enviscale.com)

The official Python SDK and Command-Line Interface (`enviscale`) for **EnviScale** — the physics grounding and SimReady pipeline engine for robotics and reinforcement learning.

---

## Key Features

- ⚡ **Native Multi-Part Extraction**: Discovers assemblies in GLTF/GLB, STEP, and USD; reconciles part masses against an anchor prior.
- 📐 **3D Parallel-Axis Theorem**: Calculates authoritative $3 \times 3$ rigid-body cumulative inertia tensors ($I_{\text{global}}$) rather than diagonal box simplifications.
- 🧪 **Fluid Fill States**: Voxel cavity extraction to simulate empty, half, and full containers with displaced Center of Mass and viscous friction damping.
- 🤖 **Multi-Simulator Export**: Generates validated MuJoCo MJCF XMLs (`fullinertia`), URDFs, and Isaac Sim USD Physics.
- 🗃️ **Programmatic Scene Composition**: Automatically lays out multi-object evaluation scenes on workspace tables, desks, bins, or shelves.
- 🔄 **Domain Randomization (DR)**: Iterates over calibrated friction wear and mass variation profiles directly in PyTorch/Gymnasium training loops.

---

## Installation

```bash
pip install enviscale
```

Or for local development:
```bash
git clone https://github.com/enviscale/enviscale-sdk.git
cd enviscale-sdk
pip install -e .
```

---

## Quickstart: Python SDK

```python
import enviscale

# 1. Initialize client (defaults to http://localhost:8000 or ENVISCALE_BASE_URL)
client = enviscale.Client(api_key="es_live_YOUR_API_KEY")

# 2. Compile an asset with automatic multi-part physics
asset = client.compile(
    file_path="lantern.glb",
    export_format="mjcf",
    surface_condition="all",
    output_dir="./compiled_lantern",
)

print(f"Object: {asset.object_name}")
print(f"Reconciled Mass: {asset.mass_kg:.3f} kg")
print(f"Center of Mass: {asset.center_of_mass}")

if asset.is_native_multipart:
    print(f"Multi-Part Mode: {asset.native_parts_count} parts reconciled via Parallel-Axis Theorem")
    print(f"Full Inertia: {asset.inertia_tensor}")  # [Ixx, Iyy, Izz, Ixy, Ixz, Iyz]

# 3. Access MuJoCo XML for simulation
xml_content = asset.get_xml(profile_prefix="clean")
```

### Reinforcement Learning Domain Randomization Loop

```python
import mujoco
import enviscale

client = enviscale.Client()
asset = client.compile("drill.step", export_format="mjcf")

# Train policy across physically calibrated wear and fill profiles
for profile in asset.profiles:
    print(f"Training on profile: {profile.profile_name}")
    print(f"  Friction: {profile.friction_sliding}")
    print(f"  DR Mass Bounds: {profile.dr_mass_range}")
    
    # Load profile directly into MuJoCo model
    xml_str = asset.get_xml(profile_prefix=profile.profile_name)
    model = mujoco.MjModel.from_xml_string(xml_str)
```

### Programmatic Scene Composition

```python
import enviscale

client = enviscale.Client()

scene = client.compose(
    files=["mug.glb", "pliers.step", "box.obj"],
    template="tabletop_manipulation",
    seed=101,
    output_dir="./eval_scene",
)

print(f"Generated scene world file at ./eval_scene/scene.xml")
```

---

## Quickstart: CLI Tool

The package registers the `enviscale` command directly in your shell:

### Compile a single asset:
```bash
enviscale compile gearbox.step --format mjcf -o ./gearbox_simready
```

### Compile multi-part container with fill states:
```bash
enviscale compile travel_mug.glb --fill all --quality precise -o ./mug_simready
```

### Compose multi-object evaluation scene:
```bash
enviscale compose cup.glb pliers.glb screwdriver.step \
  --template tabletop_manipulation \
  --seed 42 \
  -o ./composed_bench
```

### Check API connectivity:
```bash
enviscale status
```

---

## CI/CD Pipeline Integration (GitHub Actions)

Add physical validity checks before merging robot simulation assets:

```yaml
name: Simulation Asset Verification

on:
  pull_request:
    paths:
      - 'assets/**'

jobs:
  validate-assets:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      
      - name: Install EnviScale
        run: pip install enviscale
      
      - name: Compile and Verify Asset
        env:
          ENVISCALE_API_KEY: ${{ secrets.ENVISCALE_API_KEY }}
        run: |
          enviscale compile ./assets/new_tool.glb --format mjcf -o ./dist/
```

---

## License

MIT License. Developed for the robotics and simulation community.
