sqa 0.0.24 → 0.0.31

data/docs/strategies/custom.md

@@ -0,0 +1,310 @@
+# Creating Custom Strategies
+
+## Overview
+
+Learn how to create your own trading strategies in the SQA framework.
+
+## Strategy Interface
+
+All strategies must implement a `self.trade(vector)` class method that returns `:buy`, `:sell`, or `:hold`.
+
+## Basic Template
+
+```ruby
+# lib/sqa/strategy/my_strategy.rb
+
+class SQA::Strategy::MyStrategy
+  def self.trade(vector)
+    # 1. Validate input
+    return :hold unless vector.respond_to?(:prices)
+    return :hold if vector.prices.nil? || vector.prices.size < 20
+
+    # 2. Extract data
+    prices = vector.prices
+    
+    # 3. Calculate indicators
+    sma = SQAI.sma(prices, period: 20)
+    rsi = SQAI.rsi(prices, period: 14)
+    
+    # 4. Implement trading logic
+    if rsi.last < 30 && prices.last > sma.last
+      :buy
+    elsif rsi.last > 70 && prices.last < sma.last
+      :sell
+    else
+      :hold
+    end
+  rescue => e
+    warn "MyStrategy error: #{e.message}"
+    :hold
+  end
+end
+```
+
+## Step-by-Step Guide
+
+### 1. Create Strategy File
+
+Create a new file in `lib/sqa/strategy/`:
+
+```bash
+touch lib/sqa/strategy/my_strategy.rb
+```
+
+### 2. Define Strategy Class
+
+```ruby
+class SQA::Strategy::MyStrategy
+  # Your implementation
+end
+```
+
+### 3. Implement Trade Method
+
+```ruby
+def self.trade(vector)
+  # Return :buy, :sell, or :hold
+end
+```
+
+### 4. Add Error Handling
+
+```ruby
+def self.trade(vector)
+  # Your logic
+rescue => e
+  warn "Error: #{e.message}"
+  :hold  # Safe default
+end
+```
+
+### 5. Write Tests
+
+Create `test/strategy/my_strategy_test.rb`:
+
+```ruby
+require_relative '../test_helper'
+require 'ostruct'
+
+class MyStrategyTest < Minitest::Test
+  def test_buy_signal
+    prices = [100, 102, 104, 106, 108]
+    vector = OpenStruct.new(prices: prices)
+    
+    signal = SQA::Strategy::MyStrategy.trade(vector)
+    assert_equal :buy, signal
+  end
+  
+  def test_hold_when_no_data
+    vector = OpenStruct.new
+    signal = SQA::Strategy::MyStrategy.trade(vector)
+    assert_equal :hold, signal
+  end
+end
+```
+
+## Advanced Example
+
+```ruby
+class SQA::Strategy::AdvancedStrategy
+  # Constants for configuration
+  RSI_OVERSOLD = 30
+  RSI_OVERBOUGHT = 70
+  MIN_VOLUME_RATIO = 1.5
+  
+  def self.trade(vector)
+    return :hold unless valid_vector?(vector)
+    
+    analysis = analyze_market(vector)
+    generate_signal(analysis)
+  end
+  
+  private
+  
+  def self.valid_vector?(vector)
+    vector.respond_to?(:prices) &&
+    vector.respond_to?(:volumes) &&
+    vector.prices&.size >= 50
+  end
+  
+  def self.analyze_market(vector)
+    {
+      rsi: SQAI.rsi(vector.prices, period: 14).last,
+      trend: detect_trend(vector.prices),
+      volume_spike: volume_spike?(vector.volumes)
+    }
+  end
+  
+  def self.detect_trend(prices)
+    sma_short = SQAI.sma(prices, period: 20).last
+    sma_long = SQAI.sma(prices, period: 50).last
+    
+    sma_short > sma_long ? :up : :down
+  end
+  
+  def self.volume_spike?(volumes)
+    current = volumes.last
+    average = volumes.last(20).sum / 20.0
+    current > (average * MIN_VOLUME_RATIO)
+  end
+  
+  def self.generate_signal(analysis)
+    if analysis[:rsi] < RSI_OVERSOLD && 
+       analysis[:trend] == :up && 
+       analysis[:volume_spike]
+      :buy
+    elsif analysis[:rsi] > RSI_OVERBOUGHT && 
+          analysis[:trend] == :down && 
+          analysis[:volume_spike]
+      :sell
+    else
+      :hold
+    end
+  end
+end
+```
+
+## Best Practices
+
+### 1. Validate Input
+
+```ruby
+return :hold unless vector.respond_to?(:prices)
+return :hold if vector.prices.nil?
+return :hold if vector.prices.size < minimum_required
+```
+
+### 2. Use Available Indicators
+
+```ruby
+# All TA-Lib indicators available via SQAI
+rsi = SQAI.rsi(prices, period: 14)
+macd = SQAI.macd(prices)
+bbands = SQAI.bbands(prices, period: 20)
+```
+
+### 3. Handle Errors Gracefully
+
+```ruby
+rescue => e
+  warn "#{self.name} error: #{e.message}"
+  :hold
+end
+```
+
+### 4. Test Edge Cases
+
+- Empty data
+- Insufficient data
+- Nil values
+- Extreme values
+
+### 5. Document Your Logic
+
+```ruby
+# Buy when:
+# 1. RSI indicates oversold (< 30)
+# 2. Price above 20-day SMA (uptrend)
+# 3. Volume confirms (> 1.5x average)
+```
+
+## Using Your Strategy
+
+### With Backtest
+
+```ruby
+backtest = SQA::Backtest.new(
+  stock: stock,
+  strategy: SQA::Strategy::MyStrategy,
+  initial_cash: 10_000
+)
+
+results = backtest.run
+```
+
+### With Real-Time Stream
+
+```ruby
+stream = SQA::Stream.new(
+  ticker: 'AAPL',
+  strategies: [SQA::Strategy::MyStrategy]
+)
+
+stream.on_signal do |signal, data|
+  puts "MyStrategy says: #{signal}"
+end
+```
+
+### With Strategy Generator
+
+```ruby
+# Discover patterns and auto-generate strategies
+generator = SQA::StrategyGenerator.new(stock: stock)
+patterns = generator.discover_patterns
+strategy_code = generator.generate_strategy(pattern_index: 0)
+```
+
+## Common Patterns
+
+### Trend Following
+
+```ruby
+if short_ma > long_ma
+  :buy
+elsif short_ma < long_ma
+  :sell
+else
+  :hold
+end
+```
+
+### Mean Reversion
+
+```ruby
+deviation = (price - average) / average
+if deviation < -threshold
+  :buy
+elsif deviation > threshold
+  :sell
+else
+  :hold
+end
+```
+
+### Momentum
+
+```ruby
+if rsi < oversold_level
+  :buy
+elsif rsi > overbought_level
+  :sell
+else
+  :hold
+end
+```
+
+### Breakout
+
+```ruby
+if price > recent_high && volume > threshold
+  :buy
+elsif price < recent_low && volume > threshold
+  :sell
+else
+  :hold
+end
+```
+
+## Next Steps
+
+1. Study existing strategies in `lib/sqa/strategy/`
+2. Read [Backtesting Guide](../advanced/backtesting.md)
+3. Explore [Strategy Generator](../advanced/strategy-generator.md)
+4. Learn about [Risk Management](../advanced/risk-management.md)
+
+## Related
+
+- [KBS Strategy](kbs.md) - Rule-based strategies
+- [Consensus](consensus.md) - Combining strategies
+- [Backtesting](../advanced/backtesting.md) - Testing strategies
+

