fundamentalista 0.1.0

data/lib/fundamentalista/configuration.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Fundamentalista
+  # Global settings, reached through Fundamentalista.configure.
+  #
+  #   Fundamentalista.configure do |config|
+  #     config.edgar_user_agent = "Acme Research research@acme.com"
+  #     config.fmp_api_key = ENV["FMP_API_KEY"]
+  #     config.default_provider = :fmp
+  #   end
+  #
+  class Configuration
+    class << self
+      def option(key, default = nil) # :nodoc:
+        attr_reader key
+
+        define_method(:"#{key}=") do |value|
+          value = nil if value.is_a?(String) && value.strip.empty?
+          instance_variable_set(:"@#{key}", value)
+        end
+        defaults[key] = default
+      end
+
+      def defaults # :nodoc:
+        @defaults ||= {}
+      end
+    end
+
+    # The User-Agent the SEC requires on every EDGAR request: an app name
+    # and a contact email.
+    option :edgar_user_agent
+
+    # Requests per second sent to EDGAR; the SEC allows ten.
+    option :edgar_requests_per_second, 8
+
+    # The Financial Modeling Prep API key.
+    option :fmp_api_key
+
+    # The provider Fundamentalista.company uses when none is given.
+    option :default_provider, :edgar
+
+    # Seconds to wait for a provider response.
+    option :request_timeout, 30
+
+    # Retries on transient provider failures.
+    option :max_retries, 2
+
+    # A store responding to +fetch(key) { value }+, such as an
+    # ActiveSupport::Cache store, that keeps provider responses. EDGAR
+    # documents run to megabytes, so set one in any long-lived process.
+    option :cache
+
+    # The logger.
+    option :logger
+
+    def initialize
+      self.class.defaults.each { |key, value| instance_variable_set(:"@#{key}", value) }
+      @logger ||= Logger.new($stdout, level: Logger::INFO)
+    end
+
+    # Shows every setting, with keys redacted.
+    def inspect
+      settings = self.class.defaults.keys.map do |key|
+        value = public_send(key)
+        value = '[REDACTED]' if key.end_with?('_key') && value
+        "#{key}: #{value.inspect}"
+      end
+      "#<#{self.class.name} #{settings.join(', ')}>"
+    end
+  end
+end

data/lib/fundamentalista/dcf.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Fundamentalista
+  # A discounted cash flow: a starting cash flow grown at +growth+ for
+  # +years+, then a terminal value at +terminal_growth+, all discounted at
+  # +discount_rate+. With +fade+ the growth declines evenly from +growth+
+  # in the first year to +terminal_growth+ in the last, instead of
+  # dropping at once. Rates are decimals, so 0.08 means 8%.
+  #
+  #   dcf = Fundamentalista::DCF.new(cash_flow: 98_767_000_000, growth: 0.06, discount_rate: 0.09)
+  #   dcf.value           # present value of the projected flows plus the terminal value
+  #   dcf.projection      # the flows, year by year
+  #   Fundamentalista::DCF.new(cash_flow: 100, growth: 0.15, discount_rate: 0.1, fade: true).growth_path
+  #
+  class DCF
+    include Inspectable
+
+    attr_reader :cash_flow, :growth, :discount_rate, :terminal_growth, :years
+
+    def initialize(cash_flow:, growth:, discount_rate:, terminal_growth: BigDecimal('0.025'), years: 10, fade: false)
+      @cash_flow = Decimal.wrap(cash_flow)
+      @growth = Decimal.wrap(growth)
+      @discount_rate = Decimal.wrap(discount_rate)
+      @terminal_growth = Decimal.wrap(terminal_growth)
+      @years = years
+      @fade = fade
+      raise ArgumentError, 'discount_rate must exceed terminal_growth' if @discount_rate <= @terminal_growth
+    end
+
+    # Whether growth fades towards the terminal rate over the projection.
+    def fade?
+      @fade
+    end
+
+    # The growth rate applied in each year, 1 to +years+.
+    def growth_path
+      return Array.new(years, growth) unless fade? && years > 1
+
+      step = (growth - terminal_growth) / (years - 1)
+      (0...years).map { |index| growth - (step * index) }
+    end
+
+    # The projected cash flow of each year, 1 to +years+.
+    def projection
+      growth_path.each_with_object([]) { |rate, flows| flows << ((flows.last || cash_flow) * (1 + rate)) }
+    end
+
+    # The present value of the projected cash flows.
+    def present_value
+      projection.each_with_index.sum(BigDecimal('0')) { |flow, index| discount(flow, index + 1) }
+    end
+
+    # The terminal value at the end of the projection, undiscounted.
+    def terminal_value
+      projection.last * (1 + terminal_growth) / (discount_rate - terminal_growth)
+    end
+
+    # The present value of the projection plus the discounted terminal value.
+    def value
+      present_value + discount(terminal_value, years)
+    end
+
+    def inspect_attributes # :nodoc:
+      { cash_flow: cash_flow, growth: growth, discount_rate: discount_rate, years: years, fade: (true if fade?), value: value }
+    end
+
+    private
+
+    def discount(amount, year)
+      amount / ((1 + discount_rate)**year)
+    end
+  end
+end

