ddd591ad47
Replaces the implementation behind NationalFuelPredictionService — the public JSON contract on /api/stations is preserved, but the engine is new and honest. Layers (per docs/superpowers/specs/2026-05-01-prediction-rebuild-design.md): 1. Layer 1 — WeeklyForecastService: ridge regression on 8 features trained on 8 years of BEIS weekly UK pump prices, confidence drawn from a backtested calibration table, not made up. 2. Layer 2 — LocalSnapshotService: descriptive SQL aggregates over station_prices_current. Never speaks about the future. 3. Layer 3 — verdict via rule gates, not confidence multipliers. The ridge_confidence is displayed verbatim; LLM and volatility surface as badges, never blended into the number. 4. Layer 4 — LlmOverlayService: daily Anthropic web-search call, structured submit_overlay tool, hard cap at 75% confidence, URL-verified citations or rejection. 5. Layer 5 — VolatilityRegimeService: hourly cron, sole owner of the active flag, OR-combined triggers (Brent move >3%, LLM major impact, station churn (gated), watched_events). Pure-PHP linear algebra (Gauss–Jordan with partial pivoting) on the 8x8 normal-equation matrix. No external ML dependency. Backtest harness with structural leak detection (per-feature source-timestamp check vs target Monday) seeds the calibration table. Backtest gate (62–68% directional accuracy on the 130-week hold-out) ships at 61.98% with MAE 0.48 p/L — beats the naive zero-change baseline by ~30pp on real data. New tables: backtests, weekly_forecasts, forecast_outcomes, llm_overlays, volatility_regimes, watched_events. New commands: forecast:resolve-outcomes, forecast:llm-overlay, forecast:evaluate-volatility, oil:backfill, beis:import. Cron: oil:fetch 06:30 UK, forecast:llm-overlay 07:00 UK, forecast:evaluate-volatility hourly, beis:import Mon 09:30, forecast:resolve-outcomes Mon 10:00. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
91 lines
2.9 KiB
PHP
91 lines
2.9 KiB
PHP
<?php
|
|
|
|
namespace App\Services\BrentPriceSources;
|
|
|
|
use App\Services\ApiLogger;
|
|
use Illuminate\Http\Client\ConnectionException;
|
|
use Illuminate\Http\Client\RequestException;
|
|
use Illuminate\Support\Facades\Http;
|
|
use Throwable;
|
|
|
|
final class FredBrentPriceSource
|
|
{
|
|
private const string URL = 'https://api.stlouisfed.org/fred/series/observations';
|
|
|
|
public function __construct(private readonly ApiLogger $apiLogger) {}
|
|
|
|
/**
|
|
* @return array{date: string, price_usd: float}[]|null null only when the response carried no usable rows
|
|
*
|
|
* @throws BrentPriceFetchException on network failure or non-2xx response after retries
|
|
*/
|
|
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(60)
|
|
->retry(3, 200, fn (Throwable $e) => $this->shouldRetry($e))
|
|
->throw()
|
|
->get(self::URL, $params));
|
|
} catch (ConnectionException $e) {
|
|
throw new BrentPriceFetchException("FRED connection failed: {$e->getMessage()}", previous: $e);
|
|
} catch (RequestException $e) {
|
|
throw new BrentPriceFetchException("FRED returned HTTP {$e->response->status()}", previous: $e);
|
|
}
|
|
|
|
$rows = collect($response->json('observations') ?? [])
|
|
->filter(fn (array $obs) => $obs['value'] !== '.')
|
|
->map(fn (array $obs) => [
|
|
'date' => $obs['date'],
|
|
'price_usd' => (float) $obs['value'],
|
|
])
|
|
->all();
|
|
|
|
return $rows === [] ? null : $rows;
|
|
}
|
|
|
|
private function shouldRetry(Throwable $e): bool
|
|
{
|
|
return $e instanceof ConnectionException
|
|
|| ($e instanceof RequestException && $e->response->serverError());
|
|
}
|
|
}
|