sqa 0.0.31 → 0.0.37

data/lib/sqa/sector_analyzer.rb

@@ -89,15 +89,11 @@ module SQA
       kb = @blackboards[sector]
       all_patterns = []
 
-      puts "=" * 70
-      puts "Discovering patterns for #{sector.to_s.upcase} sector"
-      puts "Analyzing #{stocks.size} stocks: #{stocks.map(&:ticker).join(', ')}"
-      puts "=" * 70
-      puts
+      debug_me {"Discovering patterns for #{sector.to_s.upcase} sector - #{stocks.size} stocks"}
 
       # Discover patterns for each stock
       stocks.each do |stock|
-        puts "\nAnalyzing #{stock.ticker}..."
+        debug_me {"Analyzing #{stock.ticker}..."}
 
         generator = SQA::StrategyGenerator.new(stock: stock, **options)
         patterns = generator.discover_patterns
@@ -136,11 +132,7 @@ module SQA
         })
       end
 
-      puts "\n" + "=" * 70
-      puts "Sector Analysis Complete"
-      puts "  Individual patterns found: #{all_patterns.size}"
-      puts "  Sector-wide patterns: #{sector_patterns.size}"
-      puts "=" * 70
+      debug_me {"Sector Analysis Complete - #{all_patterns.size} individual, #{sector_patterns.size} sector-wide patterns"}
 
       sector_patterns
     end

data/lib/sqa/stock.rb

@@ -1,53 +1,176 @@
 # lib/sqa/stock.rb
 
+# Represents a stock with price history, metadata, and technical analysis capabilities.
+# This is the primary domain object for interacting with stock data.
+#
+# @example Basic usage
+#   stock = SQA::Stock.new(ticker: 'AAPL')
+#   prices = stock.df["adj_close_price"].to_a
+#   puts stock.to_s
+#
+# @example With different data source
+#   stock = SQA::Stock.new(ticker: 'MSFT', source: :yahoo_finance)
+#
 class SQA::Stock
   extend Forwardable
 
-  CONNECTION = Faraday.new(url: "https://www.alphavantage.co")
+  # Default Alpha Vantage API URL
+  # @return [String] The base URL for Alpha Vantage API
+  ALPHA_VANTAGE_URL = "https://www.alphavantage.co".freeze
 
+  # @deprecated Use {.connection} method instead. Will be removed in v1.0.0
+  # @return [Faraday::Connection] Legacy constant for backward compatibility
+  CONNECTION = Faraday.new(url: ALPHA_VANTAGE_URL)
+
+  class << self
+    # Returns the current Faraday connection for API requests.
+    # Allows injection of custom connections for testing or different configurations.
+    #
+    # @return [Faraday::Connection] The current connection instance
+    def connection
+      @connection ||= default_connection
+    end
+
+    # Sets a custom Faraday connection.
+    # Useful for testing with mocks/stubs or configuring different API endpoints.
+    #
+    # @param conn [Faraday::Connection] Custom Faraday connection to use
+    # @return [Faraday::Connection] The connection that was set
+    def connection=(conn)
+      @connection = conn
+    end
+
+    # Creates the default Faraday connection to Alpha Vantage.
+    #
+    # @return [Faraday::Connection] A new connection to Alpha Vantage API
+    def default_connection
+      Faraday.new(url: ALPHA_VANTAGE_URL)
+    end
+
+    # Resets the connection to default.
+    # Useful for testing cleanup to ensure fresh state between tests.
+    #
+    # @return [nil]
+    def reset_connection!
+      @connection = nil
+    end
+  end
+
+  # @!attribute [rw] data
+  #   @return [SQA::DataFrame::Data] Stock metadata (ticker, name, exchange, etc.)
+  # @!attribute [rw] df
+  #   @return [SQA::DataFrame] Price and volume data as a DataFrame
+  # @!attribute [rw] klass
+  #   @return [Class] The data source class (e.g., SQA::DataFrame::AlphaVantage)
+  # @!attribute [rw] transformers
+  #   @return [Hash] Column transformers for data normalization
+  # @!attribute [rw] strategy
+  #   @return [SQA::Strategy, nil] Optional trading strategy attached to this stock
   attr_accessor :data, :df, :klass, :transformers, :strategy
 