data/lib/fundamentalista/decimal.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Fundamentalista
+  # Arithmetic over values that may be missing. Every statement figure is a
+  # BigDecimal or +nil+, and every derived number stays +nil+ when an input
+  # is missing, so a ratio never raises on an incomplete filing.
+  module Decimal
+    module_function
+
+    # Returns +value+ as a BigDecimal, or +nil+ for +nil+ and blank strings.
+    def wrap(value)
+      return value if value.is_a?(BigDecimal)
+      return nil if value.nil? || (value.respond_to?(:empty?) && value.empty?)
+
+      BigDecimal(value.to_s)
+    end
+
+    # Returns +numerator+ divided by +denominator+, or +nil+ when either is
+    # missing or the denominator is zero.
+    def ratio(numerator, denominator)
+      return nil if numerator.nil? || denominator.nil? || denominator.zero?
+
+      numerator / denominator
+    end
+
+    # Returns the sum of +values+, or +nil+ when any is missing.
+    def sum(*values)
+      return nil if values.any?(&:nil?)
+
+      values.sum(BigDecimal('0'))
+    end
+
+    # Returns +minuend+ minus +subtrahend+, or +nil+ when either is missing.
+    def subtract(minuend, subtrahend)
+      return nil if minuend.nil? || subtrahend.nil?
+
+      minuend - subtrahend
+    end
+
+    # Returns the mean of +values+, ignoring missing ones, or +nil+ when all
+    # are missing.
+    def average(*values)
+      present = values.compact
+      return nil if present.empty?
+
+      present.sum(BigDecimal('0')) / present.length
+    end
+
+    # Returns the compound annual growth rate from +first+ to +last+ over
+    # +years+, or +nil+ when it cannot be computed.
+    def cagr(first, last, years)
+      return nil if first.nil? || last.nil? || years.nil? || years <= 0 || first <= 0 || last <= 0
+
+      BigDecimal((last / first).to_f**(1.0 / years), 12) - 1
+    end
+  end
+end

data/lib/fundamentalista/error.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Fundamentalista
+  # Base class for errors raised while talking to a data provider. Carries
+  # the HTTP response when there is one.
+  class Error < StandardError
+    attr_reader :response
+
+    def initialize(message = nil, response: nil)
+      @response = response
+      super(message || response&.body.to_s)
+    end
+  end
+
+  class ConfigurationError < StandardError; end
+  class CompanyNotFoundError < Error; end
+  class UnauthorizedError < Error; end
+  class RateLimitError < Error; end
+  class ServerError < Error; end
+  class UnsupportedPeriodError < StandardError; end
+  class NoFinancialsError < StandardError; end
+  class QuoteUnavailableError < StandardError; end
+end

data/lib/fundamentalista/estimate.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Fundamentalista
+  # The analyst consensus for a future fiscal year: average, low and high
+  # of the estimated EPS, plus revenue, EBITDA and net income averages and
+  # the number of analysts behind the EPS figure.
+  class Estimate
+    include Inspectable
+    include Serializable
+
+    attr_reader :fiscal_year_end, :eps, :eps_low, :eps_high, :revenue, :ebitda, :net_income, :analysts
+
+    def initialize(fiscal_year_end:, eps:, eps_low: nil, eps_high: nil, revenue: nil, ebitda: nil, net_income: nil, analysts: nil)
+      @fiscal_year_end = fiscal_year_end
+      @eps = Decimal.wrap(eps)
+      @eps_low = Decimal.wrap(eps_low)
+      @eps_high = Decimal.wrap(eps_high)
+      @revenue = Decimal.wrap(revenue)
+      @ebitda = Decimal.wrap(ebitda)
+      @net_income = Decimal.wrap(net_income)
+      @analysts = analysts
+    end
+
+    # The fiscal year the estimate covers.
+    def fiscal_year
+      fiscal_year_end.year
+    end
+
+    # The growth the consensus EPS implies over +eps+, as a rate.
+    def eps_growth(from)
+      Decimal.cagr(Decimal.wrap(from), eps, 1)
+    end
+
+    def inspect_attributes # :nodoc:
+      { fiscal_year: fiscal_year, eps: eps, revenue: revenue, analysts: analysts }
+    end
+  end
+end

