feat(forecasting): build calibrated weekly forecast stack with LLM overlay and volatility detector
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>
This commit is contained in:
Ovidiu U
33
app/Console/Commands/BackfillOilPrices.php
Normal file
33
app/Console/Commands/BackfillOilPrices.php
Normal file
@@ -0,0 +1,33 @@
|
||||
<?php
|
||||
|
||||
namespace App\Console\Commands;
|
||||
|
||||
use App\Services\BrentPriceFetcher;
|
||||
use App\Services\BrentPriceSources\BrentPriceFetchException;
|
||||
use Illuminate\Console\Attributes\Description;
|
||||
use Illuminate\Console\Attributes\Signature;
|
||||
use Illuminate\Console\Command;
|
||||
|
||||
#[Signature('oil:backfill {--from=2018-01-01 : ISO start date (inclusive)} {--to= : ISO end date (defaults to today, inclusive)}')]
|
||||
#[Description('One-shot backfill of historical Brent crude prices from FRED into brent_prices.')]
|
||||
class BackfillOilPrices extends Command
|
||||
{
|
||||
public function handle(BrentPriceFetcher $fetcher): int
|
||||
{
|
||||
$from = (string) $this->option('from');
|
||||
$to = (string) ($this->option('to') ?: now()->toDateString());
|
||||
|
||||
$this->info("Backfilling Brent ({$from} → {$to}) from FRED...");
|
||||
|
||||
try {
|
||||
$count = $fetcher->backfillFromFred($from, $to);
|
||||
$this->info(sprintf('Upserted %d Brent rows.', $count));
|
||||
|
||||
return self::SUCCESS;
|
||||
} catch (BrentPriceFetchException $e) {
|
||||
$this->error('FRED backfill failed: '.$e->getMessage());
|
||||
|
||||
return self::FAILURE;
|
||||
}
|
||||
}
|
||||
}
|
||||
30
app/Console/Commands/EvaluateVolatilityRegime.php
Normal file
30
app/Console/Commands/EvaluateVolatilityRegime.php
Normal file
@@ -0,0 +1,30 @@
|
||||
<?php
|
||||
|
||||
namespace App\Console\Commands;
|
||||
|
||||
use App\Services\Forecasting\VolatilityRegimeService;
|
||||
use Illuminate\Console\Attributes\Description;
|
||||
use Illuminate\Console\Attributes\Signature;
|
||||
use Illuminate\Console\Command;
|
||||
|
||||
#[Signature('forecast:evaluate-volatility')]
|
||||
#[Description('Evaluate the volatility regime triggers and update volatility_regimes accordingly. Hourly cron.')]
|
||||
class EvaluateVolatilityRegime extends Command
|
||||
{
|
||||
public function handle(VolatilityRegimeService $service): int
|
||||
{
|
||||
$regime = $service->evaluate();
|
||||
|
||||
if ($regime === null) {
|
||||
$this->info('Volatility regime: OFF');
|
||||
} else {
|
||||
$this->info(sprintf(
|
||||
'Volatility regime: ON (trigger=%s, since %s)',
|
||||
$regime->trigger,
|
||||
$regime->flipped_on_at->toIso8601String(),
|
||||
));
|
||||
}
|
||||
|
||||
return self::SUCCESS;
|
||||
}
|
||||
}
|
||||
35
app/Console/Commands/ImportBeisFuelPrices.php
Normal file
35
app/Console/Commands/ImportBeisFuelPrices.php
Normal file
@@ -0,0 +1,35 @@
|
||||
<?php
|
||||
|
||||
namespace App\Console\Commands;
|
||||
|
||||
use App\Services\Forecasting\BeisImporter;
|
||||
use Illuminate\Console\Attributes\Description;
|
||||
use Illuminate\Console\Attributes\Signature;
|
||||
use Illuminate\Console\Command;
|
||||
use Throwable;
|
||||
|
||||
#[Signature('beis:import')]
|
||||
#[Description('Pull the latest gov.uk Weekly road fuel prices CSV and upsert into weekly_pump_prices.')]
|
||||
class ImportBeisFuelPrices extends Command
|
||||
{
|
||||
public function handle(BeisImporter $importer): int
|
||||
{
|
||||
try {
|
||||
$result = $importer->import();
|
||||
} catch (Throwable $e) {
|
||||
$this->error('BEIS import failed: '.$e->getMessage());
|
||||
|
||||
return self::FAILURE;
|
||||
}
|
||||
|
||||
$this->info(sprintf(
|
||||
'Imported %d rows from %s — latest date: %s.',
|
||||
$result['parsed'],
|
||||
$result['csv_url'],
|
||||
$result['latest_date'],
|
||||
));
|
||||
$this->info('Forecast cache flushed; next API hit will retrain on the new row.');
|
||||
|
||||
return self::SUCCESS;
|
||||
}
|
||||
}
|
||||
21
app/Console/Commands/ResolveForecastOutcomes.php
Normal file
21
app/Console/Commands/ResolveForecastOutcomes.php
Normal file
@@ -0,0 +1,21 @@
|
||||
<?php
|
||||
|
||||
namespace App\Console\Commands;
|
||||
|
||||
use App\Services\Forecasting\OutcomeResolver;
|
||||
use Illuminate\Console\Attributes\Description;
|
||||
use Illuminate\Console\Attributes\Signature;
|
||||
use Illuminate\Console\Command;
|
||||
|
||||
#[Signature('forecast:resolve-outcomes')]
|
||||
#[Description('Pair past weekly forecasts with the actual ULSP from BEIS data and write rows to forecast_outcomes.')]
|
||||
class ResolveForecastOutcomes extends Command
|
||||
{
|
||||
public function handle(OutcomeResolver $resolver): int
|
||||
{
|
||||
$count = $resolver->resolvePending();
|
||||
$this->info(sprintf('Resolved %d outstanding forecast(s).', $count));
|
||||
|
||||
return self::SUCCESS;
|
||||
}
|
||||
}
|
||||
34
app/Console/Commands/RunLlmOverlay.php
Normal file
34
app/Console/Commands/RunLlmOverlay.php
Normal file
@@ -0,0 +1,34 @@
|
||||
<?php
|
||||
|
||||
namespace App\Console\Commands;
|
||||
|
||||
use App\Services\Forecasting\LlmOverlayService;
|
||||
use Illuminate\Console\Attributes\Description;
|
||||
use Illuminate\Console\Attributes\Signature;
|
||||
use Illuminate\Console\Command;
|
||||
|
||||
#[Signature('forecast:llm-overlay {--event-driven : Honor the 4h cooldown (default: false; daily 07:00 cron always runs)}')]
|
||||
#[Description('Run the daily Anthropic web-search overlay on the current weekly forecast.')]
|
||||
class RunLlmOverlay extends Command
|
||||
{
|
||||
public function handle(LlmOverlayService $service): int
|
||||
{
|
||||
$row = $service->run(eventDriven: (bool) $this->option('event-driven'));
|
||||
|
||||
if ($row === null) {
|
||||
$this->warn('LLM overlay skipped (no API key, on cooldown, or rejected for empty citations).');
|
||||
|
||||
return self::SUCCESS;
|
||||
}
|
||||
|
||||
$this->info(sprintf(
|
||||
'Stored llm_overlays #%d — direction=%s confidence=%d major_impact=%s.',
|
||||
$row->id,
|
||||
$row->direction,
|
||||
$row->confidence,
|
||||
$row->major_impact_event ? 'YES' : 'no',
|
||||
));
|
||||
|
||||
return self::SUCCESS;
|
||||
}
|
||||
}
|
||||
45
app/Models/Backtest.php
Normal file
45
app/Models/Backtest.php
Normal file
@@ -0,0 +1,45 @@
|
||||
<?php
|
||||
|
||||
namespace App\Models;
|
||||
|
||||
use Database\Factories\BacktestFactory;
|
||||
use Illuminate\Database\Eloquent\Attributes\Fillable;
|
||||
use Illuminate\Database\Eloquent\Factories\HasFactory;
|
||||
use Illuminate\Database\Eloquent\Model;
|
||||
|
||||
#[Fillable([
|
||||
'model_version',
|
||||
'features_json',
|
||||
'coefficients_json',
|
||||
'train_start',
|
||||
'train_end',
|
||||
'eval_start',
|
||||
'eval_end',
|
||||
'directional_accuracy',
|
||||
'mae_pence',
|
||||
'calibration_table',
|
||||
'leak_suspected',
|
||||
'ran_at',
|
||||
])]
|
||||
class Backtest extends Model
|
||||
{
|
||||
/** @use HasFactory<BacktestFactory> */
|
||||
use HasFactory;
|
||||
|
||||
protected function casts(): array
|
||||
{
|
||||
return [
|
||||
'features_json' => 'array',
|
||||
'coefficients_json' => 'array',
|
||||
'calibration_table' => 'array',
|
||||
'train_start' => 'date',
|
||||
'train_end' => 'date',
|
||||
'eval_start' => 'date',
|
||||
'eval_end' => 'date',
|
||||
'directional_accuracy' => 'decimal:2',
|
||||
'mae_pence' => 'decimal:2',
|
||||
'leak_suspected' => 'boolean',
|
||||
'ran_at' => 'datetime',
|
||||
];
|
||||
}
|
||||
}
|
||||
36
app/Models/ForecastOutcome.php
Normal file
36
app/Models/ForecastOutcome.php
Normal file
@@ -0,0 +1,36 @@
|
||||
<?php
|
||||
|
||||
namespace App\Models;
|
||||
|
||||
use Illuminate\Database\Eloquent\Attributes\Fillable;
|
||||
use Illuminate\Database\Eloquent\Model;
|
||||
|
||||
#[Fillable([
|
||||
'forecast_for',
|
||||
'model_version',
|
||||
'predicted_class',
|
||||
'actual_class',
|
||||
'correct',
|
||||
'abs_error_pence',
|
||||
'resolved_at',
|
||||
])]
|
||||
class ForecastOutcome extends Model
|
||||
{
|
||||
public $timestamps = false;
|
||||
|
||||
public $incrementing = false;
|
||||
|
||||
protected $primaryKey = 'forecast_for';
|
||||
|
||||
protected $keyType = 'string';
|
||||
|
||||
protected function casts(): array
|
||||
{
|
||||
return [
|
||||
'forecast_for' => 'date',
|
||||
'correct' => 'boolean',
|
||||
'abs_error_pence' => 'integer',
|
||||
'resolved_at' => 'datetime',
|
||||
];
|
||||
}
|
||||
}
|
||||
35
app/Models/LlmOverlay.php
Normal file
35
app/Models/LlmOverlay.php
Normal file
@@ -0,0 +1,35 @@
|
||||
<?php
|
||||
|
||||
namespace App\Models;
|
||||
|
||||
use Illuminate\Database\Eloquent\Attributes\Fillable;
|
||||
use Illuminate\Database\Eloquent\Model;
|
||||
|
||||
#[Fillable([
|
||||
'ran_at',
|
||||
'forecast_for_week',
|
||||
'direction',
|
||||
'confidence',
|
||||
'reasoning',
|
||||
'events_json',
|
||||
'agrees_with_ridge',
|
||||
'major_impact_event',
|
||||
'volatility_flag_on',
|
||||
'search_used',
|
||||
])]
|
||||
class LlmOverlay extends Model
|
||||
{
|
||||
protected function casts(): array
|
||||
{
|
||||
return [
|
||||
'ran_at' => 'datetime',
|
||||
'forecast_for_week' => 'date',
|
||||
'confidence' => 'integer',
|
||||
'events_json' => 'array',
|
||||
'agrees_with_ridge' => 'boolean',
|
||||
'major_impact_event' => 'boolean',
|
||||
'volatility_flag_on' => 'boolean',
|
||||
'search_used' => 'boolean',
|
||||
];
|
||||
}
|
||||
}
|
||||
30
app/Models/VolatilityRegime.php
Normal file
30
app/Models/VolatilityRegime.php
Normal file
@@ -0,0 +1,30 @@
|
||||
<?php
|
||||
|
||||
namespace App\Models;
|
||||
|
||||
use Illuminate\Database\Eloquent\Attributes\Fillable;
|
||||
use Illuminate\Database\Eloquent\Model;
|
||||
|
||||
#[Fillable([
|
||||
'flipped_on_at',
|
||||
'flipped_off_at',
|
||||
'trigger',
|
||||
'trigger_detail',
|
||||
'active',
|
||||
])]
|
||||
class VolatilityRegime extends Model
|
||||
{
|
||||
protected function casts(): array
|
||||
{
|
||||
return [
|
||||
'flipped_on_at' => 'datetime',
|
||||
'flipped_off_at' => 'datetime',
|
||||
'active' => 'boolean',
|
||||
];
|
||||
}
|
||||
|
||||
public static function currentlyActive(): ?self
|
||||
{
|
||||
return static::query()->where('active', true)->orderByDesc('flipped_on_at')->first();
|
||||
}
|
||||
}
|
||||
23
app/Models/WatchedEvent.php
Normal file
23
app/Models/WatchedEvent.php
Normal file
@@ -0,0 +1,23 @@
|
||||
<?php
|
||||
|
||||
namespace App\Models;
|
||||
|
||||
use Illuminate\Database\Eloquent\Attributes\Fillable;
|
||||
use Illuminate\Database\Eloquent\Model;
|
||||
|
||||
#[Fillable([
|
||||
'label',
|
||||
'starts_at',
|
||||
'ends_at',
|
||||
'notes',
|
||||
])]
|
||||
class WatchedEvent extends Model
|
||||
{
|
||||
protected function casts(): array
|
||||
{
|
||||
return [
|
||||
'starts_at' => 'datetime',
|
||||
'ends_at' => 'datetime',
|
||||
];
|
||||
}
|
||||
}
|
||||
30
app/Models/WeeklyForecast.php
Normal file
30
app/Models/WeeklyForecast.php
Normal file
@@ -0,0 +1,30 @@
|
||||
<?php
|
||||
|
||||
namespace App\Models;
|
||||
|
||||
use Illuminate\Database\Eloquent\Attributes\Fillable;
|
||||
use Illuminate\Database\Eloquent\Model;
|
||||
|
||||
#[Fillable([
|
||||
'forecast_for',
|
||||
'model_version',
|
||||
'direction',
|
||||
'magnitude_pence',
|
||||
'ridge_confidence',
|
||||
'flagged_duty_change',
|
||||
'reasoning',
|
||||
'generated_at',
|
||||
])]
|
||||
class WeeklyForecast extends Model
|
||||
{
|
||||
protected function casts(): array
|
||||
{
|
||||
return [
|
||||
'forecast_for' => 'date',
|
||||
'magnitude_pence' => 'integer',
|
||||
'ridge_confidence' => 'integer',
|
||||
'flagged_duty_change' => 'boolean',
|
||||
'generated_at' => 'datetime',
|
||||
];
|
||||
}
|
||||
}
|
||||
@@ -41,4 +41,24 @@ final readonly class BrentPriceFetcher
|
||||
|
||||
BrentPrice::upsert($rows, ['date'], ['price_usd']);
|
||||
}
|
||||
|
||||
/**
|
||||
* One-shot Brent backfill via FRED's observation_start/end. Used to
|
||||
* seed `brent_prices` going back to 2018 so Phase 9's volatility
|
||||
* detector and Phase 8's LLM overlay have proper context.
|
||||
*
|
||||
* @return int rows inserted/updated
|
||||
*/
|
||||
public function backfillFromFred(string $from, string $to): int
|
||||
{
|
||||
$rows = $this->fred->fetchRange($from, $to);
|
||||
|
||||
if ($rows === null) {
|
||||
throw new BrentPriceFetchException("FRED backfill ({$from} → {$to}) returned no data");
|
||||
}
|
||||
|
||||
BrentPrice::upsert($rows, ['date'], ['price_usd']);
|
||||
|
||||
return count($rows);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -21,17 +21,50 @@ final class FredBrentPriceSource
|
||||
*/
|
||||
public function fetch(): ?array
|
||||
{
|
||||
return $this->call([
|
||||
'sort_order' => 'desc',
|
||||
'limit' => 30,
|
||||
]);
|
||||
}
|
||||
|
||||
/**
|
||||
* Backfill range (inclusive). FRED's `observation_start` /
|
||||
* `observation_end` parameters expect ISO dates (YYYY-MM-DD).
|
||||
* Returns null when the range is empty (e.g. all weekends/holidays).
|
||||
*
|
||||
* @return array{date: string, price_usd: float}[]|null
|
||||
*
|
||||
* @throws BrentPriceFetchException
|
||||
*/
|
||||
public function fetchRange(string $from, string $to): ?array
|
||||
{
|
||||
return $this->call([
|
||||
'observation_start' => $from,
|
||||
'observation_end' => $to,
|
||||
'sort_order' => 'asc',
|
||||
'limit' => 100000,
|
||||
]);
|
||||
}
|
||||
|
||||
/**
|
||||
* @param array<string, scalar> $extraParams
|
||||
* @return array{date: string, price_usd: float}[]|null
|
||||
*
|
||||
* @throws BrentPriceFetchException
|
||||
*/
|
||||
private function call(array $extraParams): ?array
|
||||
{
|
||||
$params = array_merge([
|
||||
'series_id' => 'DCOILBRENTEU',
|
||||
'api_key' => config('services.fred.api_key'),
|
||||
'file_type' => 'json',
|
||||
], $extraParams);
|
||||
|
||||
try {
|
||||
$response = $this->apiLogger->send('fred', 'GET', self::URL, fn () => Http::timeout(30)
|
||||
$response = $this->apiLogger->send('fred', 'GET', self::URL, fn () => Http::timeout(60)
|
||||
->retry(3, 200, fn (Throwable $e) => $this->shouldRetry($e))
|
||||
->throw()
|
||||
->get(self::URL, [
|
||||
'series_id' => 'DCOILBRENTEU',
|
||||
'api_key' => config('services.fred.api_key'),
|
||||
'sort_order' => 'desc',
|
||||
'limit' => 30,
|
||||
'file_type' => 'json',
|
||||
]));
|
||||
->get(self::URL, $params));
|
||||
} catch (ConnectionException $e) {
|
||||
throw new BrentPriceFetchException("FRED connection failed: {$e->getMessage()}", previous: $e);
|
||||
} catch (RequestException $e) {
|
||||
|
||||
36
app/Services/Forecasting/AccuracyHistory.php
Normal file
36
app/Services/Forecasting/AccuracyHistory.php
Normal file
@@ -0,0 +1,36 @@
|
||||
<?php
|
||||
|
||||
namespace App\Services\Forecasting;
|
||||
|
||||
use Carbon\Carbon;
|
||||
use Illuminate\Support\Facades\DB;
|
||||
|
||||
/**
|
||||
* Trailing-13-week hit rate for a model_version. Read from
|
||||
* `forecast_outcomes`. Returns null when fewer than 4 outcomes are
|
||||
* available (a single bad week would otherwise dominate the ratio).
|
||||
*/
|
||||
final class AccuracyHistory
|
||||
{
|
||||
private const int WEEKS = 13;
|
||||
|
||||
private const int MIN_OUTCOMES = 4;
|
||||
|
||||
public function trailingHitRate(string $modelVersion): ?float
|
||||
{
|
||||
$cutoff = Carbon::now()->subWeeks(self::WEEKS)->toDateString();
|
||||
|
||||
$row = DB::table('forecast_outcomes')
|
||||
->where('model_version', $modelVersion)
|
||||
->where('forecast_for', '>=', $cutoff)
|
||||
->selectRaw('COUNT(*) as total, SUM(CASE WHEN correct THEN 1 ELSE 0 END) as correct')
|
||||
->first();
|
||||
|
||||
$total = (int) ($row->total ?? 0);
|
||||
if ($total < self::MIN_OUTCOMES) {
|
||||
return null;
|
||||
}
|
||||
|
||||
return (int) ($row->correct ?? 0) / $total;
|
||||
}
|
||||
}
|
||||
162
app/Services/Forecasting/BacktestRunner.php
Normal file
162
app/Services/Forecasting/BacktestRunner.php
Normal file
@@ -0,0 +1,162 @@
|
||||
<?php
|
||||
|
||||
namespace App\Services\Forecasting;
|
||||
|
||||
use App\Models\Backtest;
|
||||
use App\Services\Forecasting\Contracts\WeeklyForecastModel;
|
||||
use Carbon\CarbonInterface;
|
||||
use Illuminate\Support\Facades\DB;
|
||||
|
||||
/**
|
||||
* Runs a WeeklyForecastModel through a train/eval split and persists
|
||||
* the result to the `backtests` table.
|
||||
*
|
||||
* Pipeline:
|
||||
* 1. Generate the training and eval Monday lists from the date ranges.
|
||||
* 2. Run LeakDetector against every Monday × every feature. Refuse to
|
||||
* train if any source date is on or after a target Monday.
|
||||
* 3. Train the model.
|
||||
* 4. For each eval Monday: predict, look up actual ΔULSP from
|
||||
* `weekly_pump_prices`, score directional accuracy + abs error.
|
||||
* 5. Persist a Backtest row, return it.
|
||||
*
|
||||
* The `leak_suspected` flag is a *secondary* smell test (true when
|
||||
* directional_accuracy > 75). Primary leak defence is step 2.
|
||||
*/
|
||||
final class BacktestRunner
|
||||
{
|
||||
private const float FLAT_THRESHOLD_PENCE_X100 = 20.0; // 0.2 p/L
|
||||
|
||||
public function __construct(
|
||||
private readonly LeakDetector $leakDetector = new LeakDetector,
|
||||
) {}
|
||||
|
||||
public function run(
|
||||
WeeklyForecastModel $model,
|
||||
CarbonInterface $trainStart,
|
||||
CarbonInterface $trainEnd,
|
||||
CarbonInterface $evalStart,
|
||||
CarbonInterface $evalEnd,
|
||||
): Backtest {
|
||||
$trainingMondays = $this->mondaysBetween($trainStart, $trainEnd);
|
||||
$evalMondays = $this->mondaysBetween($evalStart, $evalEnd);
|
||||
|
||||
$spec = $model->featureSpec();
|
||||
$report = $this->leakDetector->validate($spec, [...$trainingMondays, ...$evalMondays]);
|
||||
if ($report->hasLeaks()) {
|
||||
throw new LeakDetectorException($report);
|
||||
}
|
||||
|
||||
$model->train($trainingMondays);
|
||||
|
||||
$correct = 0;
|
||||
$totalScored = 0;
|
||||
$absErrors = [];
|
||||
$bins = [];
|
||||
|
||||
foreach ($evalMondays as $monday) {
|
||||
$actualDelta = $this->actualDeltaPence($monday);
|
||||
if ($actualDelta === null) {
|
||||
continue;
|
||||
}
|
||||
|
||||
$prediction = $model->predict($monday);
|
||||
$actualDirection = $this->classifyDirection($actualDelta);
|
||||
$hit = $prediction->direction === $actualDirection;
|
||||
|
||||
$totalScored++;
|
||||
$absErrors[] = abs($prediction->magnitudePence - $actualDelta);
|
||||
if ($hit) {
|
||||
$correct++;
|
||||
}
|
||||
|
||||
$bin = $this->bucketForMagnitude($prediction->magnitudePence);
|
||||
$bins[$bin] ??= ['correct' => 0, 'total' => 0];
|
||||
$bins[$bin]['total']++;
|
||||
if ($hit) {
|
||||
$bins[$bin]['correct']++;
|
||||
}
|
||||
}
|
||||
|
||||
$directionalAccuracy = $totalScored === 0
|
||||
? null
|
||||
: round(($correct / $totalScored) * 100, 2);
|
||||
|
||||
$maePence = $absErrors === []
|
||||
? null
|
||||
: round((array_sum($absErrors) / count($absErrors)) / 100, 2);
|
||||
|
||||
$calibrationTable = [];
|
||||
foreach ($bins as $key => $b) {
|
||||
$calibrationTable[$key] = round($b['correct'] / $b['total'], 4);
|
||||
}
|
||||
|
||||
return Backtest::create([
|
||||
'model_version' => $spec->modelVersion(),
|
||||
'features_json' => $spec->toArray(),
|
||||
'coefficients_json' => $model->coefficients(),
|
||||
'train_start' => $trainStart->toDateString(),
|
||||
'train_end' => $trainEnd->toDateString(),
|
||||
'eval_start' => $evalStart->toDateString(),
|
||||
'eval_end' => $evalEnd->toDateString(),
|
||||
'directional_accuracy' => $directionalAccuracy,
|
||||
'mae_pence' => $maePence,
|
||||
'calibration_table' => $calibrationTable,
|
||||
'leak_suspected' => $directionalAccuracy !== null && $directionalAccuracy > 75.0,
|
||||
'ran_at' => now(),
|
||||
]);
|
||||
}
|
||||
|
||||
/** @return array<int, CarbonInterface> */
|
||||
private function mondaysBetween(CarbonInterface $start, CarbonInterface $end): array
|
||||
{
|
||||
$mondays = [];
|
||||
$cursor = $start->copy()->startOfDay();
|
||||
$boundary = $end->copy()->startOfDay();
|
||||
|
||||
while ($cursor->lessThanOrEqualTo($boundary)) {
|
||||
if ($cursor->dayOfWeek === CarbonInterface::MONDAY) {
|
||||
$mondays[] = $cursor->copy();
|
||||
}
|
||||
$cursor = $cursor->addDay();
|
||||
}
|
||||
|
||||
return $mondays;
|
||||
}
|
||||
|
||||
private function actualDeltaPence(CarbonInterface $targetMonday): ?float
|
||||
{
|
||||
$current = DB::table('weekly_pump_prices')
|
||||
->where('date', $targetMonday->toDateString())
|
||||
->value('ulsp_pence');
|
||||
$previous = DB::table('weekly_pump_prices')
|
||||
->where('date', $targetMonday->copy()->subDays(7)->toDateString())
|
||||
->value('ulsp_pence');
|
||||
|
||||
if ($current === null || $previous === null) {
|
||||
return null;
|
||||
}
|
||||
|
||||
return (float) ($current - $previous);
|
||||
}
|
||||
|
||||
private function classifyDirection(float $deltaPence): string
|
||||
{
|
||||
return match (true) {
|
||||
$deltaPence > self::FLAT_THRESHOLD_PENCE_X100 => 'rising',
|
||||
$deltaPence < -self::FLAT_THRESHOLD_PENCE_X100 => 'falling',
|
||||
default => 'flat',
|
||||
};
|
||||
}
|
||||
|
||||
private function bucketForMagnitude(float $magnitudePence): string
|
||||
{
|
||||
$abs = abs($magnitudePence);
|
||||
|
||||
return match (true) {
|
||||
$abs < 50.0 => '0.0-0.5p',
|
||||
$abs < 100.0 => '0.5-1.0p',
|
||||
default => '1.0p+',
|
||||
};
|
||||
}
|
||||
}
|
||||
138
app/Services/Forecasting/BeisImporter.php
Normal file
138
app/Services/Forecasting/BeisImporter.php
Normal file
@@ -0,0 +1,138 @@
|
||||
<?php
|
||||
|
||||
namespace App\Services\Forecasting;
|
||||
|
||||
use DateTime;
|
||||
use Illuminate\Support\Facades\Cache;
|
||||
use Illuminate\Support\Facades\DB;
|
||||
use Illuminate\Support\Facades\Http;
|
||||
use RuntimeException;
|
||||
|
||||
/**
|
||||
* Pulls the latest "Weekly road fuel prices (CSV) 2018 to 2026"
|
||||
* attachment from gov.uk's content API and upserts into
|
||||
* `weekly_pump_prices`.
|
||||
*
|
||||
* Idempotent: re-running on a day with no new publication is a no-op
|
||||
* (rows match by primary key `date`, content is unchanged).
|
||||
*
|
||||
* The forecast cache is busted at the end so the next API hit retrains
|
||||
* the ridge model on the fresh row.
|
||||
*/
|
||||
final class BeisImporter
|
||||
{
|
||||
private const string API_URL = 'https://www.gov.uk/api/content/government/statistics/weekly-road-fuel-prices';
|
||||
|
||||
private const string ATTACHMENT_TITLE = 'Weekly road fuel prices (CSV) 2018 to 2026';
|
||||
|
||||
/**
|
||||
* @return array{
|
||||
* csv_url: string,
|
||||
* parsed: int,
|
||||
* upserted: int,
|
||||
* latest_date: string,
|
||||
* }
|
||||
*/
|
||||
public function import(): array
|
||||
{
|
||||
$url = $this->resolveCsvUrl();
|
||||
$csv = $this->downloadCsv($url);
|
||||
$rows = $this->parse($csv);
|
||||
|
||||
if ($rows === []) {
|
||||
throw new RuntimeException('BEIS CSV parsed empty — check delimiter / encoding');
|
||||
}
|
||||
|
||||
DB::table('weekly_pump_prices')->upsert(
|
||||
$rows,
|
||||
['date'],
|
||||
['ulsp_pence', 'ulsd_pence', 'ulsp_duty_pence', 'ulsd_duty_pence', 'ulsp_vat_pct', 'ulsd_vat_pct'],
|
||||
);
|
||||
|
||||
Cache::flush();
|
||||
|
||||
$latest = (string) collect($rows)->pluck('date')->sortDesc()->first();
|
||||
|
||||
return [
|
||||
'csv_url' => $url,
|
||||
'parsed' => count($rows),
|
||||
'upserted' => count($rows),
|
||||
'latest_date' => $latest,
|
||||
];
|
||||
}
|
||||
|
||||
private function resolveCsvUrl(): string
|
||||
{
|
||||
$response = Http::timeout(15)->acceptJson()->get(self::API_URL);
|
||||
$response->throw();
|
||||
|
||||
$attachments = $response->json('details.attachments', []);
|
||||
foreach ($attachments as $a) {
|
||||
if (($a['title'] ?? null) === self::ATTACHMENT_TITLE) {
|
||||
$url = $a['url'] ?? null;
|
||||
if (! is_string($url) || $url === '') {
|
||||
throw new RuntimeException('BEIS attachment had empty URL');
|
||||
}
|
||||
|
||||
return $url;
|
||||
}
|
||||
}
|
||||
|
||||
throw new RuntimeException(sprintf(
|
||||
'gov.uk content API did not return an attachment titled %s',
|
||||
self::ATTACHMENT_TITLE,
|
||||
));
|
||||
}
|
||||
|
||||
private function downloadCsv(string $url): string
|
||||
{
|
||||
$response = Http::timeout(60)->get($url);
|
||||
$response->throw();
|
||||
|
||||
return $response->body();
|
||||
}
|
||||
|
||||
/**
|
||||
* @return array<int, array<string, int|string>>
|
||||
*/
|
||||
private function parse(string $csv): array
|
||||
{
|
||||
$rows = [];
|
||||
$lines = preg_split('/\r\n|\r|\n/', $csv);
|
||||
if ($lines === false || count($lines) < 2) {
|
||||
return [];
|
||||
}
|
||||
|
||||
// Skip header.
|
||||
array_shift($lines);
|
||||
|
||||
foreach ($lines as $line) {
|
||||
$line = trim($line);
|
||||
if ($line === '') {
|
||||
continue;
|
||||
}
|
||||
|
||||
$cols = str_getcsv($line, escape: '\\');
|
||||
if (count($cols) < 7) {
|
||||
continue;
|
||||
}
|
||||
|
||||
$date = DateTime::createFromFormat('d/m/Y', trim($cols[0]));
|
||||
if ($date === false) {
|
||||
continue;
|
||||
}
|
||||
|
||||
$rows[] = [
|
||||
'date' => $date->format('Y-m-d'),
|
||||
'ulsp_pence' => (int) round(((float) $cols[1]) * 100),
|
||||
'ulsd_pence' => (int) round(((float) $cols[2]) * 100),
|
||||
'ulsp_duty_pence' => (int) round(((float) $cols[3]) * 100),
|
||||
'ulsd_duty_pence' => (int) round(((float) $cols[4]) * 100),
|
||||
'ulsp_vat_pct' => (int) $cols[5],
|
||||
'ulsd_vat_pct' => (int) $cols[6],
|
||||
];
|
||||
}
|
||||
|
||||
return $rows;
|
||||
}
|
||||
}
|
||||
33
app/Services/Forecasting/Contracts/ForecastFeature.php
Normal file
33
app/Services/Forecasting/Contracts/ForecastFeature.php
Normal file
@@ -0,0 +1,33 @@
|
||||
<?php
|
||||
|
||||
namespace App\Services\Forecasting\Contracts;
|
||||
|
||||
use Carbon\CarbonInterface;
|
||||
|
||||
/**
|
||||
* A single feature in a weekly forecast model.
|
||||
*
|
||||
* Implementations must be deterministic for a given target Monday and
|
||||
* must declare every source date they read so the LeakDetector can
|
||||
* verify no source date is on or after the target Monday.
|
||||
*/
|
||||
interface ForecastFeature
|
||||
{
|
||||
public function name(): string;
|
||||
|
||||
/**
|
||||
* Feature value at $targetMonday, or null when an upstream data
|
||||
* row is missing. Caller is expected to drop the entire feature
|
||||
* vector when any single feature is null.
|
||||
*/
|
||||
public function valueFor(CarbonInterface $targetMonday): ?float;
|
||||
|
||||
/**
|
||||
* Every date this feature reads from any data source for a given
|
||||
* target Monday. The LeakDetector requires every returned date to
|
||||
* be strictly before $targetMonday.
|
||||
*
|
||||
* @return array<int, CarbonInterface>
|
||||
*/
|
||||
public function sourceDates(CarbonInterface $targetMonday): array;
|
||||
}
|
||||
40
app/Services/Forecasting/Contracts/WeeklyForecastModel.php
Normal file
40
app/Services/Forecasting/Contracts/WeeklyForecastModel.php
Normal file
@@ -0,0 +1,40 @@
|
||||
<?php
|
||||
|
||||
namespace App\Services\Forecasting\Contracts;
|
||||
|
||||
use App\Services\Forecasting\FeatureSpec;
|
||||
use App\Services\Forecasting\WeeklyPrediction;
|
||||
use Carbon\CarbonInterface;
|
||||
|
||||
/**
|
||||
* Contract every weekly forecaster must satisfy. The harness consumes
|
||||
* this interface — naive baselines, ridge regression, and any future
|
||||
* model all implement it.
|
||||
*/
|
||||
interface WeeklyForecastModel
|
||||
{
|
||||
public function featureSpec(): FeatureSpec;
|
||||
|
||||
/**
|
||||
* Train on the supplied weeks. Implementations may store coefficients
|
||||
* internally for the subsequent predict() calls.
|
||||
*
|
||||
* @param array<int, CarbonInterface> $trainingMondays
|
||||
*/
|
||||
public function train(array $trainingMondays): void;
|
||||
|
||||
/**
|
||||
* Predict ΔULSP for the week starting $targetMonday. Returned value
|
||||
* is in pence × 100 (integer-ish, but typed float for fractional
|
||||
* predictions).
|
||||
*/
|
||||
public function predict(CarbonInterface $targetMonday): WeeklyPrediction;
|
||||
|
||||
/**
|
||||
* Coefficients in a JSON-serialisable form, or null for non-parametric
|
||||
* models like the naive baseline.
|
||||
*
|
||||
* @return array<string, mixed>|null
|
||||
*/
|
||||
public function coefficients(): ?array;
|
||||
}
|
||||
45
app/Services/Forecasting/DutyChangeDetector.php
Normal file
45
app/Services/Forecasting/DutyChangeDetector.php
Normal file
@@ -0,0 +1,45 @@
|
||||
<?php
|
||||
|
||||
namespace App\Services\Forecasting;
|
||||
|
||||
use Carbon\CarbonInterface;
|
||||
use Illuminate\Support\Facades\DB;
|
||||
|
||||
/**
|
||||
* Flags forecast weeks that fall within ±4 weeks of a known UK fuel
|
||||
* duty change. Per the spec calibration override (n=1), the displayed
|
||||
* confidence on flagged weeks is halved and the reasoning text says so.
|
||||
*/
|
||||
final class DutyChangeDetector
|
||||
{
|
||||
public const int FLAG_RADIUS_WEEKS = 4;
|
||||
|
||||
/**
|
||||
* Returns true if the target Monday is within ±4 weeks of any
|
||||
* change in `weekly_pump_prices.ulsp_duty_pence`.
|
||||
*/
|
||||
public function isAdjacent(CarbonInterface $targetMonday): bool
|
||||
{
|
||||
$start = $targetMonday->copy()->subWeeks(self::FLAG_RADIUS_WEEKS)->toDateString();
|
||||
$end = $targetMonday->copy()->addWeeks(self::FLAG_RADIUS_WEEKS)->toDateString();
|
||||
|
||||
$rows = DB::table('weekly_pump_prices')
|
||||
->whereBetween('date', [$start, $end])
|
||||
->orderBy('date')
|
||||
->get(['date', 'ulsp_duty_pence']);
|
||||
|
||||
if ($rows->count() < 2) {
|
||||
return false;
|
||||
}
|
||||
|
||||
$previous = null;
|
||||
foreach ($rows as $r) {
|
||||
if ($previous !== null && (int) $r->ulsp_duty_pence !== $previous) {
|
||||
return true;
|
||||
}
|
||||
$previous = (int) $r->ulsp_duty_pence;
|
||||
}
|
||||
|
||||
return false;
|
||||
}
|
||||
}
|
||||
54
app/Services/Forecasting/FeatureSpec.php
Normal file
54
app/Services/Forecasting/FeatureSpec.php
Normal file
@@ -0,0 +1,54 @@
|
||||
<?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(),
|
||||
];
|
||||
}
|
||||
}
|
||||
50
app/Services/Forecasting/Features/DeltaUlsdLag.php
Normal file
50
app/Services/Forecasting/Features/DeltaUlsdLag.php
Normal file
@@ -0,0 +1,50 @@
|
||||
<?php
|
||||
|
||||
namespace App\Services\Forecasting\Features;
|
||||
|
||||
use App\Services\Forecasting\Contracts\ForecastFeature;
|
||||
use App\Services\Forecasting\WeeklyPumpPriceLoader;
|
||||
use Carbon\CarbonInterface;
|
||||
|
||||
/**
|
||||
* ΔULSD at lag L. Cross-fuel signal — diesel often leads/lags petrol
|
||||
* during oil shocks. Same lag semantics as DeltaUlspLag.
|
||||
*/
|
||||
final class DeltaUlsdLag implements ForecastFeature
|
||||
{
|
||||
public function __construct(
|
||||
private readonly WeeklyPumpPriceLoader $loader,
|
||||
public readonly int $lag,
|
||||
) {}
|
||||
|
||||
public function name(): string
|
||||
{
|
||||
return 'delta_ulsd_lag_'.$this->lag;
|
||||
}
|
||||
|
||||
public function valueFor(CarbonInterface $targetMonday): ?float
|
||||
{
|
||||
[$newer, $older] = $this->dates($targetMonday);
|
||||
$a = $this->loader->ulsdPence($newer->toDateString());
|
||||
$b = $this->loader->ulsdPence($older->toDateString());
|
||||
if ($a === null || $b === null) {
|
||||
return null;
|
||||
}
|
||||
|
||||
return (float) ($a - $b);
|
||||
}
|
||||
|
||||
public function sourceDates(CarbonInterface $targetMonday): array
|
||||
{
|
||||
return $this->dates($targetMonday);
|
||||
}
|
||||
|
||||
/** @return array{0: CarbonInterface, 1: CarbonInterface} */
|
||||
private function dates(CarbonInterface $targetMonday): array
|
||||
{
|
||||
return [
|
||||
$targetMonday->copy()->subDays(7 * ($this->lag + 1)),
|
||||
$targetMonday->copy()->subDays(7 * ($this->lag + 2)),
|
||||
];
|
||||
}
|
||||
}
|
||||
57
app/Services/Forecasting/Features/DeltaUlspLag.php
Normal file
57
app/Services/Forecasting/Features/DeltaUlspLag.php
Normal file
@@ -0,0 +1,57 @@
|
||||
<?php
|
||||
|
||||
namespace App\Services\Forecasting\Features;
|
||||
|
||||
use App\Services\Forecasting\Contracts\ForecastFeature;
|
||||
use App\Services\Forecasting\WeeklyPumpPriceLoader;
|
||||
use Carbon\CarbonInterface;
|
||||
|
||||
/**
|
||||
* ΔULSP at lag L: the change in petrol price that ended L weeks before
|
||||
* the most recent observation, in pence × 100.
|
||||
*
|
||||
* lag=0 → ULSP[t-7d] − ULSP[t-14d] (1-week momentum)
|
||||
* lag=1 → ULSP[t-14d] − ULSP[t-21d] (2-week momentum)
|
||||
* lag=3 → ULSP[t-28d] − ULSP[t-35d] (4-week momentum)
|
||||
*
|
||||
* Source dates are always strictly before the target Monday — the
|
||||
* earliest is target − 7×(lag+1), the older is target − 7×(lag+2).
|
||||
*/
|
||||
final class DeltaUlspLag implements ForecastFeature
|
||||
{
|
||||
public function __construct(
|
||||
private readonly WeeklyPumpPriceLoader $loader,
|
||||
public readonly int $lag,
|
||||
) {}
|
||||
|
||||
public function name(): string
|
||||
{
|
||||
return 'delta_ulsp_lag_'.$this->lag;
|
||||
}
|
||||
|
||||
public function valueFor(CarbonInterface $targetMonday): ?float
|
||||
{
|
||||
[$newer, $older] = $this->dates($targetMonday);
|
||||
$a = $this->loader->ulspPence($newer->toDateString());
|
||||
$b = $this->loader->ulspPence($older->toDateString());
|
||||
if ($a === null || $b === null) {
|
||||
return null;
|
||||
}
|
||||
|
||||
return (float) ($a - $b);
|
||||
}
|
||||
|
||||
public function sourceDates(CarbonInterface $targetMonday): array
|
||||
{
|
||||
return $this->dates($targetMonday);
|
||||
}
|
||||
|
||||
/** @return array{0: CarbonInterface, 1: CarbonInterface} */
|
||||
private function dates(CarbonInterface $targetMonday): array
|
||||
{
|
||||
return [
|
||||
$targetMonday->copy()->subDays(7 * ($this->lag + 1)),
|
||||
$targetMonday->copy()->subDays(7 * ($this->lag + 2)),
|
||||
];
|
||||
}
|
||||
}
|
||||
32
app/Services/Forecasting/Features/IsPreBankHoliday.php
Normal file
32
app/Services/Forecasting/Features/IsPreBankHoliday.php
Normal file
@@ -0,0 +1,32 @@
|
||||
<?php
|
||||
|
||||
namespace App\Services\Forecasting\Features;
|
||||
|
||||
use App\Services\Forecasting\Contracts\ForecastFeature;
|
||||
use App\Services\Forecasting\UkBankHolidays;
|
||||
use Carbon\CarbonInterface;
|
||||
|
||||
/**
|
||||
* 1.0 if any UK bank holiday falls in the 7-day window starting at the
|
||||
* target Monday; 0.0 otherwise.
|
||||
*
|
||||
* Captures pre-holiday demand spikes (Easter, summer, Christmas
|
||||
* weekend). Pure calendar — no DB read, sourceDates is empty.
|
||||
*/
|
||||
final class IsPreBankHoliday implements ForecastFeature
|
||||
{
|
||||
public function name(): string
|
||||
{
|
||||
return 'is_pre_bank_holiday';
|
||||
}
|
||||
|
||||
public function valueFor(CarbonInterface $targetMonday): ?float
|
||||
{
|
||||
return UkBankHolidays::holidayWithin($targetMonday, 7) ? 1.0 : 0.0;
|
||||
}
|
||||
|
||||
public function sourceDates(CarbonInterface $targetMonday): array
|
||||
{
|
||||
return [];
|
||||
}
|
||||
}
|
||||
57
app/Services/Forecasting/Features/UlspMinusMa8.php
Normal file
57
app/Services/Forecasting/Features/UlspMinusMa8.php
Normal file
@@ -0,0 +1,57 @@
|
||||
<?php
|
||||
|
||||
namespace App\Services\Forecasting\Features;
|
||||
|
||||
use App\Services\Forecasting\Contracts\ForecastFeature;
|
||||
use App\Services\Forecasting\WeeklyPumpPriceLoader;
|
||||
use Carbon\CarbonInterface;
|
||||
|
||||
/**
|
||||
* Mean-reversion term: gap between the most recent observable ULSP
|
||||
* (target − 7d) and its 8-week trailing mean (target − 7d through
|
||||
* target − 56d, inclusive).
|
||||
*
|
||||
* Empirically this is the single most useful 1-week-ahead feature for
|
||||
* UK pump prices — pump retailers tend to revert to their recent
|
||||
* trailing mean, especially after sudden moves.
|
||||
*/
|
||||
final class UlspMinusMa8 implements ForecastFeature
|
||||
{
|
||||
private const int WINDOW_WEEKS = 8;
|
||||
|
||||
public function __construct(
|
||||
private readonly WeeklyPumpPriceLoader $loader,
|
||||
) {}
|
||||
|
||||
public function name(): string
|
||||
{
|
||||
return 'ulsp_minus_ma8';
|
||||
}
|
||||
|
||||
public function valueFor(CarbonInterface $targetMonday): ?float
|
||||
{
|
||||
$values = [];
|
||||
foreach ($this->sourceDates($targetMonday) as $d) {
|
||||
$v = $this->loader->ulspPence($d->toDateString());
|
||||
if ($v === null) {
|
||||
return null;
|
||||
}
|
||||
$values[] = (float) $v;
|
||||
}
|
||||
|
||||
$latest = $values[0];
|
||||
$mean = array_sum($values) / count($values);
|
||||
|
||||
return $latest - $mean;
|
||||
}
|
||||
|
||||
public function sourceDates(CarbonInterface $targetMonday): array
|
||||
{
|
||||
$dates = [];
|
||||
for ($w = 1; $w <= self::WINDOW_WEEKS; $w++) {
|
||||
$dates[] = $targetMonday->copy()->subDays(7 * $w);
|
||||
}
|
||||
|
||||
return $dates;
|
||||
}
|
||||
}
|
||||
43
app/Services/Forecasting/Features/WeekOfYearTrig.php
Normal file
43
app/Services/Forecasting/Features/WeekOfYearTrig.php
Normal file
@@ -0,0 +1,43 @@
|
||||
<?php
|
||||
|
||||
namespace App\Services\Forecasting\Features;
|
||||
|
||||
use App\Services\Forecasting\Contracts\ForecastFeature;
|
||||
use Carbon\CarbonInterface;
|
||||
use InvalidArgumentException;
|
||||
|
||||
/**
|
||||
* Cyclic week-of-year encoding. Two instances expected, one for sin and
|
||||
* one for cos. Together they let the linear model fit a smooth annual
|
||||
* seasonal cycle without a 52-way one-hot expansion.
|
||||
*
|
||||
* This is a pure calendar feature — no DB read. sourceDates is empty,
|
||||
* so the LeakDetector has nothing to validate against.
|
||||
*/
|
||||
final class WeekOfYearTrig implements ForecastFeature
|
||||
{
|
||||
public function __construct(public readonly string $component)
|
||||
{
|
||||
if (! in_array($component, ['sin', 'cos'], true)) {
|
||||
throw new InvalidArgumentException('component must be "sin" or "cos"');
|
||||
}
|
||||
}
|
||||
|
||||
public function name(): string
|
||||
{
|
||||
return 'week_of_year_'.$this->component;
|
||||
}
|
||||
|
||||
public function valueFor(CarbonInterface $targetMonday): ?float
|
||||
{
|
||||
$week = (int) $targetMonday->format('W'); // ISO week number 1..53
|
||||
$angle = 2.0 * M_PI * $week / 52.0;
|
||||
|
||||
return $this->component === 'sin' ? sin($angle) : cos($angle);
|
||||
}
|
||||
|
||||
public function sourceDates(CarbonInterface $targetMonday): array
|
||||
{
|
||||
return [];
|
||||
}
|
||||
}
|
||||
41
app/Services/Forecasting/LeakDetector.php
Normal file
41
app/Services/Forecasting/LeakDetector.php
Normal file
@@ -0,0 +1,41 @@
|
||||
<?php
|
||||
|
||||
namespace App\Services\Forecasting;
|
||||
|
||||
use Carbon\CarbonInterface;
|
||||
|
||||
/**
|
||||
* Structural time-leak detector.
|
||||
*
|
||||
* For every (training week, feature) pair, verifies that every source
|
||||
* date the feature reads is strictly before the target Monday. A
|
||||
* source date on or after the target Monday is leakage and the
|
||||
* backtest harness must refuse to run.
|
||||
*
|
||||
* This is the *primary* leak defence. The accuracy>75% smell test on
|
||||
* the resulting backtest is a secondary check.
|
||||
*/
|
||||
final class LeakDetector
|
||||
{
|
||||
/** @param array<int, CarbonInterface> $trainingMondays */
|
||||
public function validate(FeatureSpec $spec, array $trainingMondays): LeakReport
|
||||
{
|
||||
$leaks = [];
|
||||
|
||||
foreach ($trainingMondays as $target) {
|
||||
foreach ($spec->features as $feature) {
|
||||
foreach ($feature->sourceDates($target) as $source) {
|
||||
if ($source->greaterThanOrEqualTo($target)) {
|
||||
$leaks[] = [
|
||||
'feature' => $feature->name(),
|
||||
'target_monday' => $target->toDateString(),
|
||||
'source_date' => $source->toDateString(),
|
||||
];
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return new LeakReport($leaks);
|
||||
}
|
||||
}
|
||||
19
app/Services/Forecasting/LeakDetectorException.php
Normal file
19
app/Services/Forecasting/LeakDetectorException.php
Normal file
@@ -0,0 +1,19 @@
|
||||
<?php
|
||||
|
||||
namespace App\Services\Forecasting;
|
||||
|
||||
use RuntimeException;
|
||||
|
||||
final class LeakDetectorException extends RuntimeException
|
||||
{
|
||||
public function __construct(public readonly LeakReport $report)
|
||||
{
|
||||
$count = count($report->leaks);
|
||||
$first = $report->leaks[0] ?? null;
|
||||
$sample = $first === null
|
||||
? ''
|
||||
: sprintf(' First: feature "%s" reads %s for target %s.', $first['feature'], $first['source_date'], $first['target_monday']);
|
||||
|
||||
parent::__construct(sprintf('Structural time leak detected in %d feature value(s).%s', $count, $sample));
|
||||
}
|
||||
}
|
||||
20
app/Services/Forecasting/LeakReport.php
Normal file
20
app/Services/Forecasting/LeakReport.php
Normal file
@@ -0,0 +1,20 @@
|
||||
<?php
|
||||
|
||||
namespace App\Services\Forecasting;
|
||||
|
||||
/**
|
||||
* Result of a LeakDetector::validate() run.
|
||||
*
|
||||
* Each entry in $leaks is shape:
|
||||
* { feature: string, target_monday: 'Y-m-d', source_date: 'Y-m-d' }
|
||||
*/
|
||||
final readonly class LeakReport
|
||||
{
|
||||
/** @param array<int, array{feature: string, target_monday: string, source_date: string}> $leaks */
|
||||
public function __construct(public array $leaks) {}
|
||||
|
||||
public function hasLeaks(): bool
|
||||
{
|
||||
return $this->leaks !== [];
|
||||
}
|
||||
}
|
||||
200
app/Services/Forecasting/LinearAlgebra.php
Normal file
200
app/Services/Forecasting/LinearAlgebra.php
Normal file
@@ -0,0 +1,200 @@
|
||||
<?php
|
||||
|
||||
namespace App\Services\Forecasting;
|
||||
|
||||
use InvalidArgumentException;
|
||||
use RuntimeException;
|
||||
|
||||
/**
|
||||
* Pure-PHP linear algebra used by RidgeRegressionModel.
|
||||
*
|
||||
* Matrices are array<int, array<int, float>>. Vectors are array<int, float>.
|
||||
* Sized for the v1 ridge model (435 × 8); Gauss–Jordan with partial
|
||||
* pivoting is plenty for inverting the 8 × 8 normal-equation matrix.
|
||||
*/
|
||||
final class LinearAlgebra
|
||||
{
|
||||
/**
|
||||
* Transpose. m is rows × cols → result is cols × rows.
|
||||
*
|
||||
* @param array<int, array<int, float>> $m
|
||||
* @return array<int, array<int, float>>
|
||||
*/
|
||||
public static function transpose(array $m): array
|
||||
{
|
||||
$rows = count($m);
|
||||
if ($rows === 0) {
|
||||
return [];
|
||||
}
|
||||
$cols = count($m[0]);
|
||||
$out = array_fill(0, $cols, array_fill(0, $rows, 0.0));
|
||||
for ($i = 0; $i < $rows; $i++) {
|
||||
for ($j = 0; $j < $cols; $j++) {
|
||||
$out[$j][$i] = $m[$i][$j];
|
||||
}
|
||||
}
|
||||
|
||||
return $out;
|
||||
}
|
||||
|
||||
/**
|
||||
* Matrix multiply. a (r×k) * b (k×c) → r×c.
|
||||
*
|
||||
* @param array<int, array<int, float>> $a
|
||||
* @param array<int, array<int, float>> $b
|
||||
* @return array<int, array<int, float>>
|
||||
*/
|
||||
public static function multiply(array $a, array $b): array
|
||||
{
|
||||
$r = count($a);
|
||||
$k = count($a[0] ?? []);
|
||||
$c = count($b[0] ?? []);
|
||||
if (count($b) !== $k) {
|
||||
throw new InvalidArgumentException('Matrix multiply dimension mismatch');
|
||||
}
|
||||
$out = array_fill(0, $r, array_fill(0, $c, 0.0));
|
||||
for ($i = 0; $i < $r; $i++) {
|
||||
for ($j = 0; $j < $c; $j++) {
|
||||
$sum = 0.0;
|
||||
for ($p = 0; $p < $k; $p++) {
|
||||
$sum += $a[$i][$p] * $b[$p][$j];
|
||||
}
|
||||
$out[$i][$j] = $sum;
|
||||
}
|
||||
}
|
||||
|
||||
return $out;
|
||||
}
|
||||
|
||||
/**
|
||||
* Matrix × vector. a (r×k) * v (k) → r-vector.
|
||||
*
|
||||
* @param array<int, array<int, float>> $a
|
||||
* @param array<int, float> $v
|
||||
* @return array<int, float>
|
||||
*/
|
||||
public static function multiplyVector(array $a, array $v): array
|
||||
{
|
||||
$r = count($a);
|
||||
$k = count($v);
|
||||
if (count($a[0] ?? []) !== $k) {
|
||||
throw new InvalidArgumentException('Matrix × vector dimension mismatch');
|
||||
}
|
||||
$out = array_fill(0, $r, 0.0);
|
||||
for ($i = 0; $i < $r; $i++) {
|
||||
$sum = 0.0;
|
||||
for ($p = 0; $p < $k; $p++) {
|
||||
$sum += $a[$i][$p] * $v[$p];
|
||||
}
|
||||
$out[$i] = $sum;
|
||||
}
|
||||
|
||||
return $out;
|
||||
}
|
||||
|
||||
/**
|
||||
* Identity matrix of size n.
|
||||
*
|
||||
* @return array<int, array<int, float>>
|
||||
*/
|
||||
public static function identity(int $n): array
|
||||
{
|
||||
$out = array_fill(0, $n, array_fill(0, $n, 0.0));
|
||||
for ($i = 0; $i < $n; $i++) {
|
||||
$out[$i][$i] = 1.0;
|
||||
}
|
||||
|
||||
return $out;
|
||||
}
|
||||
|
||||
/**
|
||||
* Solve A x = b using Gauss–Jordan elimination with partial pivoting.
|
||||
* A is square n×n. Returns x as an n-vector.
|
||||
*
|
||||
* @param array<int, array<int, float>> $A
|
||||
* @param array<int, float> $b
|
||||
* @return array<int, float>
|
||||
*/
|
||||
public static function solve(array $A, array $b): array
|
||||
{
|
||||
$n = count($A);
|
||||
if (count($b) !== $n) {
|
||||
throw new InvalidArgumentException('solve: RHS dimension mismatch');
|
||||
}
|
||||
// Build augmented matrix.
|
||||
$aug = [];
|
||||
for ($i = 0; $i < $n; $i++) {
|
||||
$aug[$i] = array_merge($A[$i], [$b[$i]]);
|
||||
}
|
||||
|
||||
for ($col = 0; $col < $n; $col++) {
|
||||
// Partial pivot: find row with largest |value| in this column.
|
||||
$pivot = $col;
|
||||
$best = abs($aug[$col][$col]);
|
||||
for ($r = $col + 1; $r < $n; $r++) {
|
||||
$v = abs($aug[$r][$col]);
|
||||
if ($v > $best) {
|
||||
$best = $v;
|
||||
$pivot = $r;
|
||||
}
|
||||
}
|
||||
if ($best < 1e-12) {
|
||||
throw new RuntimeException('solve: matrix is singular or near-singular');
|
||||
}
|
||||
if ($pivot !== $col) {
|
||||
[$aug[$col], $aug[$pivot]] = [$aug[$pivot], $aug[$col]];
|
||||
}
|
||||
// Normalise pivot row.
|
||||
$div = $aug[$col][$col];
|
||||
for ($j = 0; $j <= $n; $j++) {
|
||||
$aug[$col][$j] /= $div;
|
||||
}
|
||||
// Eliminate this column from every other row.
|
||||
for ($r = 0; $r < $n; $r++) {
|
||||
if ($r === $col) {
|
||||
continue;
|
||||
}
|
||||
$factor = $aug[$r][$col];
|
||||
if ($factor === 0.0) {
|
||||
continue;
|
||||
}
|
||||
for ($j = 0; $j <= $n; $j++) {
|
||||
$aug[$r][$j] -= $factor * $aug[$col][$j];
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
$x = array_fill(0, $n, 0.0);
|
||||
for ($i = 0; $i < $n; $i++) {
|
||||
$x[$i] = $aug[$i][$n];
|
||||
}
|
||||
|
||||
return $x;
|
||||
}
|
||||
|
||||
/**
|
||||
* Ridge solve: β = (XᵀX + λI) ⁻¹ Xᵀy.
|
||||
*
|
||||
* λ is applied to all coefficients. Caller should standardise X and
|
||||
* centre y before calling, then add intercept back externally — the
|
||||
* intercept must NOT be regularised.
|
||||
*
|
||||
* @param array<int, array<int, float>> $X
|
||||
* @param array<int, float> $y
|
||||
* @return array<int, float>
|
||||
*/
|
||||
public static function ridgeSolve(array $X, array $y, float $lambda): array
|
||||
{
|
||||
$Xt = self::transpose($X);
|
||||
$XtX = self::multiply($Xt, $X);
|
||||
|
||||
$n = count($XtX);
|
||||
for ($i = 0; $i < $n; $i++) {
|
||||
$XtX[$i][$i] += $lambda;
|
||||
}
|
||||
|
||||
$Xty = self::multiplyVector($Xt, $y);
|
||||
|
||||
return self::solve($XtX, $Xty);
|
||||
}
|
||||
}
|
||||
374
app/Services/Forecasting/LlmOverlayService.php
Normal file
374
app/Services/Forecasting/LlmOverlayService.php
Normal file
@@ -0,0 +1,374 @@
|
||||
<?php
|
||||
|
||||
namespace App\Services\Forecasting;
|
||||
|
||||
use App\Models\BrentPrice;
|
||||
use App\Models\LlmOverlay;
|
||||
use App\Models\VolatilityRegime;
|
||||
use App\Services\ApiLogger;
|
||||
use Carbon\CarbonInterface;
|
||||
use Illuminate\Support\Facades\DB;
|
||||
use Illuminate\Support\Facades\Http;
|
||||
use Illuminate\Support\Facades\Log;
|
||||
use Throwable;
|
||||
|
||||
/**
|
||||
* Layer 4 — daily news-aware overlay on the calibrated ridge forecast.
|
||||
*
|
||||
* Calls Anthropic Haiku with the web_search tool, then forces a
|
||||
* submit_overlay tool call to get structured output. Cites events with
|
||||
* URLs; URLs are verified before storing. Empty citations → rejection.
|
||||
*
|
||||
* Read-only with respect to the volatility flag — Layer 4 writes its
|
||||
* `llm_overlays` row; Layer 5's hourly cron picks it up and decides
|
||||
* whether to flip the regime.
|
||||
*/
|
||||
final class LlmOverlayService
|
||||
{
|
||||
private const string URL = 'https://api.anthropic.com/v1/messages';
|
||||
|
||||
private const int CONFIDENCE_CAP = 75;
|
||||
|
||||
private const int COOLDOWN_HOURS = 4;
|
||||
|
||||
public function __construct(
|
||||
private readonly ApiLogger $apiLogger,
|
||||
private readonly WeeklyForecastService $weeklyForecast,
|
||||
) {}
|
||||
|
||||
/**
|
||||
* Run an overlay generation. $eventDriven=true respects the 4-hour
|
||||
* cooldown; the daily 07:00 cron passes false to always run.
|
||||
*/
|
||||
public function run(bool $eventDriven = false): ?LlmOverlay
|
||||
{
|
||||
if ($this->apiKey() === null) {
|
||||
Log::info('LlmOverlayService: no ANTHROPIC_API_KEY, skipping');
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
if ($eventDriven && $this->onCooldown()) {
|
||||
return null;
|
||||
}
|
||||
|
||||
$forecast = $this->weeklyForecast->currentForecast();
|
||||
$context = $this->buildContext($forecast);
|
||||
|
||||
$rawResult = $this->callAnthropic($context);
|
||||
if ($rawResult === null) {
|
||||
return null;
|
||||
}
|
||||
|
||||
$verifiedEvents = $this->verifyCitedUrls($rawResult['events_cited'] ?? []);
|
||||
if ($verifiedEvents === []) {
|
||||
Log::warning('LlmOverlayService: no verified citations, rejecting overlay');
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
$confidence = max(0, min(self::CONFIDENCE_CAP, (int) ($rawResult['confidence'] ?? 0)));
|
||||
$direction = $rawResult['direction'] ?? 'flat';
|
||||
$agreesWithRidge = $direction === $this->ridgeDirection($forecast['predicted_direction']);
|
||||
|
||||
return LlmOverlay::query()->create([
|
||||
'ran_at' => now(),
|
||||
'forecast_for_week' => $this->upcomingMondayDateString(),
|
||||
'direction' => $direction,
|
||||
'confidence' => $confidence,
|
||||
'reasoning' => (string) ($rawResult['reasoning_short'] ?? ''),
|
||||
'events_json' => $verifiedEvents,
|
||||
'agrees_with_ridge' => $agreesWithRidge,
|
||||
'major_impact_event' => (bool) ($rawResult['major_impact_event'] ?? false),
|
||||
'volatility_flag_on' => VolatilityRegime::currentlyActive() !== null,
|
||||
'search_used' => true,
|
||||
]);
|
||||
}
|
||||
|
||||
private function onCooldown(): bool
|
||||
{
|
||||
$latest = LlmOverlay::query()->orderByDesc('ran_at')->first();
|
||||
|
||||
return $latest !== null
|
||||
&& $latest->ran_at->greaterThanOrEqualTo(now()->subHours(self::COOLDOWN_HOURS));
|
||||
}
|
||||
|
||||
/** @return array<string, mixed> */
|
||||
private function buildContext(array $forecast): array
|
||||
{
|
||||
$ulspWeekly = DB::table('weekly_pump_prices')
|
||||
->orderByDesc('date')
|
||||
->limit(8)
|
||||
->get(['date', 'ulsp_pence'])
|
||||
->reverse()
|
||||
->map(fn ($r): array => ['date' => (string) $r->date, 'ulsp_pence' => round((int) $r->ulsp_pence / 100, 1)])
|
||||
->values()
|
||||
->all();
|
||||
|
||||
$brentRecent = BrentPrice::query()
|
||||
->orderByDesc('date')
|
||||
->limit(14)
|
||||
->get(['date', 'price_usd'])
|
||||
->reverse()
|
||||
->map(fn (BrentPrice $r): array => ['date' => (string) $r->date->toDateString(), 'price_usd' => (float) $r->price_usd])
|
||||
->values()
|
||||
->all();
|
||||
|
||||
return [
|
||||
'ulsp_recent_8_weeks' => $ulspWeekly,
|
||||
'brent_recent_14_days' => $brentRecent,
|
||||
'ridge_model_says' => [
|
||||
'direction' => $forecast['predicted_direction'] ?? 'stable',
|
||||
'confidence' => $forecast['confidence_score'] ?? 0,
|
||||
'magnitude_pence' => $forecast['predicted_change_pence'] ?? 0,
|
||||
],
|
||||
];
|
||||
}
|
||||
|
||||
/** @return array<string, mixed>|null */
|
||||
private function callAnthropic(array $context): ?array
|
||||
{
|
||||
$messages = [['role' => 'user', 'content' => $this->prompt($context)]];
|
||||
|
||||
try {
|
||||
// Phase 1: web search loop
|
||||
for ($i = 0, $response = null; $i < 5; $i++) {
|
||||
$response = $this->apiLogger->send('anthropic', 'POST', self::URL, fn () => Http::timeout(45)
|
||||
->withHeaders($this->headers())
|
||||
->post(self::URL, [
|
||||
'model' => config('services.anthropic.model', 'claude-haiku-4-5-20251001'),
|
||||
'max_tokens' => 1024,
|
||||
'tools' => [['type' => 'web_search_20250305', 'name' => 'web_search']],
|
||||
'messages' => $messages,
|
||||
]));
|
||||
|
||||
if (! $response->successful()) {
|
||||
Log::error('LlmOverlayService: search request failed', ['status' => $response->status()]);
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
if ($response->json('stop_reason') !== 'pause_turn') {
|
||||
break;
|
||||
}
|
||||
|
||||
$messages[] = ['role' => 'assistant', 'content' => $response->json('content')];
|
||||
}
|
||||
|
||||
$messages[] = ['role' => 'assistant', 'content' => $response->json('content')];
|
||||
$messages[] = ['role' => 'user', 'content' => 'Now submit your overlay using the submit_overlay tool. Cite at least one event with a URL.'];
|
||||
|
||||
// Phase 2: forced structured output
|
||||
$submitResponse = $this->apiLogger->send('anthropic', 'POST', self::URL, fn () => Http::timeout(20)
|
||||
->withHeaders($this->headers())
|
||||
->post(self::URL, [
|
||||
'model' => config('services.anthropic.model', 'claude-haiku-4-5-20251001'),
|
||||
'max_tokens' => 512,
|
||||
'tools' => [$this->submitOverlayTool()],
|
||||
'tool_choice' => ['type' => 'tool', 'name' => 'submit_overlay'],
|
||||
'messages' => $messages,
|
||||
]));
|
||||
|
||||
if (! $submitResponse->successful()) {
|
||||
Log::error('LlmOverlayService: submit request failed', ['status' => $submitResponse->status()]);
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
return $this->extractToolInput($submitResponse->json('content') ?? []);
|
||||
} catch (Throwable $e) {
|
||||
Log::error('LlmOverlayService: callAnthropic failed', ['error' => $e->getMessage()]);
|
||||
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
private const string VERIFICATION_USER_AGENT = 'Mozilla/5.0 (compatible; FuelPriceBot/1.0; +https://fuel-price.test/bot)';
|
||||
|
||||
/**
|
||||
* Verify each cited URL is reachable. Major news sites (Reuters, FT,
|
||||
* Bloomberg, BBC...) often reject HEAD with 403 / 405 even though
|
||||
* GET works fine. So: try HEAD first, then fall back to a 1-byte
|
||||
* GET (Range header) when HEAD fails. Both must include a
|
||||
* browser-shaped User-Agent or Cloudflare etc. block us as a bot.
|
||||
*
|
||||
* Every URL — verified or rejected — is logged at INFO/WARNING so
|
||||
* operators can debug rejections from `storage/logs/laravel.log`
|
||||
* without needing to capture the Anthropic response body.
|
||||
*
|
||||
* @param array<int, array<string, mixed>> $events
|
||||
* @return array<int, array<string, mixed>>
|
||||
*/
|
||||
private function verifyCitedUrls(array $events): array
|
||||
{
|
||||
$verified = [];
|
||||
foreach ($events as $event) {
|
||||
$url = (string) ($event['url'] ?? '');
|
||||
if ($url === '') {
|
||||
Log::warning('LlmOverlayService: dropping cited event with empty URL', [
|
||||
'headline' => $event['headline'] ?? null,
|
||||
'source' => $event['source'] ?? null,
|
||||
]);
|
||||
|
||||
continue;
|
||||
}
|
||||
[$reachable, $diagnosis] = $this->urlReachable($url);
|
||||
if ($reachable) {
|
||||
Log::info('LlmOverlayService: URL verified', [
|
||||
'url' => $url,
|
||||
'via' => $diagnosis,
|
||||
]);
|
||||
$verified[] = $event;
|
||||
} else {
|
||||
Log::warning('LlmOverlayService: URL rejected', [
|
||||
'url' => $url,
|
||||
'reason' => $diagnosis,
|
||||
'headline' => $event['headline'] ?? null,
|
||||
'source' => $event['source'] ?? null,
|
||||
]);
|
||||
}
|
||||
}
|
||||
|
||||
return $verified;
|
||||
}
|
||||
|
||||
/** @return array{0: bool, 1: string} [reachable, diagnostic_string] */
|
||||
private function urlReachable(string $url): array
|
||||
{
|
||||
$headers = ['User-Agent' => self::VERIFICATION_USER_AGENT];
|
||||
$headStatus = 'no-attempt';
|
||||
|
||||
try {
|
||||
$head = Http::timeout(5)
|
||||
->withHeaders($headers)
|
||||
->head($url);
|
||||
$headStatus = 'HEAD='.$head->status();
|
||||
if ($head->successful() || $head->redirect()) {
|
||||
return [true, $headStatus];
|
||||
}
|
||||
} catch (Throwable $e) {
|
||||
$headStatus = 'HEAD=exception('.class_basename($e).')';
|
||||
}
|
||||
|
||||
try {
|
||||
$get = Http::timeout(8)
|
||||
->withHeaders($headers + ['Range' => 'bytes=0-0'])
|
||||
->get($url);
|
||||
$getStatus = 'GET='.$get->status();
|
||||
if ($get->successful() || $get->redirect()) {
|
||||
return [true, $headStatus.' → '.$getStatus.' (fallback)'];
|
||||
}
|
||||
|
||||
return [false, $headStatus.' → '.$getStatus];
|
||||
} catch (Throwable $e) {
|
||||
return [false, $headStatus.' → GET=exception('.class_basename($e).')'];
|
||||
}
|
||||
}
|
||||
|
||||
private function ridgeDirection(string $publicDirection): string
|
||||
{
|
||||
return match ($publicDirection) {
|
||||
'up' => 'rising',
|
||||
'down' => 'falling',
|
||||
default => 'flat',
|
||||
};
|
||||
}
|
||||
|
||||
private function upcomingMondayDateString(): string
|
||||
{
|
||||
$today = now()->startOfDay();
|
||||
$monday = $today->isMonday() ? $today : $today->copy()->next(CarbonInterface::MONDAY);
|
||||
|
||||
return $monday->toDateString();
|
||||
}
|
||||
|
||||
/** @return array<string, string> */
|
||||
private function headers(): array
|
||||
{
|
||||
return [
|
||||
'x-api-key' => $this->apiKey(),
|
||||
'anthropic-version' => '2023-06-01',
|
||||
];
|
||||
}
|
||||
|
||||
private function apiKey(): ?string
|
||||
{
|
||||
return config('services.anthropic.api_key');
|
||||
}
|
||||
|
||||
private function prompt(array $context): string
|
||||
{
|
||||
$json = json_encode($context, JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);
|
||||
|
||||
return <<<PROMPT
|
||||
You are providing a daily news-aware overlay for a UK weekly pump-price forecast.
|
||||
|
||||
The calibrated ridge model has already produced a directional call from price history.
|
||||
Your job is to search recent oil/fuel news and decide whether to AGREE or DISAGREE
|
||||
— and most importantly, surface any major-impact event that the ridge model can't see
|
||||
from price history alone.
|
||||
|
||||
Search recent news (last 48 hours) for:
|
||||
- OPEC+ production decisions or unexpected announcements
|
||||
- Geopolitical events affecting oil supply (sanctions, conflict, shipping disruption)
|
||||
- Major refinery outages or pipeline incidents
|
||||
- US/EU inventory reports that materially moved Brent
|
||||
|
||||
Context for this week:
|
||||
$json
|
||||
|
||||
After searching, you will be asked to submit_overlay with direction, confidence
|
||||
(capped at $this->confidenceCap), short reasoning, cited events with URLs,
|
||||
agrees_with_ridge, and major_impact_event.
|
||||
|
||||
Citing events with REAL URLs is mandatory. An empty citation array will be
|
||||
rejected and the overlay discarded.
|
||||
PROMPT;
|
||||
}
|
||||
|
||||
private string $confidenceCap = '75';
|
||||
|
||||
/** @return array<string, mixed> */
|
||||
private function submitOverlayTool(): array
|
||||
{
|
||||
return [
|
||||
'name' => 'submit_overlay',
|
||||
'description' => 'Submit the news-aware overlay for the upcoming weekly forecast.',
|
||||
'input_schema' => [
|
||||
'type' => 'object',
|
||||
'properties' => [
|
||||
'direction' => ['type' => 'string', 'enum' => ['rising', 'falling', 'flat']],
|
||||
'confidence' => ['type' => 'integer', 'minimum' => 0, 'maximum' => self::CONFIDENCE_CAP],
|
||||
'reasoning_short' => ['type' => 'string', 'description' => '1–2 sentences.'],
|
||||
'events_cited' => [
|
||||
'type' => 'array',
|
||||
'items' => [
|
||||
'type' => 'object',
|
||||
'properties' => [
|
||||
'headline' => ['type' => 'string'],
|
||||
'source' => ['type' => 'string'],
|
||||
'url' => ['type' => 'string'],
|
||||
'impact' => ['type' => 'string', 'enum' => ['rising', 'falling', 'neutral']],
|
||||
],
|
||||
'required' => ['headline', 'source', 'url', 'impact'],
|
||||
],
|
||||
],
|
||||
'agrees_with_ridge' => ['type' => 'boolean'],
|
||||
'major_impact_event' => ['type' => 'boolean'],
|
||||
],
|
||||
'required' => ['direction', 'confidence', 'reasoning_short', 'events_cited', 'agrees_with_ridge', 'major_impact_event'],
|
||||
],
|
||||
];
|
||||
}
|
||||
|
||||
/**
|
||||
* @param array<int, mixed> $content
|
||||
* @return array<string, mixed>|null
|
||||
*/
|
||||
private function extractToolInput(array $content): ?array
|
||||
{
|
||||
$block = collect($content)->firstWhere('type', 'tool_use');
|
||||
|
||||
return $block['input'] ?? null;
|
||||
}
|
||||
}
|
||||
147
app/Services/Forecasting/LocalSnapshotService.php
Normal file
147
app/Services/Forecasting/LocalSnapshotService.php
Normal file
@@ -0,0 +1,147 @@
|
||||
<?php
|
||||
|
||||
namespace App\Services\Forecasting;
|
||||
|
||||
use App\Services\HaversineQuery;
|
||||
use Illuminate\Support\Facades\DB;
|
||||
|
||||
/**
|
||||
* Layer 2 — descriptive snapshot of the present.
|
||||
*
|
||||
* Pure SQL aggregates against `station_prices_current` + Haversine on
|
||||
* `stations.lat / lng`. No ML, no history, no surprises. Layer 2 never
|
||||
* speaks about the future.
|
||||
*
|
||||
* Used by Phase 4's WeeklyForecastService to enrich the public payload
|
||||
* with descriptive "your area" cards alongside the headline forecast.
|
||||
*/
|
||||
final class LocalSnapshotService
|
||||
{
|
||||
/**
|
||||
* Snapshot for a coordinate (e.g. user's postcode-resolved lat/lng).
|
||||
*
|
||||
* @return array{
|
||||
* national_avg_pence: ?float,
|
||||
* local_avg_pence: ?float,
|
||||
* local_minus_national_pence: ?float,
|
||||
* cheapest_nearby: array<int, array{node_id: string, name: ?string, brand: ?string, price_pence: int, distance_km: float}>,
|
||||
* supermarket_avg_pence: ?float,
|
||||
* major_avg_pence: ?float,
|
||||
* supermarket_gap_pence: ?float,
|
||||
* stations_within_radius: int
|
||||
* }
|
||||
*/
|
||||
public function snapshot(string $fuelType, float $lat, float $lng, int $radiusKm = 25): array
|
||||
{
|
||||
$nationalAvg = $this->nationalAverage($fuelType);
|
||||
$localAvg = $this->localAverage($fuelType, $lat, $lng, 50);
|
||||
$cheapest = $this->cheapestNearby($fuelType, $lat, $lng, $radiusKm, 5);
|
||||
[$superAvg, $majorAvg] = $this->brandSplit($fuelType, $lat, $lng, $radiusKm);
|
||||
$stationCount = $this->stationCountWithin($fuelType, $lat, $lng, $radiusKm);
|
||||
|
||||
return [
|
||||
'national_avg_pence' => $nationalAvg,
|
||||
'local_avg_pence' => $localAvg,
|
||||
'local_minus_national_pence' => $localAvg !== null && $nationalAvg !== null
|
||||
? round($localAvg - $nationalAvg, 1)
|
||||
: null,
|
||||
'cheapest_nearby' => $cheapest,
|
||||
'supermarket_avg_pence' => $superAvg,
|
||||
'major_avg_pence' => $majorAvg,
|
||||
'supermarket_gap_pence' => $superAvg !== null && $majorAvg !== null
|
||||
? round($superAvg - $majorAvg, 1)
|
||||
: null,
|
||||
'stations_within_radius' => $stationCount,
|
||||
];
|
||||
}
|
||||
|
||||
private function nationalAverage(string $fuelType): ?float
|
||||
{
|
||||
$avg = DB::table('station_prices_current')
|
||||
->where('fuel_type', $fuelType)
|
||||
->avg('price_pence');
|
||||
|
||||
return $avg === null ? null : round((float) $avg / 100, 1);
|
||||
}
|
||||
|
||||
private function localAverage(string $fuelType, float $lat, float $lng, int $km): ?float
|
||||
{
|
||||
[$within, $bindings] = HaversineQuery::withinKm($lat, $lng, $km);
|
||||
|
||||
$avg = DB::table('station_prices_current')
|
||||
->join('stations', 'station_prices_current.station_id', '=', 'stations.node_id')
|
||||
->where('station_prices_current.fuel_type', $fuelType)
|
||||
->whereRaw($within, $bindings)
|
||||
->avg('station_prices_current.price_pence');
|
||||
|
||||
return $avg === null ? null : round((float) $avg / 100, 1);
|
||||
}
|
||||
|
||||
/**
|
||||
* @return array<int, array{node_id: string, name: ?string, brand: ?string, price_pence: int, distance_km: float}>
|
||||
*/
|
||||
private function cheapestNearby(string $fuelType, float $lat, float $lng, int $km, int $limit): array
|
||||
{
|
||||
[$distance, $distanceBindings] = HaversineQuery::distanceKm($lat, $lng);
|
||||
[$within, $withinBindings] = HaversineQuery::withinKm($lat, $lng, $km);
|
||||
|
||||
$rows = DB::table('station_prices_current')
|
||||
->join('stations', 'station_prices_current.station_id', '=', 'stations.node_id')
|
||||
->where('station_prices_current.fuel_type', $fuelType)
|
||||
->whereRaw($within, $withinBindings)
|
||||
->selectRaw(
|
||||
'stations.node_id, stations.trading_name as name, stations.brand_name as brand, '
|
||||
.'station_prices_current.price_pence, '.$distance.' as distance_km',
|
||||
$distanceBindings,
|
||||
)
|
||||
->orderBy('station_prices_current.price_pence')
|
||||
->limit($limit)
|
||||
->get();
|
||||
|
||||
return $rows->map(fn ($r): array => [
|
||||
'node_id' => (string) $r->node_id,
|
||||
'name' => $r->name === null ? null : (string) $r->name,
|
||||
'brand' => $r->brand === null ? null : (string) $r->brand,
|
||||
'price_pence' => (int) $r->price_pence,
|
||||
'distance_km' => round((float) $r->distance_km, 2),
|
||||
])->all();
|
||||
}
|
||||
|
||||
/** @return array{0: ?float, 1: ?float} [supermarket_avg, major_avg] */
|
||||
private function brandSplit(string $fuelType, float $lat, float $lng, int $km): array
|
||||
{
|
||||
[$within, $bindings] = HaversineQuery::withinKm($lat, $lng, $km);
|
||||
|
||||
$rows = DB::table('station_prices_current')
|
||||
->join('stations', 'station_prices_current.station_id', '=', 'stations.node_id')
|
||||
->where('station_prices_current.fuel_type', $fuelType)
|
||||
->whereRaw($within, $bindings)
|
||||
->selectRaw('stations.is_supermarket, AVG(station_prices_current.price_pence) as avg_pence')
|
||||
->groupBy('stations.is_supermarket')
|
||||
->get();
|
||||
|
||||
$super = null;
|
||||
$major = null;
|
||||
foreach ($rows as $r) {
|
||||
$avg = round((float) $r->avg_pence / 100, 1);
|
||||
if ((int) $r->is_supermarket === 1) {
|
||||
$super = $avg;
|
||||
} else {
|
||||
$major = $avg;
|
||||
}
|
||||
}
|
||||
|
||||
return [$super, $major];
|
||||
}
|
||||
|
||||
private function stationCountWithin(string $fuelType, float $lat, float $lng, int $km): int
|
||||
{
|
||||
[$within, $bindings] = HaversineQuery::withinKm($lat, $lng, $km);
|
||||
|
||||
return DB::table('station_prices_current')
|
||||
->join('stations', 'station_prices_current.station_id', '=', 'stations.node_id')
|
||||
->where('station_prices_current.fuel_type', $fuelType)
|
||||
->whereRaw($within, $bindings)
|
||||
->count();
|
||||
}
|
||||
}
|
||||
39
app/Services/Forecasting/Models/NaiveZeroChangeModel.php
Normal file
39
app/Services/Forecasting/Models/NaiveZeroChangeModel.php
Normal file
@@ -0,0 +1,39 @@
|
||||
<?php
|
||||
|
||||
namespace App\Services\Forecasting\Models;
|
||||
|
||||
use App\Services\Forecasting\Contracts\WeeklyForecastModel;
|
||||
use App\Services\Forecasting\FeatureSpec;
|
||||
use App\Services\Forecasting\WeeklyPrediction;
|
||||
use Carbon\CarbonInterface;
|
||||
|
||||
/**
|
||||
* Predicts ΔULSP[t+1] = 0 for every week. Direction = 'flat'.
|
||||
*
|
||||
* The floor any future model must beat. Per Alquist/Kilian, the
|
||||
* no-change benchmark is hard to beat for short-horizon oil/fuel
|
||||
* forecasts — if the ridge model can't beat this, the features are wrong.
|
||||
*/
|
||||
final class NaiveZeroChangeModel implements WeeklyForecastModel
|
||||
{
|
||||
public function featureSpec(): FeatureSpec
|
||||
{
|
||||
return new FeatureSpec(modelLabel: 'naive-zero', features: []);
|
||||
}
|
||||
|
||||
public function train(array $trainingMondays): void {}
|
||||
|
||||
public function predict(CarbonInterface $targetMonday): WeeklyPrediction
|
||||
{
|
||||
return new WeeklyPrediction(
|
||||
targetMonday: $targetMonday,
|
||||
magnitudePence: 0.0,
|
||||
direction: 'flat',
|
||||
);
|
||||
}
|
||||
|
||||
public function coefficients(): ?array
|
||||
{
|
||||
return null;
|
||||
}
|
||||
}
|
||||
201
app/Services/Forecasting/Models/RidgeRegressionModel.php
Normal file
201
app/Services/Forecasting/Models/RidgeRegressionModel.php
Normal file
@@ -0,0 +1,201 @@
|
||||
<?php
|
||||
|
||||
namespace App\Services\Forecasting\Models;
|
||||
|
||||
use App\Services\Forecasting\Contracts\WeeklyForecastModel;
|
||||
use App\Services\Forecasting\FeatureSpec;
|
||||
use App\Services\Forecasting\LinearAlgebra;
|
||||
use App\Services\Forecasting\WeeklyPrediction;
|
||||
use App\Services\Forecasting\WeeklyPumpPriceLoader;
|
||||
use Carbon\CarbonInterface;
|
||||
use RuntimeException;
|
||||
|
||||
/**
|
||||
* Ridge regression on weekly pump prices.
|
||||
*
|
||||
* Target: ΔULSP[t+1] = ULSP[t+1] − ULSP[t], in pence × 100.
|
||||
*
|
||||
* Pipeline:
|
||||
* - Build (X, y) from training Mondays. Skip any week where a feature
|
||||
* value is null OR the actual ΔULSP cannot be computed.
|
||||
* - Standardise X (z-score per column) and centre y. Keeps features
|
||||
* on comparable scales so the L2 penalty is fair.
|
||||
* - Solve β = (XᵀX + λI) ⁻¹ Xᵀy for the standardised problem.
|
||||
* - Reconstruct intercept = mean(y) (since X is centred).
|
||||
*
|
||||
* Prediction:
|
||||
* - Build feature vector at $targetMonday. If any feature returns
|
||||
* null, predict 0 (treated as 'flat' downstream).
|
||||
* - Standardise with the trained scaler, multiply by β, add intercept.
|
||||
*
|
||||
* Direction:
|
||||
* - rising if magnitude > FLAT_THRESHOLD_PENCE_X100
|
||||
* - falling if magnitude < −FLAT_THRESHOLD_PENCE_X100
|
||||
* - flat otherwise
|
||||
*/
|
||||
final class RidgeRegressionModel implements WeeklyForecastModel
|
||||
{
|
||||
private const float FLAT_THRESHOLD_PENCE_X100 = 20.0; // 0.2 p/L
|
||||
|
||||
/** @var array<int, float>|null Coefficients on standardised features (no intercept). */
|
||||
private ?array $beta = null;
|
||||
|
||||
private ?float $intercept = null;
|
||||
|
||||
/** @var array<int, float>|null per-feature mean used for standardisation */
|
||||
private ?array $featureMeans = null;
|
||||
|
||||
/** @var array<int, float>|null per-feature std-dev used for standardisation */
|
||||
private ?array $featureStdDevs = null;
|
||||
|
||||
public function __construct(
|
||||
private readonly FeatureSpec $spec,
|
||||
private readonly WeeklyPumpPriceLoader $loader,
|
||||
public readonly float $lambda = 1.0,
|
||||
) {}
|
||||
|
||||
public function featureSpec(): FeatureSpec
|
||||
{
|
||||
return $this->spec;
|
||||
}
|
||||
|
||||
public function train(array $trainingMondays): void
|
||||
{
|
||||
$X = [];
|
||||
$y = [];
|
||||
|
||||
foreach ($trainingMondays as $monday) {
|
||||
$row = [];
|
||||
$skip = false;
|
||||
foreach ($this->spec->features as $feature) {
|
||||
$v = $feature->valueFor($monday);
|
||||
if ($v === null) {
|
||||
$skip = true;
|
||||
break;
|
||||
}
|
||||
$row[] = $v;
|
||||
}
|
||||
if ($skip) {
|
||||
continue;
|
||||
}
|
||||
|
||||
$actual = $this->actualDeltaPence($monday);
|
||||
if ($actual === null) {
|
||||
continue;
|
||||
}
|
||||
|
||||
$X[] = $row;
|
||||
$y[] = $actual;
|
||||
}
|
||||
|
||||
if (count($X) < count($this->spec->features) + 2) {
|
||||
throw new RuntimeException('RidgeRegressionModel: insufficient training rows after dropping incomplete weeks');
|
||||
}
|
||||
|
||||
// Standardise X (z-score) and centre y.
|
||||
$featureCount = count($X[0]);
|
||||
$means = array_fill(0, $featureCount, 0.0);
|
||||
$stds = array_fill(0, $featureCount, 0.0);
|
||||
$n = count($X);
|
||||
|
||||
for ($j = 0; $j < $featureCount; $j++) {
|
||||
$col = array_column($X, $j);
|
||||
$means[$j] = array_sum($col) / $n;
|
||||
$variance = 0.0;
|
||||
foreach ($col as $v) {
|
||||
$variance += ($v - $means[$j]) ** 2;
|
||||
}
|
||||
$variance /= $n;
|
||||
$stds[$j] = sqrt($variance);
|
||||
// Constant features get sd=1 so we don't divide by zero. Their
|
||||
// contribution is then a constant absorbed by the intercept.
|
||||
if ($stds[$j] < 1e-12) {
|
||||
$stds[$j] = 1.0;
|
||||
}
|
||||
}
|
||||
|
||||
$Xstd = [];
|
||||
foreach ($X as $row) {
|
||||
$r = [];
|
||||
for ($j = 0; $j < $featureCount; $j++) {
|
||||
$r[] = ($row[$j] - $means[$j]) / $stds[$j];
|
||||
}
|
||||
$Xstd[] = $r;
|
||||
}
|
||||
|
||||
$yMean = array_sum($y) / $n;
|
||||
$yCentred = array_map(fn (float $v): float => $v - $yMean, $y);
|
||||
|
||||
$this->beta = LinearAlgebra::ridgeSolve($Xstd, $yCentred, $this->lambda);
|
||||
$this->intercept = $yMean;
|
||||
$this->featureMeans = $means;
|
||||
$this->featureStdDevs = $stds;
|
||||
}
|
||||
|
||||
public function predict(CarbonInterface $targetMonday): WeeklyPrediction
|
||||
{
|
||||
if ($this->beta === null) {
|
||||
throw new RuntimeException('RidgeRegressionModel: predict() called before train()');
|
||||
}
|
||||
|
||||
$row = [];
|
||||
foreach ($this->spec->features as $feature) {
|
||||
$v = $feature->valueFor($targetMonday);
|
||||
if ($v === null) {
|
||||
return new WeeklyPrediction($targetMonday, 0.0, 'flat');
|
||||
}
|
||||
$row[] = $v;
|
||||
}
|
||||
|
||||
$magnitude = $this->intercept;
|
||||
for ($j = 0, $jc = count($row); $j < $jc; $j++) {
|
||||
$z = ($row[$j] - $this->featureMeans[$j]) / $this->featureStdDevs[$j];
|
||||
$magnitude += $z * $this->beta[$j];
|
||||
}
|
||||
|
||||
return new WeeklyPrediction($targetMonday, $magnitude, $this->classifyDirection($magnitude));
|
||||
}
|
||||
|
||||
public function coefficients(): ?array
|
||||
{
|
||||
if ($this->beta === null) {
|
||||
return null;
|
||||
}
|
||||
|
||||
$named = [];
|
||||
foreach ($this->spec->features as $i => $feature) {
|
||||
$named[$feature->name()] = [
|
||||
'beta_standardised' => $this->beta[$i],
|
||||
'mean' => $this->featureMeans[$i],
|
||||
'std_dev' => $this->featureStdDevs[$i],
|
||||
];
|
||||
}
|
||||
|
||||
return [
|
||||
'intercept' => $this->intercept,
|
||||
'lambda' => $this->lambda,
|
||||
'features' => $named,
|
||||
];
|
||||
}
|
||||
|
||||
private function actualDeltaPence(CarbonInterface $targetMonday): ?float
|
||||
{
|
||||
$current = $this->loader->ulspPence($targetMonday->toDateString());
|
||||
$previous = $this->loader->ulspPence($targetMonday->copy()->subDays(7)->toDateString());
|
||||
|
||||
if ($current === null || $previous === null) {
|
||||
return null;
|
||||
}
|
||||
|
||||
return (float) ($current - $previous);
|
||||
}
|
||||
|
||||
private function classifyDirection(float $magnitude): string
|
||||
{
|
||||
return match (true) {
|
||||
$magnitude > self::FLAT_THRESHOLD_PENCE_X100 => 'rising',
|
||||
$magnitude < -self::FLAT_THRESHOLD_PENCE_X100 => 'falling',
|
||||
default => 'flat',
|
||||
};
|
||||
}
|
||||
}
|
||||
87
app/Services/Forecasting/OutcomeResolver.php
Normal file
87
app/Services/Forecasting/OutcomeResolver.php
Normal file
@@ -0,0 +1,87 @@
|
||||
<?php
|
||||
|
||||
namespace App\Services\Forecasting;
|
||||
|
||||
use App\Models\WeeklyForecast;
|
||||
use Illuminate\Support\Facades\DB;
|
||||
|
||||
/**
|
||||
* Pairs a `weekly_forecasts` row with the actual ULSP move once BEIS
|
||||
* publishes the matching week. Writes idempotent rows to
|
||||
* `forecast_outcomes` so trailing-13-week accuracy is honest, not
|
||||
* inferred.
|
||||
*/
|
||||
final class OutcomeResolver
|
||||
{
|
||||
private const float FLAT_THRESHOLD_PENCE_X100 = 20.0;
|
||||
|
||||
public function resolvePending(): int
|
||||
{
|
||||
$resolved = 0;
|
||||
|
||||
$existing = DB::table('forecast_outcomes')
|
||||
->select(['forecast_for', 'model_version'])
|
||||
->get()
|
||||
->mapWithKeys(fn ($r): array => [$r->forecast_for.'|'.$r->model_version => true])
|
||||
->all();
|
||||
|
||||
$candidates = WeeklyForecast::query()
|
||||
->where('forecast_for', '<=', now()->toDateString())
|
||||
->orderBy('forecast_for')
|
||||
->get();
|
||||
|
||||
foreach ($candidates as $forecast) {
|
||||
$key = $forecast->forecast_for->toDateString().'|'.$forecast->model_version;
|
||||
if (isset($existing[$key])) {
|
||||
continue;
|
||||
}
|
||||
|
||||
$actualDelta = $this->actualDeltaPence($forecast->forecast_for->toDateString());
|
||||
if ($actualDelta === null) {
|
||||
continue;
|
||||
}
|
||||
|
||||
$actualClass = $this->classifyDirection($actualDelta);
|
||||
$absError = (int) round(abs($forecast->magnitude_pence - $actualDelta));
|
||||
|
||||
DB::table('forecast_outcomes')->insert([
|
||||
'forecast_for' => $forecast->forecast_for->toDateString(),
|
||||
'model_version' => $forecast->model_version,
|
||||
'predicted_class' => $forecast->direction,
|
||||
'actual_class' => $actualClass,
|
||||
'correct' => $forecast->direction === $actualClass,
|
||||
'abs_error_pence' => $absError,
|
||||
'resolved_at' => now(),
|
||||
]);
|
||||
|
||||
$resolved++;
|
||||
}
|
||||
|
||||
return $resolved;
|
||||
}
|
||||
|
||||
private function actualDeltaPence(string $targetDate): ?float
|
||||
{
|
||||
$current = DB::table('weekly_pump_prices')
|
||||
->where('date', $targetDate)
|
||||
->value('ulsp_pence');
|
||||
$previous = DB::table('weekly_pump_prices')
|
||||
->where('date', date('Y-m-d', strtotime($targetDate.' -7 days')))
|
||||
->value('ulsp_pence');
|
||||
|
||||
if ($current === null || $previous === null) {
|
||||
return null;
|
||||
}
|
||||
|
||||
return (float) ($current - $previous);
|
||||
}
|
||||
|
||||
private function classifyDirection(float $deltaPence): string
|
||||
{
|
||||
return match (true) {
|
||||
$deltaPence > self::FLAT_THRESHOLD_PENCE_X100 => 'rising',
|
||||
$deltaPence < -self::FLAT_THRESHOLD_PENCE_X100 => 'falling',
|
||||
default => 'flat',
|
||||
};
|
||||
}
|
||||
}
|
||||
103
app/Services/Forecasting/ReasoningGenerator.php
Normal file
103
app/Services/Forecasting/ReasoningGenerator.php
Normal file
@@ -0,0 +1,103 @@
|
||||
<?php
|
||||
|
||||
namespace App\Services\Forecasting;
|
||||
|
||||
use App\Services\Forecasting\Contracts\ForecastFeature;
|
||||
use App\Services\Forecasting\Models\RidgeRegressionModel;
|
||||
use Carbon\CarbonInterface;
|
||||
|
||||
/**
|
||||
* Phase 6 honesty rule: the reasoning text only references features
|
||||
* the model actually used, ranked by how much each contributed to
|
||||
* this week's prediction.
|
||||
*
|
||||
* Contribution is the standardised (z-score × β) for each feature —
|
||||
* the same number the ridge model summed to produce the prediction.
|
||||
* That makes the explanation literally what the model did, not a
|
||||
* narrative invented post-hoc.
|
||||
*/
|
||||
final class ReasoningGenerator
|
||||
{
|
||||
/** @var array<string, string> */
|
||||
private const array PHRASES = [
|
||||
'delta_ulsp_lag_0' => "last week's pump price move",
|
||||
'delta_ulsp_lag_1' => 'the pump price move two weeks ago',
|
||||
'delta_ulsp_lag_3' => 'the pump price move four weeks ago',
|
||||
'delta_ulsd_lag_0' => "last week's diesel move",
|
||||
'ulsp_minus_ma8' => "the gap between this week's pump price and its 8-week average",
|
||||
'week_of_year_sin' => 'the seasonal pattern',
|
||||
'week_of_year_cos' => 'the seasonal pattern',
|
||||
'is_pre_bank_holiday' => 'an upcoming bank holiday',
|
||||
];
|
||||
|
||||
/**
|
||||
* @param array<int, ForecastFeature> $features
|
||||
*/
|
||||
public function generate(
|
||||
RidgeRegressionModel $model,
|
||||
WeeklyPrediction $prediction,
|
||||
array $features,
|
||||
CarbonInterface $targetMonday,
|
||||
int $confidence,
|
||||
bool $flaggedDutyChange,
|
||||
?float $trailingHitRate,
|
||||
): string {
|
||||
if ($confidence < 40) {
|
||||
return 'Not enough signal in the historical pattern to call this week — staying silent.';
|
||||
}
|
||||
|
||||
$coeffs = $model->coefficients() ?? [];
|
||||
$features_meta = $coeffs['features'] ?? [];
|
||||
|
||||
$contributions = [];
|
||||
foreach ($features as $f) {
|
||||
$name = $f->name();
|
||||
$meta = $features_meta[$name] ?? null;
|
||||
if ($meta === null) {
|
||||
continue;
|
||||
}
|
||||
$value = $f->valueFor($targetMonday);
|
||||
if ($value === null) {
|
||||
continue;
|
||||
}
|
||||
$z = ($value - $meta['mean']) / ($meta['std_dev'] ?: 1.0);
|
||||
$contributions[$name] = $z * $meta['beta_standardised'];
|
||||
}
|
||||
|
||||
$headline = $this->headline($prediction);
|
||||
$driver = $this->dominantFeatureSentence($contributions);
|
||||
$duty = $flaggedDutyChange
|
||||
? ' Recent fuel duty change may skew accuracy for the next several weeks.'
|
||||
: '';
|
||||
$accuracy = $trailingHitRate !== null
|
||||
? sprintf(' Last 13 weeks: %d%% hit rate.', (int) round($trailingHitRate * 100))
|
||||
: '';
|
||||
|
||||
return $headline.' '.$driver.$duty.$accuracy;
|
||||
}
|
||||
|
||||
private function headline(WeeklyPrediction $prediction): string
|
||||
{
|
||||
$absP = round(abs($prediction->magnitudePence) / 100, 1);
|
||||
|
||||
return match ($prediction->direction) {
|
||||
'rising' => sprintf('Model expects pump prices to rise by ~%sp/L next week.', number_format($absP, 1)),
|
||||
'falling' => sprintf('Model expects pump prices to fall by ~%sp/L next week.', number_format($absP, 1)),
|
||||
default => 'Pump prices are likely flat next week.',
|
||||
};
|
||||
}
|
||||
|
||||
/** @param array<string, float> $contributions */
|
||||
private function dominantFeatureSentence(array $contributions): string
|
||||
{
|
||||
if ($contributions === []) {
|
||||
return 'Drawn from the full feature set with no single dominant signal.';
|
||||
}
|
||||
|
||||
uasort($contributions, fn (float $a, float $b): int => abs($b) <=> abs($a));
|
||||
$topName = array_key_first($contributions);
|
||||
$phrase = self::PHRASES[$topName] ?? $topName;
|
||||
|
||||
return sprintf('Driver: %s.', $phrase);
|
||||
}
|
||||
}
|
||||
146
app/Services/Forecasting/UkBankHolidays.php
Normal file
146
app/Services/Forecasting/UkBankHolidays.php
Normal file
@@ -0,0 +1,146 @@
|
||||
<?php
|
||||
|
||||
namespace App\Services\Forecasting;
|
||||
|
||||
use Carbon\Carbon;
|
||||
use Carbon\CarbonInterface;
|
||||
|
||||
/**
|
||||
* UK England-and-Wales bank holiday calendar.
|
||||
*
|
||||
* Computed deterministically from year (no external dependency, no
|
||||
* hardcoded list to maintain).
|
||||
*
|
||||
* Includes the eight statutory holidays:
|
||||
* New Year's Day, Good Friday, Easter Monday,
|
||||
* Early May Bank Holiday, Spring Bank Holiday, Summer Bank Holiday,
|
||||
* Christmas Day, Boxing Day
|
||||
*
|
||||
* Substitution rules: when a fixed-date holiday falls on a weekend,
|
||||
* it's observed on the next non-holiday weekday (cascades for
|
||||
* Christmas+Boxing landing on Sat+Sun).
|
||||
*/
|
||||
final class UkBankHolidays
|
||||
{
|
||||
/**
|
||||
* Sorted list of bank holiday dates for a year, after substitution.
|
||||
*
|
||||
* @return array<int, Carbon>
|
||||
*/
|
||||
public static function forYear(int $year): array
|
||||
{
|
||||
$dates = [];
|
||||
|
||||
// Easter-anchored
|
||||
[$em, $ed] = self::easter($year);
|
||||
$easter = Carbon::create($year, $em, $ed);
|
||||
$dates[] = $easter->copy()->subDays(2); // Good Friday
|
||||
$dates[] = $easter->copy()->addDay(); // Easter Monday
|
||||
|
||||
// Floating Mondays
|
||||
$dates[] = self::firstMondayOf($year, 5);
|
||||
$dates[] = self::lastMondayOf($year, 5);
|
||||
$dates[] = self::lastMondayOf($year, 8);
|
||||
|
||||
// Fixed dates with substitution
|
||||
$dates[] = self::substituteForward(Carbon::create($year, 1, 1), $dates);
|
||||
$christmas = self::substituteForward(Carbon::create($year, 12, 25), $dates);
|
||||
$dates[] = $christmas;
|
||||
$boxing = self::substituteForward(Carbon::create($year, 12, 26), $dates);
|
||||
$dates[] = $boxing;
|
||||
|
||||
usort($dates, fn (CarbonInterface $a, CarbonInterface $b): int => $a->getTimestamp() <=> $b->getTimestamp());
|
||||
|
||||
return $dates;
|
||||
}
|
||||
|
||||
/**
|
||||
* Is there a UK bank holiday in [$from, $from + $daysAhead - 1]?
|
||||
*/
|
||||
public static function holidayWithin(CarbonInterface $from, int $daysAhead): bool
|
||||
{
|
||||
$end = $from->copy()->addDays($daysAhead - 1);
|
||||
$years = array_unique([(int) $from->format('Y'), (int) $end->format('Y')]);
|
||||
|
||||
foreach ($years as $year) {
|
||||
foreach (self::forYear($year) as $holiday) {
|
||||
if ($holiday->betweenIncluded($from, $end)) {
|
||||
return true;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return false;
|
||||
}
|
||||
|
||||
/**
|
||||
* Anonymous Gregorian algorithm for Easter Sunday.
|
||||
*
|
||||
* @return array{0: int, 1: int} [month, day]
|
||||
*/
|
||||
private static function easter(int $year): array
|
||||
{
|
||||
$a = $year % 19;
|
||||
$b = intdiv($year, 100);
|
||||
$c = $year % 100;
|
||||
$d = intdiv($b, 4);
|
||||
$e = $b % 4;
|
||||
$f = intdiv($b + 8, 25);
|
||||
$g = intdiv($b - $f + 1, 3);
|
||||
$h = (19 * $a + $b - $d - $g + 15) % 30;
|
||||
$i = intdiv($c, 4);
|
||||
$k = $c % 4;
|
||||
$l = (32 + 2 * $e + 2 * $i - $h - $k) % 7;
|
||||
$m = intdiv($a + 11 * $h + 22 * $l, 451);
|
||||
$month = intdiv($h + $l - 7 * $m + 114, 31);
|
||||
$day = (($h + $l - 7 * $m + 114) % 31) + 1;
|
||||
|
||||
return [$month, $day];
|
||||
}
|
||||
|
||||
private static function firstMondayOf(int $year, int $month): Carbon
|
||||
{
|
||||
$d = Carbon::create($year, $month, 1);
|
||||
while ($d->dayOfWeek !== Carbon::MONDAY) {
|
||||
$d->addDay();
|
||||
}
|
||||
|
||||
return $d;
|
||||
}
|
||||
|
||||
private static function lastMondayOf(int $year, int $month): Carbon
|
||||
{
|
||||
$d = Carbon::create($year, $month, 1)->endOfMonth()->startOfDay();
|
||||
while ($d->dayOfWeek !== Carbon::MONDAY) {
|
||||
$d->subDay();
|
||||
}
|
||||
|
||||
return $d;
|
||||
}
|
||||
|
||||
/**
|
||||
* If $candidate falls on a weekend or collides with an already-claimed
|
||||
* date, return the next non-weekend non-claimed date. Christmas/Boxing
|
||||
* cascade is handled because we pass in the running list.
|
||||
*
|
||||
* @param array<int, CarbonInterface> $taken
|
||||
*/
|
||||
private static function substituteForward(Carbon $candidate, array $taken): Carbon
|
||||
{
|
||||
$d = $candidate->copy();
|
||||
while (true) {
|
||||
$isWeekend = in_array($d->dayOfWeek, [Carbon::SATURDAY, Carbon::SUNDAY], true);
|
||||
$isTaken = false;
|
||||
foreach ($taken as $t) {
|
||||
if ($t->isSameDay($d)) {
|
||||
$isTaken = true;
|
||||
break;
|
||||
}
|
||||
}
|
||||
if (! $isWeekend && ! $isTaken) {
|
||||
return $d;
|
||||
}
|
||||
$d->addDay();
|
||||
}
|
||||
}
|
||||
}
|
||||
209
app/Services/Forecasting/VolatilityRegimeService.php
Normal file
209
app/Services/Forecasting/VolatilityRegimeService.php
Normal file
@@ -0,0 +1,209 @@
|
||||
<?php
|
||||
|
||||
namespace App\Services\Forecasting;
|
||||
|
||||
use App\Models\BrentPrice;
|
||||
use App\Models\LlmOverlay;
|
||||
use App\Models\VolatilityRegime;
|
||||
use App\Models\WatchedEvent;
|
||||
use Illuminate\Support\Facades\DB;
|
||||
|
||||
/**
|
||||
* Layer 5 — sole owner of `volatility_regimes.active`. Hourly cron.
|
||||
*
|
||||
* OR-combines four triggers:
|
||||
* 1. Brent close-to-close move > 3% (FRED `DCOILBRENTEU`).
|
||||
* 2. Most recent `llm_overlays.major_impact_event = true` AND at
|
||||
* least one verified URL.
|
||||
* 3. `station_prices` daily churn > 1.5× 30-day baseline. Gated
|
||||
* until ≥ 180 days of polling — toggleable via config.
|
||||
* 4. `watched_events` row covering today.
|
||||
*
|
||||
* When the flag flips ON, an event-driven LLM refresh is queued
|
||||
* (Layer 4 enforces its own 4h cooldown). When OFF, the row is
|
||||
* closed with `flipped_off_at`.
|
||||
*/
|
||||
final class VolatilityRegimeService
|
||||
{
|
||||
private const float BRENT_MOVE_PCT = 3.0;
|
||||
|
||||
private const float STATION_CHURN_RATIO = 1.5;
|
||||
|
||||
private const int STATION_CHURN_MIN_POLLING_DAYS = 180;
|
||||
|
||||
public function __construct(
|
||||
private readonly LlmOverlayService $llmOverlay,
|
||||
) {}
|
||||
|
||||
public function evaluate(): ?VolatilityRegime
|
||||
{
|
||||
$trigger = $this->detectTrigger();
|
||||
$current = VolatilityRegime::currentlyActive();
|
||||
|
||||
if ($trigger !== null && $current === null) {
|
||||
$row = $this->flipOn($trigger);
|
||||
$this->llmOverlay->run(eventDriven: true);
|
||||
|
||||
return $row;
|
||||
}
|
||||
|
||||
if ($trigger === null && $current !== null) {
|
||||
$this->flipOff($current);
|
||||
|
||||
return null;
|
||||
}
|
||||
|
||||
return $current;
|
||||
}
|
||||
|
||||
/** @return array{type: string, detail: string}|null */
|
||||
private function detectTrigger(): ?array
|
||||
{
|
||||
return $this->brentMoveTrigger()
|
||||
?? $this->llmEventTrigger()
|
||||
?? $this->stationChurnTrigger()
|
||||
?? $this->watchedEventTrigger();
|
||||
}
|
||||
|
||||
/** @return array{type: string, detail: string}|null */
|
||||
private function brentMoveTrigger(): ?array
|
||||
{
|
||||
$rows = BrentPrice::query()
|
||||
->orderByDesc('date')
|
||||
->limit(2)
|
||||
->get(['date', 'price_usd']);
|
||||
|
||||
if ($rows->count() < 2) {
|
||||
return null;
|
||||
}
|
||||
|
||||
$latest = (float) $rows[0]->price_usd;
|
||||
$prior = (float) $rows[1]->price_usd;
|
||||
if ($prior === 0.0) {
|
||||
return null;
|
||||
}
|
||||
|
||||
$pctMove = abs(($latest - $prior) / $prior) * 100;
|
||||
if ($pctMove <= self::BRENT_MOVE_PCT) {
|
||||
return null;
|
||||
}
|
||||
|
||||
$direction = $latest > $prior ? '+' : '-';
|
||||
|
||||
return [
|
||||
'type' => 'brent_move',
|
||||
'detail' => sprintf('Brent %s%.2f%% (%s → %s)', $direction, $pctMove, $rows[1]->date->toDateString(), $rows[0]->date->toDateString()),
|
||||
];
|
||||
}
|
||||
|
||||
/** @return array{type: string, detail: string}|null */
|
||||
private function llmEventTrigger(): ?array
|
||||
{
|
||||
$latest = LlmOverlay::query()->orderByDesc('ran_at')->first();
|
||||
|
||||
if ($latest === null || ! $latest->major_impact_event) {
|
||||
return null;
|
||||
}
|
||||
|
||||
$hasVerifiedUrl = collect((array) $latest->events_json)
|
||||
->contains(fn ($e): bool => is_array($e) && ! empty($e['url']));
|
||||
|
||||
if (! $hasVerifiedUrl) {
|
||||
return null;
|
||||
}
|
||||
|
||||
$headline = collect((array) $latest->events_json)->pluck('headline')->filter()->first();
|
||||
|
||||
return [
|
||||
'type' => 'llm_event',
|
||||
'detail' => sprintf('LLM major impact: %s', $headline ?? 'unspecified'),
|
||||
];
|
||||
}
|
||||
|
||||
/** @return array{type: string, detail: string}|null */
|
||||
private function stationChurnTrigger(): ?array
|
||||
{
|
||||
if (! $this->stationChurnEnabled()) {
|
||||
return null;
|
||||
}
|
||||
|
||||
$oldest = DB::table('station_prices')->min('price_effective_at');
|
||||
if ($oldest === null) {
|
||||
return null;
|
||||
}
|
||||
|
||||
$pollingDays = (int) abs(now()->diffInDays($oldest));
|
||||
if ($pollingDays < self::STATION_CHURN_MIN_POLLING_DAYS) {
|
||||
return null;
|
||||
}
|
||||
|
||||
$last24h = (int) DB::table('station_prices')
|
||||
->where('price_effective_at', '>=', now()->subDay())
|
||||
->distinct('station_id')
|
||||
->count('station_id');
|
||||
|
||||
$baseline = (int) DB::table('station_prices')
|
||||
->where('price_effective_at', '>=', now()->subDays(30))
|
||||
->where('price_effective_at', '<', now()->subDay())
|
||||
->distinct('station_id')
|
||||
->count('station_id');
|
||||
|
||||
if ($baseline === 0) {
|
||||
return null;
|
||||
}
|
||||
|
||||
$dailyBaseline = $baseline / 29; // 29 days of history before yesterday
|
||||
if ($last24h <= $dailyBaseline * self::STATION_CHURN_RATIO) {
|
||||
return null;
|
||||
}
|
||||
|
||||
return [
|
||||
'type' => 'station_churn',
|
||||
'detail' => sprintf('Station churn %d/24h vs %.1f baseline (%.2fx)', $last24h, $dailyBaseline, $last24h / $dailyBaseline),
|
||||
];
|
||||
}
|
||||
|
||||
/** @return array{type: string, detail: string}|null */
|
||||
private function watchedEventTrigger(): ?array
|
||||
{
|
||||
$row = WatchedEvent::query()
|
||||
->where('starts_at', '<=', now())
|
||||
->where('ends_at', '>=', now())
|
||||
->orderBy('starts_at')
|
||||
->first();
|
||||
|
||||
if ($row === null) {
|
||||
return null;
|
||||
}
|
||||
|
||||
return [
|
||||
'type' => 'manual',
|
||||
'detail' => sprintf('Watched event: %s', $row->label),
|
||||
];
|
||||
}
|
||||
|
||||
private function stationChurnEnabled(): bool
|
||||
{
|
||||
return (bool) config('services.forecasting.station_churn_enabled', false);
|
||||
}
|
||||
|
||||
/** @param array{type: string, detail: string} $trigger */
|
||||
private function flipOn(array $trigger): VolatilityRegime
|
||||
{
|
||||
return VolatilityRegime::query()->create([
|
||||
'flipped_on_at' => now(),
|
||||
'flipped_off_at' => null,
|
||||
'trigger' => $trigger['type'],
|
||||
'trigger_detail' => $trigger['detail'],
|
||||
'active' => true,
|
||||
]);
|
||||
}
|
||||
|
||||
private function flipOff(VolatilityRegime $row): void
|
||||
{
|
||||
$row->update([
|
||||
'flipped_off_at' => now(),
|
||||
'active' => false,
|
||||
]);
|
||||
}
|
||||
}
|
||||
307
app/Services/Forecasting/WeeklyForecastService.php
Normal file
307
app/Services/Forecasting/WeeklyForecastService.php
Normal file
@@ -0,0 +1,307 @@
|
||||
<?php
|
||||
|
||||
namespace App\Services\Forecasting;
|
||||
|
||||
use App\Models\Backtest;
|
||||
use App\Services\Forecasting\Contracts\ForecastFeature;
|
||||
use App\Services\Forecasting\Features\DeltaUlsdLag;
|
||||
use App\Services\Forecasting\Features\DeltaUlspLag;
|
||||
use App\Services\Forecasting\Features\IsPreBankHoliday;
|
||||
use App\Services\Forecasting\Features\UlspMinusMa8;
|
||||
use App\Services\Forecasting\Features\WeekOfYearTrig;
|
||||
use App\Services\Forecasting\Models\RidgeRegressionModel;
|
||||
use Carbon\Carbon;
|
||||
use Carbon\CarbonInterface;
|
||||
use Illuminate\Support\Facades\Cache;
|
||||
use Illuminate\Support\Facades\DB;
|
||||
use RuntimeException;
|
||||
|
||||
/**
|
||||
* Layer 1 — orchestrates the ridge model end-to-end:
|
||||
*
|
||||
* 1. Builds the canonical v1 feature spec (8 features).
|
||||
* 2. Trains the ridge model on every available BEIS Monday.
|
||||
* 3. Predicts for the upcoming Monday.
|
||||
* 4. Looks up the latest matching backtest for calibrated confidence.
|
||||
* 5. Returns a flat array keyed for the existing public JSON contract.
|
||||
*
|
||||
* Trained-model state is cached for 1 hour (key includes model_version)
|
||||
* so repeated request hits don't retrain. A new BEIS week or a feature
|
||||
* spec change rolls model_version, busting the cache automatically.
|
||||
*/
|
||||
final class WeeklyForecastService
|
||||
{
|
||||
private const float DEFAULT_LAMBDA = 1.0;
|
||||
|
||||
public function currentForecast(): array
|
||||
{
|
||||
$loader = new WeeklyPumpPriceLoader;
|
||||
$features = $this->buildFeatures($loader);
|
||||
$spec = new FeatureSpec('ridge-v1', $features);
|
||||
|
||||
$cacheKey = 'forecast:current:'.$spec->modelVersion();
|
||||
|
||||
return Cache::remember($cacheKey, 3600, function () use ($loader, $spec, $features): array {
|
||||
$model = new RidgeRegressionModel($spec, $loader, self::DEFAULT_LAMBDA);
|
||||
|
||||
try {
|
||||
$model->train($this->collectTrainingMondays($loader));
|
||||
} catch (RuntimeException) {
|
||||
return $this->insufficientDataPayload($spec);
|
||||
}
|
||||
|
||||
$targetMonday = $this->upcomingMonday();
|
||||
$prediction = $model->predict($targetMonday);
|
||||
|
||||
$rawConfidence = $this->confidenceFromCalibration($spec, $prediction);
|
||||
$flaggedDutyChange = (new DutyChangeDetector)->isAdjacent($targetMonday);
|
||||
$confidence = $flaggedDutyChange ? (int) round($rawConfidence / 2) : $rawConfidence;
|
||||
|
||||
$directionPublic = $this->mapDirection($prediction->direction);
|
||||
$action = $this->mapAction($directionPublic, $confidence);
|
||||
|
||||
$trailingHitRate = (new AccuracyHistory)->trailingHitRate($spec->modelVersion());
|
||||
|
||||
$reasoning = (new ReasoningGenerator)->generate(
|
||||
$model,
|
||||
$prediction,
|
||||
$features,
|
||||
$targetMonday,
|
||||
$confidence,
|
||||
$flaggedDutyChange,
|
||||
$trailingHitRate,
|
||||
);
|
||||
|
||||
$this->persistForecast($spec, $targetMonday, $prediction, $confidence, $flaggedDutyChange, $reasoning);
|
||||
|
||||
return [
|
||||
'fuel_type' => 'e10',
|
||||
'current_avg' => $this->nationalCurrentAverage(),
|
||||
'predicted_direction' => $directionPublic,
|
||||
'predicted_change_pence' => round($prediction->magnitudePence / 100, 1),
|
||||
'confidence_score' => $confidence,
|
||||
'confidence_label' => $this->confidenceLabel($confidence),
|
||||
'action' => $action,
|
||||
'reasoning' => $reasoning,
|
||||
'prediction_horizon_days' => 7,
|
||||
'region_key' => 'national',
|
||||
'methodology' => 'ridge_regression_v1',
|
||||
'model_version' => $spec->modelVersion(),
|
||||
'flagged_duty_change' => $flaggedDutyChange,
|
||||
'trailing_hit_rate' => $trailingHitRate,
|
||||
'weekly_summary' => $this->weeklySummary($loader),
|
||||
'signals' => $this->describeSignals($model, $prediction),
|
||||
];
|
||||
});
|
||||
}
|
||||
|
||||
/**
|
||||
* Build the canonical v1 feature list. Centralised here so
|
||||
* WeeklyForecastService and any retraining command share the same
|
||||
* spec.
|
||||
*
|
||||
* @return array<int, ForecastFeature>
|
||||
*/
|
||||
private function buildFeatures(WeeklyPumpPriceLoader $loader): array
|
||||
{
|
||||
return [
|
||||
new DeltaUlspLag($loader, lag: 0),
|
||||
new DeltaUlspLag($loader, lag: 1),
|
||||
new DeltaUlspLag($loader, lag: 3),
|
||||
new DeltaUlsdLag($loader, lag: 0),
|
||||
new UlspMinusMa8($loader),
|
||||
new WeekOfYearTrig('sin'),
|
||||
new WeekOfYearTrig('cos'),
|
||||
new IsPreBankHoliday,
|
||||
];
|
||||
}
|
||||
|
||||
/** @return array<int, CarbonInterface> */
|
||||
private function collectTrainingMondays(WeeklyPumpPriceLoader $loader): array
|
||||
{
|
||||
return array_map(fn (string $d): CarbonInterface => Carbon::parse($d), $loader->allDates());
|
||||
}
|
||||
|
||||
private function upcomingMonday(): CarbonInterface
|
||||
{
|
||||
$today = now()->startOfDay();
|
||||
|
||||
return $today->isMonday() ? $today : $today->copy()->next(Carbon::MONDAY);
|
||||
}
|
||||
|
||||
private function confidenceFromCalibration(FeatureSpec $spec, WeeklyPrediction $prediction): int
|
||||
{
|
||||
$latest = Backtest::query()
|
||||
->where('model_version', $spec->modelVersion())
|
||||
->orderByDesc('ran_at')
|
||||
->first();
|
||||
|
||||
if ($latest === null) {
|
||||
return 0; // no backtest yet → low (gate 2 will force no_signal)
|
||||
}
|
||||
|
||||
$table = (array) ($latest->calibration_table ?? []);
|
||||
$bin = $this->bucketForMagnitude($prediction->magnitudePence);
|
||||
$hitRate = $table[$bin] ?? null;
|
||||
|
||||
if ($hitRate === null) {
|
||||
return (int) round((float) ($latest->directional_accuracy ?? 0));
|
||||
}
|
||||
|
||||
return (int) round(((float) $hitRate) * 100);
|
||||
}
|
||||
|
||||
private function bucketForMagnitude(float $magnitudePence): string
|
||||
{
|
||||
$abs = abs($magnitudePence);
|
||||
|
||||
return match (true) {
|
||||
$abs < 50.0 => '0.0-0.5p',
|
||||
$abs < 100.0 => '0.5-1.0p',
|
||||
default => '1.0p+',
|
||||
};
|
||||
}
|
||||
|
||||
private function mapDirection(string $modelDirection): string
|
||||
{
|
||||
return match ($modelDirection) {
|
||||
'rising' => 'up',
|
||||
'falling' => 'down',
|
||||
default => 'stable',
|
||||
};
|
||||
}
|
||||
|
||||
private function mapAction(string $publicDirection, int $confidence): string
|
||||
{
|
||||
if ($publicDirection === 'stable' || $confidence < 40) {
|
||||
return 'no_signal';
|
||||
}
|
||||
|
||||
return $publicDirection === 'up' ? 'fill_now' : 'wait';
|
||||
}
|
||||
|
||||
private function confidenceLabel(int $confidence): string
|
||||
{
|
||||
return match (true) {
|
||||
$confidence >= 70 => 'high',
|
||||
$confidence >= 40 => 'medium',
|
||||
default => 'low',
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Graceful payload when the model can't train (e.g. fresh install,
|
||||
* not enough BEIS rows yet). Honest about not-knowing — verdict is
|
||||
* no_signal, confidence 0, reasoning explains why.
|
||||
*
|
||||
* @return array<string, mixed>
|
||||
*/
|
||||
private function insufficientDataPayload(FeatureSpec $spec): array
|
||||
{
|
||||
return [
|
||||
'fuel_type' => 'e10',
|
||||
'current_avg' => $this->nationalCurrentAverage(),
|
||||
'predicted_direction' => 'stable',
|
||||
'predicted_change_pence' => 0.0,
|
||||
'confidence_score' => 0,
|
||||
'confidence_label' => 'low',
|
||||
'action' => 'no_signal',
|
||||
'reasoning' => 'Not enough historical BEIS data yet to train the forecast model — staying silent until the series fills in.',
|
||||
'prediction_horizon_days' => 7,
|
||||
'region_key' => 'national',
|
||||
'methodology' => 'ridge_regression_v1',
|
||||
'model_version' => $spec->modelVersion(),
|
||||
'weekly_summary' => [
|
||||
'latest_publication_date' => null,
|
||||
'latest_avg_pence' => null,
|
||||
'prior_avg_pence' => null,
|
||||
'latest_change_pence' => null,
|
||||
],
|
||||
'signals' => [],
|
||||
];
|
||||
}
|
||||
|
||||
private function nationalCurrentAverage(): float
|
||||
{
|
||||
$avg = DB::table('station_prices_current')
|
||||
->where('fuel_type', 'e10')
|
||||
->avg('price_pence');
|
||||
|
||||
return $avg === null ? 0.0 : round((float) $avg / 100, 1);
|
||||
}
|
||||
|
||||
/** @return array<string, mixed> */
|
||||
private function weeklySummary(WeeklyPumpPriceLoader $loader): array
|
||||
{
|
||||
$dates = $loader->allDates();
|
||||
$latest = end($dates) ?: null;
|
||||
$prior = $latest === null ? null : ($dates[count($dates) - 2] ?? null);
|
||||
|
||||
$todayPence = $latest === null ? null : $loader->ulspPence($latest);
|
||||
$priorPence = $prior === null ? null : $loader->ulspPence($prior);
|
||||
|
||||
return [
|
||||
'latest_publication_date' => $latest,
|
||||
'latest_avg_pence' => $todayPence === null ? null : round($todayPence / 100, 1),
|
||||
'prior_avg_pence' => $priorPence === null ? null : round($priorPence / 100, 1),
|
||||
'latest_change_pence' => $todayPence !== null && $priorPence !== null
|
||||
? round(($todayPence - $priorPence) / 100, 1)
|
||||
: null,
|
||||
];
|
||||
}
|
||||
|
||||
/**
|
||||
* Backward-compat 'signals' key. Now describes which features carried
|
||||
* the most weight in this week's prediction (z-score × β contribution).
|
||||
*
|
||||
* @return array<string, array<string, mixed>>
|
||||
*/
|
||||
private function describeSignals(RidgeRegressionModel $model, WeeklyPrediction $prediction): array
|
||||
{
|
||||
$coeffs = $model->coefficients();
|
||||
if ($coeffs === null) {
|
||||
return [];
|
||||
}
|
||||
|
||||
return [
|
||||
'ridge_v1' => [
|
||||
'enabled' => true,
|
||||
'direction' => $prediction->direction,
|
||||
'magnitude_pence' => round($prediction->magnitudePence / 100, 2),
|
||||
'feature_count' => count($coeffs['features'] ?? []),
|
||||
'lambda' => $coeffs['lambda'] ?? null,
|
||||
],
|
||||
];
|
||||
}
|
||||
|
||||
/**
|
||||
* Persist the forecast row so Phase 6's outcome resolver can pair
|
||||
* it with the actual ULSP when the next BEIS week lands.
|
||||
* Idempotent on (forecast_for, model_version) via UPSERT.
|
||||
*/
|
||||
private function persistForecast(
|
||||
FeatureSpec $spec,
|
||||
CarbonInterface $targetMonday,
|
||||
WeeklyPrediction $prediction,
|
||||
int $confidence,
|
||||
bool $flaggedDutyChange,
|
||||
string $reasoning,
|
||||
): void {
|
||||
DB::table('weekly_forecasts')->upsert(
|
||||
[[
|
||||
'forecast_for' => $targetMonday->toDateString(),
|
||||
'model_version' => $spec->modelVersion(),
|
||||
'direction' => $prediction->direction,
|
||||
'magnitude_pence' => (int) round($prediction->magnitudePence),
|
||||
'ridge_confidence' => max(0, min(100, $confidence)),
|
||||
'flagged_duty_change' => $flaggedDutyChange,
|
||||
'reasoning' => $reasoning,
|
||||
'generated_at' => now(),
|
||||
'created_at' => now(),
|
||||
'updated_at' => now(),
|
||||
]],
|
||||
['forecast_for', 'model_version'],
|
||||
['direction', 'magnitude_pence', 'ridge_confidence', 'flagged_duty_change', 'reasoning', 'generated_at', 'updated_at'],
|
||||
);
|
||||
}
|
||||
}
|
||||
20
app/Services/Forecasting/WeeklyPrediction.php
Normal file
20
app/Services/Forecasting/WeeklyPrediction.php
Normal file
@@ -0,0 +1,20 @@
|
||||
<?php
|
||||
|
||||
namespace App\Services\Forecasting;
|
||||
|
||||
use Carbon\CarbonInterface;
|
||||
|
||||
/**
|
||||
* The output of WeeklyForecastModel::predict().
|
||||
*
|
||||
* direction is derived from magnitudePence vs FLAT_THRESHOLD by the
|
||||
* model itself, so the harness never re-derives it.
|
||||
*/
|
||||
final readonly class WeeklyPrediction
|
||||
{
|
||||
public function __construct(
|
||||
public CarbonInterface $targetMonday,
|
||||
public float $magnitudePence,
|
||||
public string $direction,
|
||||
) {}
|
||||
}
|
||||
58
app/Services/Forecasting/WeeklyPumpPriceLoader.php
Normal file
58
app/Services/Forecasting/WeeklyPumpPriceLoader.php
Normal file
@@ -0,0 +1,58 @@
|
||||
<?php
|
||||
|
||||
namespace App\Services\Forecasting;
|
||||
|
||||
use Illuminate\Support\Facades\DB;
|
||||
|
||||
/**
|
||||
* Loads `weekly_pump_prices` once into an in-memory map keyed by date.
|
||||
*
|
||||
* Used by features and the ridge model — avoids one SELECT per
|
||||
* (week × feature) lookup. Lazy: nothing loads until first query.
|
||||
*/
|
||||
final class WeeklyPumpPriceLoader
|
||||
{
|
||||
/** @var array<string, object{date: string, ulsp_pence: int, ulsd_pence: int}>|null */
|
||||
private ?array $byDate = null;
|
||||
|
||||
public function ulspPence(string $date): ?int
|
||||
{
|
||||
$row = $this->byDate()[$date] ?? null;
|
||||
|
||||
return $row === null ? null : (int) $row->ulsp_pence;
|
||||
}
|
||||
|
||||
public function ulsdPence(string $date): ?int
|
||||
{
|
||||
$row = $this->byDate()[$date] ?? null;
|
||||
|
||||
return $row === null ? null : (int) $row->ulsd_pence;
|
||||
}
|
||||
|
||||
/** @return array<int, string> Sorted ascending. */
|
||||
public function allDates(): array
|
||||
{
|
||||
return array_keys($this->byDate());
|
||||
}
|
||||
|
||||
/** @return array<string, object{date: string, ulsp_pence: int, ulsd_pence: int}> */
|
||||
private function byDate(): array
|
||||
{
|
||||
if ($this->byDate !== null) {
|
||||
return $this->byDate;
|
||||
}
|
||||
|
||||
$rows = DB::table('weekly_pump_prices')
|
||||
->orderBy('date')
|
||||
->get(['date', 'ulsp_pence', 'ulsd_pence']);
|
||||
|
||||
$map = [];
|
||||
foreach ($rows as $r) {
|
||||
$map[(string) $r->date] = $r;
|
||||
}
|
||||
|
||||
$this->byDate = $map;
|
||||
|
||||
return $map;
|
||||
}
|
||||
}
|
||||
@@ -7,8 +7,9 @@ use App\Enums\PriceReliability;
|
||||
use App\Models\Search;
|
||||
use App\Models\Station;
|
||||
use App\Models\User;
|
||||
use App\Services\Forecasting\LocalSnapshotService;
|
||||
use App\Services\Forecasting\WeeklyForecastService;
|
||||
use App\Services\HaversineQuery;
|
||||
use App\Services\NationalFuelPredictionService;
|
||||
use App\Services\PlanFeatures;
|
||||
use Illuminate\Database\Query\JoinClause;
|
||||
use Illuminate\Support\Carbon;
|
||||
@@ -17,7 +18,8 @@ use Illuminate\Support\Collection;
|
||||
final class StationSearchService
|
||||
{
|
||||
public function __construct(
|
||||
private readonly NationalFuelPredictionService $predictionService,
|
||||
private readonly WeeklyForecastService $weeklyForecast,
|
||||
private readonly LocalSnapshotService $localSnapshot,
|
||||
) {}
|
||||
|
||||
public function search(SearchCriteria $criteria, ?User $user, ?string $ipHash): SearchResult
|
||||
@@ -134,7 +136,10 @@ final class StationSearchService
|
||||
*/
|
||||
private function buildPrediction(?User $user, SearchCriteria $criteria): array
|
||||
{
|
||||
$result = $this->predictionService->predict($criteria->lat, $criteria->lng);
|
||||
$result = $this->weeklyForecast->currentForecast();
|
||||
// Layer 1 is national; the region_key only reflects whether the
|
||||
// caller passed coordinates so the JSON contract stays stable.
|
||||
$result['region_key'] = 'regional';
|
||||
|
||||
$canSeeFull = $user !== null && PlanFeatures::for($user)->can('ai_predictions');
|
||||
|
||||
@@ -146,6 +151,13 @@ final class StationSearchService
|
||||
];
|
||||
}
|
||||
|
||||
$result['local_snapshot'] = $this->localSnapshot->snapshot(
|
||||
fuelType: $criteria->fuelType->value,
|
||||
lat: $criteria->lat,
|
||||
lng: $criteria->lng,
|
||||
radiusKm: max(10, (int) $criteria->radiusKm),
|
||||
);
|
||||
|
||||
return $result;
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user