sqa 0.0.24 → 0.0.31

data/docs/index.md

@@ -0,0 +1,163 @@
+# SQA - Simple Qualitative Analysis
+
+<p align="center">
+  <strong>A Powerful Ruby Library for Stock Market Technical Analysis</strong>
+</p>
+
+---
+
+## Welcome to SQA
+
+**SQA (Simple Qualitative Analysis)** is an educational Ruby library designed for stock market technical analysis and trading strategy development. Built with high-performance data structures and seamlessly integrated with TA-Lib, SQA provides a comprehensive toolkit for analyzing historical stock data, implementing trading strategies, and backtesting your ideas.
+
+!!! warning "Educational Purpose Only"
+    SQA is designed for **educational purposes** only. It should not be used for actual trading without extensive testing and professional financial advice. Trading stocks involves substantial risk of loss.
+
+## Why SQA?
+
+### :zap: High Performance
+- **Polars DataFrames**: Rust-backed data structures providing 30x faster operations than pure Ruby
+- **TA-Lib Integration**: Access to 150+ battle-tested technical indicators via the `sqa-tai` gem
+- **Efficient Algorithms**: Optimized for large historical datasets
+
+### :toolbox: Comprehensive Feature Set
+- **13+ Trading Strategies**: From simple moving averages to advanced machine learning-based strategies
+- **Portfolio Management**: Track positions, calculate P&L, manage commissions
+- **Backtesting Framework**: Simulate strategies with comprehensive performance metrics
+- **Real-Time Streaming**: Process live price data with callback support
+- **Strategy Generation**: Reverse-engineer profitable trades to discover patterns
+- **Genetic Programming**: Evolve optimal strategy parameters
+
+### :mortar_board: Educational Focus
+- **Clear Documentation**: Extensive guides and examples
+- **Transparent Algorithms**: Understand how each indicator and strategy works
+- **Modular Design**: Learn by building custom strategies
+- **Risk Disclaimers**: Honest about limitations and risks
+
+## Quick Example
+
+```ruby
+require 'sqa'
+
+# Initialize SQA
+SQA.init
+
+# Load stock data
+stock = SQA::Stock.new(ticker: 'AAPL')
+
+# Get price data
+prices = stock.df["adj_close_price"].to_a
+
+# Calculate RSI indicator
+rsi = SQAI.rsi(prices, period: 14)
+
+# Execute RSI trading strategy
+require 'ostruct'
+vector = OpenStruct.new(rsi: { trend: rsi.last < 30 ? :over_sold : :over_bought })
+signal = SQA::Strategy::RSI.trade(vector)  # => :buy, :sell, or :hold
+
+# Backtest the strategy
+backtest = SQA::Backtest.new(
+  stock: stock,
+  strategy: SQA::Strategy::RSI,
+  initial_cash: 10_000
+)
+results = backtest.run
+
+puts "Total Return: #{results.total_return}%"
+puts "Sharpe Ratio: #{results.sharpe_ratio}"
+puts "Max Drawdown: #{results.max_drawdown}%"
+```
+
+## Core Features
+
+### Data Management
+- **Multiple Data Sources**: Alpha Vantage, Yahoo Finance, CSV imports
+- **Polars DataFrames**: High-performance time series data manipulation
+- **Automatic Updates**: Keep historical data current
+
+### Technical Analysis
+- **150+ Indicators**: SMA, EMA, RSI, MACD, Bollinger Bands, Stochastic, ADX, ATR, and more
+- **Custom Calculations**: Build your own indicators
+- **Trend Detection**: Identify market conditions automatically
+
+### Trading Strategies
+- **Built-in Strategies**: RSI, MACD, Bollinger Bands, Moving Average crossovers, Volume Breakout
+- **Strategy Framework**: Plugin architecture for custom strategies
+- **Consensus Approach**: Combine multiple strategies
+- **Rule-Based (KBS)**: RETE-based forward-chaining inference engine
+
+### Advanced Analytics
+- **Portfolio Tracking**: Monitor positions, P&L, commissions
+- **Backtesting**: Historical simulation with performance metrics
+- **Strategy Generator**: Mine patterns from profitable trades
+- **Genetic Programming**: Evolutionary parameter optimization
+- **FPOP Analysis**: Future Period of Performance calculations
+- **Real-Time Streaming**: Process live data with event callbacks
+
+## Architecture
+
+```mermaid
+graph TD
+    A[Stock Data] --> B[SQA::DataFrame]
+    B --> C[Technical Indicators]
+    C --> D[Trading Strategies]
+    D --> E{Strategy Type}
+    E -->|Simple| F[SMA/EMA/RSI]
+    E -->|Advanced| G[MACD/Bollinger]
+    E -->|Rule-Based| H[KBS Strategy]
+    D --> I[Portfolio Management]
+    I --> J[Backtesting]
+    J --> K[Performance Metrics]
+
+    L[Real-Time Data] --> M[SQA::Stream]
+    M --> D
+
+    N[Pattern Discovery] --> O[StrategyGenerator]
+    O --> P[Generated Strategies]
+    P --> D
+```
+
+## Getting Started
+
+Ready to dive in? Check out our guides:
+
+- **[Installation Guide](getting-started/installation.md)** - Get SQA up and running
+- **[Quick Start](getting-started/quick-start.md)** - Your first analysis in minutes
+- **[Configuration](getting-started/configuration.md)** - Customize SQA for your needs
+- **[Console Usage](getting-started/console-usage.md)** - Interactive exploration with `sqa-console`
+
+## Key Resources
+
+### For Beginners
+- [Core Concepts](concepts/index.md) - Understand the fundamentals
+- [Technical Indicators](indicators/index.md) - Learn about indicators
+- [Trading Strategies](strategies/index.md) - Explore built-in strategies
+
+### For Advanced Users
+- [Portfolio Management](advanced/portfolio.md) - Track your trades
+- [Backtesting](advanced/backtesting.md) - Test strategies historically
+- [Strategy Generator](advanced/strategy-generator.md) - Discover patterns
+- [Genetic Programming](genetic_programming.md) - Optimize parameters
+
+### Reference
+- [API Documentation](api/index.md) - Complete API reference
+- [Data Sources](data-sources/index.md) - Working with data
+- [Terms of Use](terms_of_use.md) - Important legal information
+
+## Community & Support
+
+- **GitHub**: [github.com/madbomber/sqa](https://github.com/madbomber/sqa)
+- **RubyGems**: [rubygems.org/gems/sqa](https://rubygems.org/gems/sqa)
+- **Issues**: Report bugs or request features on [GitHub Issues](https://github.com/madbomber/sqa/issues)
+
+## License
+
+SQA is released under the MIT License. See the [LICENSE](https://github.com/madbomber/sqa/blob/main/LICENSE.txt) file for details.
+
+---
+
+<p align="center">
+  <strong>Remember: The House Always Wins</strong><br>
+  <em>Trade responsibly. Never risk more than you can afford to lose.</em>
+</p>

data/docs/indicators/index.md

@@ -0,0 +1,97 @@
+# Technical Indicators
+
+SQA provides access to 150+ technical indicators via the sqa-tai gem, which wraps the industry-standard TA-Lib library.
+
+## Quick Reference
+
+All indicators are available through the `SQAI` module:
+
+```ruby
+require 'sqa'
+
+prices = [100, 102, 101, 103, 105, 104, 106]
+
+# Simple Moving Average
+sma = SQAI.sma(prices, period: 5)
+
+# Relative Strength Index
+rsi = SQAI.rsi(prices, period: 14)
+
+# Bollinger Bands (returns 3 arrays: upper, middle, lower)
+upper, middle, lower = SQAI.bbands(prices, period: 20)
+```
+
+## Indicator Categories
+
+### Overlap Studies (Moving Averages)
+- SMA - Simple Moving Average
+- EMA - Exponential Moving Average
+- WMA - Weighted Moving Average
+- DEMA - Double Exponential Moving Average
+- TEMA - Triple Exponential Moving Average
+- T3 - Triple Exponential Moving Average (T3)
+- MA - Moving Average (configurable type)
+
+### Momentum Indicators
+- RSI - Relative Strength Index
+- STOCH - Stochastic Oscillator
+- STOCHF - Stochastic Fast
+- STOCHRSI - Stochastic RSI
+- MACD - Moving Average Convergence Divergence
+- MOM - Momentum
+- ROC - Rate of Change
+- CCI - Commodity Channel Index
+- WILLR - Williams' %R
+
+### Volatility Indicators
+- ATR - Average True Range
+- NATR - Normalized Average True Range
+- TRANGE - True Range
+- BBANDS - Bollinger Bands
+
+### Volume Indicators
+- AD - Chaikin A/D Line
+- ADOSC - Chaikin A/D Oscillator
+- OBV - On Balance Volume
+
+### See Individual Indicators
+
+Browse the navigation menu for detailed information about each indicator.
+
+## Common Patterns
+
+### Single-Value Indicators
+
+```ruby
+# Returns array of values
+values = SQAI.rsi(prices, period: 14)
+current_rsi = values.last
+```
+
+### Multi-Value Indicators
+
+```ruby
+# MACD returns 3 arrays
+macd_line, signal_line, histogram = SQAI.macd(prices)
+```
+
+### Indicators Requiring Multiple Inputs
+
+```ruby
+# ATR needs high, low, close
+high = [105, 107, 106, 108]
+low = [103, 104, 103, 105]
+close = [104, 106, 105, 107]
+
+atr = SQAI.atr(high, low, close, period: 14)
+```
+
+## Full Indicator List
+
+To see all available indicators:
+
+```ruby
+SQAI.methods.grep(/^[a-z]/).sort
+```
+
+This will list all 150+ indicators in alphabetical order.

data/docs/indicators.md

@@ -1,33 +1,119 @@
-# Indicators
+# Technical Indicators Overview
 
-An indicator is a formula/metric on a stock's historical activity.  It is presumed to be a forecast as to what the stock activity might be in the future.  A single indicator is not necessarily an accurate predictor of future events not is any specific group of indicators.
+## The Philosophy of Indicators
 
-In other words the future is uncertain.  Is it a coin flip?  Heads the stock's price goes up.  Tails, the stock's price goes down.  Its one or the other right?  What if the price never changes.  Then its not a coin flip.  Also what is the time frame involved in the forecast?  Is it tomorrow, next week, next month, next year, next decade?  What is the delta change in price that can be expected?
+An indicator is a formula/metric on a stock's historical activity. It is presumed to be a forecast as to what the stock activity might be in the future. A single indicator is not necessarily an accurate predictor of future events, nor is any specific group of indicators.
 
-So indicators are like TV weather forecastors.  Sometimes they are right.  Sometimes they are wrong.
+In other words, the future is uncertain. Is it a coin flip? Heads the stock's price goes up. Tails, the stock's price goes down. It's one or the other, right? What if the price never changes? Then it's not a coin flip. Also what is the time frame involved in the forecast? Is it tomorrow, next week, next month, next year, next decade? What is the delta change in price that can be expected?
 
-We are dealing with uncertainity.  In uncertainity there is chaos. If it is possible to be right more times that you are wrong you can make money.  If you are always wrong then always do the opposite and you will make money.  When you are wrong more times than you are right.... you loose.
+So indicators are like TV weather forecasters. Sometimes they are right. Sometimes they are wrong.
 
-Its a game.  Game theory tells us that there are winners and losers. Bookies at the track make money every day by taking a cut of the losers loses before giving them to the winners.  Bookies always win so long as they keep their books balanced.  Accounts are important.
+We are dealing with uncertainty. In uncertainty there is chaos. If it is possible to be right more times than you are wrong, you can make money. If you are always wrong, then always do the opposite and you will make money. When you are wrong more times than you are right... you lose.
 
-Back to indicators.  Here is a list of the current indicators:
+It's a game. Game theory tells us that there are winners and losers. Bookies at the track make money every day by taking a cut of the losers' losses before giving them to the winners. Bookies always win so long as they keep their books balanced. Accounts are important.
 
+---
 
+## SQA Indicator System
 
-* [Average True Range](average true range.md)
-* [Bollinger Bands](bollinger bands.md)
-* [Vandlestick Pattern Recognizer](candlestick pattern recognizer.md)
-* [Vlassify Market Profile](classify market profile.md)
-* [Donchian Channel](donchian channel.md)
-* [Double Top Bottom Pattern](double top bottom pattern.md)
-* [EMA Analysis](ema analysis.md)
-* [Fibonacci Retracement](fibonacci retracement.md)
-* [Head and Shoulders Pattern](head and shoulders pattern.md)
-* [Identify Wave Condition](identify wave condition.md)
-* [MACD](macd.md)
-* [Mean Reversion](mean reversion.md)
-* [Momentum](momentum.md)
-* [RSI](rsi.md)
-* [Simple Moving Average](simple moving average.md)
-* [Stochastic Oscillator](stochastic oscillator.md)
-* [True Range](true range.md)
+SQA provides access to **150+ technical indicators** via the separate **sqa-tai gem**, which wraps the industry-standard TA-Lib library.
+
+### Quick Start
+
+All indicators are available through the `SQAI` module:
+
+```ruby
+require 'sqa'
+
+# Get price data
+stock = SQA::Stock.new(ticker: 'AAPL')
+prices = stock.df["adj_close_price"].to_a
+
+# Calculate indicators
+sma = SQAI.sma(prices, period: 20)
+rsi = SQAI.rsi(prices, period: 14)
+macd_line, signal_line, histogram = SQAI.macd(prices)
+
+puts "20-day SMA: #{sma.last}"
+puts "14-day RSI: #{rsi.last}"
+puts "MACD: #{macd_line.last}"
+```
+
+### Indicator Categories
+
+- **Overlap Studies** - SMA, EMA, WMA, DEMA, TEMA, Bollinger Bands
+- **Momentum Indicators** - RSI, MACD, Stochastic, CCI, Williams %R, Momentum
+- **Volatility Indicators** - ATR, NATR, True Range, Bollinger Bands
+- **Volume Indicators** - OBV, AD, Chaikin Oscillator
+- **Pattern Recognition** - Candlestick patterns, chart patterns
+- **And 100+ more...**
+
+### Full Indicator List
+
+To see all available indicators:
+
+```ruby
+SQAI.methods.grep(/^[a-z]/).sort
+```
+
+---
+
+## Documentation
+
+For comprehensive indicator documentation, see:
+
+- **[Technical Indicators Guide](indicators/index.md)** - Complete guide with examples
+- **[sqa-tai Gem](https://github.com/MadBomber/sqa-tai)** - Indicator library source code
+- **[TA-Lib Documentation](https://ta-lib.org/)** - Underlying C library reference
+
+---
+
+## Using Indicators with Strategies
+
+Indicators are commonly used within trading strategies:
+
+```ruby
+require 'sqa'
+
+SQA.init
+
+# Load stock data
+stock = SQA::Stock.new(ticker: 'AAPL')
+df = stock.df
+prices = df["adj_close_price"].to_a
+
+# Calculate indicators
+rsi = SQAI.rsi(prices, period: 14)
+sma_20 = SQAI.sma(prices, period: 20)
+sma_50 = SQAI.sma(prices, period: 50)
+
+# Build signal vector
+require 'ostruct'
+vector = OpenStruct.new(
+  rsi: rsi.last,
+  sma_20: sma_20.last,
+  sma_50: sma_50.last,
+  price: prices.last
+)
+
+# Execute strategy
+signal = SQA::Strategy::RSI.trade(vector)
+puts "Signal: #{signal}"  # => :buy, :sell, or :hold
+```
+
+---
+
+## Related Documentation
+
+- **[DataFrame API](api/dataframe.md)** - Working with price data
+- **[Trading Strategies](strategies/index.md)** - Using indicators in strategies
+- **[Backtesting](advanced/backtesting.md)** - Testing indicator-based strategies
+- **[Strategy Generator](advanced/strategy-generator.md)** - Discovering indicator patterns
+
+---
+
+## External Resources
+
+- **[TA-Lib Official Site](https://ta-lib.org/)** - Technical Analysis Library
+- **[Investopedia](https://www.investopedia.com/technical-analysis-4689657)** - Technical analysis education
+- **[TradingView](https://www.tradingview.com/)** - Charting platform with indicators

data/docs/options.md

@@ -0,0 +1,8 @@
+# Options
+
+https://www.youtube.com/watch?v=A5w-dEgIU1M
+
+## Call Option
+
+## Put Option
+

data/docs/strategies/bollinger-bands.md

@@ -0,0 +1,146 @@
+# Bollinger Bands Strategy
+
+## Overview
+
+The Bollinger Bands strategy uses volatility bands to identify oversold and overbought conditions. The strategy generates buy signals when price touches the lower band and sell signals when price touches the upper band.
+
+## How It Works
+
+Bollinger Bands consist of three lines:
+
+- **Middle Band**: 20-period Simple Moving Average (SMA)
+- **Upper Band**: Middle Band + (2 × Standard Deviation)
+- **Lower Band**: Middle Band - (2 × Standard Deviation)
+
+The bands expand and contract based on market volatility. When volatility increases, the bands widen; when volatility decreases, the bands narrow.
+
+## Trading Signals
+
+### Buy Signal
+Price touches or falls below the **lower band**, indicating an oversold condition.
+
+```ruby
+current_price <= lower_band  # => :buy
+```
+
+### Sell Signal
+Price touches or exceeds the **upper band**, indicating an overbought condition.
+
+```ruby
+current_price >= upper_band  # => :sell
+```
+
+### Hold Signal
+Price remains between the bands.
+
+```ruby
+lower_band < current_price < upper_band  # => :hold
+```
+
+## Parameters
+
+| Parameter | Value | Description |
+|-----------|-------|-------------|
+| Period | 20 | Number of periods for SMA calculation |
+| Std Dev | 2.0 | Number of standard deviations for bands |
+
+## Usage Example
+
+```ruby
+require 'sqa'
+require 'ostruct'
+
+# Load stock data
+stock = SQA::Stock.new(ticker: 'AAPL')
+prices = stock.df["adj_close_price"].to_a
+
+# Create vector with price data
+vector = OpenStruct.new(prices: prices)
+
+# Execute strategy
+signal = SQA::Strategy::BollingerBands.trade(vector)
+puts "Signal: #{signal}"  # => :buy, :sell, or :hold
+```
+
+## Backtesting Example
+
+```ruby
+# Create backtest with Bollinger Bands strategy
+backtest = SQA::Backtest.new(
+  stock: stock,
+  strategy: SQA::Strategy::BollingerBands,
+  initial_cash: 10_000
+)
+
+results = backtest.run
+
+puts "Total Return: #{results.total_return}%"
+puts "Sharpe Ratio: #{results.sharpe_ratio}"
+puts "Max Drawdown: #{results.max_drawdown}%"
+puts "Win Rate: #{results.win_rate}%"
+```
+
+## Characteristics
+
+| Attribute | Value |
+|-----------|-------|
+| Complexity | Medium |
+| Best Market | Volatile, range-bound markets |
+| Typical Win Rate | 50-60% |
+| Risk Level | Medium |
+| Time Horizon | Short to medium term |
+
+## Strengths
+
+- ✅ Works well in ranging markets
+- ✅ Adapts to volatility changes
+- ✅ Provides clear entry/exit points
+- ✅ Simple to understand and implement
+
+## Weaknesses
+
+- ❌ Less effective in strong trends
+- ❌ Can generate false signals during breakouts
+- ❌ Requires sufficient price history (20+ periods)
+- ❌ May whipsaw in choppy markets
+
+## Tips for Best Results
+
+1. **Combine with Trend Indicators**: Use with RSI or MACD to filter false signals
+2. **Watch for Band Squeezes**: Narrow bands often precede big moves
+3. **Adjust Parameters**: Consider wider bands (3 std dev) for less frequent signals
+4. **Volume Confirmation**: Look for high volume on band touches for stronger signals
+5. **Avoid in Trends**: Strategy works best in sideways markets
+
+## Implementation Details
+
+The strategy is implemented in `lib/sqa/strategy/bollinger_bands.rb` and uses TA-Lib's `bbands` indicator via the `sqa-tai` gem:
+
+```ruby
+class SQA::Strategy::BollingerBands
+  def self.trade(vector)
+    # Calculate Bollinger Bands
+    upper, middle, lower = SQAI.bbands(
+      prices,
+      period: 20,
+      nbdev_up: 2.0,
+      nbdev_down: 2.0
+    )
+
+    # Compare current price to bands
+    # ... (see source for full implementation)
+  end
+end
+```
+
+## Related Strategies
+
+- [RSI Strategy](rsi.md) - Combine for better oversold/overbought detection
+- [Volume Breakout](volume-breakout.md) - Use together to confirm breakouts
+- [Mean Reversion](mean-reversion.md) - Similar range-trading approach
+
+## Further Reading
+
+- [Bollinger Bands on Wikipedia](https://en.wikipedia.org/wiki/Bollinger_Bands)
+- [John Bollinger's Official Site](https://www.bollingerbands.com/)
+- [Understanding Volatility with Bollinger Bands](../concepts/volatility.md)

data/docs/strategies/consensus.md

@@ -0,0 +1,64 @@
+# Consensus Strategy
+
+## Overview
+
+Aggregates signals from multiple strategies and makes trading decisions based on majority vote. Reduces risk of acting on single false signals.
+
+## How It Works
+
+Executes 5 independent strategies and counts votes:
+- **Majority Buy**: More buy signals than sell → Buy
+- **Majority Sell**: More sell signals than buy → Sell
+- **Tie or No Consensus**: Hold
+
+## Trading Signals
+
+```ruby
+strategies = [Strategy1, Strategy2, Strategy3, Strategy4, Strategy5]
+votes = strategies.map { |s| s.trade(vector) }
+# votes = [:buy, :buy, :sell, :hold, :buy]
+
+# Count: buy=3, sell=1, hold=1
+# Result: :buy (majority)
+```
+
+## Usage Example
+
+```ruby
+vector = OpenStruct.new(
+  rsi: rsi_data,
+  macd: macd_data,
+  prices: prices
+)
+
+signal = SQA::Strategy::Consensus.trade(vector)
+# Returns :buy, :sell, or :hold based on majority
+```
+
+## Characteristics
+
+- **Complexity**: Medium
+- **Best Market**: All markets
+- **Win Rate**: 50-60%
+- **Reduces**: False signals
+
+## Strengths
+
+✅ Reduces false positives  
+✅ More reliable than single strategy  
+✅ Democratic decision making  
+✅ Can combine different approaches  
+
+## Weaknesses
+
+❌ May be slower to act  
+❌ Can dilute strong signals  
+❌ Requires multiple data inputs  
+
+## Tips
+
+1. **Diverse Strategies**: Mix trend and momentum strategies
+2. **Odd Number**: Use odd number of strategies to avoid ties
+3. **Weighted Voting**: Consider weighting better-performing strategies
+4. **Threshold**: Require super-majority (e.g., 4 out of 5) for higher conviction
+