data/lib/fundamentalista/financials.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Fundamentalista
+  # The reporting history of a company: an ordered collection of Periods,
+  # newest first, each linked to the one before it.
+  #
+  #   financials = company.financials(limit: 5)
+  #   financials.latest.ratios.net_margin
+  #   financials.growth(:revenue)              # CAGR over the whole history
+  #   financials.series(:free_cash_flow)       # {2025 => ..., 2024 => ...}
+  #
+  class Financials
+    include Enumerable
+    include Inspectable
+    include Serializable
+
+    def initialize(periods)
+      @periods = periods.sort_by(&:ended_on).reverse
+      @periods.each_cons(2) { |period, prior| period.prior = prior }
+    end
+
+    def each(&)
+      @periods.each(&)
+    end
+
+    # The most recent Period.
+    def latest
+      @periods.first
+    end
+
+    # The oldest Period.
+    def oldest
+      @periods.last
+    end
+
+    # The number of periods.
+    def size
+      @periods.size
+    end
+
+    # Returns the Period of +fiscal_year+, and of +quarter+ within it for
+    # quarterly periods, or +nil+.
+    def year(fiscal_year, quarter = nil)
+      @periods.find { |period| period.fiscal_year == fiscal_year && period.quarter == quarter }
+    end
+
+    # Returns every period as a Hash, newest first.
+    def to_h
+      { periods: @periods.map(&:to_h) }
+    end
+
+    # Returns +metric+ for every period keyed by fiscal year, or by
+    # [fiscal year, quarter] for quarterly periods, newest first.
+    def series(metric)
+      @periods.to_h do |period|
+        [period.quarter ? [period.fiscal_year, period.quarter] : period.fiscal_year, period.metric(metric)]
+      end
+    end
+
+    # Returns the trailing twelve months as one Period: the last four
+    # quarters' flows added up, the latest balance sheet, and the four
+    # quarters before as its prior period when there are eight. Needs
+    # quarterly periods.
+    def ttm
+      raise UnsupportedPeriodError, 'No quarterly periods on file; IFRS filers report annually on EDGAR' if size.zero?
+      raise UnsupportedPeriodError, 'The trailing twelve months need quarterly periods' unless latest.quarterly?
+      raise UnsupportedPeriodError, 'The trailing twelve months need four quarters' if size < 4
+
+      trailing(@periods.first(4), prior: size >= 8 ? trailing(@periods[4, 4]) : nil)
+    end
+
+    # Returns the compound annual growth rate of +metric+ from the period
+    # +years+ back to the latest one, or over the whole history by default.
+    # Quarterly periods count four to a year.
+    def growth(metric, years: nil)
+      span = years ? periods_per_year * years : size - 1
+      base = @periods[span]
+      return nil if base.nil? || span.zero?
+
+      Decimal.cagr(base.metric(metric), latest.metric(metric), span.to_f / periods_per_year)
+    end
+
+    def inspect_attributes # :nodoc:
+      { periods: size, latest: latest&.fiscal_year, oldest: oldest&.fiscal_year }
+    end
+
+    private
+
+    def trailing(quarters, prior: nil)
+      Period.new(
+        fiscal_year: quarters.first.fiscal_year, ended_on: quarters.first.ended_on, type: :ttm, prior: prior,
+        currency: quarters.first.currency, balance: quarters.first.balance,
+        income: IncomeStatement.sum(quarters.map(&:income)),
+        cash_flow: CashFlowStatement.sum(quarters.map(&:cash_flow)),
+        banking: Banking.sum(quarters.map(&:banking))
+      )
+    end
+
+    def periods_per_year
+      latest&.quarterly? ? 4 : 1
+    end
+  end
+end