+  # Creates a new Stock instance and loads or fetches its data.
+  #
+  # @param ticker [String] The stock ticker symbol (e.g., 'AAPL', 'MSFT')
+  # @param source [Symbol] The data source to use (:alpha_vantage or :yahoo_finance)
+  # @raise [SQA::DataFetchError] If data cannot be fetched and no cached data exists
+  #
+  # @example
+  #   stock = SQA::Stock.new(ticker: 'AAPL')
+  #   stock = SQA::Stock.new(ticker: 'GOOG', source: :yahoo_finance)
+  #
   def initialize(ticker:, source: :alpha_vantage)
     @ticker = ticker.downcase
     @source = source
 
-    raise "Invalid Ticker #{ticker}" unless SQA::Ticker.valid?(ticker)
-
     @data_path = SQA.data_dir + "#{@ticker}.json"
     @df_path = SQA.data_dir + "#{@ticker}.csv"
 
+    # Validate ticker if validation data is available and cached data doesn't exist
+    unless @data_path.exist? && @df_path.exist?
+      unless SQA::Ticker.valid?(ticker)
+        warn "Warning: Ticker #{ticker} could not be validated. Proceeding anyway." if $VERBOSE
+      end
+    end
+
     @klass = "SQA::DataFrame::#{@source.to_s.camelize}".constantize
     @transformers = "SQA::DataFrame::#{@source.to_s.camelize}::TRANSFORMERS".constantize
 
     load_or_create_data
-    update_the_dataframe
+    update_dataframe
   end
 
+  # Loads existing data from cache or creates new data structure.
+  # If cached data exists, loads from JSON file. Otherwise creates
+  # minimal structure and attempts to fetch overview from API.
+  #
+  # @return [void]
   def load_or_create_data
     if @data_path.exist?
       @data = SQA::DataFrame::Data.new(JSON.parse(@data_path.read))
     else
+      # Create minimal data structure
       create_data
+
+      # Try to fetch overview data, but don't fail if we can't
+      # This is optional metadata - we can work with just price data
       update
+
+      # Save whatever data we have (even if overview fetch failed)
       save_data
     end
   end
 
+  # Creates a new minimal data structure for the stock.
+  #
+  # @return [SQA::DataFrame::Data] The newly created data object
   def create_data
-    @data = SQA::DataFrame::Data.new(ticker: @ticker, source: @source, indicators: { xyzzy: "Magic" })
+    @data = SQA::DataFrame::Data.new(ticker: @ticker, source: @source, indicators: {})
   end
 
+  # Updates the stock's overview data from the API.
+  # Silently handles errors since overview data is optional.
+  #
+  # @return [void]
   def update
-    merge_overview
+    begin
+      merge_overview
+    rescue StandardError => e
+      # Log warning but don't fail - overview data is optional
+      # Common causes: rate limits, network issues, API errors
+      warn "Warning: Could not fetch overview data for #{@ticker} (#{e.class}: #{e.message}). Continuing without it."
+    end
   end
 
+  # Persists the stock's metadata to a JSON file.
+  #
+  # @return [Integer] Number of bytes written
   def save_data
     @data_path.write(@data.to_json)
   end
 
+  # @!method ticker
+  #   @return [String] The stock's ticker symbol
+  # @!method name
+  #   @return [String, nil] The company name
+  # @!method exchange
+  #   @return [String, nil] The exchange where the stock trades
+  # @!method source
+  #   @return [Symbol] The data source (:alpha_vantage or :yahoo_finance)
+  # @!method indicators
+  #   @return [Hash] Cached indicator values
+  # @!method indicators=(value)
+  #   @param value [Hash] New indicator values
+  # @!method overview
+  #   @return [Hash, nil] Company overview data from API
   def_delegators :@data, :ticker, :name, :exchange, :source, :indicators, :indicators=, :overview
 
