pure_greeks 0.1.0

data/lib/pure_greeks/engines/fallback_chain.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "pure_greeks/engines/black_scholes_european"
+require "pure_greeks/engines/crr_binomial_american"
+require "pure_greeks/engines/intrinsic"
+
+module PureGreeks
+  module Engines
+    module FallbackChain
+      module_function
+
+      def calculate(exercise_style:, type:, strike:, underlying_price:, time_to_expiry:,
+                    implied_volatility:, risk_free_rate:, dividend_yield:)
+        return Intrinsic.calculate(type: type, strike: strike, underlying_price: underlying_price) if implied_volatility <= 0.0
+
+        engine_args = {
+          type: type,
+          strike: strike,
+          underlying_price: underlying_price,
+          time_to_expiry: time_to_expiry,
+          implied_volatility: implied_volatility,
+          risk_free_rate: risk_free_rate,
+          dividend_yield: dividend_yield
+        }
+
+        if exercise_style == :american
+          begin
+            return CrrBinomialAmerican.calculate(**engine_args)
+          rescue StandardError
+            # fall through to BS European
+          end
+        end
+
+        begin
+          return BlackScholesEuropean.calculate(**engine_args)
+        rescue StandardError
+          # fall through to intrinsic
+        end
+
+        Intrinsic.calculate(type: type, strike: strike, underlying_price: underlying_price)
+      end
+    end
+  end
+end

data/lib/pure_greeks/engines/intrinsic.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "pure_greeks/greeks"
+
+module PureGreeks
+  module Engines
+    module Intrinsic
+      module_function
+
+      def calculate(type:, strike:, underlying_price:)
+        if type == :call
+          price = [0.0, underlying_price - strike].max
+          delta = underlying_price > strike ? 1.0 : 0.0
+        else
+          price = [0.0, strike - underlying_price].max
+          delta = underlying_price < strike ? -1.0 : 0.0
+        end
+
+        Greeks.new(
+          delta: delta,
+          gamma: 0.0,
+          theta: 0.0,
+          vega: 0.0,
+          rho: 0.0,
+          price: price,
+          model: :intrinsic
+        )
+      end
+    end
+  end
+end

data/lib/pure_greeks/errors.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module PureGreeks
+  class Error < StandardError; end
+  class InvalidInputError < Error; end
+  class ExpiredContractError < InvalidInputError; end
+  class CalculationError < Error; end
+  class IVConvergenceError < CalculationError; end
+end

data/lib/pure_greeks/greeks.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PureGreeks
+  Greeks = Data.define(:delta, :gamma, :theta, :vega, :rho, :price, :model)
+end

data/lib/pure_greeks/implied_volatility/brent_solver.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "pure_greeks/errors"
+
+module PureGreeks
+  module ImpliedVolatility
+    module BrentSolver
+      MAX_ITERATIONS = 100
+
+      module_function
+
+      def find_root(lower:, upper:, tolerance: 1e-8, &f)
+        a = lower.to_f
+        b = upper.to_f
+        fa = f.call(a)
+        fb = f.call(b)
+
+        raise IVConvergenceError, "root not bracketed: f(#{a})=#{fa}, f(#{b})=#{fb}" if (fa * fb).positive?
+
+        if fa.abs < fb.abs
+          a, b = b, a
+          fa, fb = fb, fa
+        end
+
+        c = a
+        fc = fa
+        mflag = true
+        d = nil
+
+        MAX_ITERATIONS.times do
+          return b if fb.abs < tolerance || (b - a).abs < tolerance
+
+          s =
+            if fa != fc && fb != fc
+              # Inverse quadratic interpolation
+              (a * fb * fc / ((fa - fb) * (fa - fc))) +
+                (b * fa * fc / ((fb - fa) * (fb - fc))) +
+                (c * fa * fb / ((fc - fa) * (fc - fb)))
+            else
+              # Secant method
+              b - (fb * (b - a) / (fb - fa))
+            end
+
+          condition1 = !s.between?([(3 * a + b) / 4, b].min, [(3 * a + b) / 4, b].max)
+          condition2 = mflag && (s - b).abs >= (b - c).abs / 2
+          condition3 = !mflag && (s - b).abs >= (c - d).abs / 2
+          condition4 = mflag && (b - c).abs < tolerance
+          condition5 = !mflag && d && (c - d).abs < tolerance
+
+          if condition1 || condition2 || condition3 || condition4 || condition5
+            s = (a + b) / 2.0
+            mflag = true
+          else
+            mflag = false
+          end
+
+          fs = f.call(s)
+          d = c
+          c = b
+          fc = fb
+
+          if (fa * fs).negative?
+            b = s
+            fb = fs
+          else
+            a = s
+            fa = fs
+          end
+
+          if fa.abs < fb.abs
+            a, b = b, a
+            fa, fb = fb, fa
+          end
+        end
+
+        raise IVConvergenceError, "exceeded #{MAX_ITERATIONS} iterations"
+      end
+    end
+  end
+end

