sqa 0.0.31 → 0.0.37

data/docs/strategy.md

@@ -1,5 +1,383 @@
-# Strategy
+# Strategy Framework
 
-A strategy is a recipe that cooks all the indicators together to make a decision on a potential trade.  The SQA::Strategy class provides the framework for executing multiple strategies.
+A comprehensive guide to SQA's trading strategy architecture.
 
-You can also think of a strategy as a set of rules like in the old days of rule-based forward/backward chaining engines.  The rules are evaluated to determine whether a specific decision to trade is good or bad.
+## Overview
+
+A strategy in SQA is a set of rules that analyze technical indicators and market data to generate trading signals. The `SQA::Strategy` class provides the framework for managing and executing multiple strategies.
+
+## Architecture
+
+![Strategy Flow](assets/images/strategy-flow.svg)
+
+## The Strategy Pattern
+
+All SQA strategies follow a common interface:
+
+```ruby
+class SQA::Strategy::YourStrategy
+  def self.trade(vector)
+    # Analyze the vector (OpenStruct with indicator data)
+    # Return :buy, :sell, or :hold
+  end
+end
+```
+
+### The Vector
+
+The vector is an `OpenStruct` containing all the data a strategy needs to make a decision:
+
+```ruby
+require 'ostruct'
+
+vector = OpenStruct.new(
+  rsi: { trend: :over_sold, value: 28.5 },
+  macd: { crossover: :bullish, histogram: 0.5 },
+  prices: prices_array,
+  sma_20: sma_20.last,
+  sma_50: sma_50.last
+)
+```
+
+## Using the Strategy Framework
+
+### Managing Multiple Strategies
+
+```ruby
+# Create a strategy manager
+strategy = SQA::Strategy.new
+
+# Add strategies
+strategy.add SQA::Strategy::RSI
+strategy.add SQA::Strategy::MACD
+strategy.add SQA::Strategy::BollingerBands
+
+# Execute all strategies
+signals = strategy.execute(vector)
+# => [:buy, :hold, :sell]
+
+# Count votes for consensus
+buy_votes = signals.count(:buy)
+sell_votes = signals.count(:sell)
+```
+
+### Auto-Loading Strategies
+
+```ruby
+# Load all built-in strategies
+strategy = SQA::Strategy.new
+strategy.auto_load
+
+# Load specific strategies only
+strategy.auto_load(only: [:rsi, :macd])
+
+# Load all except certain strategies
+strategy.auto_load(except: [:random, :common])
+```
+
+### Listing Available Strategies
+
+```ruby
+strategy = SQA::Strategy.new
+available = strategy.available
+# => [SQA::Strategy::RSI, SQA::Strategy::MACD, ...]
+```
+
+## Built-in Strategies
+
+SQA includes 13+ built-in trading strategies:
+
+### Trend-Following
+
+| Strategy | Description | Best For |
+|----------|-------------|----------|
+| **SMA** | Simple Moving Average crossovers | Trending markets |
+| **EMA** | Exponential Moving Average crossovers | Faster trend detection |
+| **MACD** | Moving Average Convergence Divergence | Momentum + trend |
+
+### Momentum
+
+| Strategy | Description | Best For |
+|----------|-------------|----------|
+| **RSI** | Relative Strength Index (oversold/overbought) | Range-bound markets |
+| **Stochastic** | Stochastic oscillator crossovers | Short-term reversals |
+
+### Volatility
+
+| Strategy | Description | Best For |
+|----------|-------------|----------|
+| **Bollinger Bands** | Price touching volatility bands | Volatile markets |
+| **Volume Breakout** | High volume price breakouts | Breakout trading |
+
+### Advanced
+
+| Strategy | Description | Best For |
+|----------|-------------|----------|
+| **KBS** | Knowledge-Based System with RETE engine | Complex rule combinations |
+| **Consensus** | Aggregates multiple strategy signals | Reducing noise |
+| **Mean Reversion** | Statistical mean reversion | Range-bound markets |
+
+## Creating Custom Strategies
+
+### Basic Template
+
+```ruby
+# lib/my_strategies/awesome_strategy.rb
+
+class SQA::Strategy::AwesomeStrategy
+  def self.trade(vector)
+    # Your trading logic here
+    if buy_condition?(vector)
+      :buy
+    elsif sell_condition?(vector)
+      :sell
+    else
+      :hold
+    end
+  end
+
+  private
+
+  def self.buy_condition?(vector)
+    vector.rsi[:value] < 30 &&
+    vector.macd[:crossover] == :bullish
+  end
+
+  def self.sell_condition?(vector)
+    vector.rsi[:value] > 70 &&
+    vector.macd[:crossover] == :bearish
+  end
+end
+```
+
+### Using Your Strategy
+
+```ruby
+require_relative 'my_strategies/awesome_strategy'
+
+# Execute directly
+signal = SQA::Strategy::AwesomeStrategy.trade(vector)
+
+# Or add to strategy manager
+strategy = SQA::Strategy.new
+strategy.add SQA::Strategy::AwesomeStrategy
+```
+
+### Strategy with Configuration
+
+```ruby
+class SQA::Strategy::ConfigurableRSI
+  @oversold_threshold = 30
+  @overbought_threshold = 70
+
+  class << self
+    attr_accessor :oversold_threshold, :overbought_threshold
+
+    def trade(vector)
+      rsi_value = vector.rsi[:value] || vector.rsi
+
+      if rsi_value < oversold_threshold
+        :buy
+      elsif rsi_value > overbought_threshold
+        :sell
+      else
+        :hold
+      end
+    end
+  end
+end
+
+# Configure before using
+SQA::Strategy::ConfigurableRSI.oversold_threshold = 25
+SQA::Strategy::ConfigurableRSI.overbought_threshold = 75
+```
+
+## Combining Strategies
+
+### Consensus Strategy
+
+The built-in Consensus strategy aggregates signals from multiple strategies:
+
+```ruby
+# Simple majority vote
+signals = strategy.execute(vector)
+# => [:buy, :buy, :hold, :sell]
+
+consensus = signals.group_by(&:itself)
+                   .transform_values(&:count)
+                   .max_by { |_, v| v }
+                   .first
+# => :buy (2 votes vs 1 each for hold/sell)
+```
+
+### Weighted Voting
+
+```ruby
+# Assign weights to strategies
+weights = {
+  SQA::Strategy::RSI => 2.0,      # RSI gets double weight
+  SQA::Strategy::MACD => 1.5,     # MACD gets 1.5x weight
+  SQA::Strategy::SMA => 1.0       # SMA gets normal weight
+}
+
+# Calculate weighted consensus
+weighted_votes = { buy: 0.0, sell: 0.0, hold: 0.0 }
+signals.each_with_index do |signal, i|
+  weight = weights.values[i]
+  weighted_votes[signal] += weight
+end
+
+final_signal = weighted_votes.max_by { |_, v| v }.first
+```
+
+## Testing Strategies
+
+### Unit Testing
+
+```ruby
+# test/strategy/awesome_strategy_test.rb
+require 'minitest/autorun'
+require 'ostruct'
+
+class AwesomeStrategyTest < Minitest::Test
+  def test_buy_signal_on_oversold
+    vector = OpenStruct.new(
+      rsi: { value: 25, trend: :over_sold },
+      macd: { crossover: :bullish }
+    )
+
+    assert_equal :buy, SQA::Strategy::AwesomeStrategy.trade(vector)
+  end
+
+  def test_sell_signal_on_overbought
+    vector = OpenStruct.new(
+      rsi: { value: 75, trend: :over_bought },
+      macd: { crossover: :bearish }
+    )
+
+    assert_equal :sell, SQA::Strategy::AwesomeStrategy.trade(vector)
+  end
+end
+```
+
+### Backtesting
+
+```ruby
+backtest = SQA::Backtest.new(
+  stock: stock,
+  strategy: SQA::Strategy::AwesomeStrategy,
+  initial_cash: 10_000
+)
+
+results = backtest.run
+puts "Return: #{results.total_return}%"
+puts "Sharpe: #{results.sharpe_ratio}"
+```
+
+## Strategy Internals
+
+### How Strategies Process Data
+
+1. **Data Preparation**: Raw price data is converted to indicators
+2. **Vector Creation**: Indicators are packaged into an OpenStruct
+3. **Strategy Execution**: Each strategy analyzes the vector
+4. **Signal Generation**: Strategy returns `:buy`, `:sell`, or `:hold`
+5. **Aggregation**: Signals can be combined for consensus
+
+### Data Ordering
+
+All indicator data in SQA follows **ascending chronological order** (oldest first):
+
+```ruby
+# prices[0] = oldest price
+# prices[-1] = most recent price
+
+prices = stock.df["adj_close_price"].to_a
+rsi = SQAI.rsi(prices, period: 14)
+
+# rsi.last is the most recent RSI value
+current_rsi = rsi.last
+```
+
+## Best Practices
+
+### 1. Keep Strategies Simple
+
+```ruby
+# GOOD: Clear, single-purpose logic
+def self.trade(vector)
+  vector.rsi[:value] < 30 ? :buy : :hold
+end
+
+# BAD: Complex nested conditions
+def self.trade(vector)
+  if vector.rsi[:value] < 30
+    if vector.macd[:histogram] > 0
+      if vector.volume > vector.avg_volume * 1.5
+        # ... more nesting ...
+      end
+    end
+  end
+end
+```
+
+### 2. Use Named Parameters in Vectors
+
+```ruby
+# GOOD: Self-documenting
+vector = OpenStruct.new(
+  rsi_value: rsi.last,
+  rsi_trend: rsi.last < 30 ? :oversold : :neutral,
+  sma_20: sma_20.last,
+  sma_50: sma_50.last
+)
+
+# BAD: Magic numbers
+vector = OpenStruct.new(
+  val1: 28.5,
+  val2: 150.0,
+  val3: 148.0
+)
+```
+
+### 3. Handle Edge Cases
+
+```ruby
+def self.trade(vector)
+  return :hold if vector.rsi.nil?
+  return :hold if vector.prices.empty?
+
+  # Main logic here
+end
+```
+
+### 4. Document Your Strategy
+
+```ruby
+# Dual Moving Average Crossover Strategy
+#
+# Generates buy signals when short MA crosses above long MA,
+# sell signals when short MA crosses below long MA.
+#
+# Parameters:
+#   vector.sma_short - Short-term SMA (e.g., 20-day)
+#   vector.sma_long - Long-term SMA (e.g., 50-day)
+#
+# Returns:
+#   :buy - Short MA > Long MA (bullish crossover)
+#   :sell - Short MA < Long MA (bearish crossover)
+#   :hold - No clear signal
+#
+class SQA::Strategy::DualMA
+  def self.trade(vector)
+    # ...
+  end
+end
+```
+
+## Related Documentation
+
+- [Trading Strategies Reference](strategies/index.md) - Details on each built-in strategy
+- [Custom Strategies](strategies/custom.md) - Guide to creating your own
+- [Backtesting](advanced/backtesting.md) - Test strategies on historical data
+- [Technical Indicators](indicators/index.md) - Calculate indicator values