-  def update_the_dataframe
+  # Updates the DataFrame with price data.
+  # Loads from cache if available, otherwise fetches from API.
+  # Applies migrations for old data formats and updates with recent data.
+  #
+  # @return [void]
+  # @raise [SQA::DataFetchError] If data cannot be fetched and no cache exists
+  def update_dataframe
     if @df_path.exist?
       # Load cached CSV - transformers already applied when data was first fetched
       # Don't reapply them as columns are already in correct format
@@ -82,36 +205,111 @@ class SQA::Stock
       @df.to_csv(@df_path) if migrated
     else
       # Fetch fresh data from source (applies transformers and mapping)
-      @df = @klass.recent(@ticker, full: true)
-      @df.to_csv(@df_path)
-      return
+      begin
+        @df = @klass.recent(@ticker, full: true)
+        @df.to_csv(@df_path)
+        return
+      rescue StandardError => e
+        # If we can't fetch data, raise a more helpful error
+        raise SQA::DataFetchError.new(
+          "Unable to fetch data for #{@ticker}. Please ensure API key is set or provide cached CSV file at #{@df_path}. Error: #{e.message}",
+          original: e
+        )
+      end
     end
 
     update_dataframe_with_recent_data
   end
 
+  # Fetches recent data from API and appends to existing DataFrame.
+  # Only called if should_update? returns true.
+  #
+  # @return [void]
   def update_dataframe_with_recent_data
-    from_date = Date.parse(@df["timestamp"].to_a.last)
-    df2 = @klass.recent(@ticker, from_date: from_date)
+    return unless should_update?
+
+    begin
+      # CSV is sorted ascending (oldest first, TA-Lib compatible), so .last gets the most recent date
+      from_date = Date.parse(@df["timestamp"].to_a.last)
+      df2 = @klass.recent(@ticker, from_date: from_date)
+
+      if df2 && (df2.size > 0)
+        # Use concat_and_deduplicate! to prevent duplicate timestamps and maintain ascending sort
+        @df.concat_and_deduplicate!(df2)
+        @df.to_csv(@df_path)
+      end
+    rescue StandardError => e
+      # Log warning but don't fail - we have cached data
+      # Common causes: rate limits, network issues, API errors
+      warn "Warning: Could not update #{@ticker} from API (#{e.class}: #{e.message}). Using cached data."
+    end
+  end
+
+  # @deprecated Use {#update_dataframe} instead. Will be removed in v1.0.0
+  # @return [void]
+  def update_the_dataframe
+    warn "[SQA DEPRECATION] update_the_dataframe is deprecated; use update_dataframe instead" if $VERBOSE
+    update_dataframe
+  end
 
-    if df2 && (df2.size > 0)
-      @df.concat!(df2)
-      @df.to_csv(@df_path)
+  # Determines whether the DataFrame should be updated from the API.
+  # Returns false if lazy_update is enabled, API key is missing,
+  # or data is already current.
+  #
+  # @return [Boolean] true if update should proceed, false otherwise
+  def should_update?
+    # Don't update if we're in lazy update mode
+    return false if SQA.config.lazy_update
+
+    # Don't update if we don't have an API key (only relevant for Alpha Vantage)
+    if @source == :alpha_vantage
+      begin
+        SQA.av_api_key
+      rescue SQA::ConfigurationError
+        return false
+      end
     end
+
+    # Don't update if CSV data is already current (last timestamp is today or later)
+    # This prevents unnecessary API calls when we already have today's data
+    if @df && @df.size > 0
+      begin
+        last_timestamp = Date.parse(@df["timestamp"].to_a.last)
+        return false if last_timestamp >= Date.today
+      rescue ArgumentError, Date::Error => e
+        # If we can't parse the date, assume we need to update
+        warn "Warning: Could not parse last timestamp for #{@ticker} (#{e.message}). Will attempt update." if $VERBOSE
+      end
+    end
+
+    true
   end
 
+  # Returns a human-readable string representation of the stock.
+  #
+  # @return [String] Summary including ticker, data points count, and date range
+  #
+  # @example
+  #   stock.to_s  # => "aapl with 252 data points from 2023-01-03 to 2023-12-29"
   def to_s
     "#{ticker} with #{@df.size} data points from #{@df["timestamp"].to_a.first} to #{@df["timestamp"].to_a.last}"
   end
