SignalStack

Business Intelligence Forecasting Engine

What It Does

• Ingests EIA petroleum Excel datasets and sample wholesale/inventory/weather CSVs
• Appends live EIA API updates without duplicates
• Runs SARIMA forecasts (30/60/90 day) with MAPE, RMSE, and directional-accuracy metrics
• Computes market regime, seasonal patterns, wholesale-vs-cost-basis spread strategy, and weather correlation
• Generates active price/spread/regime alerts
• Exports an executive .docx report, API-style JSON payloads, and an LLM context file

Data Layout

• data/eia/ - EIA public Excel files (input)
• data/sample/ - synthetic wholesale, inventory cost basis, and weather CSVs for demo reproducibility
• data/processed/ - normalized long-format outputs (date, product, value, source)
• data/traffic/raw/ - CDOT public corridor pulls
• data/traffic/processed/ - normalized corridor traffic panel
• output/forecasts/ - model JSON outputs
• output/alerts/active_alerts.json - current alert state
• output/reports/analysis_snapshot.json - analysis summary

Note on sample data. Files under data/sample/ are programmatically generated with a fixed random seed (see repo history) and do not reflect any real market or client data. They exist so the pipeline can be run end-to-end out of the box.

Setup

python -m pip install -r requirements.txt

For live EIA API updates, create .env:

EIA_API_KEY=your_eia_api_key

A free key is available at https://www.eia.gov/opendata/.

Commands

Ingest local files:

python run_ingest.py --all
python run_ingest.py --source spot_prices
python run_ingest.py --source traffic_cdot

Update from EIA API:

python run_ingest.py --api-update
python run_ingest.py --api-update --force-api

Run forecasts:

python run_pipeline.py --all
python run_pipeline.py --product heating_oil --horizon 90

Export reports / JSON / LLM context:

python export_reports.py --format docx --period monthly
python export_reports.py --skip-docx

Key Outputs

Forecast JSON:

• product
• generated_at
• horizon_days
• forecast[] (date, point, ci_80_low, ci_80_high, ci_95_low, ci_95_high)
• metrics (mae, rmse, mape, directional_accuracy, naive_mape)

Analysis snapshot:

• market regime
• seasonal outlook
• pricing strategy recommendation (index_plus or cost_plus)
• weather correlation summary
• alert counts

Tests

python -m pytest tests -q

License

MIT - see LICENSE.

Author

petrostack is built by Jacob Johnston / True North Data Strategies LLC as an operator-grade petroleum market intelligence reference.

petrostack