sqa 0.0.32 → 0.0.37

data/lib/api/alpha_vantage_api.rb

@@ -3,13 +3,9 @@
 require 'faraday'
 require 'json'
 
-# TODO: Reorganize the methods by category
-#         Market Data
-#         Technical Indicators
-#         Trading
-#         Economic Indicators
-#         Digital and Forex
-#
+# Alpha Vantage API wrapper
+# Categories: Market Data, Technical Indicators, Trading, Economic Indicators, Digital/Forex
+# See: https://www.alphavantage.co/documentation/
 
 
 class AlphaVantageAPI

data/lib/sqa/config.rb

@@ -1,30 +1,63 @@
 # lib/sqa/config.rb
 
-# The hierarchies of values should be:
-#   default
-#   envar ..... overrides default
-#   config file ..... overrides envar
-#   command line parameters ...... overrides config file
-
+# Configuration management for SQA with hierarchical value resolution.
+# Values are resolved in this order (later overrides earlier):
+#   1. default values
+#   2. environment variables (SQA_ prefix)
+#   3. config file (YAML, TOML, or JSON)
+#   4. command line parameters
+#
+# @example Basic configuration
+#   SQA.init
+#   SQA.config.data_dir = "~/my_data"
+#   SQA.config.debug = true
+#
+# @example Using config file
+#   SQA.config.config_file = "~/.sqa.yml"
+#   SQA.config.from_file
+#
+# @example Environment variables
+#   # Set SQA_DATA_DIR, SQA_DEBUG, etc. before requiring sqa
+#
+
+require 'fileutils'
 require 'yaml'
 require 'toml-rb'
 
 module SQA
-  # class Config < Hashie::Trash
-  #   include Hashie::Extensions::IgnoreUndeclared
-  #   include Hashie::Extensions::Coercion
-
-
+  # Configuration class for SQA settings.
+  # Extends Hashie::Dash for property-based configuration with coercion.
+  #
+  # @!attribute [rw] command
+  #   @return [String, nil] Current command (nil, 'analysis', or 'web')
+  # @!attribute [rw] config_file
+  #   @return [String, nil] Path to configuration file
+  # @!attribute [rw] dump_config
+  #   @return [String, nil] Path to dump current configuration
+  # @!attribute [rw] data_dir
+  #   @return [String] Directory for data storage (default: ~/sqa_data)
+  # @!attribute [rw] portfolio_filename
+  #   @return [String] Portfolio CSV filename (default: portfolio.csv)
+  # @!attribute [rw] trades_filename
+  #   @return [String] Trades CSV filename (default: trades.csv)
+  # @!attribute [rw] log_level
+  #   @return [Symbol] Log level (:debug, :info, :warn, :error, :fatal)
+  # @!attribute [rw] debug
+  #   @return [Boolean] Enable debug mode
+  # @!attribute [rw] verbose
+  #   @return [Boolean] Enable verbose output
+  # @!attribute [rw] plotting_library
+  #   @return [Symbol] Plotting library to use (:gruff)
+  # @!attribute [rw] lazy_update
+  #   @return [Boolean] Skip API updates if cached data exists
+  #
 	class Config < Hashie::Dash
     include Hashie::Extensions::Dash::PropertyTranslation
     include Hashie::Extensions::MethodAccess
     include Hashie::Extensions::Coercion
 
-    # FIXME:  Getting undefined error PredefinedValues
-    #         I'm thinking that Ruby is dropping it from the ObjectSpace
-    #         Looks like it is only used for the log level.  Should
-    #         able to work around that.
-    #
+    # NOTE: PredefinedValues extension disabled due to compatibility issues.
+    # Log level validation is handled via the `values:` option on the property instead.
     # include Hashie::Extensions::Dash::PredefinedValues
 
     property :command       # a String currently, nil, analysis or web
@@ -33,18 +66,17 @@ module SQA
 
     property :data_dir,     default: Nenv.home + "/sqa_data"
 
-    # TODO: If no path is given, these files will be in
-    #       data directory, otherwise, use the given path
+    # Relative filenames are resolved against data_dir; absolute paths used as-is
     property :portfolio_filename, from: :portfolio, default: "portfolio.csv"
     property :trades_filename,    from: :trades,    default: "trades.csv"
 
     property :log_level,    default: :info,  coerce: Symbol, values: %i[debug info warn error fatal]
 