data/lib/fundamentalista/income_statement.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Fundamentalista
+  # One period of the income statement. Figures are in the reporting
+  # currency; +eps_diluted+ is per share, +diluted_shares+ a share count
+  # and +sga+ the selling, general and administrative expense.
+  class IncomeStatement < Statement
+    field :revenue, :cost_of_revenue, :gross_profit, :sga, :operating_income, :interest_expense,
+          :income_before_tax, :income_tax, :net_income, :depreciation_amortization, :ebitda,
+          :eps_diluted, :diluted_shares
+
+    # Gross profit, derived from revenue and cost of revenue when not reported.
+    def gross_profit
+      @gross_profit || Decimal.subtract(revenue, cost_of_revenue)
+    end
+
+    # EBITDA, derived from operating income and depreciation when not reported.
+    def ebitda
+      @ebitda || Decimal.sum(operating_income, depreciation_amortization)
+    end
+
+    # Diluted earnings per share, derived from net income and diluted shares
+    # when not reported.
+    def eps_diluted
+      @eps_diluted || Decimal.ratio(net_income, diluted_shares)
+    end
+
+    # Adds up +statements+, averaging the diluted share count instead.
+    def self.sum(statements)
+      summed = super
+      shares = Decimal.average(*statements.map(&:diluted_shares))
+      new(**summed.to_h, eps_diluted: summed.instance_variable_get(:@eps_diluted), diluted_shares: shares)
+    end
+
+    # The effective tax rate, income tax over income before tax.
+    def tax_rate
+      Decimal.ratio(income_tax, income_before_tax)
+    end
+  end
+end

data/lib/fundamentalista/inspectable.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Fundamentalista
+  module Inspectable # :nodoc:
+    def inspect
+      attributes = inspect_attributes.compact.map { |name, value| "#{name}: #{format_for_inspect(value)}" }
+      return "#<#{self.class.name}>" if attributes.empty?
+
+      "#<#{self.class.name} #{attributes.join(', ')}>"
+    end
+
+    def pretty_print(printer)
+      printer.text(inspect)
+    end
+
+    private
+
+    def format_for_inspect(value)
+      case value
+      when BigDecimal then value.round(4).to_s('F')
+      when Date then value.iso8601
+      else value.inspect
+      end
+    end
+  end
+end

data/lib/fundamentalista/period.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+module Fundamentalista
+  # One reporting period: a fiscal year, a quarter, or the trailing twelve
+  # months, with its three statements. Periods know the period before
+  # them, which is what period-over-period metrics such as ROE on average
+  # equity, growth and the Piotroski score are built on.
+  class Period
+    include Inspectable
+    include Serializable
+
+    # The fiscal year the period belongs to, as an Integer.
+    attr_reader :fiscal_year
+
+    # +:annual+, +:quarterly+ or +:ttm+.
+    attr_reader :type
+
+    # The quarter within the fiscal year, 1 to 4, for quarterly periods.
+    attr_reader :quarter
+
+    # The last day of the period, as a Date.
+    attr_reader :ended_on
+
+    # The IncomeStatement, BalanceSheet and CashFlowStatement.
+    attr_reader :income, :balance, :cash_flow
+
+    # The Banking lines, empty for companies that are not banks.
+    attr_reader :banking
+
+    # Where each line item came from, keyed by item, as Source objects.
+    # Empty when the provider does not say.
+    attr_reader :sources
+
+    # The ISO code of the reporting currency.
+    attr_reader :currency
+
+    # The period before this one, or +nil+.
+    attr_accessor :prior
+
+    def initialize(fiscal_year:, ended_on:, income:, balance:, cash_flow:, banking: Banking.new, sources: {},
+                   type: :annual, quarter: nil, currency: 'USD', prior: nil)
+      @fiscal_year = fiscal_year
+      @ended_on = ended_on
+      @income = income
+      @balance = balance
+      @cash_flow = cash_flow
+      @banking = banking
+      @sources = sources
+      @type = type
+      @quarter = quarter
+      @currency = currency
+      @prior = prior
+    end
+
+    def annual?
+      type == :annual
+    end
+
+    def quarterly?
+      type == :quarterly
+    end
+
+    def ttm?
+      type == :ttm
+    end
+
+    # Whether the company is a bank, judged by net interest income.
+    def bank?
+      banking.bank?
+    end
+
+    # Returns the Source of the line item +name+, or +nil+.
+    def source(name)
+      sources[name]
+    end
+
+    # The period one year earlier: the prior period for annual ones, four
+    # periods back for quarters, or +nil+.
+    def year_ago
+      quarterly? ? 4.times.reduce(self) { |period, _| period&.prior } : prior
+    end
+
+    # Returns the growth of +metric+ against the same period a year
+    # earlier as a rate, or +nil+ without one or a positive base.
+    def yoy(metric)
+      earlier = year_ago
+      earlier && Decimal.cagr(earlier.metric(metric), self.metric(metric), 1)
+    end
+
+    # Returns the period and its statements as a Hash.
+    def to_h
+      { fiscal_year: fiscal_year, quarter: quarter, type: type, ended_on: ended_on, currency: currency,
+        income: income.to_h, balance: balance.to_h, cash_flow: cash_flow.to_h, banking: banking.to_h }
+    end
+
+    # The days the period spans, for turning turnover into days.
+    def days
+      quarterly? ? BigDecimal('91.25') : BigDecimal('365')
+    end
+
+    # Buffett's owner earnings: net income plus depreciation and
+    # amortization minus capital expenditure.
+    def owner_earnings
+      Decimal.subtract(Decimal.sum(income.net_income, income.depreciation_amortization), cash_flow.capital_expenditure)
+    end
+
+    # Returns the Beneish M-score of this period.
+    def beneish
+      Scores::Beneish.new(self)
+    end
+
+    # Returns the Ratios of this period.
+    def ratios
+      Ratios.new(self)
+    end
+
+    # Returns the Piotroski F-score of this period.
+    def piotroski
+      Scores::Piotroski.new(self)
+    end
+
+    # Returns the Altman Z-score of this period for +market_cap+.
+    def altman_z(market_cap:)
+      Scores::AltmanZ.new(self, market_cap: market_cap)
+    end
+
+    # Returns the line item +name+ from whichever statement reports it, or
+    # +nil+. Derived items such as +free_cash_flow+ count, so does
+    # +owner_earnings+, and any of them followed by +_per_share+ is divided
+    # by the shares outstanding.
+    #
+    #   period.metric(:revenue)                    # => 0.416161e12
+    #   period.metric(:free_cash_flow_per_share)   # => 0.66854e1
+    #
+    def metric(name)
+      return owner_earnings if name == :owner_earnings
+      return per_share(name.to_s.delete_suffix('_per_share').to_sym) if name.end_with?('_per_share')
+
+      statement = [income, balance, cash_flow, banking].find { |candidate| candidate.respond_to?(name) }
+      raise ArgumentError, "Unknown metric #{name.inspect}" unless statement
+
+      statement.public_send(name)
+    end
+
+    # Returns +name+ divided by the shares outstanding at the end of the
+    # period, or by the diluted weighted average when the count is missing.
+    def per_share(name)
+      Decimal.ratio(metric(name), balance.shares_outstanding || income.diluted_shares)
+    end
+
+    # Returns the growth of +metric+ against the prior period as a rate, or
+    # +nil+ without a prior period or a positive base.
+    def growth(metric)
+      return nil unless prior
+
+      Decimal.cagr(prior.metric(metric), self.metric(metric), 1)
+    end
+
+    def inspect_attributes # :nodoc:
+      { fiscal_year: fiscal_year, quarter: quarter, type: type, ended_on: ended_on }
+    end
+  end
+end

