sqa 0.0.32 → 0.0.38

data/lib/sqa/portfolio.rb

@@ -5,7 +5,7 @@ require 'date'
 require 'csv'
 
 class SQA::Portfolio
-  attr_accessor :positions, :trades, :cash, :initial_cash
+  attr_accessor :positions, :trades, :cash, :initial_cash, :commission
 
   # Represents a single position in the portfolio
   Position = Struct.new(:ticker, :shares, :avg_cost, :total_cost) do
@@ -52,6 +52,19 @@ class SQA::Portfolio
   # @param price [Float] Price per share
   # @param date [Date] Date of trade
   # @return [Trade] The executed trade
+  #
+  # @example Buy 10 shares of AAPL
+  #   portfolio = SQA::Portfolio.new(initial_cash: 10_000, commission: 1.0)
+  #   trade = portfolio.buy('AAPL', shares: 10, price: 150.0)
+  #   trade.action  # => :buy
+  #   trade.total   # => 1500.0
+  #   portfolio.cash  # => 8499.0 (10_000 - 1500 - 1.0 commission)
+  #
+  # @example Buy multiple stocks
+  #   portfolio.buy('AAPL', shares: 10, price: 150.0)
+  #   portfolio.buy('MSFT', shares: 5, price: 300.0)
+  #   portfolio.positions.size  # => 2
+  #
   def buy(ticker, shares:, price:, date: Date.today)
     raise BadParameterError, "Shares must be positive" if shares <= 0
     raise BadParameterError, "Price must be positive" if price <= 0
@@ -95,6 +108,19 @@ class SQA::Portfolio
   # @param price [Float] Price per share
   # @param date [Date] Date of trade
   # @return [Trade] The executed trade
+  #
+  # @example Sell entire position for profit
+  #   portfolio = SQA::Portfolio.new(initial_cash: 10_000, commission: 1.0)
+  #   portfolio.buy('AAPL', shares: 10, price: 150.0)
+  #   trade = portfolio.sell('AAPL', shares: 10, price: 160.0)
+  #   trade.total  # => 1600.0
+  #   portfolio.cash  # => 8498.0 + 1599.0 = 10097.0 (after commissions)
+  #
+  # @example Partial sale
+  #   portfolio.buy('AAPL', shares: 100, price: 150.0)
+  #   portfolio.sell('AAPL', shares: 50, price: 160.0)  # Sell half
+  #   portfolio.position('AAPL').shares  # => 50
+  #
   def sell(ticker, shares:, price:, date: Date.today)
     raise BadParameterError, "Shares must be positive" if shares <= 0
     raise BadParameterError, "Price must be positive" if price <= 0
@@ -145,6 +171,18 @@ class SQA::Portfolio
   # Calculate total portfolio value
   # @param current_prices [Hash] Hash of ticker => current_price
   # @return [Float] Total portfolio value (cash + positions)
+  #
+  # @example Calculate portfolio value with current prices
+  #   portfolio = SQA::Portfolio.new(initial_cash: 10_000)
+  #   portfolio.buy('AAPL', shares: 10, price: 150.0)
+  #   portfolio.buy('MSFT', shares: 5, price: 300.0)
+  #
+  #   current_prices = { 'AAPL' => 160.0, 'MSFT' => 310.0 }
+  #   portfolio.value(current_prices)  # => 10_000 - 1500 - 1500 + 1600 + 1550 = 10_150
+  #
+  # @example Without current prices (uses avg_cost)
+  #   portfolio.value  # Uses purchase prices if no current prices provided
+  #
   def value(current_prices = {})
     positions_value = @positions.sum do |ticker, pos|
       current_price = current_prices[ticker] || pos.avg_cost
@@ -186,6 +224,22 @@ class SQA::Portfolio
   # Get summary statistics
   # @param current_prices [Hash] Hash of ticker => current_price
   # @return [Hash] Summary statistics
+  #
+  # @example Get portfolio performance summary
+  #   portfolio = SQA::Portfolio.new(initial_cash: 10_000, commission: 1.0)
+  #   portfolio.buy('AAPL', shares: 10, price: 150.0)
+  #   portfolio.sell('AAPL', shares: 5, price: 160.0)
+  #
+  #   summary = portfolio.summary({ 'AAPL' => 165.0 })
+  #   summary[:initial_cash]        # => 10_000.0
+  #   summary[:current_cash]        # => 8798.0
+  #   summary[:positions_count]     # => 1
+  #   summary[:total_value]         # => 9623.0
+  #   summary[:profit_loss_percent] # => -3.77%
+  #   summary[:total_trades]        # => 2
+  #   summary[:buy_trades]          # => 1
+  #   summary[:sell_trades]         # => 1
+  #
   def summary(current_prices = {})
     {
       initial_cash: @initial_cash,

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,12 +1,83 @@
 # 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
@@ -25,9 +96,14 @@ class SQA::Stock
     @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))
@@ -44,27 +120,68 @@ class SQA::Stock
     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]
+  #
+  # @example Update stock metadata from API
+  #   stock = SQA::Stock.new(ticker: 'AAPL')
+  #   stock.update  # Fetches latest company overview data
+  #   stock.data.overview['market_capitalization']  # => 2500000000000
+  #   stock.data.overview['pe_ratio']  # => 28.5
+  #
+  # @example Update is safe if API fails
+  #   stock.update  # No error raised if API is unavailable
+  #   # Warning logged but stock remains usable with cached data
+  #
   def update
     begin
       merge_overview
-    rescue => e
+    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
@@ -103,15 +220,22 @@ class SQA::Stock
         @df = @klass.recent(@ticker, full: true)
         @df.to_csv(@df_path)
         return
-      rescue => e
+      rescue StandardError => e
         # If we can't fetch data, raise a more helpful error
-        raise "Unable to fetch data for #{@ticker}. Please ensure API key is set or provide cached CSV file at #{@df_path}. Error: #{e.message}"
+        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
     return unless should_update?
 
@@ -125,13 +249,25 @@ class SQA::Stock
         @df.concat_and_deduplicate!(df2)
         @df.to_csv(@df_path)
       end
-    rescue => e
+    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
+
+  # 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
@@ -140,7 +276,7 @@ class SQA::Stock
     if @source == :alpha_vantage
       begin
         SQA.av_api_key
-      rescue
+      rescue SQA::ConfigurationError
         return false
       end
     end
@@ -151,7 +287,7 @@ class SQA::Stock
       begin
         last_timestamp = Date.parse(@df["timestamp"].to_a.last)
         return false if last_timestamp >= Date.today
-      rescue => e
+      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
@@ -160,6 +296,12 @@ class SQA::Stock
     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
@@ -167,13 +309,18 @@ class SQA::Stock
   # 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
 
@@ -192,10 +339,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)
 
@@ -216,7 +373,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