-    # TODO: need a custom proc since there is no Boolean class in Ruby
-    property :debug,        default: false  #, coerce: Boolean
-    property :verbose,      default: false  #, coerce: Boolean
+    # Boolean coercion handled via coerce_key blocks below (no Boolean class in Ruby)
+    property :debug,        default: false
+    property :verbose,      default: false
 
-    # TODO: use svggraph
+    # Plotting library - gruff is default; svggraph support could be added in future
     property :plotting_library, from: :plot_lib,  default: :gruff, coerce: Symbol
     property :lazy_update,      from: :lazy,      default: false
 
@@ -71,17 +103,41 @@ module SQA
       end
     end
 
+    coerce_key :log_level, ->(v) do
+      v.is_a?(String) ? v.to_sym : v
+    end
+
+    coerce_key :plotting_library, ->(v) do
+      v.is_a?(String) ? v.to_sym : v
+    end
+
     ########################################################
+
+    # Creates a new Config instance with optional initial values.
+    # Automatically applies environment variable overrides.
+    #
+    # @param a_hash [Hash] Initial configuration values
     def initialize(a_hash={})
       super(a_hash)
       override_with_envars
     end
 
+    # Returns whether debug mode is enabled.
+    # @return [Boolean] true if debug mode is on
     def debug?    = debug
+
+    # Returns whether verbose mode is enabled.
+    # @return [Boolean] true if verbose mode is on
     def verbose?  = verbose
 
 
     ########################################################
+
+    # Loads configuration from a file.
+    # Supports YAML (.yml, .yaml), TOML (.toml), and JSON (.json) formats.
+    #
+    # @return [void]
+    # @raise [BadParameterError] If config file is invalid or unsupported format
     def from_file
       return if config_file.nil?
 
@@ -93,8 +149,7 @@ module SQA
         type = "invalid"
       end
 
-      # TODO: arrange order in mostly often used
-
+      # Config file format detection (YAML is most common)
       if ".json" == type
         incoming = form_json
 
@@ -108,19 +163,24 @@ module SQA
         raise BadParameterError, "Invalid Config File: #{config_file}"
       end
 
-      if incoming.has_key? :data_dir
+      if incoming.key?(:data_dir)
         incoming[:data_dir] = incoming[:data_dir].gsub(/^~/, Nenv.home)
       end
 
       merge! incoming
     end
 
+    # Writes current configuration to a file.
+    # Format is determined by file extension.
+    #
+    # @return [void]
+    # @raise [BadParameterError] If config file is not set or unsupported format
     def dump_file
       if config_file.nil?
         raise BadParameterError, "No config file given"
       end
 
-      `touch #{config_file}`
+      FileUtils.touch(config_file)
       # unless  File.exist?(config_file)
 
       type = File.extname(config_file).downcase
@@ -139,7 +199,10 @@ module SQA
       end
     end
 
-    # Method to dynamically extend properties from external sources (e.g., plugins)
+    # Injects additional properties from plugins.
+    # Allows external code to register new configuration options.
+    #
+    # @return [void]
     def inject_additional_properties
       SQA::PluginManager.registered_properties.each do |prop, options|
         self.class.property(prop, options)
@@ -185,11 +248,29 @@ module SQA
 
     #####################################
     class << self
+      # Resets the configuration to default values.
+      # Creates a new Config instance and assigns it to SQA.config.
+      #
+      # @return [SQA::Config] The new config instance
       def reset
+        @initialized = true
         SQA.config = new
       end
+
+      # Returns whether the configuration has been initialized.
+      #
+      # @return [Boolean] true if reset has been called
+      def initialized?
+        @initialized ||= false
+      end
     end
   end
 end
 
-SQA::Config.reset
+# Auto-initialization with deprecation warning
+# This will be removed in v1.0.0 - applications should call SQA.init explicitly
+unless SQA::Config.initialized?
+  warn "[SQA DEPRECATION] Auto-initialization at require time will be removed in v1.0. " \
+       "Please call SQA.init explicitly in your application startup." if $VERBOSE
+  SQA::Config.reset
+end