data/lib/fundamentalista/provider.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Fundamentalista
+  # The contract every data source implements: resolve a Company, return
+  # its Financials, a Quote or +nil+, and the analyst Estimates it has.
+  # Subclasses get an HTTP client with retries and error mapping.
+  class Provider
+    class << self
+      # The symbol the provider is registered under.
+      def slug
+        name.split('::').last.downcase.to_sym
+      end
+    end
+
+    attr_reader :config
+
+    def initialize(config)
+      @config = config
+    end
+
+    def company(ticker)
+      raise NotImplementedError
+    end
+
+    def financials(company, period:, limit:)
+      raise NotImplementedError
+    end
+
+    def quote(company)
+      raise NotImplementedError
+    end
+
+    def estimates(company)
+      raise NotImplementedError
+    end
+
+    private
+
+    def get(url, params = {}, headers: {})
+      key = "fundamentalista:#{url}?#{URI.encode_www_form(params.sort)}"
+      config.cache ? config.cache.fetch(key) { fetch_json(url, params, headers) } : fetch_json(url, params, headers)
+    end
+
+    def fetch_json(url, params, headers)
+      response = connection(headers).get(url, params)
+      check(response)
+      response.body
+    end
+
+    def connection(headers)
+      @connections ||= {}
+      @connections[headers] ||= Faraday.new(headers: headers, request: { timeout: config.request_timeout }) do |faraday|
+        faraday.request :retry, max: config.max_retries, interval: 0.5, backoff_factor: 2,
+                                retry_statuses: [429, 500, 502, 503, 504]
+        faraday.response :json, content_type: /\bjson$/
+        faraday.adapter Faraday.default_adapter
+      end
+    end
+
+    def check(response)
+      case response.status
+      when 200..299 then response
+      when 401, 403 then raise UnauthorizedError.new("#{self.class.slug} rejected the credentials", response: response)
+      when 404 then raise CompanyNotFoundError.new('not found', response: response)
+      when 429 then raise RateLimitError.new("#{self.class.slug} rate limit reached", response: response)
+      else raise ServerError.new("#{self.class.slug} answered #{response.status}", response: response)
+      end
+    end
+  end
+end