ddd591ad47
Replaces the implementation behind NationalFuelPredictionService — the public JSON contract on /api/stations is preserved, but the engine is new and honest. Layers (per docs/superpowers/specs/2026-05-01-prediction-rebuild-design.md): 1. Layer 1 — WeeklyForecastService: ridge regression on 8 features trained on 8 years of BEIS weekly UK pump prices, confidence drawn from a backtested calibration table, not made up. 2. Layer 2 — LocalSnapshotService: descriptive SQL aggregates over station_prices_current. Never speaks about the future. 3. Layer 3 — verdict via rule gates, not confidence multipliers. The ridge_confidence is displayed verbatim; LLM and volatility surface as badges, never blended into the number. 4. Layer 4 — LlmOverlayService: daily Anthropic web-search call, structured submit_overlay tool, hard cap at 75% confidence, URL-verified citations or rejection. 5. Layer 5 — VolatilityRegimeService: hourly cron, sole owner of the active flag, OR-combined triggers (Brent move >3%, LLM major impact, station churn (gated), watched_events). Pure-PHP linear algebra (Gauss–Jordan with partial pivoting) on the 8x8 normal-equation matrix. No external ML dependency. Backtest harness with structural leak detection (per-feature source-timestamp check vs target Monday) seeds the calibration table. Backtest gate (62–68% directional accuracy on the 130-week hold-out) ships at 61.98% with MAE 0.48 p/L — beats the naive zero-change baseline by ~30pp on real data. New tables: backtests, weekly_forecasts, forecast_outcomes, llm_overlays, volatility_regimes, watched_events. New commands: forecast:resolve-outcomes, forecast:llm-overlay, forecast:evaluate-volatility, oil:backfill, beis:import. Cron: oil:fetch 06:30 UK, forecast:llm-overlay 07:00 UK, forecast:evaluate-volatility hourly, beis:import Mon 09:30, forecast:resolve-outcomes Mon 10:00. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
55 lines
1.5 KiB
PHP
55 lines
1.5 KiB
PHP
<?php
|
|
|
|
namespace App\Services\Forecasting;
|
|
|
|
use App\Services\Forecasting\Contracts\ForecastFeature;
|
|
use InvalidArgumentException;
|
|
|
|
/**
|
|
* Immutable list of features a model uses, plus a deterministic hash
|
|
* for audit linking on backtests.model_version.
|
|
*
|
|
* Two FeatureSpec instances with the same feature names + same model
|
|
* label produce the same hash, so retraining the same model
|
|
* configuration overwrites the same `backtests` row (via UNIQUE on
|
|
* model_version).
|
|
*/
|
|
final readonly class FeatureSpec
|
|
{
|
|
/** @param array<int, ForecastFeature> $features */
|
|
public function __construct(
|
|
public string $modelLabel,
|
|
public array $features,
|
|
) {
|
|
foreach ($features as $f) {
|
|
if (! $f instanceof ForecastFeature) {
|
|
throw new InvalidArgumentException('Every spec entry must implement ForecastFeature');
|
|
}
|
|
}
|
|
}
|
|
|
|
/** @return array<int, string> */
|
|
public function names(): array
|
|
{
|
|
return array_map(fn (ForecastFeature $f): string => $f->name(), $this->features);
|
|
}
|
|
|
|
public function modelVersion(): string
|
|
{
|
|
$names = $this->names();
|
|
sort($names);
|
|
$hash = substr(sha1(json_encode($names, JSON_THROW_ON_ERROR)), 0, 12);
|
|
|
|
return $this->modelLabel.'-'.$hash;
|
|
}
|
|
|
|
/** @return array{model_label: string, features: array<int, string>} */
|
|
public function toArray(): array
|
|
{
|
|
return [
|
|
'model_label' => $this->modelLabel,
|
|
'features' => $this->names(),
|
|
];
|
|
}
|
|
}
|