data/docs/strategies/ema.md

@@ -0,0 +1,53 @@
+# EMA (Exponential Moving Average) Strategy
+
+## Overview
+
+Similar to SMA but gives more weight to recent prices, making it more responsive to price changes.
+
+## How It Works
+
+Uses EMA crossovers for signals:
+- **Short EMA**: 12 or 20-period
+- **Long EMA**: 26 or 50-period
+
+## Trading Signals
+
+### Buy Signal
+Short EMA crosses above long EMA.
+
+### Sell Signal
+Short EMA crosses below long EMA.
+
+## Usage Example
+
+```ruby
+prices = stock.df["adj_close_price"].to_a
+
+ema_short = SQAI.ema(prices, period: 12)
+ema_long = SQAI.ema(prices, period: 26)
+
+vector = OpenStruct.new(
+  ema_short: ema_short,
+  ema_long: ema_long
+)
+
+signal = SQA::Strategy::EMA.trade(vector)
+```
+
+## Characteristics
+
+- **Complexity**: Low
+- **Best Market**: Trending
+- **Win Rate**: 45-55%
+
+## Strengths
+
+✅ Faster than SMA  
+✅ Better for short-term trading  
+✅ Reduces lag  
+
+## Weaknesses
+
+❌ More false signals  
+❌ Still lags in fast markets  
+