data/lib/sqa/data_frame/data.rb

@@ -21,9 +21,21 @@ class SQA::DataFrame
   #   data = SQA::DataFrame::Data.new(json_data)
   #
   class Data
+    # @!attribute [rw] ticker
+    #   @return [String, nil] Stock ticker symbol (e.g., 'AAPL', 'MSFT')
+    # @!attribute [rw] name
+    #   @return [String, nil] Company name
+    # @!attribute [rw] exchange
+    #   @return [String, nil] Exchange where stock trades (e.g., 'NASDAQ', 'NYSE')
+    # @!attribute [rw] source
+    #   @return [Symbol] Data source (:alpha_vantage, :yahoo_finance)
+    # @!attribute [rw] indicators
+    #   @return [Hash] Technical indicators configuration and cached values
+    # @!attribute [rw] overview
+    #   @return [Hash] Company overview data from API
     attr_accessor :ticker, :name, :exchange, :source, :indicators, :overview
 
-    # Initialize stock metadata
+    # Initializes stock metadata.
     #
     # Can be called in two ways:
     #   1. With a hash: SQA::DataFrame::Data.new(hash) - for JSON deserialization

data/lib/sqa/data_frame.rb

@@ -10,11 +10,40 @@ require_relative 'data_frame/data'
 require_relative 'data_frame/yahoo_finance'
 require_relative 'data_frame/alpha_vantage'
 
+# High-performance DataFrame wrapper around Polars for time series data manipulation.
+# Provides convenience methods for stock market data while leveraging Polars' Rust-backed
+# performance for vectorized operations.
+#
+# @example Creating from CSV
+#   df = SQA::DataFrame.load(source: "path/to/data.csv")
+#
+# @example Creating from array of hashes
+#   data = [{ timestamp: "2024-01-01", close: 100.0 }, { timestamp: "2024-01-02", close: 101.5 }]
+#   df = SQA::DataFrame.from_aofh(data)
+#
+# @example Accessing data
+#   prices = df["adj_close_price"].to_a
+#   df.columns  # => ["timestamp", "open_price", "high_price", ...]
+#
 class SQA::DataFrame
   extend Forwardable
 
+  # @!attribute [rw] data
+  #   @return [Polars::DataFrame] The underlying Polars DataFrame
   attr_accessor :data
 
+  # Creates a new DataFrame instance.
+  #
+  # @param raw_data [Hash, Array, Polars::DataFrame, nil] Initial data for the DataFrame
+  # @param mapping [Hash] Column name mappings to apply (old_name => new_name)
+  # @param transformers [Hash] Column transformers to apply (column => lambda)
+  #
+  # @example With column mapping
+  #   df = SQA::DataFrame.new(data, mapping: { "Close" => "close_price" })
+  #
+  # @example With transformers
+  #   df = SQA::DataFrame.new(data, transformers: { "price" => ->(v) { v.to_f } })
+  #
   def initialize(raw_data = nil, mapping: {}, transformers: {})
     @data = Polars::DataFrame.new(raw_data || [])
 
@@ -25,6 +54,14 @@ class SQA::DataFrame
   end
 
 
+  # Applies transformer functions to specified columns in place.
+  #
+  # @param transformers [Hash{String, Symbol => Proc}] Column name to transformer mapping
+  # @return [void]
+  #
+  # @example
+  #   df.apply_transformers!({ "price" => ->(v) { v.to_f }, "volume" => ->(v) { v.to_i } })
+  #
   def apply_transformers!(transformers)
     transformers.each do |col, transformer|
       col_name = col.to_s
@@ -34,7 +71,14 @@ class SQA::DataFrame
     end
   end
 
-
+  # Renames columns according to the provided mapping in place.
+  #
+  # @param mapping [Hash{String, Symbol => String}] Old column name to new column name mapping
+  # @return [void]
+  #
+  # @example
+  #   df.rename_columns!({ "open" => "open_price", "close" => "close_price" })
+  #
   def rename_columns!(mapping)
     # Normalize mapping keys to strings for consistent lookup
     # mapping can have string or symbol keys, columns are always strings