data/lib/pure_greeks/math/normal.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "distribution"
+
+module PureGreeks
+  module Math
+    module Normal
+      def self.cdf(x)
+        Distribution::Normal.cdf(x)
+      end
+
+      def self.pdf(x)
+        Distribution::Normal.pdf(x)
+      end
+    end
+  end
+end

data/lib/pure_greeks/option.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "date"
+require "pure_greeks/errors"
+require "pure_greeks/engines/fallback_chain"
+require "pure_greeks/engines/black_scholes_european"
+require "pure_greeks/implied_volatility/brent_solver"
+
+module PureGreeks
+  class Option
+    VALID_EXERCISE_STYLES = %i[american european].freeze
+    VALID_TYPES = %i[call put].freeze
+    DAYS_PER_YEAR = 365.0
+
+    attr_reader :exercise_style, :type, :strike, :expiration, :underlying_price,
+                :risk_free_rate, :dividend_yield, :valuation_date
+
+    def initialize(exercise_style:, type:, strike:, expiration:, underlying_price:,
+                   risk_free_rate:, dividend_yield:, valuation_date:,
+                   implied_volatility: nil, market_price: nil)
+      validate!(exercise_style, type, strike, underlying_price, expiration, valuation_date)
+
+      @exercise_style = exercise_style
+      @type = type
+      @strike = strike.to_f
+      @expiration = expiration
+      @underlying_price = underlying_price.to_f
+      @implied_volatility = implied_volatility&.to_f
+      @market_price = market_price&.to_f
+      @risk_free_rate = risk_free_rate.to_f
+      @dividend_yield = dividend_yield.to_f
+      @valuation_date = valuation_date
+    end
+
+    def time_to_expiry
+      (@expiration - @valuation_date).to_f / DAYS_PER_YEAR
+    end
+
+    def greeks
+      @greeks ||= compute_greeks
+    end
+
+    def price
+      greeks.price
+    end
+
+    def delta
+      greeks.delta
+    end
+
+    def gamma
+      greeks.gamma
+    end
+
+    def theta
+      greeks.theta
+    end
+
+    def vega
+      greeks.vega
+    end
+
+    def rho
+      greeks.rho
+    end
+
+    def calculation_model
+      greeks.model
+    end
+
+    def implied_volatility
+      return @implied_volatility if @implied_volatility
+      raise InvalidInputError, "market_price required to solve for implied_volatility" unless @market_price
+
+      @implied_volatility = ImpliedVolatility::BrentSolver.find_root(lower: 1e-6, upper: 5.0, tolerance: 1e-6) do |sigma|
+        Engines::BlackScholesEuropean.price(
+          type: @type,
+          strike: @strike,
+          underlying_price: @underlying_price,
+          time_to_expiry: time_to_expiry,
+          implied_volatility: sigma,
+          risk_free_rate: @risk_free_rate,
+          dividend_yield: @dividend_yield
+        ) - @market_price
+      end
+    end
+
+    private
+
+    def compute_greeks
+      Engines::FallbackChain.calculate(
+        exercise_style: @exercise_style,
+        type: @type,
+        strike: @strike,
+        underlying_price: @underlying_price,
+        time_to_expiry: time_to_expiry,
+        implied_volatility: @implied_volatility,
+        risk_free_rate: @risk_free_rate,
+        dividend_yield: @dividend_yield
+      )
+    end
+
+    def validate!(exercise_style, type, strike, spot, expiration, valuation_date)
+      unless VALID_EXERCISE_STYLES.include?(exercise_style)
+        raise InvalidInputError, "exercise_style must be one of #{VALID_EXERCISE_STYLES}"
+      end
+      raise InvalidInputError, "type must be one of #{VALID_TYPES}" unless VALID_TYPES.include?(type)
+      raise InvalidInputError, "strike must be positive" unless strike.is_a?(Numeric) && strike.positive?
+      raise InvalidInputError, "underlying_price must be positive" unless spot.is_a?(Numeric) && spot.positive?
+      raise ExpiredContractError, "contract expired on #{expiration}" if expiration <= valuation_date
+    end
+  end
+end

