sqa 0.0.32 → 0.0.37

data/docs/index.md

@@ -1,8 +1,25 @@
 # SQA - Simple Qualitative Analysis
 
-<p align="center">
-  <strong>A Powerful Ruby Library for Stock Market Technical Analysis</strong>
-</p>
+<div style="display: flex; align-items: flex-start; gap: 2rem; margin-bottom: 2rem;">
+  <div style="flex: 0 0 400px;">
+    <img src="assets/images/sqa.jpg" alt="SQA - Simple Qualitative Analysis" style="width: 100%; border-radius: 8px; box-shadow: 0 4px 6px rgba(0,0,0,0.1);">
+  </div>
+  <div style="flex: 1;">
+    <h2 style="margin-top: 0;">Key Features</h2>
+    <ul>
+      <li><strong>High Performance</strong> - Rust-backed Polars DataFrames (30x faster)</li>
+      <li><strong>150+ Technical Indicators</strong> - TA-Lib integration via sqa-tai</li>
+      <li><strong>13+ Trading Strategies</strong> - RSI, MACD, Bollinger Bands, and more</li>
+      <li><strong>Portfolio Management</strong> - Track positions, P&L, commissions</li>
+      <li><strong>Backtesting Framework</strong> - Comprehensive performance metrics</li>
+      <li><strong>Real-Time Streaming</strong> - Live price data with callbacks</li>
+      <li><strong>Strategy Generation</strong> - Discover patterns from profitable trades</li>
+      <li><strong>Genetic Programming</strong> - Evolve optimal parameters</li>
+      <li><strong>Risk Management</strong> - VaR, CVaR, position sizing</li>
+      <li><strong>Pattern Matching</strong> - Find similar historical patterns</li>
+    </ul>
+  </div>
+</div>
 
 ---
 
@@ -97,26 +114,7 @@ puts "Max Drawdown: #{results.max_drawdown}%"
 
 ## 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
