tasks.task_safe_demo

tasks.task_safe_demo

Task demo: compare baseline, covariate, and custom LightGBM forecasts against ground truth.

This script executes the baseline N-to-1 task, the covariate-enhanced N-to-1 pipeline, and a custom LightGBM model with optimized hyperparameters, then loads the ground truth from a specified data directory. Logging Mechanism: This script uses a dual-handler logging system designed for safety-critical MLOps:

Console Handler: Provides real-time progress updates to stdout.
File Handler: Persists all log messages (including debug/tracebacks) to a timestamped file in {model_root}/logs/.
Log File Location: By default, logs are saved to ~/spotforecast2_safe_models/logs/task_safe_demo_YYYYMMDD_HHMMSS.log.
Safety-Critical Features:
- Persistent file-based logging for auditability.
- Path management using pathlib for cross-platform reliability.
- Explicit input validation and existence checks.
- Comprehensive error handling with traceback logging.
- Deterministic random seeding where applicable.
- Minimal dependency footprint (no plotting libraries).

Examples

# These are shell commands; they cannot run inside a Python kernel.
# 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 a custom data path:
#   uv run spotforecast-safe-demo --data_path /path/to/data.csv
# Enable logging:
#   uv run spotforecast-safe-demo --logging true

Functions

Name	Description
main	Main execution entry point.

main

tasks.task_safe_demo.main(
    force_train=True,
    data_path=None,
    logging_enabled=False,
)

Main execution entry point. Returns 0 on success, non-zero on failure.

Examples

from pathlib import Path
from spotforecast2_safe.tasks.task_safe_demo import main

# Fail-fast path: when the ground truth file does not exist,
# main() returns 1 immediately without attempting any training.
result = main(
    force_train=False,
    data_path=Path("/nonexistent/path/data.csv"),
    logging_enabled=False,
)
print(f"Return code (missing data): {result}")
assert result == 1, f"Expected 1, got {result}"

Return code (missing data): 1