@@ -51,6 +95,15 @@ class SQA::DataFrame
   end
 
 
+  # Appends another DataFrame to this one in place.
+  #
+  # @param other_df [SQA::DataFrame] DataFrame to append
+  # @return [void]
+  # @raise [RuntimeError] If the resulting row count doesn't match expected
+  #
+  # @example
+  #   df1.append!(df2)
+  #
   def append!(other_df)
     self_row_count = @data.shape[0]
     other_row_count = other_df.data.shape[0]
@@ -76,7 +129,16 @@ class SQA::DataFrame
   # @param other_df [SQA::DataFrame] DataFrame to append
   # @param sort_column [String] Column to use for deduplication and sorting (default: "timestamp")
   # @param descending [Boolean] Sort order - false for ascending (oldest first, TA-Lib compatible), true for descending
+  #
+  # NOTE: TA-Lib requires data in ascending (oldest-first) order. Using descending: true
+  # will produce a warning and force ascending order to prevent silent calculation errors.
   def concat_and_deduplicate!(other_df, sort_column: "timestamp", descending: false)
+    # Enforce ascending order for TA-Lib compatibility
+    if descending
+      warn "[SQA WARNING] TA-Lib requires ascending (oldest-first) order. Forcing descending: false"
+      descending = false
+    end
+
     # Concatenate the dataframes
     @data = if @data.shape[0] == 0
               other_df.data
@@ -91,32 +153,53 @@ class SQA::DataFrame
     @data = @data.sort(sort_column, reverse: descending)
   end
 
+  # Returns the column names of the DataFrame.
+  #
+  # @return [Array<String>] List of column names
   def columns
     @data.columns
   end
 
-
+  # Returns the column names of the DataFrame.
+  # Alias for {#columns}.
+  #
+  # @return [Array<String>] List of column names
   def keys
     @data.columns
   end
   alias vectors keys
 
+  # Converts the DataFrame to a Ruby Hash.
+  #
+  # @return [Hash{Symbol => Array}] Hash with column names as keys and column data as arrays
+  #
+  # @example
+  #   df.to_h  # => { timestamp: ["2024-01-01", ...], close_price: [100.0, ...] }
+  #
   def to_h
     @data.columns.map { |col| [col.to_sym, @data[col].to_a] }.to_h
   end
 
-
+  # Writes the DataFrame to a CSV file.
+  #
+  # @param path_to_file [String, Pathname] Path to output CSV file
+  # @return [void]
   def to_csv(path_to_file)
     @data.write_csv(path_to_file)
   end
 
-
+  # Returns the number of rows in the DataFrame.
+  #
+  # @return [Integer] Row count
   def size
     @data.height
   end
   alias nrows size
   alias length size
 
+  # Returns the number of columns in the DataFrame.
+  #
+  # @return [Integer] Column count
   def ncols
     @data.width
   end
@@ -156,23 +239,31 @@ class SQA::DataFrame
   end
 
 
+  # Checks if a value appears to be a date string.
+  #
+  # @param value [Object] Value to check
+  # @return [Boolean] true if value matches YYYY-MM-DD format
   def self.is_date?(value)
     value.is_a?(String) && !/\d{4}-\d{2}-\d{2}/.match(value).nil?
   end
 
-
+  # Delegates unknown methods to the underlying Polars DataFrame.
+  # This allows direct access to Polars methods like filter, select, etc.
+  #
+  # @param method_name [Symbol] Method name being called
+  # @param args [Array] Method arguments
+  # @param block [Proc] Optional block
+  # @return [Object] Result from Polars DataFrame method
   def method_missing(method_name, *args, &block)
-    if @data.respond_to?(method_name)
-      self.class.send(:define_method, method_name) do |*method_args, &method_block|
-        @data.send(method_name, *method_args, &method_block)
-      end
-      send(method_name, *args, &block)
-    else
-      super
-    end
+    return super unless @data.respond_to?(method_name)
+    @data.send(method_name, *args, &block)
   end
 
