Task Scripts

spotforecast2-safe provides command-line task scripts for safety-critical forecasting workflows. These scripts are registered as console entry points and can be invoked directly via uv run or after package installation.

Available Commands

Command Description
spotforecast-safe-demo Demo task comparing baseline, covariate, and custom LightGBM forecasts

Demo Task

The spotforecast-safe-demo command runs a comprehensive comparison of three forecasting approaches:

  1. Baseline: Standard N-to-1 recursive forecaster
  2. Covariate-enhanced: Includes weather, holidays, and cyclical features
  3. Custom LightGBM: Optimized hyperparameters with safety-critical configuration

Usage

# Run with default settings (force training)
uv run spotforecast-safe-demo

# Skip training (use cached models if available)
uv run spotforecast-safe-demo --force_train false

# Specify custom data path
uv run spotforecast-safe-demo --data_path /path/to/data.csv

# Enable logging
uv run spotforecast-safe-demo --logging true

Exit Codes

Code Meaning
0 Success
1 General failure
2 Data loading error
3 Model training error

!!! warning “Safety-Critical Consideration” The demo task logs all execution steps and errors. In production, always enable logging with --logging true for auditability.

Configuration

All tasks use sensible defaults but can be customized via:

  • Command-line arguments (use --help for details)
  • Environment variables for API keys and paths
  • Configuration files stored in ~/spotforecast2_data/
# View available options for any command
uv run spotforecast-safe-demo --help

Model Persistence

Trained models are saved to ~/spotforecast2_models/<task_name>/ by default. This allows:

  • Incremental retraining: Only retrain when models are stale
  • Reproducibility: Models are versioned by task and timestamp
  • Auditability: Full training logs are stored alongside models

!!! tip “Best Practice” For production deployments, always verify model checksums and training timestamps before using cached models.

Logging

Safety-critical tasks support comprehensive logging:

# Enable logging to default directory
uv run spotforecast-safe-demo --logging true

Log files include:

  • Execution timestamps
  • Parameter configurations
  • Model training metrics
  • Error tracebacks (if any)