timeprice 0.7.0 → 0.8.0

data/lib/timeprice/cli/presenters/compare.rb

@@ -15,30 +15,66 @@ module Timeprice
         end
 
         def json_hash
-          @result.to_h.merge(
+          base = @result.to_h.merge(
             amount: round_money(@result.amount, @result.to_currency),
             original_amount: round_money(@result.original_amount, @result.from_currency),
             converted_amount: round_money(@result.converted_amount, @result.to_currency),
             fx_rate: @result.fx_rate.to_f.round(6),
             cpi_ratio: @result.cpi_ratio.to_f.round(6)
           )
+          if @result.forecast
+            fc = @result.forecast
+            base[:forecast] = fc.merge(
+              low: round_money(fc[:low], @result.to_currency),
+              high: round_money(fc[:high], @result.to_currency)
+            )
+          else
+            base.delete(:forecast)
+          end
+          base
         end
 
         # Headline + left-to-right chain so the FX + CPI composition reads naturally.
         def text_lines
-          final = "#{fmt_money(@result.amount, @result.to_currency)} #{@result.to_currency}"
-          original = "#{fmt_money(@result.original_amount, @result.from_currency)} #{@result.from_currency}"
+          final     = "#{fmt_money(@result.amount, @result.to_currency)} #{@result.to_currency}"
+          original  = "#{fmt_money(@result.original_amount, @result.from_currency)} #{@result.from_currency}"
           converted = "#{fmt_money(@result.converted_amount, @result.to_currency)} #{@result.to_currency}"
-          step1 = "fx @ #{fmt_rate(@result.fx_rate)}"
-          step2 = "inflate x#{format("%.4f", @result.cpi_ratio)} #{@result.country}"
-          width = [step1.length, step2.length].max
-          [
-            "#{final}  in #{@result.to_date}",
+          step1     = "fx @ #{fmt_rate(@result.fx_rate)}"
+          step2     = "inflate x#{format("%.4f", @result.cpi_ratio)} #{@result.country}"
+          width     = [step1.length, step2.length].max
+          headline = if @result.forecast
+                       "#{final}  in #{@result.to_date}  (forecast)"
+                     else
+                       "#{final}  in #{@result.to_date}"
+                     end
+          lines = [
+            headline,
             "  #{original} (#{@result.from_date})",
             format("    -> %-#{width}s -> %s (%s)", step1, converted, @result.from_date),
             format("    -> %-#{width}s -> %s (%s, %s)", step2, final, @result.to_date,
                    Granularity.humanize(@result.granularity)),
           ]
+          @result.forecast ? lines + forecast_lines(final) : lines
+        end
+
+        private
+
+        def forecast_lines(mid_str)
+          fc       = @result.forecast
+          low_str  = "#{fmt_money(fc[:low], @result.to_currency)} #{@result.to_currency}"
+          high_str = "#{fmt_money(fc[:high], @result.to_currency)} #{@result.to_currency}"
+          extra = [
+            "",
+            "  range     #{low_str}  —  #{mid_str}  —  #{high_str}",
+            "            (low -1σ)        (most likely)      (high +1σ)",
+            "",
+            "  basis     trailing #{fc[:window_years]}y CAGR · last data #{fc[:last_known_date]}",
+            "            sigma ±#{format("%.1f", fc[:sigma_pct] * 100)}%/yr · horizon +#{fc[:horizon_months]}mo",
+          ]
+          if fc[:warnings].include?("horizon_exceeds_cap")
+            extra << "  caveat    long-horizon forecast: results are illustrative, not predictive"
+          end
+          extra
         end
       end
     end

data/lib/timeprice/cli.rb

@@ -1,6 +1,20 @@
 # frozen_string_literal: true
 
-require "thor"
+begin
+  require "thor"
+rescue LoadError
+  warn <<~MSG
+    The `timeprice` CLI requires the `thor` gem, which isn't installed in
+    this environment. Install it with:
+
+        gem install thor
+
+    Library use (`require "timeprice"`) does not need thor; it's a CLI-only
+    dependency as of v0.8.0.
+  MSG
+  exit 1
+end
+
 require "json"
 require_relative "../timeprice"
 require_relative "cli/presenters/inflation"
@@ -106,8 +120,10 @@ module Timeprice
     end
 
     desc "compare AMOUNT", "Combine FX + inflation across two (year, currency) points"
-    method_option :from, type: :string, required: true, desc: "Source as \"YEAR CURRENCY\" or \"CURRENCY YEAR\""
-    method_option :to,   type: :string, required: true, desc: "Target as \"YEAR CURRENCY\" or \"CURRENCY YEAR\""
+    method_option :from,     type: :string,  required: true,  desc: "Source as \"YEAR CURRENCY\" or \"CURRENCY YEAR\""
+    method_option :to,       type: :string,  required: true,  desc: "Target as \"YEAR CURRENCY\" or \"CURRENCY YEAR\""
+    method_option :forecast, type: :boolean, default: false,
+                             desc: "Allow target dates past bundled data via trailing-CAGR forecast"
     def compare(amount)
       with_error_handling do
         from_tuple = parse_compare_token(options[:from], label: "--from")
@@ -115,7 +131,8 @@ module Timeprice
         result = Timeprice.compare(
           amount: parse_amount(amount),
           from: from_tuple,
-          to: to_tuple
+          to: to_tuple,
+          forecast: options[:forecast]
         )
         render Presenters::Compare.new(result)
       end

data/lib/timeprice/compare/series.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require_relative "../inflation"
+require_relative "../exchange"
+require_relative "../forecast/cpi_forecaster"
+require_relative "../forecast/cagr"
+require_relative "../cpi_lookup"
+require_relative "../data_loader"
+require_relative "../point"
+require_relative "../supported"
+
+module Timeprice
+  module Compare
+    # Annual sample points for the result-card chart. Composes the same FX
+    # leg as {Compare.run} and a year-by-year measured-or-forecast CPI ratio
+    # for the destination country.
+    #
+    # Each point is `{ date: "YYYY-01", amount:, measured: }`. Forecast
+    # points additionally carry `:low` and `:high` for the ±1σ band.
+    #
+    # @api private
+    module Series
+      module_function
+
+      DEFAULT_AMOUNT = 100.0
+
+      def for(from:, to:, forecast: false, amount: DEFAULT_AMOUNT)
+        ctx = build_context(from: from, to: to, amount: amount, forecast: forecast)
+        (ctx[:from_year]..ctx[:to_year]).map { |y| point_for(y, ctx) }
+      end
+
+      def build_context(from:, to:, amount:, forecast:)
+        from_point, to_point, to_country = coerce_points(from, to)
+        data = DataLoader.load_cpi(to_country)
+        last_key, last_cpi = last_known(data)
+        last_year = Forecast::Cagr.parse(last_key).year
+
+        {
+          source_in_dest: source_amount_in_dest(amount, from_point, to_point),
+          source_cpi: CpiLookup.new(data).at(from_point.date.to_s).value.to_f,
+          lookup: CpiLookup.new(data),
+          last_year: last_year,
+          last_cpi: last_cpi,
+          from_year: Forecast::Cagr.parse(from_point.date.to_s).year,
+          to_year: Forecast::Cagr.parse(to_point.date.to_s).year,
+          stats: forecast_stats(data, last_key, forecast, to_point, last_year),
+        }
+      end
+
+      def coerce_points(from, to)
+        from_point = Point.coerce(from)
+        to_point   = Point.coerce(to)
+        to_country = Supported.country_for_currency(to_point.currency)
+        fail UnsupportedCurrency, to_point.currency unless to_country
+
+        [from_point, to_point, to_country]
+      end
+
+      def source_amount_in_dest(amount, from_point, to_point)
+        Exchange.convert(
+          amount: amount, from: from_point.currency,
+          to: to_point.currency, date: from_point.fx_anchor_date
+        ).amount
+      end
+
+      def last_known(data)
+        annual_or_monthly = Forecast::CpiForecaster.pick_series(data)
+        last_key = annual_or_monthly.keys.max_by { |k| Forecast::Cagr.parse(k) }
+        [last_key, annual_or_monthly[last_key].to_f]
+      end
+
+      def forecast_stats(data, last_key, forecast, to_point, last_year)
+        return nil unless forecast && Forecast::Cagr.parse(to_point.date.to_s).year > last_year
+
+        Forecast::Cagr.compute(
+          series: Forecast::CpiForecaster.pick_series(data),
+          last_date: last_key,
+          window_years: Forecast::CpiForecaster::DEFAULT_WINDOW_YEARS
+        )
+      end
+
+      def point_for(year, ctx)
+        if year <= ctx[:last_year]
+          measured_point(y: year, lookup: ctx[:lookup],
+                         source_in_dest: ctx[:source_in_dest], source_cpi: ctx[:source_cpi])
+        else
+          forecast_point(y: year, last_year: ctx[:last_year], last_cpi: ctx[:last_cpi],
+                         source_in_dest: ctx[:source_in_dest], source_cpi: ctx[:source_cpi],
+                         stats: ctx[:stats])
+        end
+      end
+
+      def measured_point(y:, lookup:, source_in_dest:, source_cpi:)
+        cpi_y = lookup.at(y.to_s).value.to_f
+        { date: "#{y}-01", amount: source_in_dest * (cpi_y / source_cpi), measured: true }
+      rescue DataNotFound
+        nil
+      end
+
+      def forecast_point(y:, last_year:, last_cpi:, source_in_dest:, source_cpi:, stats:)
+        yrs = y - last_year
+        mid  = last_cpi * ((1.0 + stats[:cagr])**yrs)
+        low  = last_cpi * ((1.0 + stats[:cagr] - stats[:sigma_yoy])**yrs)
+        high = last_cpi * ((1.0 + stats[:cagr] + stats[:sigma_yoy])**yrs)
+        {
+          date: "#{y}-01",
+          amount: source_in_dest * (mid / source_cpi),
+          low: source_in_dest * (low / source_cpi),
+          high: source_in_dest * (high / source_cpi),
+          measured: false,
+        }
+      end
+    end
+
+    # @see Series.for
+    def self.series_for(**)
+      Series.for(**).compact
+    end
+  end
+end

data/lib/timeprice/compare.rb

@@ -6,6 +6,8 @@ require_relative "point"
 require_relative "inflation"
 require_relative "exchange"
 require_relative "granularity"
+require_relative "cpi_lookup"
+require_relative "compare/series"
 
 module Timeprice
   CompareResult = Data.define(
@@ -13,7 +15,8 @@ module Timeprice
     :from_currency, :from_date,
     :to_currency, :to_date,
     :country, :fx_rate, :cpi_ratio,
-    :converted_amount, :granularity
+    :converted_amount, :granularity,
+    :forecast
   )
 
   # Compare combines FX and inflation across two (currency, date) points.
@@ -44,23 +47,20 @@ module Timeprice
     # @param to     [Timeprice::Point, Array(String, String)] destination point
     # @return [CompareResult]
     # @raise [UnsupportedCurrency] if either currency is not in {Supported.currencies}
-    def run(amount:, from:, to:)
+    def run(amount:, from:, to:, forecast: false)
       from_point, to_point, to_country = resolve_points(from, to)
 
-      # Step 1: convert at source date into destination currency.
+      if forecast && future_target?(to_point, to_country)
+        return run_with_forecast(
+          amount: amount, from_point: from_point, to_point: to_point, to_country: to_country
+        )
+      end
+
       fx_result = Exchange.convert(
-        amount: amount,
-        from: from_point.currency,
-        to: to_point.currency,
-        date: from_point.fx_anchor_date
+        amount: amount, from: from_point.currency,
+        to: to_point.currency, date: from_point.fx_anchor_date
       )
-      converted = fx_result.amount
 
-      # Step 2: inflate that destination-currency amount from source date to
-      # destination date using destination-country CPI. When both points
-      # share a date there's no time-elapsed inflation to apply — short-
-      # circuit with a ratio of 1.0 so daily-grain FX dates (which CPI's
-      # monthly-max resolution can't accept) still resolve cleanly.
       if from_point.date == to_point.date
         return fx_only_result(
           amount: amount, from_point: from_point, to_point: to_point,
@@ -68,8 +68,15 @@ module Timeprice
         )
       end
 
+      measured_result(
+        amount: amount, from_point: from_point, to_point: to_point,
+        to_country: to_country, fx_result: fx_result
+      )
+    end
+
+    def measured_result(amount:, from_point:, to_point:, to_country:, fx_result:)
       infl = Inflation.adjust(
-        amount: converted,
+        amount: fx_result.amount,
         from: from_point.date.to_s,
         to: to_point.date.to_s,
         country: to_country
@@ -85,8 +92,9 @@ module Timeprice
         country: to_country,
         fx_rate: fx_result.rate,
         cpi_ratio: infl.to_index.to_f / infl.from_index,
-        converted_amount: converted,
-        granularity: Granularity.merge(fx_result.granularity, infl.granularity)
+        converted_amount: fx_result.amount,
+        granularity: Granularity.merge(fx_result.granularity, infl.granularity),
+        forecast: nil
       )
     end
 
@@ -104,7 +112,8 @@ module Timeprice
         fx_rate: fx_result.rate,
         cpi_ratio: 1.0,
         converted_amount: fx_result.amount,
-        granularity: fx_result.granularity
+        granularity: fx_result.granularity,
+        forecast: nil
       )
     end
 
@@ -119,5 +128,56 @@ module Timeprice
 
       [from_point, to_point, to_country]
     end
+
+    # Returns true when to_point.date is past the destination country's last
+    # bundled CPI date.
+    def future_target?(to_point, to_country)
+      data   = DataLoader.load_cpi(to_country)
+      series = Forecast::CpiForecaster.pick_series(data)
+      last   = series.keys.max_by { |k| Forecast::Cagr.parse(k) }
+      Forecast::Cagr.parse(to_point.date.to_s) > Forecast::Cagr.parse(last)
+    end
+
+    def run_with_forecast(amount:, from_point:, to_point:, to_country:)
+      fx_result = Exchange.convert(
+        amount: amount, from: from_point.currency,
+        to: to_point.currency, date: from_point.fx_anchor_date
+      )
+      cpi_fwd          = Forecast::CpiForecaster.project(country: to_country, target: to_point.date.to_s)
+      source_cpi_value = source_index(to_country, from_point.date.to_s)
+      inflation_ratio  = cpi_fwd.value / source_cpi_value
+
+      CompareResult.new(
+        amount: fx_result.amount * inflation_ratio,
+        original_amount: amount.to_f,
+        from_currency: from_point.currency, from_date: from_point.date.to_s,
+        to_currency: to_point.currency,     to_date: to_point.date.to_s,
+        country: to_country,
+        fx_rate: fx_result.rate,
+        cpi_ratio: inflation_ratio,
+        converted_amount: fx_result.amount,
+        granularity: :forecast,
+        forecast: forecast_hash(cpi_fwd: cpi_fwd, converted: fx_result.amount, source_cpi: source_cpi_value)
+      )
+    end
+
+    def forecast_hash(cpi_fwd:, converted:, source_cpi:)
+      {
+        basis_kind: cpi_fwd.basis_kind,
+        projection_method: cpi_fwd.projection_method,
+        window_years: cpi_fwd.window_years,
+        sigma_pct: cpi_fwd.sigma_pct,
+        last_known_date: cpi_fwd.last_known_date,
+        horizon_months: cpi_fwd.horizon_months,
+        low: converted * (cpi_fwd.low / source_cpi),
+        high: converted * (cpi_fwd.high / source_cpi),
+        warnings: cpi_fwd.warnings,
+      }
+    end
+
+    # Resolve a measured CPI index for the source date (which must be in range).
+    def source_index(country, date)
+      CpiLookup.new(DataLoader.load_cpi(country)).at(date).value.to_f
+    end
   end
 end

data/lib/timeprice/cpi_lookup.rb

@@ -22,17 +22,23 @@ module Timeprice
       @annual    = data.dig("series", "annual")    || {}
     end
 
-    # @param key [String] "YYYY", "YYYY-MM", or "YYYY-Qn"
+    # @param key [String] "YYYY", "YYYY-MM", "YYYY-Qn", or "YYYY-MM-DD"
     # @return [CpiPoint]
     # @raise [DataNotFound] if no CPI value covers `key`
     # @raise [ArgumentError] on malformed `key`
+    #
+    # Daily keys are accepted and silently resolved at month grain — CPI is
+    # published monthly at best, so the day is dropped before lookup. The
+    # returned granularity reflects what the monthly cascade actually found
+    # (monthly / quarterly fallback / annual fallback), not "daily".
     def at(key)
       key = key.to_s
       case key
-      when QUARTER_RE        then quarterly_or_fallbacks(key)
-      when /\A\d{4}-\d{2}\z/ then monthly_or_fallbacks(key)
-      when /\A\d{4}\z/       then annual_or_derived(key)
-      else fail ArgumentError, "Invalid date format: #{key.inspect} (use YYYY, YYYY-MM, or YYYY-Qn)"
+      when QUARTER_RE              then quarterly_or_fallbacks(key)
+      when /\A\d{4}-\d{2}-\d{2}\z/ then monthly_or_fallbacks(key[0, 7])
+      when /\A\d{4}-\d{2}\z/       then monthly_or_fallbacks(key)
+      when /\A\d{4}\z/             then annual_or_derived(key)
+      else fail ArgumentError, "Invalid date format: #{key.inspect} (use YYYY, YYYY-MM, YYYY-Qn, or YYYY-MM-DD)"
       end
     end
 

data/lib/timeprice/forecast/cagr.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Timeprice
+  module Forecast
+    # Pure math: trailing CAGR and σ of year-over-year changes.
+    #
+    # The series is a hash mapping date strings (`"YYYY"` or `"YYYY-MM"`) to
+    # numeric values. The trailing window is anchored on `last_date` and
+    # extends `window_years` backward. CAGR is the annualized geometric
+    # return between the first and last samples in the window. Sigma is the
+    # sample stdev of 1-year-spaced returns within the window.
+    #
+    # No I/O, no DataLoader. Pure function — call from anywhere.
+    #
+    # @api private
+    module Cagr
+      module_function
+
+      # @param series       [Hash{String => Numeric}]
+      # @param last_date    [String] anchor ("YYYY" or "YYYY-MM")
+      # @param window_years [Integer]
+      # @return [Hash] { cagr: Float, sigma_yoy: Float, window_start: String,
+      #                  window_end: String, samples: Integer }
+      def compute(series:, last_date:, window_years:)
+        end_date   = parse(last_date)
+        start_date = shift_years(end_date, -window_years)
+
+        sorted = series
+                 .select { |k, _| within?(k, start_date, end_date) }
+                 .sort_by { |k, _| parse(k) }
+
+        fail ArgumentError, "need at least 2 points in window" if sorted.size < 2
+
+        cagr = annualised_return(sorted)
+
+        {
+          cagr: cagr,
+          sigma_yoy: stdev_of_yoy(sorted),
+          window_start: sorted.first.first,
+          window_end: sorted.last.first,
+          samples: sorted.size,
+        }
+      end
+
+      def annualised_return(sorted)
+        first_v = sorted.first.last.to_f
+        last_v  = sorted.last.last.to_f
+
+        fail ArgumentError, "first window value must be positive (got #{first_v})" unless first_v.positive?
+        fail ArgumentError, "last window value must be positive (got #{last_v})"   unless last_v.positive?
+
+        years_elapsed = (parse(sorted.last.first) - parse(sorted.first.first)) / 365.2425
+        fail ArgumentError, "window has zero elapsed time" unless years_elapsed.positive?
+
+        ((last_v / first_v)**(1.0 / years_elapsed)) - 1.0
+      end
+
+      def parse(s)
+        s = s.to_s
+        return ::Date.new(s.to_i, 1, 1) if s.length == 4
+
+        y, m = s.split("-").map(&:to_i)
+        ::Date.new(y, m, 1)
+      end
+
+      def shift_years(date, years)
+        ::Date.new(date.year + years, date.month, 1)
+      end
+
+      def within?(key, start_date, end_date)
+        d = parse(key)
+        d.between?(start_date, end_date)
+      end
+
+      # Stdev of simple (arithmetic) 1-year-spaced returns within the window.
+      # Returns 0.0 when fewer than 2 paired samples exist.
+      def stdev_of_yoy(sorted)
+        by_date = sorted.to_h
+        returns = sorted.filter_map do |key, value|
+          prior_key = shift_years(parse(key), -1).strftime(key.length == 4 ? "%Y" : "%Y-%m")
+          prior = by_date[prior_key]
+          next unless prior&.positive?
+
+          (value.to_f / prior) - 1.0
+        end
+        return 0.0 if returns.size < 2
+
+        mean = returns.sum / returns.size
+        variance = returns.sum { |r| (r - mean)**2 } / (returns.size - 1)
+        Math.sqrt(variance)
+      end
+    end
+  end
+end

data/lib/timeprice/forecast/cpi_forecaster.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative "../forecast"
+require_relative "../data_loader"
+require_relative "../errors"
+require_relative "cagr"
+
+module Timeprice
+  module Forecast
+    # Project a country's CPI index forward from the last bundled data point.
+    #
+    # @api private
+    module CpiForecaster
+      module_function
+
+      DEFAULT_WINDOW_YEARS = 10
+      HORIZON_CAP_YEARS    = 5
+
+      # @param country      [String]
+      # @param target       [String] "YYYY" or "YYYY-MM"
+      # @param window_years [Integer]
+      # @return [Forecast::Result]
+      # @raise [DataNotFound] if the CPI series has no usable monthly or annual data
+      def project(country:, target:, window_years: DEFAULT_WINDOW_YEARS)
+        series = load_series(country)
+        last_key, last_value = last_entry(series)
+        horizon_months = months_between(last_key, target)
+        warnings = build_warnings(series, last_key, window_years, horizon_months)
+        stats = Cagr.compute(series: series, last_date: last_key, window_years: window_years)
+        build_result(last_key: last_key, last_value: last_value, target: target,
+                     horizon_months: horizon_months, window_years: window_years,
+                     stats: stats, warnings: warnings)
+      end
+
+      # Prefer monthly when present; fall back to annual.
+      def pick_series(data)
+        monthly = data.dig("series", "monthly") || {}
+        return monthly unless monthly.empty?
+
+        data.dig("series", "annual") || {}
+      end
+
+      def months_between(from_key, to_key)
+        f = Cagr.parse(from_key)
+        t = Cagr.parse(to_key)
+        ((t.year - f.year) * 12) + (t.month - f.month)
+      end
+
+      def load_series(country)
+        data = DataLoader.load_cpi(country.to_s.upcase)
+        series = pick_series(data)
+        fail DataNotFound, "no CPI series for #{country}" if series.empty?
+
+        series
+      end
+
+      def last_entry(series)
+        last_key = series.keys.max_by { |k| Cagr.parse(k) }
+        [last_key, series[last_key].to_f]
+      end
+
+      def build_warnings(series, last_key, window_years, horizon_months)
+        warnings = []
+        earliest = series.keys.map { |k| Cagr.parse(k).year }.min
+        warnings << "insufficient_window" if Cagr.parse(last_key).year - window_years < earliest
+        warnings << "horizon_exceeds_cap" if horizon_months > HORIZON_CAP_YEARS * 12
+        warnings.uniq
+      end
+
+      def build_result(last_key:, last_value:, target:, horizon_months:, window_years:, stats:, warnings:)
+        years_forward = horizon_months / 12.0
+        value = last_value * ((1.0 + stats[:cagr])**years_forward)
+        low   = last_value * ((1.0 + stats[:cagr] - stats[:sigma_yoy])**years_forward)
+        high  = last_value * ((1.0 + stats[:cagr] + stats[:sigma_yoy])**years_forward)
+
+        Forecast::Result.new(
+          value: value, low: low, high: high,
+          projection_method: "cagr_trailing",
+          window_years: window_years,
+          sigma_pct: stats[:sigma_yoy],
+          last_known_date: last_key,
+          target_date: target,
+          horizon_months: horizon_months,
+          basis_kind: :cpi,
+          warnings: warnings.uniq
+        )
+      end
+    end
+  end
+end