data/docs/strategies/index.md

@@ -0,0 +1,92 @@
+# Trading Strategies
+
+Explore SQA's comprehensive suite of trading strategies.
+
+## Overview
+
+SQA provides 13+ built-in trading strategies, from simple moving average crossovers to advanced rule-based systems. All strategies follow a common interface and can be easily backtested or combined.
+
+## Strategy Categories
+
+### Trend-Following Strategies
+Strategies that identify and follow market trends:
+
+- **SMA Strategy** - Simple Moving Average crossovers
+- **EMA Strategy** - Exponential Moving Average crossovers
+- **MACD Strategy** - Moving Average Convergence Divergence
+
+### Momentum Strategies
+Strategies based on price momentum and oscillators:
+
+- **RSI Strategy** - Relative Strength Index (oversold/overbought)
+- **Stochastic Strategy** - Stochastic oscillator crossovers
+
+### Volatility Strategies
+Strategies that use volatility measures:
+
+- **Bollinger Bands Strategy** - Price touches bands
+- **ATR-based Strategies** - Average True Range volatility
+
+### Volume Strategies
+Strategies incorporating volume analysis:
+
+- **Volume Breakout** - High volume price breakouts
+
+### Mean Reversion
+Strategies assuming prices return to average:
+
+- **Mean Reversion Strategy** - Statistical mean reversion
+
+### Advanced Strategies
+Complex, rule-based approaches:
+
+- **KBS Strategy** - Knowledge-Based System with RETE engine
+- **Consensus Strategy** - Aggregates multiple strategies
+
+## Using Strategies
+
+### Basic Usage
+
+```ruby
+require 'sqa'
+require 'ostruct'
+
+# Create data vector
+vector = OpenStruct.new(
+  rsi: { trend: :over_sold },
+  prices: [100, 102, 105, 103, 107]
+)
+
+# Execute strategy
+signal = SQA::Strategy::RSI.trade(vector)
+# => :buy, :sell, or :hold
+```
+
+### Backtesting
+
+```ruby
+backtest = SQA::Backtest.new(
+  stock: stock,
+  strategy: SQA::Strategy::MACD,
+  initial_cash: 10_000
+)
+
+results = backtest.run
+puts "Return: #{results.total_return}%"
+```
+
+## Strategy Comparison
+
+| Strategy | Complexity | Best For | Typical Win Rate |
+|----------|------------|----------|------------------|
+| SMA | Low | Trending markets | 45-55% |
+| RSI | Low | Range-bound markets | 50-60% |
+| MACD | Medium | Trending markets | 45-55% |
+| Bollinger Bands | Medium | Volatile markets | 50-60% |
+| KBS | High | Complex rules | Varies |
+
+## Next Steps
+
+- [Built-in Strategies](bollinger-bands.md) - Explore each strategy in detail
+- [Custom Strategies](custom.md) - Create your own strategies
+- [Backtesting](../advanced/backtesting.md) - Test strategies historically