+  # Note: CSV data is stored in ascending chronological order (oldest to newest)
+  # This ensures compatibility with TA-Lib indicators which expect arrays in this order
   alias_method :inspect, :to_s
 
+  # Fetches and merges company overview data from Alpha Vantage API.
+  # Converts API response keys to snake_case and appropriate data types.
+  #
+  # @return [Hash] The merged overview data
+  # @raise [ApiError] If the API returns an error response
   def merge_overview
     temp = JSON.parse(
-      CONNECTION.get("/query?function=OVERVIEW&symbol=#{ticker.upcase}&apikey=#{SQA.av.key}")
+      self.class.connection.get("/query?function=OVERVIEW&symbol=#{ticker.upcase}&apikey=#{SQA.av.key}")
       .to_hash[:body]
     )
 
-    if temp.has_key? "Information"
+    if temp.key?("Information")
       ApiError.raise(temp["Information"])
     end
 
@@ -130,10 +328,20 @@ class SQA::Stock
   ## Class Methods
 
   class << self
+    # Fetches top gainers, losers, and most actively traded stocks from Alpha Vantage.
+    # Results are cached after the first call.
+    #
+    # @return [Hashie::Mash] Object with top_gainers, top_losers, and most_actively_traded arrays
+    #
+    # @example
+    #   top = SQA::Stock.top
+    #   top.top_gainers.each { |stock| puts "#{stock.ticker}: +#{stock.change_percentage}%" }
+    #   top.top_losers.first.ticker  # => "XYZ"
+    #
     def top
-      return @@top unless @@top.nil?
+      return @top if @top
 
-      a_hash = JSON.parse(CONNECTION.get("/query?function=TOP_GAINERS_LOSERS&apikey=#{SQA.av.key}").to_hash[:body])
+      a_hash = JSON.parse(connection.get("/query?function=TOP_GAINERS_LOSERS&apikey=#{SQA.av.key}").to_hash[:body])
 
       mash = Hashie::Mash.new(a_hash)
 
@@ -154,7 +362,15 @@ class SQA::Stock
         end
       end
 
-      @@top = mash
+      @top = mash
+    end
+
+    # Resets the cached top gainers/losers data.
+    # Useful for testing or forcing a refresh.
+    #
+    # @return [nil]
+    def reset_top!
+      @top = nil
     end
   end
 end

data/lib/sqa/strategy.rb

@@ -1,16 +1,45 @@
 # lib/sqa/strategy.rb
 
+# Framework for managing and executing trading strategies.
+# Strategies are pluggable modules that generate buy/sell/hold signals.
+#
+# @example Basic usage
+#   strategy = SQA::Strategy.new
+#   strategy.add(SQA::Strategy::RSI)
+#   strategy.add(SQA::Strategy::MACD)
+#   signals = strategy.execute(vector)  # => [:buy, :hold]
+#
+# @example Auto-loading strategies
+#   strategy = SQA::Strategy.new
+#   strategy.auto_load(except: [:random])
+#
 class SQA::Strategy
+  # @!attribute [rw] strategies
+  #   @return [Array<Method>] Collection of strategy trade methods
   attr_accessor :strategies
 
+  # Creates a new Strategy instance with an empty strategies collection.
   def initialize
     @strategies = []
   end
 
+  # Adds a trading strategy to the collection.
+  # Strategies must be either a Class with a .trade method or a Method object.
+  #
+  # @param a_strategy [Class, Method] Strategy to add
+  # @return [Array<Method>] Updated strategies collection
+  # @raise [BadParameterError] If strategy is not a Class or Method
+  #
+  # @example Adding a class-based strategy
+  #   strategy.add(SQA::Strategy::RSI)
+  #
+  # @example Adding a method directly
+  #   strategy.add(MyModule.method(:custom_trade))
+  #
   def add(a_strategy)
-    raise BadParameterError unless [Class, Method].include? a_strategy.class
+    raise BadParameterError unless a_strategy.is_a?(Class) || a_strategy.is_a?(Method)
 
-    a_proc  = if Class == a_strategy.class
+    a_proc  = if a_strategy.is_a?(Class)
                 a_strategy.method(:trade)
               else
                 a_strategy
