sqa 0.0.31 → 0.0.37

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d6d22476a47a9bfc41607bfaf78edd211f3e8be7badaef817512b3b9c04cb04
-  data.tar.gz: 97ae20203d7bca4bef0bb619e1ae4550071e6072ebe8d357ec99a5957df874a4
+  metadata.gz: 484455cc08530992abd5fc38f02ae973bf1fb243aced961bdf7a8961e3f1b161
+  data.tar.gz: dd3f4cfc5fc7112d6c6e84973f1f5c6376678e69d7713a653c9e04223df35cd1
 SHA512:
-  metadata.gz: 3a51b38307d0c14f750dab7916a505dfd59e793a0d3bd1e1f19c45e5daab39d7e4b0913ace7661bfdb056017f9e5ac43164ea194c4f06d5dbb1423d3cdad6649
-  data.tar.gz: cc4985173611bc3131cb017beb0e3812a3df593799ef1423b741aa7c9113f4ef308df1bba6f808990731bb9d101502dd641a44582dea7a1460d3d65a03bd152b
+  metadata.gz: bce9d957fb7014508833d97fc733eafb0b776fd824b9c2c5fd8417c94ce29f0ff3cbd6a164a19f82f8a5c25cff657ed200f89d223e6a246ddc19bb9857e4befb
+  data.tar.gz: 57477ab3cc699310ebd205588855252db79127dd160ca981ae2ab0b6ebebd39f3dd19b7b26829f130decaf1a38fe006c3c20857e6a739342b793390d5f3fecea

data/CHANGELOG.md

@@ -1,6 +1,110 @@
 ## [Unreleased]
 
