🛰️ Aether OS — Satellite AI Analytics System

A production-ready satellite imagery intelligence system that classifies, filters, and ranks multispectral EuroSAT images using a Random Forest classifier with adaptive calibration and an end-to-end audit verification engine.

---

✨ Features

Feature	Description
Base Classifier	Random Forest model (terramind_rf.joblib) trained on EuroSAT-MS 13-band Sentinel-2 imagery
Adaptive Intelligence	Experimental module for rapid-change detection and novelty scoring
Stability Guard	Temperature-scaled calibration layer — eliminates overconfidence, produces realistic confidence values
Sorted Downlink Output	Filters invalid frames, sorts selected images by confidence, packages as a ranked JSON downlink
TIF → PNG Preview	In-browser satellite image viewer — converts raw 13-band uint16 TIF to RGB PNG on demand
Sorted Image ZIP	Downloads all selected images as a numbered ZIP (001_conf-0.97_Forest_Forest_1.tif) with manifest
Audit Verification Engine	11-check deep audit of the full pipeline — calibration bypass, overconfidence, raw leakage, safety, bias, temporal stability
Aether Dashboard	Apple-style React glassmorphism UI with Data Ingestion and Telemetry Output pages

---

🗂️ Project Structure

space-hackathon/
├── backend_main.py              # FastAPI server (all API endpoints)
├── orbital_inference_eurosat.py # Core inference pipeline
├── audit_verification.py        # End-to-end system audit engine
├── requirements.txt
├── .env.example
│
├── utils/                       # ML utilities (model loading, preprocessing)
│   ├── terramind_rf.joblib      # 3.84 MB Random Forest model
│   └── terramind_scaler.joblib  # StandardScaler
│
├── data/                        # Generated outputs (gitignored)
│   ├── eurosat_downlink.json    # Pipeline output (auto-generated)
│   └── system_audit_report.json # Audit report (auto-generated)
│
└── Front/aether-frontend/       # React + TypeScript + Vite frontend
    ├── src/
    │   ├── pages/
    │   │   ├── DataIngestion.tsx
    │   │   └── TelemetryOutput.tsx
    │   └── components/
    │       ├── TifPreviewViewer.tsx
    │       └── AuditPanel.tsx
    ├── package.json
    └── vite.config.ts

---

⚙️ Setup

Prerequisites

• Python 3.10+
• Node.js 18+
• EuroSAT Multispectral dataset (not included — see Dataset section)

Backend

# Install dependencies
pip install -r requirements.txt

# Start the API server
python -m uvicorn backend_main:app --port 8000

The backend runs at http://localhost:8000

Frontend

cd Front/aether-frontend

# Copy env file
cp ../../.env.example .env

# Install and run
npm install
npm run dev

The dashboard runs at http://localhost:5173

---

📡 API Endpoints

Method	Endpoint	Description
GET	/health	Backend health check
POST	/run-analysis	Run the inference pipeline
GET	/results	Get latest telemetry JSON
GET	/preview-image?class_name=Forest&sample=Forest_1.tif	Stream TIF → PNG preview
GET	/download-sorted-images	Download sorted images as ZIP
POST	/run-audit	Run end-to-end audit verification
GET	/audit-report	Get latest audit report

---

🗃️ Dataset

The EuroSAT Multispectral dataset is not included in this repository (>2GB).

Download it from: https://github.com/phelber/EuroSAT

Expected folder structure after download:

EuroSAT_MS/
└── EuroSAT_MS/
    ├── Forest/
    │   ├── Forest_1.tif
    │   └── ...
    ├── SeaLake/
    ├── River/
    └── ...

Place it at the project root. The backend auto-detects this path.

To use a custom path: open Advanced Options in the Data Ingestion page and enter the full folder path, or set dataset_path in the POST /run-analysis body.

---

🧠 Model

File	Size	Description
utils/terramind_rf.joblib	3.84 MB	Random Forest classifier (EuroSAT 10-class)
utils/terramind_scaler.joblib	1.23 KB	StandardScaler for band normalization

Total model size: 3.84 MB — lightweight enough for edge/orbital deployment.

---

🔍 Audit Engine

The audit runs 11 checks across the full decision pipeline:

• Calibration bypass detection
• Overconfidence flagging (threshold: 0.95)
• Raw confidence leakage
• Margin collapse
• Distribution sharpness (top-2 probability)
• Cross-layer label consistency
• Unsafe SEND on low-confidence decisions
• Rarity/novelty logic validation
• Priority bounds and inflation
• Class bias / dominance
• Temporal label oscillation

Outputs a system_audit_report.json with PASS / PARTIAL / FAIL verdict.

---

📄 License

MIT