-
+  # Checks if the DataFrame responds to a method.
+  #
+  # @param method_name [Symbol] Method name to check
+  # @param include_private [Boolean] Include private methods
+  # @return [Boolean] true if method is available
   def respond_to_missing?(method_name, include_private = false)
     @data.respond_to?(method_name) || super
   end
@@ -197,37 +288,74 @@ class SQA::DataFrame
       new(df, mapping: mapping, transformers: transformers)
     end
 
+    # Creates a DataFrame from an array of hashes.
+    #
+    # @param aofh [Array<Hash>] Array of hash records
+    # @param mapping [Hash] Column name mappings to apply
+    # @param transformers [Hash] Column transformers to apply
+    # @return [SQA::DataFrame] New DataFrame instance
+    #
+    # @example
+    #   data = [{ "date" => "2024-01-01", "price" => 100.0 }]
+    #   df = SQA::DataFrame.from_aofh(data)
+    #
     def from_aofh(aofh, mapping: {}, transformers: {})
+      return new({}, mapping: mapping, transformers: transformers) if aofh.empty?
+
+      # Sanitize keys to strings and convert to hash of arrays (Polars-compatible format)
       aoh_sanitized = aofh.map { |entry| entry.transform_keys(&:to_s) }
       columns = aoh_sanitized.first.keys
-      data = aoh_sanitized.map(&:values)
-      df = Polars::DataFrame.new(
-        data,
-        columns: columns
-      )
-      new(df)
-    end
 
+      # Convert array-of-hashes to hash-of-arrays for Polars
+      hofa = columns.each_with_object({}) do |col, hash|
+        hash[col] = aoh_sanitized.map { |row| row[col] }
+      end
+
+      df = Polars::DataFrame.new(hofa)
+      new(df, mapping: mapping, transformers: transformers)
+    end
 
+    # Creates a DataFrame from a CSV file.
+    #
+    # @param source [String, Pathname] Path to CSV file
+    # @param mapping [Hash] Column name mappings to apply
+    # @param transformers [Hash] Column transformers to apply
+    # @return [SQA::DataFrame] New DataFrame instance
     def from_csv_file(source, mapping: {}, transformers: {})
       df = Polars.read_csv(source)
       new(df, mapping: mapping, transformers: transformers)
     end
 
-
+    # Creates a DataFrame from a JSON file.
+    #
+    # @param source [String, Pathname] Path to JSON file containing array of objects
+    # @param mapping [Hash] Column name mappings to apply
+    # @param transformers [Hash] Column transformers to apply
+    # @return [SQA::DataFrame] New DataFrame instance
     def from_json_file(source, mapping: {}, transformers: {})
       aofh = JSON.parse(File.read(source)).map { |entry| entry.transform_keys(&:to_s) }
       from_aofh(aofh, mapping: mapping, transformers: transformers)
     end
 
-
+    # Generates a mapping of original keys to underscored keys.
+    #
+    # @param keys [Array<String>] Original key names
+    # @return [Hash{String => Symbol}] Mapping from original to underscored keys
     def generate_mapping(keys)
       keys.each_with_object({}) do |key, hash|
         hash[key.to_s] = underscore_key(key.to_s)
       end
     end
 
-
+    # Converts a key string to underscored snake_case format.
+    #
+    # @param key [String] Key to convert
+    # @return [Symbol] Underscored key as symbol
+    #
+    # @example
+    #   underscore_key("closePrice")  # => :close_price
+    #   underscore_key("Close Price") # => :close_price
+    #
     def underscore_key(key)
       key.to_s
          .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
@@ -242,19 +370,33 @@ class SQA::DataFrame
 
     alias sanitize_key underscore_key
 
+    # Normalizes all keys in a hash to snake_case format.
+    #
+    # @param hash [Hash] Hash with keys to normalize
+    # @param adapter_mapping [Hash] Optional pre-mapping to apply first
+    # @return [Hash] Hash with normalized keys
     def normalize_keys(hash, adapter_mapping: {})
       hash = rename(hash, adapter_mapping) unless adapter_mapping.empty?
       mapping = generate_mapping(hash.keys)
       rename(hash, mapping)
     end
 