data/lib/pure_greeks/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PureGreeks
+  VERSION = "0.1.0"
+end

data/lib/pure_greeks.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "pure_greeks/version"
+require "pure_greeks/errors"
+require "pure_greeks/greeks"
+require "pure_greeks/option"
+
+module PureGreeks
+end

data/sig/pure_greeks.rbs

@@ -0,0 +1,4 @@
+module PureGreeks
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

data/tools/drift_report.rb

@@ -0,0 +1,109 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# One-shot diagnostic: compute drift between PureGreeks and Tenor's
+# QuantLib output across the entire golden fixture. Used during Phase 7
+# to characterize regression drift before deciding on test tolerances.
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "json"
+require "date"
+require "pure_greeks"
+
+fixture = JSON.parse(File.read(File.expand_path("../spec/regression/fixtures/tenor_golden.json", __dir__)))
+
+EXERCISE_STYLE = {
+  "quantlib_american" => :american,
+  "quantlib_european" => :european
+}.freeze
+
+GREEKS = %i[price delta gamma theta vega rho].freeze
+
+drifts = Hash.new { |h, k| h[k] = [] }
+errors = []
+
+fixture["rows"].each do |row|
+  option = PureGreeks::Option.new(
+    exercise_style: EXERCISE_STYLE.fetch(row["calculation_model"]),
+    type: row["option_type"].to_sym,
+    strike: row["strike"],
+    expiration: Date.parse(row["expiration"]),
+    underlying_price: row["underlying_price"],
+    implied_volatility: row["implied_volatility"],
+    risk_free_rate: row["risk_free_rate"],
+    dividend_yield: row["dividend_yield"],
+    valuation_date: Date.parse(row["snapshot_date"])
+  )
+
+  GREEKS.each do |g|
+    mine = option.public_send(g)
+    expected = g == :price ? row["calculated_price"] : row[g.to_s]
+    next if expected.nil?
+
+    drifts[g] << {
+      abs: (mine - expected).abs,
+      mine: mine, expected: expected,
+      iv: row["implied_volatility"],
+      ttm: (Date.parse(row["expiration"]) - Date.parse(row["snapshot_date"])).to_f / 365.0,
+      moneyness: row["underlying_price"] / row["strike"],
+      type: row["option_type"], style: row["calculation_model"],
+      snapshot: row["snapshot_id"]
+    }
+  end
+rescue StandardError => e
+  errors << { row: row["snapshot_id"], error: e.message }
+end
+
+def stats(arr)
+  vals = arr.map { |d| d[:abs] }
+  sorted = vals.sort
+  {
+    n: vals.size,
+    mean: vals.sum / vals.size.to_f,
+    p50: sorted[sorted.size / 2],
+    p95: sorted[(sorted.size * 0.95).to_i],
+    p99: sorted[(sorted.size * 0.99).to_i],
+    max: sorted.last
+  }
+end
+
+puts "=== Drift summary (absolute |mine - expected|) ==="
+puts format("%-7s %5s %12s %12s %12s %12s %12s", "greek", "n", "mean", "p50", "p95", "p99", "max")
+GREEKS.each do |g|
+  s = stats(drifts[g])
+  puts format("%-7s %5d %12.6g %12.6g %12.6g %12.6g %12.6g", g, s[:n], s[:mean], s[:p50], s[:p95], s[:p99], s[:max])
+end
+
+puts "\n=== Pass-rate at proposed tolerances (Greek absolute, price relative) ==="
+proposed = { price_rel: 0.05, price_abs: 0.10, delta: 0.01, gamma: 0.005,
+             theta: 0.005, vega: 0.05, rho: 0.15 }
+pass_counts = Hash.new(0)
+total = drifts[:price].size
+total.times do |i|
+  failures = []
+  failures << :price if drifts[:price][i][:abs] > [proposed[:price_abs], proposed[:price_rel] * drifts[:price][i][:expected].abs].max
+  failures << :delta if drifts[:delta][i][:abs] > proposed[:delta]
+  failures << :gamma if drifts[:gamma][i][:abs] > proposed[:gamma]
+  failures << :theta if drifts[:theta][i][:abs] > proposed[:theta]
+  failures << :vega if drifts[:vega][i][:abs] > proposed[:vega]
+  failures << :rho if drifts[:rho][i][:abs] > proposed[:rho]
+  pass_counts[:all] += 1 if failures.empty?
+  failures.each { |g| pass_counts[g] += 1 }
+end
+puts "  proposed tolerances: #{proposed.inspect}"
+puts "  rows passing all: #{total - pass_counts[:all]} fail / #{total} total = #{((total - pass_counts[:all]) * 100.0 / total).round(1)}%"
+%i[price delta gamma theta vega rho].each do |g|
+  puts "    #{g}: #{pass_counts[g]} fail (#{(pass_counts[g] * 100.0 / total).round(1)}%)"
+end
+
+puts "\n=== Top-5 worst price drifts ==="
+drifts[:price].sort_by { |d| -d[:abs] }.first(5).each do |d|
+  puts format("  %s | %s/%s | iv=%.3f ttm=%.2fy moneyness=%.2f | mine=%.4f expected=%.4f drift=%.4f",
+              d[:snapshot][0, 8], d[:type], d[:style], d[:iv], d[:ttm], d[:moneyness],
+              d[:mine], d[:expected], d[:abs])
+end
+
+if errors.any?
+  puts "\n=== Errors during compute (#{errors.size}) ==="
+  errors.first(5).each { |e| puts "  #{e[:row][0, 8]}: #{e[:error]}" }
+end