data/docs/strategies/kbs.md

@@ -0,0 +1,164 @@
+# KBS (Knowledge-Based Strategy)
+
+## Overview
+
+Advanced rule-based trading system using RETE forward-chaining inference engine. Combines multiple indicators with custom logic rules.
+
+## How It Works
+
+Defines trading rules with conditions and actions:
+- **Conditions** (`on`): Facts that must be true
+- **Actions** (`perform`): What to do when conditions met
+
+## Rule Definition
+
+```ruby
+strategy = SQA::Strategy::KBS.new(load_defaults: true)
+kb = strategy.kb
+
+# Add custom rule
+strategy.add_rule :buy_oversold_uptrend do
+  on :rsi, { level: :oversold }
+  on :trend, { short_term: :up }
+  perform do
+    kb.assert(:signal, { action: :buy, confidence: :high })
+  end
+end
+```
+
+## Default Rules
+
+The KBS strategy includes 10 default rules:
+1. Buy on RSI oversold in uptrend
+2. Sell on RSI overbought in downtrend
+3. Buy on bullish MACD crossover
+4. Sell on bearish MACD crossover
+5. Buy at lower Bollinger Band
+6. Sell at upper Bollinger Band
+7. Buy on stochastic oversold crossover
+8. Sell on stochastic overbought crossover
+9. Buy on SMA golden cross
+10. Sell on SMA death cross
+
+## Usage Example
+
+```ruby
+# Use with default rules
+strategy = SQA::Strategy::KBS.new(load_defaults: true)
+
+# Provide market data
+prices = stock.df["adj_close_price"].to_a
+vector = OpenStruct.new(
+  rsi: SQAI.rsi(prices, period: 14),
+  prices: prices
+)
+
+signal = strategy.execute(vector)
+```
+
+## Advanced Example
+
+```ruby
+# Create custom strategy without defaults
+strategy = SQA::Strategy::KBS.new(load_defaults: false)
+kb = strategy.kb
+
+# Define sophisticated multi-condition rule
+strategy.add_rule :strong_buy do
+  on :rsi, { level: :oversold }
+  on :macd, { crossover: :bullish }
+  on :volume, { level: :high }
+  without :position  # Don't buy if already holding
+
+  perform do
+    kb.assert(:signal, { 
+      action: :buy, 
+      confidence: :high,
+      reason: :triple_confirmation 
+    })
+  end
+end
+
+# Execute
+signal = strategy.execute(vector)
+```
+
+## Confidence Levels
+
+Signals include confidence scoring:
+- **High**: 1.0
+- **Medium**: 0.6
+- **Low**: 0.3
+
+Multiple rules can fire, with aggregate confidence determining final signal.
+
+## Characteristics
+
+- **Complexity**: High
+- **Best Market**: All markets (depends on rules)
+- **Win Rate**: Varies (50-70% with good rules)
+
+## Strengths
+
+✅ Highly customizable  
+✅ Combines multiple indicators  
+✅ Confidence scoring  
+✅ Forward-chaining inference  
+✅ Can encode expert knowledge  
+
+## Weaknesses
+
+❌ Complex to configure  
+❌ Requires domain knowledge  
+❌ Can be slow with many rules  
+❌ Overfitting risk  
+
+## Tips
+
+1. **Start Simple**: Begin with 2-3 rules
+2. **Test Thoroughly**: Backtest each rule independently
+3. **Avoid Conflicts**: Ensure rules don't contradict
+4. **Use Confidence**: Combine weak signals for stronger conviction
+5. **Monitor Performance**: Track which rules fire most often
+
+## Available Facts
+
+The KBS strategy processes these fact types:
+- `:rsi` - RSI indicator data
+- `:macd` - MACD crossovers
+- `:trend` - Price trend analysis
+- `:bollinger` - Bollinger Band position
+- `:stochastic` - Stochastic oscillator
+- `:volume` - Volume analysis
+- `:sma_crossover` - SMA crossovers
+
+## DSL Keywords
+
+- `on` - Assert condition (fact must exist with attributes)
+- `without` - Negated condition (fact must NOT exist)
+- `perform` - Action to execute when rule fires
+
+## Important Note
+
+Due to KBS gem DSL limitations, you must use `kb.assert` (not just `assert`) inside `perform` blocks:
+
+```ruby
+# CORRECT
+kb = strategy.kb
+strategy.add_rule :my_rule do
+  on :condition
+  perform { kb.assert(:signal, { action: :buy }) }
+end
+
+# INCORRECT
+strategy.add_rule :my_rule do
+  on :condition
+  perform { assert(:signal, { action: :buy }) }  # Won't work!
+end
+```
+
+## Related
+
+- [Strategy Generator](../advanced/strategy-generator.md) - Auto-generate rules
+- [Genetic Programming](../genetic_programming.md) - Optimize rule parameters
+