+## [0.0.36] - 2025-11-24
+
+### Changed
+- **Phase 3 Architecture & Design Improvements**:
+  - Added deprecation warning for auto-initialization at require time (will be removed in v1.0)
+    - Added `SQA::Config.initialized?` class method to track initialization state
+    - Warning only shows when `$VERBOSE` is set
+  - `concat_and_deduplicate!` now enforces ascending order for TA-Lib compatibility
+    - Warns and forces `descending: false` if `descending: true` is passed
+    - Prevents silent calculation errors from incorrect data ordering
+  - Extracted Faraday connection to configurable dependency in `SQA::Stock`
+    - Added `ALPHA_VANTAGE_URL` constant
+    - Added class methods: `connection`, `connection=`, `default_connection`, `reset_connection!`
+    - Allows injection of custom connections for testing/mocking
+    - Deprecated `CONNECTION` constant (will be removed in v1.0)
+
+### Added
+- **Test Coverage for Phase 3**:
+  - Added 2 tests to `test/config_test.rb` for `initialized?` method
+  - Added 7 tests to `test/stock_test.rb` for configurable connection
+  - Updated `test/data_frame_test.rb` to verify ascending order enforcement
+
+## [0.0.35] - 2025-11-23
+
+### Changed
+- **Phase 2 Code Quality & Best Practices**:
+  - Replaced class variables (`@@var`) with class instance variables (`@var`) for thread safety
+    - `SQA::init.rb`: `@@config`, `@@av_api_key` → `@config`, `@av_api_key`
+    - `SQA::Ticker`: Restructured with `class << self` block, added `reset!` method
+    - `SQA::Stock`: `@@top` → `@top`, added `reset_top!` method
+  - Replaced `puts` statements with `debug_me` in `SQA::SectorAnalyzer`
+  - Simplified `method_missing` in `SQA::DataFrame` (no longer dynamically defines methods)
+  - Fixed type checking pattern in `SQA::Strategy#add` to use `is_a?` instead of `.class ==`
+  - Fixed `SQA::Strategy#available` to use `.name` instead of `.to_s` (avoids pretty_please gem conflict)
+  - Removed magic placeholder "xyzzy" from `SQA::Stock#create_data`
+
+### Fixed
+- **DataFrame.from_aofh**: Fixed Polars compatibility by converting to hash-of-arrays format
+- **DataFrame.from_aofh**: Now properly passes `mapping:` and `transformers:` parameters
+- **Ticker.valid?**: Now handles nil and empty string inputs gracefully
+- **Ticker.lookup**: Now handles nil and empty string inputs gracefully
+
+### Added
+- **Test Coverage for Phase 2**:
+  - New `test/ticker_test.rb` with 10 tests for Ticker class
+  - New `test/strategy_test.rb` with 10 tests for Strategy class
+  - Added 4 tests to `test/data_frame_test.rb` for `from_aofh` and `method_missing`
+  - Added 2 tests to `test/stock_test.rb` for `reset_top!` method
+
+## [0.0.34] - 2025-11-23
+
+### Fixed
+- **Test Suite**: Fixed 15+ pre-existing test failures
+  - Fixed typo in RiskManagerTest (`var` → `cvar`)
+  - Fixed Portfolio test expectations (total_cost, P&L calculation, summary keys)
+  - Fixed URL trailing slash comparisons in AlphaVantage/YahooFinance tests
+  - Fixed FPOP test expectation (implementation returns partial windows)
+  - Fixed SectorAnalyzer symbol/string comparison
+  - Fixed AlphaVantage header mapping test (timestamp, no adjusted_close)
+- **PatternMatcher**: Fixed integer division bug in `pattern_quality` method
+  - Added `.to_f` conversion to prevent truncation with integer inputs
+- **Config Coercion**: Fixed string-to-symbol coercion for `log_level` and `plotting_library`
+  - Added explicit `coerce_key` handlers
+
+### Added
+- **Portfolio**: Added `commission` to `attr_accessor` for public access
+- **Error Namespacing**: Added `SQA::BadParameterError` namespace with backwards-compatible alias
+
+### Changed
+- **Phase 1 Security & Correctness** (from improvement plan):
+  - Replaced shell injection vulnerability (`touch` backticks → `FileUtils.touch`)
+  - Replaced deprecated `has_key?` with `key?` across codebase
+  - Added `SQA::DataFetchError` and `SQA::ConfigurationError` exception classes
+  - Replaced bare `rescue` clauses with specific exception types
+
+## [0.0.33] - 2025-11-23
+
+### Removed
+- **Sinatra Example App**: Removed `examples/sinatra_app/` directory
+  - Functionality moved to separate gem: [sqa_demo-sinatra](https://github.com/MadBomber/sqa_demo-sinatra)
+  - Cleaner separation between library and demo application
+
+### Added
+- **Documentation**: Added links to sqa_demo-sinatra demo application
+  - Updated README.md with Web Demo Application section
+  - Updated docs/index.md with Demo Application section
+  - Updated examples/README.md with reference to web demo
+- **LLM Documentation**: Added llms.txt for AI assistant compatibility
+- **Improvement Plan**: Added docs/IMPROVEMENT_PLAN.md for upcoming code quality improvements
+
+## [0.0.32] - 2024-11-12
+
+### Added
+- **CSV Updates**: Conditional CSV updates based on timestamp
+  - Only updates CSV files when new data is available
+  - Improves performance by avoiding unnecessary writes
+
+### Changed
+- **DataFrame**: Removed debug_me calls from SQA::DataFrame
+  - Cleaned up debugging code for production use
+
 ### Fixed
+- **CSV Data Quality**: Multiple improvements to CSV data handling
+  - Change CSV sort order to ascending (oldest-first) for TA-Lib compatibility
+  - Prevent duplicate timestamps in CSV data files
 - **DataFrame::Data**: Added missing `SQA::DataFrame::Data` class for stock metadata storage
   - Stores ticker, name, exchange, source, indicators, and overview data
   - Supports both hash initialization (JSON) and keyword arguments

data/CLAUDE.md

@@ -212,6 +212,27 @@ sqa-console        # Launch IRB with SQA library loaded
 - 150+ indicators available: SMA, EMA, RSI, MACD, Bollinger Bands, ADX, ATR, etc.
 - See: https://github.com/MadBomber/sqa-tai
 
+### Data Ordering (CRITICAL)
+**TA-Lib Requirement**: Arrays MUST be in **OLDEST-FIRST** (ascending chronological) order
+- Index [0] = oldest data point
+- Index [last] = newest/most recent data point
+- This applies to ALL TA-Lib indicators
+
+**SQA Implementation**:
+- ✅ CSV files stored in **ASCENDING order** (oldest-first) for TA-Lib compatibility
+- ✅ DataFrames maintain ascending order after updates
+- ✅ `.to_a` extracts arrays ready for TA-Lib (no reversal needed)
+- ✅ `concat_and_deduplicate!` sorts ascending by default
+- ⚠️ Alpha Vantage API returns data newest-first, but SQA automatically sorts to ascending
+
+**Example**:
+```ruby
+prices = stock.df["adj_close_price"].to_a
+# => [100.0, 101.5, 103.2, ...]  (oldest to newest - ready for TA-Lib)
+
+rsi = SQAI.rsi(prices, period: 14)  # Correct order, no reversal needed
+```
+
 ### Testing Approach
 - Minitest framework in `/test/` directory
 - SimpleCov for coverage reporting

data/README.md

@@ -1,10 +1,53 @@
-# SQA - Simple Qualitative Analysis
+<div align="center">
+  <h1>SQA - Simple Qualitative Analysis</h1>
+
+  <p>A Ruby library for technical analysis of stock market data, trading strategies, and portfolio optimization.<br/>
+      Core library of the <a href="https://github.com/MadBomber/sqa">SQA</a> (Simple Qualitative Analysis) ecosystem.</p>
+</div>
+
+<table>
+<tr>
+<td width="30%" valign="middle" align="center">
+    <img src="docs/assets/images/sqa.jpg" alt="Ruby Turns Information into Knowledge" width="80%">
+  <br/>
+  <a href="https://www.youtube.com/watch?v=VqomZQMZQCQ">
+    <img src="https://img.shields.io/badge/Badge-We%20don't%20need%20no%20stinkin'%20badges!-red" alt="Badges?">
+  </a>
+</td>
+<td width="70%" valign="top">
+
+**⚠️ WARNING:** This is a learning tool, not production software. DO NOT use this library when real money is at stake. The BUY/SELL signals it generates should not be taken seriously. If you lose your shirt playing in the stock market, don't come crying to me. Playing in the market is like playing in the street - you're going to get run over.
 
-[![Badges?](https://img.shields.io/badge/Badge-We%20don't%20need%20no%20stinkin'%20badges!-red)](https://www.youtube.com/watch?v=VqomZQMZQCQ)
+## Features
+
+### Core Capabilities
+- **High-Performance DataFrames** - Polars-based data structures for time series financial data
+- **150+ Technical Indicators** - Via the separate [`sqa-tai`](https://github.com/MadBomber/sqa-tai) gem (TA-Lib wrapper)
+- **Trading Strategies** - Framework for building and testing trading strategies
+- **Multiple Data Sources** - Alpha Vantage and Yahoo Finance adapters
+- **Stock Management** - Track stocks with historical prices and company metadata
+- **Statistical Analysis** - Comprehensive statistics on price data
+- **Ticker Validation** - Validate stock symbols against market exchanges
+- **Interactive Console** - IRB console for experimentation (`sqa-console`)
+- **CLI Tools** - Command-line interface via the separate [`sqa-cli`](https://github.com/MadBomber/sqa-cli) gem
 
-A Ruby library for technical analysis of stock market data. This is a simplistic set of tools for quantitative and qualitative stock analysis designed for **educational purposes only**.
+### Advanced Features
+- **Portfolio Management** - Track positions, trades, P&L with commission support
+- **Backtesting Framework** - Simulate trading strategies with comprehensive performance metrics
+- **Strategy Generator** - Reverse-engineer profitable trades to discover indicator patterns
+- **Genetic Programming** - Evolve optimal strategy parameters through natural selection
+- **Knowledge-Based Strategy (KBS)** - RETE-based forward-chaining inference for complex trading rules
+- **Real-Time Streaming** - Event-driven live price processing with on-the-fly signal generation
+- **FPL Analysis** - Future Period Loss/Profit analysis with risk metrics and directional classification
+- **Market Regime Detection** - Identify bull/bear/sideways markets with volatility and strength metrics
+- **Seasonal Analysis** - Discover calendar-dependent patterns (monthly/quarterly performance)
+- **Sector Analysis** - Multi-stock pattern discovery with KBS blackboards per sector
+- **Walk-Forward Validation** - Time-series cross-validation to prevent pattern overfitting
+- **Pattern Context System** - Context-aware patterns that know when/where they're valid
 
-**⚠️ WARNING:** This is a learning tool, not production software. Do NOT use this library when real money is at stake. The BUY/SELL signals it generates should not be taken seriously. If you lose your shirt playing in the stock market, don't come crying to me. Playing in the market is like playing in the street - you're going to get run over.
+</td>
+</tr>
+</table>
 
 <!-- Tocer[start]: Auto-generated, don't remove. -->
 
@@ -30,33 +73,6 @@ A Ruby library for technical analysis of stock market data. This is a simplistic
   - [License](#license)
 
 <!-- Tocer[finish]: Auto-generated, don't remove. -->
-
-## Features
-
-### Core Capabilities
-- **High-Performance DataFrames** - Polars-based data structures for time series financial data
-- **150+ Technical Indicators** - Via the `sqa-tai` gem (TA-Lib wrapper)
-- **Trading Strategies** - Framework for building and testing trading strategies
-- **Multiple Data Sources** - Alpha Vantage and Yahoo Finance adapters
-- **Stock Management** - Track stocks with historical prices and company metadata
-- **Statistical Analysis** - Comprehensive statistics on price data
-- **Ticker Validation** - Validate stock symbols against market exchanges
-- **Interactive Console** - IRB console for experimentation (`sqa-console`)
-
-### Advanced Features
-- **Portfolio Management** - Track positions, trades, P&L with commission support
-- **Backtesting Framework** - Simulate trading strategies with comprehensive performance metrics
-- **Strategy Generator** - Reverse-engineer profitable trades to discover indicator patterns
-- **Genetic Programming** - Evolve optimal strategy parameters through natural selection
-- **Knowledge-Based Strategy (KBS)** - RETE-based forward-chaining inference for complex trading rules
-- **Real-Time Streaming** - Event-driven live price processing with on-the-fly signal generation
-- **FPL Analysis** - Future Period Loss/Profit analysis with risk metrics and directional classification
-- **Market Regime Detection** - Identify bull/bear/sideways markets with volatility and strength metrics
-- **Seasonal Analysis** - Discover calendar-dependent patterns (monthly/quarterly performance)
-- **Sector Analysis** - Multi-stock pattern discovery with KBS blackboards per sector
-- **Walk-Forward Validation** - Time-series cross-validation to prevent pattern overfitting
-- **Pattern Context System** - Context-aware patterns that know when/where they're valid
-
 ## Installation
 
 Install the gem:
@@ -65,6 +81,8 @@ Install the gem:
 gem install sqa
 ```
 
+This will automatically install the `sqa-tai` gem (technical indicators) as a dependency.
+
 Or add to your `Gemfile`:
 
 ```ruby
@@ -77,6 +95,12 @@ Then run:
 bundle install
 ```
 
+For command-line tools, install the separate CLI gem:
+
+```bash
+gem install sqa-cli
+```
+
 ## Configuration
 
 ### Data Directory
@@ -186,7 +210,7 @@ df.data        # Polars::DataFrame
 
 ### Technical Indicators
 
-All technical indicators are provided by the [`sqa-tai`](https://github.com/MadBomber/sqa-tai) gem, which wraps the industry-standard TA-Lib library:
+All technical indicators are provided by the separate [`sqa-tai`](https://github.com/MadBomber/sqa-tai) gem, which wraps the industry-standard TA-Lib library. The `sqa-tai` gem must be installed separately but is automatically included as a dependency of `sqa`.
 
 ```ruby
 require 'sqa'
@@ -889,6 +913,10 @@ ruby examples/strategy_generator_example.rb
 
 See `examples/README.md` for detailed documentation and integration patterns.
 
+### 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 exploring stock analysis, technical indicators, and trading strategies.
+
 ## Architecture
 
 **Core Components:**

data/Rakefile

@@ -1,25 +1,67 @@
 # frozen_string_literal: true
 
-
-
 begin
-  require "tocer/rake/register"
-rescue LoadError => error
-  puts error.message
+  require 'tocer/rake/register'
+rescue LoadError => e
+  puts e.message
 end
 
 Tocer::Rake::Register.call
 
+begin
+  require 'yard'
+
+  namespace :docs do
+    desc 'Build complete documentation site (API markdown + MkDocs)'
+    task :build do
+      puts 'Step 1: Generating API documentation from YARD comments...'
+      sh 'ruby bin/generate_api_docs.rb'
+
+      puts "\nStep 2: Building MkDocs site with Material theme..."
+      sh 'mkdocs build'
 
+      puts "\nDocumentation complete!"
+      puts '  Site: site/index.html'
+      puts '  API Reference: site/api-reference/index.html'
+      puts "\nTo preview: rake docs:serve"
+    end
+
+    desc 'Serve documentation locally with live reload'
+    task :serve do
+      puts 'Starting MkDocs development server...'
+      puts 'View at: http://127.0.0.1:8000'
+      puts 'Press Ctrl+C to stop'
+      sh 'mkdocs serve'
+    end
+
+    desc 'Clean generated documentation files'
+    task :clean do
+      puts 'Cleaning generated documentation...'
+      sh 'rm -rf docs/api-reference site .yardoc'
+      puts 'Done!'
+    end
+
+    desc 'Deploy documentation to GitHub Pages'
+    task deploy: :build do
+      puts "\nDeploying to GitHub Pages..."
+      sh 'mkdocs gh-deploy --force'
+
+      puts "\nDeployment complete!"
+      puts 'Documentation is live at: https://madbomber.github.io/sqa/'
+    end
+  end
+rescue LoadError
+  # YARD not available
+end
 
-require "bundler/gem_tasks"
-require "minitest/test_task"
+require 'bundler/gem_tasks'
+require 'minitest/test_task'
 
 Minitest::TestTask.create(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
+  t.libs << 'test'
+  t.libs << 'lib'
   t.warning = false
-  t.test_globs = ["test/**/*_test.rb"]
+  t.test_globs = ['test/**/*_test.rb']
 end
 
 task default: %i[]