Skip to content

CHANGELOG.md

Latest commit

 

History

History
165 lines (133 loc) · 6.67 KB

CHANGELOG.md

File metadata and controls

165 lines (133 loc) · 6.67 KB
Raw

Changelog

All notable changes to stonks-lab.

[Unreleased]

Added

Phase 8: Tax-Loss Harvesting System (2026-01-25)

  • Tax Module (stonks.tax)

    • correlation.py - Security correlation matrix, find_correlated_alternatives()
    • holdings_overlap.py - ETF overlap %, find_replacement_etfs(), ReplacementCandidate
    • wash_sale.py - WashSaleTracker for 30-day window enforcement, Parquet persistence
    • harvest.py - scan_harvest_opportunities(), HarvestOpportunity, report generation

  • CLI Tool

    • scripts/harvest_scan.py - Portfolio scanner with step-by-step Vanguard instructions
    • Supports CSV input (with optional current_price column to skip API calls)
    • Interactive mode for manual position entry
    • JSON output option for programmatic use

  • Features

    • Pre-defined replacement candidates (VTI→ITOT/SCHB, VXUS→IXUS/SCHF, BND→AGG/SCHZ)
    • SAFE/CAUTION labels based on holdings overlap (>80% = CAUTION)
    • Wash sale window tracking with persistence
    • Tax savings calculation at configurable marginal rate

  • Sample Output

    VTI: -$14,720 loss → $6,182 tax savings
RECOMMENDED: ITOT (r=0.998, 95% overlap) [CAUTION]
EXECUTE: SELL 500 VTI, BUY ITOT, avoid VTI until 2026-02-24

Phase 7: OpenBB Data Expansion (2026-01-25)

  • ETF Data Module (stonks.data.etf)

    • ETFInfo dataclass for ETF metadata
    • get_etf_info(), get_etf_holdings(), get_etf_exposures()
    • Caching with configurable TTL (1-7 days depending on data type)
    • Preset ETF lists (broad market, sector, international, fixed income)

  • International Markets (stonks.data.international)

    • Support for Japan (TSE), Korea (KRX), UK (LSE), Germany (XETRA), France (EPA)
    • MarketConfig for per-market settings (suffix, currency, timezone)
    • normalize_symbol(), strip_suffix(), detect_market() helpers
    • Major stock reference lists per market
    • Price data via yfinance (only viable global provider)

  • Additional Data Types

    • stonks.data.dividends - Dividend history and yield metrics
    • stonks.data.earnings - Earnings history and calendar
    • stonks.data.insider - Insider transactions and sentiment analysis

  • CLI Scripts

    • scripts/update_etf.py - ETF data update with presets
    • scripts/update_international.py - International market data

  • Documentation

    • docs/reference/openbb/ - Cached OpenBB endpoint reference
    • docs/guides/openbb-guide.md - Project OpenBB patterns and conventions
    • docs/recommendations/ - Timestamped investment recommendations
    • docs/adr/004-international-markets.md - Architecture decision record

  • Extended Universe Module

    • INTERNATIONAL_INDICES - Nikkei, TOPIX, KOSPI, FTSE, DAX, CAC
    • INTERNATIONAL_INDEX_ETFS - Tracking ETFs as proxy for constituents
    • get_international_constituents() using ETF holdings

  • Tests

    • tests/test_etf.py - 12 tests
    • tests/test_international.py - 19 tests
    • tests/test_dividends.py - 6 tests
    • tests/test_earnings.py - 8 tests
    • tests/test_insider.py - 8 tests

Phase 7 Validation (2026-01-25)

  • yfinance Fallbacks - Added fallback data fetching when FMP/OpenBB fails

    • _get_holdings_yfinance() for ETF top holdings
    • _get_sector_exposures_yfinance() for sector weights
    • Automatic fallback in get_etf_holdings() and get_etf_exposures()

  • Data Format Fixes

    • Fixed pandas DatetimeIndex→column conversion in providers.py
    • Fixed pandas DatetimeIndex→column conversion in international.py

  • Analysis Scripts

    • scripts/setup_openbb_credentials.py - Runtime API key configuration
    • scripts/analyze_etf.py - ETF holdings/sector analysis CLI
    • scripts/backtest_vz.py - VZ buy-and-hold backtest with dividend analysis

  • VZ Backtest Results

    • 5-year backtest with dividend reinvestment analysis
    • Price return: -30.1%, Total return with dividends: -6.8%
    • Significantly underperformed SPY (+79.6%) - identified as value trap

Phase 6: Value Investing System

  • Data Layer Expansion

    • stonks.data.fundamentals - P/E, P/B, ROE, FCF, debt ratios via OpenBB
    • stonks.data.filings - SEC 10-K/10-Q retrieval with caching
    • stonks.data.news - Company news with material event filtering

  • Value Screener (stonks.screener)

    • ValueScreener - Buffett-style fundamental screening
    • ValueScreenConfig - Configurable criteria (P/E < 15, ROE > 15%, etc.)
    • universe.py - S&P 500, Russell 1000, NASDAQ 100 constituents

  • Claude LLM Integration (stonks.llm)

    • ClaudeClient - Anthropic API wrapper with caching and cost tracking
    • analyze_stock() - Quick or full depth analysis
    • Structured outputs: CompanyAnalysis, MoatAnalysis, QuickAnalysis
    • Value investing prompts for 10-K analysis, thesis critique, news digest

  • Research CLI

    • scripts/screen_value.py - Run value screens from command line
    • scripts/analyze_pick.py - Deep dive on single stocks
    • scripts/research_report.py - Generate research reports

  • Research Notebook

    • notebooks/05_value_research.qmd - Interactive value investing workflow

  • Dependencies

    • Added anthropic>=0.18.0 for Claude API
    • Added pydantic>=2.0 for structured outputs

  • Tests

    • tests/test_fundamentals.py - 11 tests for fundamental data
    • tests/test_screener.py - 13 tests for value screener
    • tests/test_llm.py - 18 tests for LLM module

Previous Phases

Phase 5: CI/CD & R Tests

  • .github/workflows/test.yml - GitHub Actions for Python + R
  • tests/R/test_db.R - 14 tests for R database functions
  • tests/R/test_garch.R - 18 tests for GARCH modeling

Phase 4: Research Notebooks

  • notebooks/01_factor_exploration.qmd - Factor distributions, correlations
  • notebooks/02_garch_volatility.qmd - R GARCH analysis
  • notebooks/03_pairs_trading.qmd - Cointegration + signals
  • notebooks/04_backtest_analysis.qmd - Strategy performance

Phase 3: Strategy Execution Pipeline

  • stonks.strategy.executor - Strategy orchestration
  • stonks.strategy.rebalancer - Weight to orders conversion
  • stonks.strategy.scheduler - Automated strategy runs
  • scripts/run_strategy.py - CLI entry point

Phase 2: Trading & Backtesting

  • stonks.trading - Alpaca integration, risk management
  • stonks.backtest - Backtest engine, walk-forward validation

Phase 1: Foundation

  • Initial project structure
  • Python package stonks with db, data, factors, ml modules
  • R scripts for GARCH, Bayesian, cointegration
  • DuckDB + Parquet data layer
  • Documentation system (CLAUDE.md, docs/, session notes)
  • Git LFS for Parquet files

Infrastructure

  • uv for Python package management
  • renv for R package management
  • Quarto for notebooks
  • git-crypt for secrets