README.md

---
title: OpenEnv
emoji: 🚁
colorFrom: green
colorTo: blue
sdk: docker
sdk_version: 6.10.0
python_version: '3.11'
app_file: app.py
pinned: false
---

# OpenEnv

<div align="center">

**A Production-Ready Reinforcement Learning Environment for Autonomous Drone Navigation**

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Hugging Face Spaces](https://img.shields.io/badge/%F0%9F%A4%97-Hugging%20Face%20Spaces-blue)](https://huggingface.co/spaces/yourusername/openenv-drone-navigation)

🚁 **Try the live demo:** [OpenEnv on Hugging Face Spaces](https://huggingface.co/spaces/yourusername/openenv-drone-navigation)

</div>

---

## 🌍 Real-World Task: Warehouse Inventory Inspection

OpenEnv simulates **autonomous drone navigation for automated warehouse inventory inspection** - a critical real-world robotics challenge faced by logistics companies worldwide.

### The Problem
- **Manual inventory checks** in massive warehouses are time-consuming and error-prone
- **Human inspectors** need to navigate aisles, read barcodes, and verify stock levels
- **Operational costs** are high, and accuracy is critical for supply chain management

### Our Solution
Train AI agents to autonomously navigate drones through warehouse environments to:
- ✅ Reach inspection checkpoints (inventory scanners)
- ✅ Avoid static obstacles (shelves, boxes, equipment)
- ✅ Compensate for dynamic disturbances (wind from ventilation, moving machinery)
- ✅ Optimize flight paths for battery efficiency
- ✅ Complete inspections within time constraints

### Industry Impact
This environment directly models challenges faced by:
- **Amazon Robotics** - Automated warehouse monitoring
- **DJI Enterprise** - Industrial inspection drones
- **Boston Dynamics** - Autonomous navigation systems
- **Wing Aviation** - Delivery drone path planning

---

## Action and Observation Space

### Observation Space
The environment uses a multi-modal observation space represented strictly through the **OpenEnv Pydantic Spec**:
- `emails_remaining`: (int) How many emails left in the queue.
- `current_email`: (Email) The current email to triage containing ID, sender, subject, body, and ground-truth metadata.
- `time_elapsed`: (float) Time taken in episode.

### Action Space
Discrete control (0-4 integer matching to Ignore, Reply, Forward, Archive, Delete).

### Meaningful Reward Structure
Unlike binary win/loss signals, this environment provides *dense* steps of reward:
- **+1** for correctly triaging an email (e.g. archiving a newsletter).
- **-1** for incorrectly triaging an email.
- **-5** Critical Safety Penalty if an agent *Ignores* or *Deletes* an urgent email.
- **-2** Safety Penalty for *Replying to* or *Forwarding* spam.

---

## Setup & Execution

### 1. Local Installation

```bash
git clone https://github.com/yourusername/OpenEnv
cd OpenEnv

# Create a virtual environment
python -m venv venv
source venv/bin/activate

# Install the package and dependencies
pip install -e .
```

### 2. Validation
Check OpenEnv Spec Compliance:
```bash
openenv validate
# or
python -m openenv.scripts.cli validate
```

### 3. Baseline Agent (OpenAI API)
You can run a completely autonomous baseline test utilizing a state-of-the-art LLM (GPT-4o-mini).
```bash
export OPENAI_API_KEY="sk-..."
python scripts/baseline.py
```

### 4. Interactive Hugging Face UI
Watch the environment in action or play it manually using the Gradio layout:
```bash
python app.py
```
> Go to `http://localhost:7860` to triage the inbox.

---

## 📈 Performance Benchmarks

### Baseline Results

Training with PPO (Stable Baselines3):

| Metric | Value |
|--------|-------|
| Timesteps | 100,000 |
| Mean Return | ~850 |
| Success Rate | ~95% |
| Episode Length | ~150 steps |

### Environment Speed

- **Step Latency:** < 0.1ms (no rendering)
- **Step Latency:** ~2ms (with rgb_array rendering)
- **Parallel Performance:** Scales linearly with VecEnv

---

## 🔬 Example Environments

### Custom Environment Variants

You can create specialized variants by modifying configuration:

```python
# Easy version - larger target, no boundary termination
easy_config = EnvConfig(
    boundary_limit=100.0,
    max_velocity=200.0,
    reward_scale=2.0,
    terminate_on_boundary=False,
)

# Hard version - smaller target, strict constraints
hard_config = EnvConfig(
    boundary_limit=20.0,
    max_velocity=50.0,
    sparse_rewards=True,
    friction=0.1,
)

# Fast training - shorter episodes
fast_config = EnvConfig(
    episode_length=200,
    dt=0.01,
)
```

---

## 🛠️ Development

### Code Quality

This project follows professional standards:

- **Type Hints:** Full type annotation throughout
- **PEP 8:** Compliant code style
- **Black Formatting:** Automated code formatting
- **Docstrings:** Comprehensive documentation
- **Logging:** Structured logging system

### Running Linters

```bash
# Code formatting
black openenv/ tests/

# Linting
flake8 openenv/ tests/

# Type checking
mypy openenv/
```

---

## 🤝 Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Run tests (`pytest tests/ -v`)
5. Ensure code passes linting (`black . && flake8`)
6. Commit your changes (`git commit -m 'Add amazing feature'`)
7. Push to the branch (`git push origin feature/amazing-feature`)
8. Open a Pull Request

---

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## 🙏 Acknowledgments

- Built on [Gymnasium](https://gymnasium.farama.org/) framework
- Inspired by classic control environments (MountainCar, LunarLander)
- Designed for compatibility with [Stable Baselines3](https://stable-baselines3.readthedocs.io/)

---

## 📞 Support

For issues, questions, or contributions:

- **Bug Reports:** GitHub Issues
- **Questions:** GitHub Discussions
- **General Inquiries:** See README contact info

---

## 🎓 Citation

If you use OpenEnv in your research, please cite:

```bibtex
@software{openenv2024,
  author = {OpenEnv Team},
  title = {OpenEnv: A Production-Ready Reinforcement Learning Environment},
  year = {2024},
  url = {https://github.com/yourusername/OpenEnv},
  version = {1.0.0}
}
```

---

<div align="center">

**Built with ❤️ for the RL Community**

</div>