Metadata-Version: 2.4
Name: maple-robotics
Version: 0.0.2
Summary: A CLI daemon interface for evaluating robotics policies across diverse simulation environments
Project-URL: Repository, https://github.com/Shaswat2001/maple-robotics
Project-URL: Documentation, https://maple-robotics.readthedocs.io
Project-URL: Issues, https://github.com/Shaswat2001/maple-robotics/issues
Author-email: Shaswat Garg <sis_shaswat@outlook.com>
License: MIT
License-File: LICENCE
Keywords: embodied-ai,policy-evaluation,reinforcement-learning,robot-learning,robotics,simulation,vla
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: docker
Requires-Dist: fastapi
Requires-Dist: fsspec[gcs,s3]
Requires-Dist: gcsfs
Requires-Dist: huggingface-hub
Requires-Dist: imageio
Requires-Dist: imageio-ffmpeg
Requires-Dist: mediapy>=1.2.4
Requires-Dist: numpy>=1.24.0
Requires-Dist: pillow
Requires-Dist: pyyaml
Requires-Dist: requests
Requires-Dist: rich
Requires-Dist: s3fs
Requires-Dist: typer
Requires-Dist: uvicorn
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: mypy>=1.5.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: myst-parser>=2.0.0; extra == 'docs'
Requires-Dist: sphinx-autodoc-typehints>=1.25.0; extra == 'docs'
Requires-Dist: sphinx-copybutton>=0.5.0; extra == 'docs'
Requires-Dist: sphinx-rtd-theme>=2.0.0; extra == 'docs'
Requires-Dist: sphinx>=7.0.0; extra == 'docs'
Description-Content-Type: text/markdown

# MAPLE - A unified CLI daemon for evaluating robotics policies across diverse simulation environments

<p align="center">
<img src="./docs/source/assets/MAPLE.svg" alt="MAPLE" width="600" height="100">
</p>

[![GitHub](https://img.shields.io/badge/GitHub-maple-blue?logo=github)](https://github.com/Shaswat2001/maple-robotics.git)
[![PyPI](https://img.shields.io/pypi/v/maple-robotics)](https://pypi.org/project/maple-robotics/)
[![Documentation](https://readthedocs.org/projects/maple-robotics/badge/?version=latest)](https://maple-robotics.readthedocs.io)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)

---

## Why Maple?

Evaluating robotics policies—whether Vision-Language-Action (VLA) models, foundation models, imitation learning policies, or reinforcement learning agents—across different simulation environments is painful:

- **Environment chaos**: Every simulator has its own observation format, action space, and API quirks
- **Dependency hell**: MuJoCo, PyBullet, Isaac Gym, LIBERO—each with conflicting dependencies  
- **Integration tax**: Each policy-environment combination requires custom glue code
- **No standardization**: Comparing policies across environments means rewriting evaluation scripts

**Maple solves this** with a daemon-based architecture that containerizes everything:

```bash
# Start the daemon
maple serve

# Pull and serve a policy
maple pull policy openvla:7b
maple serve policy openvla:7b

# Pull and serve an environment
maple pull env libero
maple serve env libero

# Run evaluation
maple eval openvla-7b-xxx libero-yyy --tasks libero_10 --seeds 0,1,2
```

**That's it.** No dependency conflicts. No custom scripts. Just results.

---

## Features

- 🐳 **Docker-First Architecture** — Every policy and environment runs in its own container
- 🔌 **Adapter System** — Automatic translation between policy outputs and environment inputs
- 📊 **Batch Evaluation** — Run evaluations across multiple tasks, seeds, and configurations
- ⚙️ **Flexible Configuration** — YAML config files, environment variables, or CLI flags
- 🏥 **Health Monitoring** — Background health checks with auto-restart on failure
- 💾 **Persistent State** — SQLite-backed state storage for tracking history

---

## Installation

```bash
pip install maple-robotics
```

### Requirements

- Python 3.10+
- Docker with NVIDIA GPU support
- NVIDIA GPU with CUDA 12.1+

### Build Docker Images

```bash
# Policy images
docker build -t maple/openvla:latest docker/openvla/
docker build -t maple/smolvla:latest docker/smolvla/

# Environment images
docker build -t maple/libero:latest docker/libero/
```

---

## Quick Start

```bash
# 1. Start daemon
maple serve --detach

# 2. Pull and serve policy
maple pull policy openvla:7b
maple serve policy openvla:7b
# Output: Policy ID: openvla-7b-a1b2c3d4

# 3. Pull and serve environment
maple pull env libero
maple serve env libero
# Output: Env ID: libero-x1y2z3w4

# 4. Run evaluation
maple eval openvla-7b-a1b2c3d4 libero-x1y2z3w4 \
    --tasks libero_10 \
    --seeds 0,1,2 \
    --output results/

# 5. View results
maple report results/
```

---

## Supported Policies and Environments

All the list of supported environments and policies can be Found - [Policies & Environments Reference](https://maple-robotics.readthedocs.io/en/latest/guides/policy_envs.html). Feel free to suggest any specific policy or environment you would like to be added in the repository.

---

## Architecture

```
┌─────────────────────────────────────────────────────────┐
│                      maple CLI                          │
└───────────────────────┬─────────────────────────────────┘
                        │
                        ▼
┌─────────────────────────────────────────────────────────┐
│                   Maple Daemon                          │
│  ┌───────────┐  ┌───────────┐  ┌─────────────────────┐  │
│  │ Policy    │  │ Env       │  │ Adapter             │  │
│  │ Backends  │  │ Backends  │  │ Registry            │  │
│  └─────┬─────┘  └─────┬─────┘  └─────────────────────┘  │
└────────┼──────────────┼─────────────────────────────────┘
         │              │
         ▼              ▼
┌─────────────────┐  ┌─────────────────┐
│ Policy Container│  │ Env Container   │
│ (Docker + GPU)  │  │ (Docker + X11)  │
└─────────────────┘  └─────────────────┘
```

---

## Configuration

Create `~/.maple/config.yaml`:

```yaml
daemon:
  port: 8000

policy:
  default_device: cuda:0
  model_kwargs: {}
  model_load_kwargs: {}

containers:
  memory_limit: 32g
  startup_timeout: 300

eval:
  max_steps: 300
  save_video: false
```

Or use environment variables:

```bash
MAPLE_DEVICE=cuda:1 maple serve
```

---

## Documentation

Full documentation: [maple-robotics.readthedocs.io](https://maple-robotics.readthedocs.io)

- [Installation Guide](https://maple-robotics.readthedocs.io/guides/installation.html)
- [Quick Start](https://maple-robotics.readthedocs.io/guides/quickstart.html)
- [CLI Reference](https://maple-robotics.readthedocs.io/commands/serve.html)
- [API Reference](https://maple-robotics.readthedocs.io/api/overview.html)

---

## License

MIT License - see [LICENSE](LICENSE) for details.
