README.md

metadata

title: Satellite Project
emoji: 🛰️
colorFrom: blue
colorTo: gray
sdk: docker
app_port: 8000
base_path: /web
tags:
  - openenv
pinned: false

Satellite Constellation Management Environment

This repository contains a real-world OpenEnv submission for satellite fleet operations. Agents must manage image capture, data downlink, maintenance timing, and resource risk across three deterministic task presets.

Overview And Motivation

This environment models a realistic operations problem: coordinating a satellite fleet that must capture imagery, preserve onboard resources, and downlink data under changing weather and workload pressure.

It is intended as a meaningful agent benchmark because good performance requires:

• balancing short-term task completion against long-term battery and storage health
• choosing among competing operational priorities
• avoiding wasteful or destructive actions across long trajectories
• adapting strategy as task mix and constellation size increase from easy to hard

What Is Included

• Canonical environment package: satellite/
• Typed Pydantic models for observation, action, reward, and state
• Three built-in tasks: easy, medium, hard
• Deterministic task grader returning scores from 0.0 to 1.0
• Reward shaping for progress, efficiency, and bad behavior penalties
• Baseline inference runner at inference.py
• Local validator-ready OpenEnv app manifest at satellite/openenv.yaml

Task Progression

Task	Satellites	Max Steps	Workload	Main Difficulty
Easy	3	50	5 image tasks	Basic resource management
Medium	5	100	12 mixed tasks	Capture/downlink balancing
Hard	8	200	20 mixed tasks	Heavier weather, more coordination, stricter grading

The progression is explicit in both configuration and grading:

• easy focuses on simple image completion and battery health
• medium adds meaningful downlink workload and more task completions
• hard increases fleet size, task count, cloud pressure, and invalid-action sensitivity

Canonical API

Use SatelliteTaskEnv for the submission-facing environment API:

from satellite import SatelliteAction, SatelliteTaskEnv

env = SatelliteTaskEnv(task_name="medium")
observation = env.reset()

observation, reward, done, info = env.step(
    SatelliteAction(satellite_actions={0: "capture", 1: "maintain"})
)

state = env.state()

Key methods:

• reset() -> SatelliteObservation
• step(action) -> (SatelliteObservation, SatelliteReward, done, info)
• state() -> SatelliteEnvState
• SatelliteTaskEnv.list_tasks() -> Dict[str, str]

Action And Observation Spaces

Action Space

The action space is a typed SatelliteAction object with one command per satellite:

SatelliteAction(
    satellite_actions={
        0: "capture",
        1: "downlink",
        2: "maintain",
        3: "idle",
    }
)

Allowed actions:

• capture: collect imagery for an image task
• downlink: transmit stored data toward a downlink task
• maintain: recover battery and preserve fleet health
• idle: take no productive action this step

For HTTP POST /step, send the action inside the OpenEnv step wrapper:

{
  "action": {
    "satellite_actions": {
      "0": "capture",
      "1": "maintain",
      "2": "idle"
    }
  },
  "timeout_s": 30
}

The server also tolerates Hugging Face-style stringified JSON for action or satellite_actions during deployment.

Observation Space

The observation space is a typed SatelliteObservation object containing:

• satellites: per-satellite state with id, position, battery, storage, and last_action
• time_step: current step in the episode
• ground_stations: available ground-station coordinates
• weather_conditions: cloud cover by region
• pending_tasks: currently visible image/downlink tasks
• total_reward: cumulative reward so far
• reward: immediate reward from the latest step
• done: whether the episode has ended
• metadata: step metadata such as reward components and metrics

Reward Model

Rewards are shaped during the trajectory, not only at the end:

• positive reward for completing image and downlink tasks
• additional reward for finishing full downlink workloads
• moderate reward for timely maintenance
• penalties for invalid actions
• penalties for repeated wasteful actions
• penalties for risky low-battery or overfull-storage behavior
• mild penalty for unproductive idling when useful work is available

Grading

TaskGrader scores episodes deterministically from environment metrics, including:

• completed image tasks
• downlinked units
• total tasks completed
• final average battery
• invalid-action rate

Local Setup

Create the local virtualenv and install the OpenEnv runtime:

python3 -m venv .venv
.venv/bin/pip install "openenv-core[core]"

Validate The Environment

The OpenEnv environment root is satellite/, not the repo root.

Use either:

.venv/bin/openenv validate satellite

or:

cd satellite
../.venv/bin/openenv validate .

Dashboard

Run the local dashboard with:

python3 dashboard.py

It supports:

• task switching across easy, medium, and hard
• heuristic, random, and manual action selection
• reward and fleet-state inspection

Web UI

The project now includes a React tracking UI served by the FastAPI app at /web.

It shows:

• randomly initialized satellites on a lightweight globe-style display
• ground stations with live downlink beams
• automatic step playback for the environment
• task switching across easy, medium, and hard
• fleet battery, storage, weather, and pending-task summaries

Frontend development files live in frontend/.

Useful local commands:

cd frontend
npm install
npm run build

For live frontend development:

cd frontend
npm install
npm run dev

The Vite dev server proxies /api, /reset, /step, /state, and /schema to http://127.0.0.1:8000. If your backend runs on a different origin, set VITE_API_BASE before starting Vite.

Then run the API server and open:

http://127.0.0.1:8000/web

Baseline Inference

The baseline script evaluates all three tasks and prints:

• per-task score
• per-task reward
• per-task step count
• final aggregate score

Set:

export HF_TOKEN="your-token"
export MODEL_NAME="your-model"
export API_BASE_URL="https://router.huggingface.co/v1"
python3 inference.py

The script uses the OpenAI Python client and reads credentials from HF_TOKEN.

Reproducible Baseline Scores

The repository also supports a deterministic heuristic baseline that can be reproduced locally without a remote model:

BASELINE_POLICY=heuristic python3 inference.py

Current baseline scores:

Task	Score	Reward	Steps	Done
easy	1.0000	34.60	50	True
medium	1.0000	126.70	100	True
hard	1.0000	170.40	200	True

Aggregate heuristic baseline score: 1.0000

Project Structure

openEnv_Hackathon/
├── dashboard.py
├── inference.py
├── satellite/
│   ├── __init__.py
│   ├── constellation.py
│   ├── env.py
│   ├── graders.py
│   ├── models.py
│   ├── openenv.yaml
│   ├── pyproject.toml
│   ├── tasks.py
│   └── server/
│       ├── app.py
│       └── satellite_environment.py
└── docs/