-
+    # Renames keys in a hash according to a mapping.
+    #
+    # @param hash [Hash] Hash to modify
+    # @param mapping [Hash] Old key to new key mapping
+    # @return [Hash] Modified hash
     def rename(hash, mapping)
       mapping.each { |old_key, new_key| hash[new_key] = hash.delete(old_key) if hash.key?(old_key) }
       hash
     end
 
-
+    # Converts array of hashes to hash of arrays format.
+    #
+    # @param aofh [Array<Hash>] Array of hash records
+    # @param mapping [Hash] Column name mappings (unused, for API compatibility)
+    # @param transformers [Hash] Column transformers (unused, for API compatibility)
+    # @return [Hash{String => Array}] Hash with column names as keys and arrays as values
     def aofh_to_hofa(aofh, mapping: {}, transformers: {})
       hofa = Hash.new { |h, k| h[k.downcase] = [] }
       aofh.each { |entry| entry.each { |key, value| hofa[key.to_s.downcase] << value } }

data/lib/sqa/errors.rb

@@ -1,30 +1,92 @@
 # lib/sqa/errors.rb
+#
+# SQA Exception Classes
+# All custom exceptions inherit from StandardError or RuntimeError
+# to ensure they can be caught by generic rescue blocks.
 
-# raised when a method is still in TODO state
+module SQA
+  # Raised when unable to fetch data from a data source (API, file, etc.).
+  # Wraps the original exception for debugging purposes.
+  #
+  # @example Raising with original error
+  #   begin
+  #     response = api.fetch(ticker)
+  #   rescue Faraday::Error => e
+  #     raise SQA::DataFetchError.new("Failed to fetch #{ticker}", original: e)
+  #   end
+  #
+  # @example Accessing original error
+  #   begin
+  #     stock = SQA::Stock.new(ticker: 'INVALID')
+  #   rescue SQA::DataFetchError => e
+  #     puts e.message
+  #     puts e.original_error.class if e.original_error
+  #   end
+  #
+  class DataFetchError < StandardError
+    # @return [Exception, nil] The original exception that caused this error
+    attr_reader :original_error
+
+    # Creates a new DataFetchError.
+    #
+    # @param message [String] Error message describing the fetch failure
+    # @param original [Exception, nil] The original exception that was caught
+    def initialize(message, original: nil)
+      @original_error = original
+      super(message)
+    end
+  end
+
+  # Raised when SQA configuration is invalid or missing.
+  # Common causes include missing API keys or invalid data directories.
+  #
+  # @example
+  #   raise SQA::ConfigurationError, "API key not set"
+  #
+  class ConfigurationError < StandardError; end
+
+  # Raised when a method parameter is invalid.
+  # Inherits from ArgumentError for semantic clarity.
+  #
+  # @example
+  #   raise SQA::BadParameterError, "Expected a Class or Method"
+  #
+  class BadParameterError < ArgumentError; end
+end
+
+# Global alias for backward compatibility.
+# @deprecated Use SQA::BadParameterError instead
+BadParameterError = SQA::BadParameterError
+
+# Raised when an external API returns an error response.
+# Automatically logs the error using debug_me before raising.
+#
+# @example
+#   ApiError.raise("Rate limit exceeded")
+#
 class ApiError < RuntimeError
+  # Raises an ApiError with debug logging.
+  #
+  # @param why [String] The error message from the API
+  # @raise [ApiError] Always raises after logging
   def self.raise(why)
-    puts "="*64
-    puts "== API Error"
-    puts why
-    puts
-    puts "Callback trace:"
-    puts caller
-    puts "="*64
+    debug_me {"API Error: #{why}"}
     super
   end
 end
 
-# raised when a method is still in TODO state
+# Raised when a feature is not yet implemented.
+# Automatically logs using debug_me before raising.
+#
+# @example
+#   NotImplemented.raise
+#
 class NotImplemented < RuntimeError
+  # Raises a NotImplemented error with debug logging.
+  #
+  # @raise [NotImplemented] Always raises after logging
   def self.raise
-    puts "="*64
-    puts "== Not Yet Implemented"
-    puts "Callback trace:"
-    puts caller
-    puts "="*64
+    debug_me {"Not Yet Implemented"}
     super
   end
 end
-
-# raised when an API contract is broken
-class BadParameterError < ArgumentError; end