data/tools/golden_dataset_export.rb

@@ -0,0 +1,124 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Manual one-shot tool to export a golden dataset from Tenor's prod DB.
+#
+# This script is NOT run as part of the gem or CI. It documents the
+# query and the JSON shape so the fixture can be regenerated reproducibly.
+#
+# Prerequisites:
+#   - psql in $PATH
+#   - Tenor's connection string available at ~/Code/tenor/.mcp.json
+#   - jq in $PATH (used to extract the connection string)
+#
+# Output: spec/regression/fixtures/tenor_golden.json
+#
+# READ-ONLY. The query below must remain a single SELECT; do not modify
+# it to write to the source database.
+
+require "json"
+require "open3"
+require "time"
+
+GOLDEN_DATASET_QUERY = <<~SQL
+  SELECT
+    g.snapshot_id::text                AS snapshot_id,
+    s.option_type                      AS option_type,
+    s.strike::float8                   AS strike,
+    s.expiration::text                 AS expiration,
+    s.snapshot_date::text              AS snapshot_date,
+    s.underlying_price::float8         AS underlying_price,
+    s.implied_volatility::float8       AS implied_volatility,
+    COALESCE(g.dividend_yield, 0)::float8 AS dividend_yield,
+    g.risk_free_rate::float8           AS risk_free_rate,
+    g.delta::float8                    AS delta,
+    g.gamma::float8                    AS gamma,
+    g.theta::float8                    AS theta,
+    g.vega::float8                     AS vega,
+    g.rho::float8                      AS rho,
+    g.calculated_price::float8         AS calculated_price,
+    g.calculation_model                AS calculation_model
+  FROM options.greeks g
+  JOIN options.snapshots s ON s.id = g.snapshot_id
+  WHERE g.calculation_model IN ('quantlib_american', 'quantlib_european')
+    AND s.option_type IN ('calls', 'puts')
+    AND s.strike IS NOT NULL
+    AND s.underlying_price IS NOT NULL
+    AND s.implied_volatility IS NOT NULL
+    -- IV band: drop near-zero (Tenor's QuantLib quietly floors σ → divergent
+    -- price/Greeks vs. our straight BS) and >200% (illiquid market noise).
+    AND s.implied_volatility BETWEEN 0.05 AND 2.0
+    AND s.expiration IS NOT NULL
+    AND s.expiration > s.snapshot_date
+    -- Drop very short tenors: 200-step CRR has O(1/N) bias that blows up
+    -- as T -> 0; <7 days isn't a realistic v0.1 use case anyway.
+    AND (s.expiration - s.snapshot_date) >= 7
+    -- Moneyness band: drop deep ITM/OTM where pricing is dominated by
+    -- intrinsic and any small discount-rate convention difference shows.
+    AND (s.underlying_price / s.strike) BETWEEN 0.5 AND 2.0
+    AND g.risk_free_rate IS NOT NULL
+    AND g.delta IS NOT NULL
+    AND g.gamma IS NOT NULL
+    AND g.theta IS NOT NULL
+    AND g.vega IS NOT NULL
+    AND g.rho IS NOT NULL
+    AND g.calculated_price IS NOT NULL
+  ORDER BY RANDOM()
+  LIMIT 500;
+SQL
+
+OPTION_TYPE_MAP = { "calls" => "call", "puts" => "put" }.freeze
+NUMERIC_FIELDS = %w[
+  strike underlying_price implied_volatility dividend_yield risk_free_rate
+  delta gamma theta vega rho calculated_price
+].freeze
+
+def main
+  pg_url = `jq -r '.mcpServers."postgres-prod".args[2]' ~/Code/tenor/.mcp.json`.strip
+  raise "could not read postgres-prod connection string" if pg_url.empty?
+
+  stdout, stderr, status = Open3.capture3(
+    "psql", pg_url, "--csv", "--pset=footer=off",
+    "-c", GOLDEN_DATASET_QUERY
+  )
+  raise "psql failed: #{stderr}" unless status.success?
+
+  rows = parse_csv(stdout)
+  rows = normalize_rows(rows)
+
+  output = {
+    "_meta" => {
+      "exported_at" => Time.now.utc.iso8601,
+      "source" => "Tenor prod DB (options.greeks JOIN options.snapshots)",
+      "rate_source" => "options.greeks.risk_free_rate per row " \
+                       "(Tenor backfills options.risk_free_rates from FRED)",
+      "calculation_models" => %w[quantlib_american quantlib_european],
+      "sampling" => "ORDER BY RANDOM() LIMIT 500",
+      "row_count" => rows.size,
+      "tool" => "tools/golden_dataset_export.rb"
+    },
+    "rows" => rows
+  }
+
+  fixture_path = File.expand_path("../spec/regression/fixtures/tenor_golden.json", __dir__)
+  File.write(fixture_path, JSON.pretty_generate(output))
+  puts "Wrote #{rows.size} rows to #{fixture_path}"
+end
+
+def parse_csv(blob)
+  require "csv"
+  table = CSV.parse(blob, headers: true)
+  table.map(&:to_h)
+end
+
+def normalize_rows(rows)
+  rows.map do |row|
+    NUMERIC_FIELDS.each { |k| row[k] = row[k].to_f }
+    row["option_type"] = OPTION_TYPE_MAP.fetch(row["option_type"]) do |t|
+      raise "unexpected option_type=#{t.inspect} on row=#{row.inspect}"
+    end
+    row
+  end
+end
+
+main if $PROGRAM_NAME == __FILE__