@@ -19,13 +48,34 @@ class SQA::Strategy
     @strategies << a_proc
   end
 
+  # Executes all registered strategies with the given data vector.
+  #
+  # @param v [OpenStruct] Data vector containing indicator values and prices
+  # @return [Array<Symbol>] Array of signals (:buy, :sell, or :hold) from each strategy
+  #
+  # @example
+  #   vector = OpenStruct.new(rsi: 25, prices: prices_array)
+  #   signals = strategy.execute(vector)  # => [:buy, :hold, :sell]
+  #
   def execute(v)
     result = []
-    # TODO: Can do this in parallel ...
+    # NOTE: Could be parallelized with Parallel gem for large strategy sets
     @strategies.each { |signal| result << signal.call(v) }
     result
   end
 
+  # Auto-loads strategy files from the strategy directory.
+  #
+  # @param except [Array<Symbol>] Strategy names to exclude (default: [:common])
+  # @param only [Array<Symbol>] If provided, only load these strategies
+  # @return [nil]
+  #
+  # @example Load all except random
+  #   strategy.auto_load(except: [:common, :random])
+  #
+  # @example Load only specific strategies
+  #   strategy.auto_load(only: [:rsi, :macd])
+  #
   def auto_load(except: [:common], only: [])
     dir_path  = Pathname.new(__dir__) + "strategy"
     except    = Array(except).map{|f| f.to_s.downcase}
@@ -47,9 +97,17 @@ class SQA::Strategy
     nil
   end
 
+  # Returns all available strategy classes in the SQA::Strategy namespace.
+  #
+  # @return [Array<Class>] Array of strategy classes
+  #
+  # @example
+  #   SQA::Strategy.new.available
+  #   # => [SQA::Strategy::RSI, SQA::Strategy::MACD, ...]
+  #
   def available
     ObjectSpace.each_object(Class).select { |klass|
-      klass.to_s.start_with?("SQA::Strategy::")
+      klass.name&.start_with?("SQA::Strategy::")
     }
   end
 end

data/lib/sqa/ticker.rb

@@ -1,68 +1,133 @@
 # sqa/lib/sqa/ticker.rb
 #
-# Uses the https://dumbstockapi.com/ website to download a CSV file
+# Stock ticker symbol validation and lookup using the dumbstockapi.com service.
+# Downloads and caches a CSV file containing ticker symbols, company names, and exchanges.
 #
-# The CSV files have names like this:
-#   "dumbstockapi-2023-09-21T16 39 55.165Z.csv"
+# @example Validating a ticker
+#   SQA::Ticker.valid?('AAPL')  # => true
+#   SQA::Ticker.valid?('FAKE')  # => false
 #
-# which has this header:
-#   ticker,name,is_etf,exchange
-#
-# Not using the is_etf columns
+# @example Looking up ticker info
+#   info = SQA::Ticker.lookup('AAPL')
+#   info[:name]      # => "Apple Inc"
+#   info[:exchange]  # => "NASDAQ"
 #
 class SQA::Ticker
+  # @return [String] Prefix for downloaded CSV filenames
   FILENAME_PREFIX = "dumbstockapi"
+
+  # @return [Faraday::Connection] Connection to dumbstockapi.com
   CONNECTION      = Faraday.new(url: "https://dumbstockapi.com")
-  @@data          = {}
 
+  class << self
+    # Downloads ticker data from dumbstockapi.com and saves to data directory.
+    #
+    # @param country [String] Country code for ticker list (default: "US")
+    # @return [Integer] HTTP status code from the download request
+    #
+    # @example
+    #   SQA::Ticker.download("US")  # => 200
+    #
+    def download(country="US")
+      response = CONNECTION.get("/stock?format=csv&countries=#{country.upcase}").to_hash
 
-  def self.download(country="US")
-    response = CONNECTION.get("/stock?format=csv&countries=#{country.upcase}").to_hash
+      if 200 == response[:status]
+        filename = response[:response_headers]["content-disposition"].split('=').last.gsub('"','')
+        out_path = Pathname.new(SQA.config.data_dir) + filename
+        out_path.write response[:body]
+      end
 