data/docs/terms_of_use.md

@@ -32,7 +32,7 @@ Your affirmative act of using our Ruby Gem ("library") located at https://github
   - [20. House rules](#20-house-rules)
   - [21. Third Party Software](#21-third-party-software)
   - [22. Scripts](#22-scripts)
-  - [23. Publications - No Recommendation or Advice Status](#23-publications---no-recommendation-or-advice-status)
+  - [23. Publications - No Recommendation or Advice Status](#23-publications-no-recommendation-or-advice-status)
 
 <!-- Tocer[finish]: Auto-generated, don't remove. -->
 

data/examples/README.md

@@ -335,6 +335,15 @@ Examples may create output files in `/tmp/`:
 - `/tmp/sqa_evolution_history.csv` - GP evolution history
 - `/tmp/sqa_backtest_results.csv` - Backtest results
 
+## Web Demo Application
+
+For a complete web-based demonstration of SQA's capabilities, see the **[sqa_demo-sinatra](https://github.com/MadBomber/sqa_demo-sinatra)** gem. This Sinatra application provides a visual interface for:
+
+- Stock analysis dashboard
+- Technical indicator visualization
+- Strategy backtesting
+- Portfolio management
+
 ## Next Steps
 
 After running these examples:
@@ -344,6 +353,7 @@ After running these examples:
 3. **Walk-Forward Validation**: Test on out-of-sample data
 4. **Combine Techniques**: Use strategy generator + GP + KBS together
 5. **Production Deployment**: Connect to real WebSocket data feeds
+6. **Try the Web Demo**: Install [sqa_demo-sinatra](https://github.com/MadBomber/sqa_demo-sinatra) for a visual interface
 
 ## Educational Disclaimer
 

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/alpha_vantage.rb

@@ -35,9 +35,14 @@ class SQA::DataFrame
 
     ################################################################
 
-    # Get recent data from JSON API
+    # Get recent data from Alpha Vantage API
+    #
     # ticker String the security to retrieve
-    # returns a Polars DataFrame
+    # full Boolean whether to fetch full history or compact (last 100 days)
+    # from_date Date optional date to fetch data after (for incremental updates)
+    #
+    # Returns: SQA::DataFrame sorted in ASCENDING order (oldest to newest)
+    # Note: Alpha Vantage returns data newest-first, but we sort ascending for TA-Lib compatibility
     def self.recent(ticker, full: false, from_date: nil)
       response  = CONNECTION.get(
         "/query?" +
@@ -67,7 +72,8 @@ class SQA::DataFrame
       # Handle date criteria if applicable
       if from_date
         # Use Polars.col() to create an expression for filtering
-        df = df.filter(Polars.col("timestamp") >= from_date.to_s)
+        # Use > (not >=) to exclude the from_date itself and prevent duplicates
+        df = df.filter(Polars.col("timestamp") > from_date.to_s)
       end
 
       # Wrap in SQA::DataFrame with proper transformers
@@ -80,6 +86,10 @@ class SQA::DataFrame
         sqa_df.data["close_price"].alias("adj_close_price")
       )
 
+      # Sort data in ascending chronological order (oldest to newest) for TA-Lib compatibility
+      # Alpha Vantage returns data newest-first, but TA-Lib expects oldest-first
+      sqa_df.data = sqa_df.data.sort("timestamp", reverse: false)
+
       sqa_df
     end
   end