--- title: Edge Deployment Resource Optimization emoji: 🦀 colorFrom: pink colorTo: blue sdk: docker pinned: false license: apache-2.0 short_description: Deploying production AI models to edge hardware. tags: - openenv --- Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference # EdgeResourceEnv: Edge Deployment Resource Management ## 📖 Description The **EdgeResourceEnv** is a high-fidelity, real-world task simulation designed to evaluate AI agents acting as system resource governors on constrained edge devices. **Motivation:** Deploying production AI models to edge hardware (smartphones, IoT sensors) presents a unique engineering trade-off between inference accuracy and system stability. If an agent is too aggressive with resources, it drains the battery; if it is too passive, the device suffers from Out-of-Memory (OOM) crashes. This environment provides a safe, simulated environment to test these "Resource-Aware" strategies before they are shipped to physical hardware. --- ## 📁 Project Structure ```text edge-deployment-env/ ├── server/ │ └── app.py # Backend/API logic ├── .dockerignore # Docker build exclusions ├── Dockerfile # Containerization for HF Spaces execution ├── env.py # Core environment, simulation, and grading logic ├── inference.py # Mandatory baseline LLM agent script ├── models.py # Pydantic schemas for Spec compliance ├── openenv.yaml # Environment metadata and task definitions ├── pyproject.toml # Build system and project metadata ├── README.md # Documentation ├── requirements.txt # Python dependencies └── uv.lock # Exact dependency versions for reproducible builds ``` --- ## 🛰️ Space Definitions The environment interface is built using strictly typed Pydantic models to ensure full **OpenEnv spec compliance**. These models define how the agent perceives and interacts with the simulated edge hardware. ### Observation Space (`EdgeObservation`) The observation provides a high-fidelity snapshot of the device's physical state at each discrete time step. | Attribute | Type | Description | | :--- | :--- | :--- | | `ram_usage` | `float` | Percentage of total RAM occupied (0.0–100.0). High values trigger OOM risks. | | `battery_level` | `float` | Remaining battery percentage (0.0–100.0). Impacts CPU frequency availability. | | `active_processes` | `int` | Count of concurrent background tasks competing for CPU priority. | | `latency` | `float` | Current inference delay in milliseconds. Impacted by CPU throttling and queue size. | ### Action Space (`EdgeAction`) The agent must select a combination of the following booleans to mitigate system failure or optimize performance. * **`kill_process`**: Immediately terminates the lowest-priority background process to reclaim ~15% RAM but incurs a small "reboot" penalty in future steps. * **`throttle_cpu`**: Reduces the simulated CPU clock speed. Decreases battery drain by 40% but doubles inference `latency`. * **`route_to_cloud`**: Offloads the current task to an external server. Reduces local RAM/Battery usage to near-zero but adds a fixed +150ms network latency. --- ## 🎯 Task Descriptions The environment features a curriculum of three tasks designed to test the agent's ability to generalize across different stress conditions. ### 1. Task: `task_stable_edge` (Easy) * **Scenario**: Standard operating conditions with consistent background noise. * **Grader Logic**: `score = 1.0 - (steps_crashed / total_steps)`. A deterministic score from 0.0–1.0 based on survival. ### 2. Task: `task_fluctuating_memory` (Medium) * **Scenario**: Simulates a user opening and closing heavy apps (e.g., Camera, Games), causing RAM usage to spike unpredictably. * **Grader Logic**: Weighted average of **Survival** (50%) and **Efficiency** (50%, measured by keeping RAM usage between 60% and 85%). ### 3. Task: `task_low_battery_spike` (Hard) * **Scenario**: High-priority request burst (5x normal) while battery is below 15%. * **Grader Logic**: Binary survival check combined with a latency penalty. If the system crashes (OOM) or dies (Battery=0), the score is 0.0. --- ## 🛠️ Setup & Usage ### Prerequisites * **Docker:** Required for containerized execution. * **Python 3.10+**. * **openenv-core library:** For spec validation. ### Local Installation 1. **Clone the repository and build the container:** ```bash docker build -t edge-deployment-env . ``` 2. **Validate the environment specification:** ```bash openenv validate ``` ### Configuration The baseline inference script reads configuration strictly from environment variables. * **`API_BASE_URL`**: Your LLM endpoint URL. * **`MODEL_NAME`**: The specific model identifier for inference (e.g., `llama3.1`). * **`HF_TOKEN`**: Your Hugging Face API key. ### Running the Baseline To execute the benchmark and produce the mandatory **STDOUT logs** for validation: ```bash export API_BASE_URL="your_url" export MODEL_NAME="your_model" export HF_TOKEN="your_token" python inference.py ``` Upon completion, the script will output the standard `[END]` line containing your final reproducible scores. ## 📊 Baseline Scores The following reproducible scores were achieved using the provided `inference.py` script with the **Llama 3.1** baseline agent. All scores are normalized between 0.0 and 1.0. * **Task 1 (Stable Edge):** 0.65 * **Task 2 (Fluctuating Memory):** 0.82 * **Task 3 (Low Battery Spike):** 0.35 ---