-    if 200 == response[:status]
-      filename = response[:response_headers]["content-disposition"].split('=').last.gsub('"','')
-      out_path = Pathname.new(SQA.config.data_dir) + filename
-      out_path.write response[:body]
+      response[:status]
     end
 
-    response[:status]
-  end
-
+    # Loads ticker data from cached CSV or downloads if not available.
+    # Retries download up to 3 times if no cached file exists.
+    #
+    # @return [Hash{String => Hash}] Hash mapping ticker symbols to info hashes
+    def load
+      tries = 0
+      found = false
 
-  def self.load
-    tries = 0
-    found = false
+      until(found || tries >= 3) do
+        files     = Pathname.new(SQA.config.data_dir).children.select{|c| c.basename.to_s.start_with?(FILENAME_PREFIX)}.sort
+        if files.empty?
+          begin
+            download
+          rescue StandardError => e
+            warn "Warning: Could not download ticker list: #{e.message}" if $VERBOSE
+          end
+          tries += 1
+        else
+          found = true
+        end
+      end
 
-     until(found || tries >= 3) do
-      files     = Pathname.new(SQA.config.data_dir).children.select{|c| c.basename.to_s.start_with?(FILENAME_PREFIX)}.sort
       if files.empty?
-        download
-        tries += 1
-      else
-        found = true
+        warn "Warning: No ticker validation data available. Proceeding without validation." if $VERBOSE
+        return {}
       end
-    end
 
-    raise "NoDataError" if files.empty?
-
-    load_from_csv files.last
-  end
+      load_from_csv files.last
+    end
 
+    # Loads ticker data from a specific CSV file.
+    #
+    # @param csv_path [Pathname, String] Path to CSV file
+    # @return [Hash{String => Hash}] Hash mapping ticker symbols to info hashes
+    def load_from_csv(csv_path)
+      @data ||= {}
+      CSV.foreach(csv_path, headers: true) do |row|
+        @data[row["ticker"]] = {
+          name:     row["name"],
+          exchange: row["exchange"]
+        }
+      end
 
-  def self.load_from_csv(csv_path)
-    CSV.foreach(csv_path, headers: true) do |row|
-      @@data[row["ticker"]] = {
-        name:     row["name"],
-        exchange: row["exchange"]
-      }
+      @data
     end
 
-    @@data
-  end
+    # Returns the cached ticker data, loading it if necessary.
+    #
+    # @return [Hash{String => Hash}] Hash mapping ticker symbols to info hashes
+    def data
+      @data ||= {}
+      @data.empty? ? load : @data
+    end
 
+    # Looks up information for a specific ticker symbol.
+    #
+    # @param ticker [String, nil] Ticker symbol to look up
+    # @return [Hash, nil] Hash with :name and :exchange keys, or nil if not found
+    #
+    # @example
+    #   SQA::Ticker.lookup('AAPL')  # => { name: "Apple Inc", exchange: "NASDAQ" }
+    #   SQA::Ticker.lookup('FAKE')  # => nil
+    #
+    def lookup(ticker)
+      return nil if ticker.nil? || ticker.to_s.empty?
+      data[ticker.to_s.upcase]
+    end
 
+    # Checks if a ticker symbol is valid (exists in the data).
+    #
+    # @param ticker [String, nil] Ticker symbol to validate
+    # @return [Boolean] true if ticker exists, false otherwise
+    #
+    # @example
+    #   SQA::Ticker.valid?('AAPL')  # => true
+    #   SQA::Ticker.valid?(nil)     # => false
+    #
+    def valid?(ticker)
+      return false if ticker.nil? || ticker.to_s.empty?
+      data.key?(ticker.to_s.upcase)
+    end
 
-  def self.data           = @@data.empty? ? load : @@data
-  def self.lookup(ticker) = data[ticker.upcase]
-  def self.valid?(ticker) = data.has_key?(ticker.upcase)
+    # Resets the cached ticker data.
+    # Useful for testing to force a fresh load.
+    #
+    # @return [Hash] Empty hash
+    def reset!
+      @data = {}
+    end
+  end
 end

data/lib/sqa/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SQA
-  VERSION = '0.0.31'
+  VERSION = '0.0.37'
 end