AgentA123/project-helios-api

Solar Flare AI Backend

FastAPI backend for CPU inference from solar_transformer_model.pt using recent NOAA SWPC GOES primary X-ray flux data.

This backend does not train models, control spacecraft, or download large historical datasets. It loads the exported PyTorch checkpoint, fetches recent NOAA JSON data, preprocesses the latest sequence, and returns forecast or approximate validation JSON.

Data Sources

• —Live prediction source: https://services.swpc.noaa.gov/json/goes/primary/xrays-1-day.json
• —Recent validation source: https://services.swpc.noaa.gov/json/goes/primary/xrays-7-day.json
• —Channel used: GOES long X-ray channel, 0.1-0.8nm
• —NOAA data can contain missing rows or dropouts, so invalid rows are skipped.

Endpoints

GET /

Returns the project name and available endpoints.

GET /health

Returns service status, model load state, and the NOAA data source URL.

GET /predict

Runs live inference using the latest seq_len GOES X-ray rows.

Returned fields include:

• —flare_probability
• —risk_level
• —threshold
• —alert
• —latest_time
• —latest_flux
• —forecast_start_time
• —forecast_end_time
• —forecast_window_minutes
• —target_flare_class
• —model_best_f1
• —data_points_used

The forecast timing fields describe the valid forecast interval. The model does not predict an exact flare onset time inside that interval.

The response also includes input_window_start_time, noaa_rows_available, and response_generated_at so clients can distinguish a stable model probability from stale data.

GET /space-weather

Returns recent NOAA GOES long-channel X-ray flux values for lightweight frontend monitoring and charting.

Returned fields include:

• —latest_time
• —latest_flux
• —data_points_returned
• —data_points_available
• —min_flux
• —max_flux
• —series

GET /validation

Runs an approximate recent backtest using only recent NOAA GOES JSON data.

The endpoint uses xrays-7-day.json when available, builds rolling windows across the recent dataset, runs model predictions, and compares predicted alerts against observed future flux thresholds. It includes both quiet and flare-active windows; it does not only check windows where an observed event occurred.

This is not the original Kaggle/DONKI validation dataset.

Observed proxy thresholds:

• —C-class proxy: flux >= 1e-6 W/m^2
• —M-class proxy: flux >= 1e-5 W/m^2
• —X-class proxy: flux >= 1e-4 W/m^2

Returned summary fields include:

• —total_windows_checked
• —predicted_alerts
• —actual_flare_level_events
• —true_positives
• —false_positives
• —false_negatives
• —true_negatives
• —accuracy
• —precision
• —recall
• —f1_score
• —observed_proxy_threshold
• —data_start_time
• —data_end_time
• —validation_note

If there is not enough recent NOAA data to cover the model input sequence plus the forecast horizon, the endpoint returns a clear 503 JSON error. For free hosting stability, recent validation uses a 60-minute stride, caps the number of windows, and runs inference in small CPU batches.

Local Run

From this backend directory:

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
python main.py

The app binds to 0.0.0.0:7860 by default. You can also run:

uvicorn main:app --host 0.0.0.0 --port 7860

For a frontend expecting port 8000, run:

uvicorn main:app --host 0.0.0.0 --port 8000

Hugging Face Spaces Deploy

This backend supports Docker-based Hugging Face Spaces.

1. 1.Create a new Hugging Face Space.
2. 2.Choose Docker as the Space SDK.
3. 3.Upload or push the contents of the backend folder.
4. 4.Make sure solar_transformer_model.pt is included.
5. 5.Hugging Face builds the included Dockerfile and serves port 7860.

Render Deploy

Python Runtime

Build command:

pip install -r requirements.txt

Start command:

uvicorn main:app --host 0.0.0.0 --port $PORT

Docker Runtime

Use the included Dockerfile. It defaults to PORT=7860 but also respects a platform-provided PORT environment variable.

Current Feature Note

The backend currently uses live GOES X-ray flux plus placeholder values:

• —sunspot_number = 0
• —radio_flux = 0

A future improvement should add reliable real-time sunspot and radio flux inputs if those features are important for matching the training distribution.