xdAILabs/edge-deployment-resource-optimization

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

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.

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. 1.Clone the repository and build the container:

    docker build -t edge-deployment-env .

1. 1.Validate the environment specification:

    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:

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