data/docs/strategies/macd.md

@@ -0,0 +1,96 @@
+# MACD Strategy
+
+## Overview
+
+Moving Average Convergence Divergence (MACD) is a trend-following momentum indicator that shows the relationship between two moving averages.
+
+## How It Works
+
+MACD consists of three components:
+- **MACD Line**: 12-period EMA - 26-period EMA
+- **Signal Line**: 9-period EMA of MACD Line
+- **Histogram**: MACD Line - Signal Line
+
+## Trading Signals
+
+### Buy Signal (Bullish Crossover)
+MACD line crosses **above** the signal line.
+
+```ruby
+SQA::Strategy::MACD.trade(vector)  # => :buy
+```
+
+### Sell Signal (Bearish Crossover)
+MACD line crosses **below** the signal line.
+
+```ruby
+SQA::Strategy::MACD.trade(vector)  # => :sell
+```
+
+## Usage Example
+
+```ruby
+stock = SQA::Stock.new(ticker: 'AAPL')
+prices = stock.df["adj_close_price"].to_a
+
+# Calculate MACD
+macd_line, signal_line, histogram = SQAI.macd(
+  prices,
+  fast_period: 12,
+  slow_period: 26,
+  signal_period: 9
+)
+
+vector = OpenStruct.new(
+  macd: [macd_line, signal_line, histogram]
+)
+
+signal = SQA::Strategy::MACD.trade(vector)
+```
+
+## Parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| Fast Period | 12 | Fast EMA period |
+| Slow Period | 26 | Slow EMA period |
+| Signal Period | 9 | Signal line EMA period |
+
+## Characteristics
+
+| Attribute | Value |
+|-----------|-------|
+| Complexity | Medium |
+| Best Market | Trending |
+| Win Rate | 45-55% |
+| Time Horizon | Medium to long term |
+
+## Strengths
+
+- ✅ Excellent trend following
+- ✅ Combines trend and momentum
+- ✅ Clear crossover signals
+- ✅ Can detect trend changes early
+
+## Weaknesses
+
+- ❌ Lags in fast markets
+- ❌ Whipsaws in ranging markets
+- ❌ False signals during consolidation
+
+## Tips
+
+1. **Confirm with Trend**: Best in established trends
+2. **Histogram Divergence**: Watch for divergence with price
+3. **Zero Line Cross**: Additional confirmation signal
+4. **Multiple Timeframes**: Align daily and weekly signals
+
+## Related Strategies
+
+- [EMA](ema.md) - Uses moving average crossovers
+- [SMA](sma.md) - Similar crossover approach
+- [RSI](rsi.md) - Complementary momentum indicator
+
+## Further Reading
+
+- [MACD on Investopedia](https://www.investopedia.com/terms/m/macd.asp)