-```
+![SQA Architecture](assets/images/architecture.svg)
 
 ## Getting Started
 
@@ -143,10 +141,15 @@ Ready to dive in? Check out our guides:
 - [Data Sources](data-sources/index.md) - Working with data
 - [Terms of Use](terms_of_use.md) - Important legal information
 
+## Demo Application
+
+Want to see SQA in action? Check out the **[sqa_demo-sinatra](https://github.com/MadBomber/sqa_demo-sinatra)** gem - a web-based demonstration application that provides a visual interface for exploring stock analysis, technical indicators, and trading strategies.
+
 ## Community & Support
 
 - **GitHub**: [github.com/madbomber/sqa](https://github.com/madbomber/sqa)
 - **RubyGems**: [rubygems.org/gems/sqa](https://rubygems.org/gems/sqa)
+- **Demo App**: [sqa_demo-sinatra](https://github.com/MadBomber/sqa_demo-sinatra) - Web-based SQA demonstration
 - **Issues**: Report bugs or request features on [GitHub Issues](https://github.com/madbomber/sqa/issues)
 
 ## License

data/docs/llms.txt

@@ -0,0 +1,109 @@
+# SQA - Simple Qualitative Analysis
+
+> A powerful Ruby library for stock market technical analysis and trading strategy development
+
+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.
+
+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.
+
+- 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
+
+## Getting Started
+
+  - [Index](https://madbomber.github.io/sqa/getting-started/index): Welcome to SQA! This guide will help you get up and running with stock market technical analysis in just a few minutes.
+  - [Installation](https://madbomber.github.io/sqa/getting-started/installation): This guide walks you through installing SQA and all its dependencies.
+  - [Quick Start](https://madbomber.github.io/sqa/getting-started/quick-start): Get up and running with SQA in just a few minutes!
+
+## Core Concepts
+
+  - [Index](https://madbomber.github.io/sqa/concepts/index): Understanding the fundamental building blocks of SQA.
+  - [Dataframes](https://madbomber.github.io/sqa/data_frame): The SQA::DataFrame class is a high-performance wrapper around the Polars DataFrame library, specifically designed for time series financial data...
+  - [Technical Indicators](https://madbomber.github.io/sqa/indicators/index): SQA provides access to 150+ technical indicators via the sqa-tai gem, which wraps the industry-standard TA-Lib library.
+  - [Trading Strategies](https://madbomber.github.io/sqa/strategy): 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...
+
+## Technical Indicators
+
+  - [Index](https://madbomber.github.io/sqa/indicators/index): SQA provides access to 150+ technical indicators via the sqa-tai gem, which wraps the industry-standard TA-Lib library.
+  - [Overview](https://madbomber.github.io/sqa/indicators): ## The Philosophy of Indicators
+
+
+
+## Trading Strategies
+
+  - [Index](https://madbomber.github.io/sqa/strategies/index): Explore SQA's comprehensive suite of trading strategies.
+
+### Built-in Strategies
+
+    - [Bollinger Bands Strategy](https://madbomber.github.io/sqa/strategies/bollinger-bands): The Bollinger Bands strategy uses volatility bands to identify oversold and overbought conditions. The strategy generates buy signals when price...
+    - [Rsi Strategy](https://madbomber.github.io/sqa/strategies/rsi): The Relative Strength Index (RSI) strategy identifies overbought and oversold conditions using momentum oscillators. It generates signals when RSI...
+    - [Macd Strategy](https://madbomber.github.io/sqa/strategies/macd): Moving Average Convergence Divergence (MACD) is a trend-following momentum indicator that shows the relationship between two moving averages.
+    - [Sma Strategy](https://madbomber.github.io/sqa/strategies/sma): The SMA strategy uses crossovers of short-term and long-term simple moving averages to identify trend changes and generate trading signals.
+    - [Ema Strategy](https://madbomber.github.io/sqa/strategies/ema): Similar to SMA but gives more weight to recent prices, making it more responsive to price changes.
+    - [Stochastic Strategy](https://madbomber.github.io/sqa/strategies/stochastic): Compares closing price to the price range over a period to identify overbought/oversold conditions and momentum changes.
+    - [Volume Breakout](https://madbomber.github.io/sqa/strategies/volume-breakout): Identifies price breakouts confirmed by high trading volume for stronger signal reliability.
+    - [Mean Reversion](https://madbomber.github.io/sqa/strategies/mean-reversion): Based on the theory that prices tend to return to their average over time. Buys when price is below average and sells when above.
+    - [Market Profile](https://madbomber.github.io/sqa/strategies/market-profile): Uses market profile analysis to identify support and resistance levels, generating signals when price reaches these key levels.
+    - [Consensus Strategy](https://madbomber.github.io/sqa/strategies/consensus): Aggregates signals from multiple strategies and makes trading decisions based on majority vote. Reduces risk of acting on single false signals.
+
+### Advanced Strategies
+
+    - [Knowledge Based Strategy (kbs)](https://madbomber.github.io/sqa/strategies/kbs): Advanced rule-based trading system using RETE forward-chaining inference engine. Combines multiple indicators with custom logic rules.
+    - [Custom Strategies](https://madbomber.github.io/sqa/strategies/custom): Learn how to create your own trading strategies in the SQA framework.
+
+## Advanced Features
+
+  - [Index](https://madbomber.github.io/sqa/advanced/index): Explore SQA's advanced capabilities for professional-grade analysis.
+  - [Portfolio Management](https://madbomber.github.io/sqa/advanced/portfolio): The Portfolio class tracks positions, calculates P&L, manages commissions, and monitors portfolio performance over time.
+  - [Backtesting](https://madbomber.github.io/sqa/advanced/backtesting): Simulate trading strategies on historical data to evaluate performance before risking real capital.
+  - [Strategy Generator](https://madbomber.github.io/sqa/advanced/strategy-generator): Reverse-engineer profitable trades to discover patterns and automatically generate executable trading strategies.
+  - [Genetic Programming](https://madbomber.github.io/sqa/genetic_programming): ### Overview of Genetic Programming (GP)
+  - [Real Time Streaming](https://madbomber.github.io/sqa/advanced/streaming): Process live price data with event callbacks and parallel strategy execution for real-time trading signals.
+  - [Fpop Analysis](https://madbomber.github.io/sqa/advanced/fpop): Calculate future returns, risk metrics, and direction classification to evaluate trading opportunities.
+  - [Risk Management](https://madbomber.github.io/sqa/advanced/risk-management): Comprehensive risk management tools including VaR, position sizing, and risk metrics.
+  - [Portfolio Optimizer](https://madbomber.github.io/sqa/advanced/portfolio-optimizer): Multi-objective portfolio optimization for optimal asset allocation and rebalancing.
+  - [Ensemble Strategies](https://madbomber.github.io/sqa/advanced/ensemble): Combine multiple strategies with voting and meta-learning.
+  - [Multi Timeframe Analysis](https://madbomber.github.io/sqa/advanced/multi-timeframe): Analyze multiple timeframes simultaneously for better trade timing.
+  - [Pattern Matcher](https://madbomber.github.io/sqa/advanced/pattern-matcher): Pattern recognition and similarity search for forecasting.
+
+## AI & Machine Learning
+
+  - [Ai And Ml](https://madbomber.github.io/sqa/ai_and_ml): ## AI and ML in Trading -- Advancing Decision-Making
+  - [Mean Reversion](https://madbomber.github.io/sqa/mean_reversion): Determines if a stock exhibits mean reversion behavior based on a given price series.
+  - [Predict Next Value](https://madbomber.github.io/sqa/predict_next_value): As a stock quantitative analyst, having a predict next value method on a timeseries array of closing day stock price data would be extremely helpful....
+  - [Identify Wave Condition](https://madbomber.github.io/sqa/identify_wave_condition): The Elliott Wave Theory is a popular method used in stock technical analysis to predict future price movements in financial markets. It is based on...
+  - [Libsvm Format](https://madbomber.github.io/sqa/libsvm_file_format): This file format is used by rumale.
+
+## API Reference
+
+  - [Index](https://madbomber.github.io/sqa/api/index): Complete API documentation for SQA classes and modules.
+  - [Dataframe Class](https://madbomber.github.io/sqa/api/dataframe): SQA::DataFrame is a high-performance wrapper around the Polars DataFrame library, specifically optimized for time series financial data manipulation....
+
+## Data Sources
+
+  - [Index](https://madbomber.github.io/sqa/data-sources/index): SQA supports multiple data sources for historical stock price data.
+
+## Resources
+
+  - [Tags](https://madbomber.github.io/sqa/tags): Browse documentation by topic.
+  - [Requirements](https://madbomber.github.io/sqa/requirements): ... otherwise know as what I want to do.  Some people would call it a roadmap; but, where I'm going "we don't need no stinking roads!"
+  - [Terms Of Use](https://madbomber.github.io/sqa/terms_of_use): Some sections of these Terms of Use are aspirational.  If found to be so, they shall not invalidate any other section which shall remain in full...
+  - [Trading Ideas](https://madbomber.github.io/sqa/i_gotta_an_idea): ... based upon my prior work with sports outcome predictions and sensor net architecture.
+  - [Factor Analysis](https://madbomber.github.io/sqa/factors_that_impact_price): ## Factors that Impact Price
+
+### External Tools
+
+    - [Finviz](https://madbomber.github.io/sqa/finviz): The original finviz unofficial gem has been untouched for 3 years.  I just forked it in the hope that I can bring it forward to current versions of...
+    - [Fx Pro Bit](https://madbomber.github.io/sqa/fx_pro_bit): FXProBot is a new trading software by Avenix Fzco, a major fintech firm located in Dubai that specializes in automated trading. This advanced robot...
+  - [Options Trading](https://madbomber.github.io/sqa/options): https://www.youtube.com/watch?v=A5w-dEgIU1M
+
+## Contributing
+
+  - [Index](https://madbomber.github.io/sqa/contributing/index): Thank you for your interest in contributing to SQA!
+
+## Optional
+
+These resources provide supplementary information that may be skipped for shorter context:
+
+- [Tags](https://madbomber.github.io/sqa/tags): Browse documentation by topic.
+- [Requirements](https://madbomber.github.io/sqa/requirements): ... otherwise know as what I want to do.  Some people would call it a roadmap; but, where I'm going "we don't need no stinking roads!"
+- [Terms of Use](https://madbomber.github.io/sqa/terms_of_use): Some sections of these Terms of Use are aspirational.  If found to be so, they shall not invalidate any other section which shall remain in full...

data/docs/strategies/kbs.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-Advanced rule-based trading system using RETE forward-chaining inference engine. Combines multiple indicators with custom logic rules.
+Advanced rule-based trading system using RETE forward-chaining inference engine. Combines multiple indicators with custom logic rules using the `kbs` (knowledge-based system) ruby gem.  A complete [documentation website for the `kbs` ruby gem is available.](https://madbomber.github.io/kbs)
 
 ## How It Works
 
@@ -29,6 +29,7 @@ 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
@@ -71,10 +72,10 @@ strategy.add_rule :strong_buy do
   without :position  # Don't buy if already holding
 
   perform do
-    kb.assert(:signal, { 
-      action: :buy, 
+    kb.assert(:signal, {
+      action: :buy,
       confidence: :high,
-      reason: :triple_confirmation 
+      reason: :triple_confirmation
     })
   end
 end
@@ -100,18 +101,18 @@ Multiple rules can fire, with aggregate confidence determining final signal.
 
 ## Strengths
 
-✅ Highly customizable  
-✅ Combines multiple indicators  
-✅ Confidence scoring  
-✅ Forward-chaining inference  
-✅ Can encode expert knowledge  
+- ✅ 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  
+- ❌ Complex to configure
+- ❌ Requires domain knowledge
+- ❌ Can be slow with many rules
+- ❌ Overfitting risk
 
 ## Tips
 
@@ -124,6 +125,7 @@ Multiple rules can fire, with aggregate confidence determining final signal.
 ## Available Facts
 
 The KBS strategy processes these fact types:
+
 - `:rsi` - RSI indicator data
 - `:macd` - MACD crossovers
 - `:trend` - Price trend analysis
@@ -161,4 +163,3 @@ end
 
 - [Strategy Generator](../advanced/strategy-generator.md) - Auto-generate rules
 - [Genetic Programming](../genetic_programming.md) - Optimize rule parameters
-

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