TradingAgents/CHANGELOG.md

# Changelog

All notable changes to TradingAgents will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added
- Backtest module for historical strategy replay (Issues #42-44)
  - BacktestEngine with historical price replay and trade execution simulation [file:tradingagents/backtest/backtest_engine.py](tradingagents/backtest/backtest_engine.py)
  - Slippage models: NoSlippage, FixedSlippage, PercentageSlippage, VolumeSlippage
  - Commission models: NoCommission, FixedCommission, PerShareCommission, PercentageCommission, TieredCommission
  - Signal processing with OrderSide, OrderType, FillStatus enums
  - OHLCV, Signal, BacktestConfig, BacktestPosition, BacktestTrade, BacktestSnapshot, BacktestResult dataclasses
  - ResultsAnalyzer for post-backtest metrics calculation [file:tradingagents/backtest/results_analyzer.py](tradingagents/backtest/results_analyzer.py)
  - RiskMetrics: Sharpe, Sortino, Calmar, VaR, CVaR, Ulcer index
  - TradeStatistics: Win rate, profit factor, consecutive wins/losses, average trade
  - BenchmarkComparison: Alpha, beta, correlation, capture ratios
  - DrawdownAnalysis: Underwater periods, recovery tracking, max drawdown duration
  - Monthly and yearly performance breakdown with PerformanceBreakdown dataclass
  - ReportGenerator for PDF/HTML/JSON/Markdown report generation [file:tradingagents/backtest/report_generator.py](tradingagents/backtest/report_generator.py)
  - SVG chart generation for equity curves, drawdown charts, monthly heatmaps
  - Configurable report sections and color schemes via ReportConfig
  - Factory functions: create_backtest_engine(), create_results_analyzer(), create_report_generator()
  - Total: 143 tests (57 backtest engine + 42 results analyzer + 44 report generator)

- Alert notification system (Issues #38-41)
  - AlertManager for orchestrating multi-channel notifications [file:tradingagents/alerts/alert_manager.py](tradingagents/alerts/alert_manager.py)
  - Alert, AlertConfig, AlertResult, AlertBatch dataclasses
  - AlertType enum: TRADE_SIGNAL, RISK_WARNING, POSITION_UPDATE, SYSTEM_ALERT, PRICE_ALERT
  - AlertPriority enum: LOW, NORMAL, HIGH, CRITICAL
  - AlertChannel enum: EMAIL, SMS, SLACK, PUSH, WEBHOOK
  - Channel routing based on alert type and priority
  - Rate limiting and batching support
  - SlackChannel for Slack webhook integration [file:tradingagents/alerts/slack_channel.py](tradingagents/alerts/slack_channel.py)
  - Block Kit message formatting with attachments
  - Thread support and emoji reactions
  - SMSChannel for Twilio SMS integration [file:tradingagents/alerts/sms_channel.py](tradingagents/alerts/sms_channel.py)
  - Message segmentation for long texts
  - Delivery status tracking
  - Total: 158 tests (55 alert manager + 44 slack + 59 SMS)

- Execution module for broker integration (Issues #22-28)
  - BrokerBase abstract interface for broker implementations [file:tradingagents/execution/broker_base.py](tradingagents/execution/broker_base.py)
  - Order, Position, OrderStatus, OrderType, OrderSide, TimeInForce dataclasses
  - BrokerRouter for routing orders by asset class [file:tradingagents/execution/broker_router.py](tradingagents/execution/broker_router.py)
  - AlpacaBroker for US stocks, ETFs, and crypto [file:tradingagents/execution/alpaca_broker.py](tradingagents/execution/alpaca_broker.py)
  - IBKRBroker for futures and ASX equities [file:tradingagents/execution/ibkr_broker.py](tradingagents/execution/ibkr_broker.py)
  - PaperBroker for simulation mode [file:tradingagents/execution/paper_broker.py](tradingagents/execution/paper_broker.py)
  - OrderManager for order lifecycle management [file:tradingagents/execution/order_manager.py](tradingagents/execution/order_manager.py)
  - RiskControls for position limits and loss limits [file:tradingagents/execution/risk_controls.py](tradingagents/execution/risk_controls.py)
  - Total: 358 tests across execution module

- Memory system with layered architecture (Issues #18-21)
  - LayeredMemory with recency, relevancy, importance scoring [file:tradingagents/memory/layered_memory.py](tradingagents/memory/layered_memory.py)
  - TradeHistoryMemory for trade outcomes and agent reasoning [file:tradingagents/memory/trade_history.py](tradingagents/memory/trade_history.py)
  - RiskProfilesMemory for user preferences over time [file:tradingagents/memory/risk_profiles.py](tradingagents/memory/risk_profiles.py)
  - Memory integration with agent prompts [file:tradingagents/memory/memory_integration.py](tradingagents/memory/memory_integration.py)
  - Total: 207 tests across memory module

- Portfolio management (Issues #29, #31-32)
  - PortfolioState for holdings, cash, mark-to-market [file:tradingagents/portfolio/portfolio_state.py](tradingagents/portfolio/portfolio_state.py)
  - PerformanceMetrics for Sharpe, Sortino, drawdown, returns [file:tradingagents/portfolio/performance_metrics.py](tradingagents/portfolio/performance_metrics.py)
  - AustralianCGTCalculator for 50% discount and tax reports [file:tradingagents/portfolio/cgt_calculator.py](tradingagents/portfolio/cgt_calculator.py)
  - Total: 197 tests across portfolio module

- Simulation and strategy comparison (Issues #33-35)
  - ScenarioRunner for parallel portfolio simulations [file:tradingagents/simulation/scenario_runner.py](tradingagents/simulation/scenario_runner.py)
  - StrategyComparator for performance comparison and statistics [file:tradingagents/simulation/strategy_comparator.py](tradingagents/simulation/strategy_comparator.py)
  - EconomicConditions for regime tagging and evaluation [file:tradingagents/simulation/economic_conditions.py](tradingagents/simulation/economic_conditions.py)
  - Total: 141 tests across simulation module

- Strategy execution (Issues #36-37)
  - SignalToOrderConverter for converting signals to orders [file:tradingagents/strategy/signal_converter.py](tradingagents/strategy/signal_converter.py)
  - StrategyExecutor for end-to-end orchestration [file:tradingagents/strategy/strategy_executor.py](tradingagents/strategy/strategy_executor.py)
  - Total: 93 tests across strategy module

- New analyst agents (Issues #13-17)
  - MomentumAnalyst for multi-timeframe momentum, ROC, ADX [file:tradingagents/agents/analysts/momentum_analyst.py](tradingagents/agents/analysts/momentum_analyst.py)
  - MacroAnalyst for FRED data interpretation, regime detection [file:tradingagents/agents/analysts/macro_analyst.py](tradingagents/agents/analysts/macro_analyst.py)
  - CorrelationAnalyst for cross-asset and sector rotation [file:tradingagents/agents/analysts/correlation_analyst.py](tradingagents/agents/analysts/correlation_analyst.py)
  - PositionSizingManager for Kelly criterion, risk parity, ATR sizing [file:tradingagents/agents/analysts/position_sizing.py](tradingagents/agents/analysts/position_sizing.py)
  - Analyst integration with graph/setup.py workflow
  - Total: 250 tests across new analyst agents

- Data vendor enhancements (Issues #11-12)
  - VendorRouter for adding new data vendors [file:tradingagents/dataflows/vendor_routing.py](tradingagents/dataflows/vendor_routing.py)
  - DataCacheLayer for FRED rate limit management [file:tradingagents/dataflows/data_cache.py](tradingagents/dataflows/data_cache.py)
  - Total: 125 tests for vendor routing and caching

- Trade model for execution history with CGT tracking (Issue #6: DB-5)
  - Trade model with BUY/SELL sides and execution status tracking (PENDING, FILLED, PARTIAL, CANCELLED, REJECTED) [file:tradingagents/api/models/trade.py](tradingagents/api/models/trade.py)
  - TradeSide, TradeStatus, TradeOrderType enums for type-safe trade operations [file:tradingagents/api/models/trade.py:86-137](tradingagents/api/models/trade.py)
  - Order type support (MARKET, LIMIT, STOP, STOP_LIMIT) with signal source and confidence tracking
  - Capital Gains Tax (CGT) support for Australian tax compliance [file:tradingagents/api/models/trade.py:201-305](tradingagents/api/models/trade.py)
  - 50% CGT discount eligibility for holdings >12 months (cgt_discount_eligible field)
  - Australian financial year (FY) calculation (July-June) via tax_year property [file:tradingagents/api/models/trade.py:418-441](tradingagents/api/models/trade.py)
  - CGT gain/loss tracking with gross_gain, gross_loss, and net_gain after discount
  - Multi-currency support with FX rate to AUD conversion [file:tradingagents/api/models/trade.py:306-325](tradingagents/api/models/trade.py)
  - High-precision decimal arithmetic (19,4) for monetary values and (19,8) for FX rates
  - Automatic acquisition_date and timestamp management via default values and validators
  - Check constraints for positive values (quantity, price, total_value, fx_rate_to_aud)
  - Signal confidence validation (0-100 range) and holding period non-negative constraint
  - Many-to-one relationship with Portfolio model with cascade delete behavior [file:tradingagents/api/models/portfolio.py:202-205](tradingagents/api/models/portfolio.py)
  - Properties for convenient trade type checking (is_buy, is_sell, is_filled) [file:tradingagents/api/models/trade.py:443-475](tradingagents/api/models/trade.py)
  - Comprehensive validators for enum normalization (side, status, order_type) and symbol/currency normalization [file:tradingagents/api/models/trade.py:477-585](tradingagents/api/models/trade.py)
  - Event listener validation (before_flush) for cross-field business rule enforcement [file:tradingagents/api/models/trade.py:596-665](tradingagents/api/models/trade.py)
  - Composite indexes for efficient queries: (portfolio_id, symbol) and (portfolio_id, side) and (status, executed_at)
  - Database migration 005_add_trade_model.py with comprehensive schema definition [file:migrations/versions/005_add_trade_model.py](migrations/versions/005_add_trade_model.py)
  - Migration with proper upgrade and downgrade functions for reversible schema changes
  - Comprehensive unit test suite covering field validation, defaults, constraints, enums, and CGT calculations [file:tests/unit/api/test_trade_model.py](tests/unit/api/test_trade_model.py) (2054 lines, 65 tests)
  - Integration test suite for relationships, cascade delete, and concurrent operations [file:tests/integration/api/test_trade_integration.py](tests/integration/api/test_trade_integration.py) (1235 lines, 22 tests)
  - Comprehensive docstrings with examples for all Trade model methods and fields
  - Total: 87 tests added for Trade model feature

- FastAPI backend with JWT authentication and strategies CRUD (Issue #48)
  - FastAPI application with async/await support and health check endpoints [file:tradingagents/api/main.py](tradingagents/api/main.py)
  - JWT authentication with asymmetric RS256 signing algorithm [file:tradingagents/api/services/auth_service.py](tradingagents/api/services/auth_service.py)
  - Argon2 password hashing with automatic salt generation for secure credential storage
  - POST /api/v1/auth/login endpoint with username/password authentication returning JWT tokens
  - GET /api/v1/strategies endpoint with pagination, user isolation, and permission-based access control
  - POST /api/v1/strategies endpoint for creating new strategies with JSON parameters support
  - GET /api/v1/strategies/{id} endpoint for retrieving individual strategies with authorization checks
  - PUT /api/v1/strategies/{id} endpoint for updating strategy metadata and parameters
  - DELETE /api/v1/strategies/{id} endpoint for removing strategies with proper cascade behavior
  - SQLAlchemy ORM with async PostgreSQL/SQLite support [file:tradingagents/api/models/](tradingagents/api/models/)
  - User model with hashed passwords, email uniqueness, and active status tracking [file:tradingagents/api/models/user.py](tradingagents/api/models/user.py)
  - Strategy model with JSON parameters, description, user association, and active/inactive toggling [file:tradingagents/api/models/strategy.py](tradingagents/api/models/strategy.py)
  - Alembic migration system with version control for database schema changes [file:migrations/](migrations/)
  - Initial migration creating users and strategies tables with proper constraints [file:migrations/versions/](migrations/versions/)
  - Database configuration with environment variable support (DATABASE_URL, SQLALCHEMY_ECHO) [file:tradingagents/api/config.py](tradingagents/api/config.py)
  - Pydantic schemas for request validation and response serialization [file:tradingagents/api/schemas/](tradingagents/api/schemas/)
  - CORS middleware configuration with environment-based allowed origins
  - Error handling middleware with consistent JSON error responses and proper HTTP status codes
  - Request logging middleware with sanitized credential exclusion and request ID tracking
  - Comprehensive test suite with 208 tests covering authentication, strategies CRUD, models, migrations, middleware, and configuration [file:tests/api/](tests/api/)
  - API-focused fixtures with async SQLAlchemy session, FastAPI test client, and test user/strategy data [file:tests/api/conftest.py](tests/api/conftest.py)
  - Security tests covering SQL injection prevention, XSS payload handling, JWT tampering detection, and rate limiting
  - Integration tests for endpoint authorization, user isolation, pagination, and cascade operations
  - Migration tests validating schema constraints, rollback behavior, and Alembic configuration
  - New dependencies in pyproject.toml: fastapi, uvicorn, sqlalchemy, alembic, pydantic-settings, passlib, argon2-cffi, python-multipart, python-jose, cryptography
  - API documentation generated from FastAPI OpenAPI schema (available at /docs and /redoc)

- FRED API integration for economic data (Issue #8: DATA-7)
  - Federal Reserve Economic Data (FRED) API wrapper module with core utilities [file:tradingagents/dataflows/fred_common.py](tradingagents/dataflows/fred_common.py) (346 lines)
  - Data retrieval functions module with high-level economic data access [file:tradingagents/dataflows/fred.py](tradingagents/dataflows/fred.py) (396 lines)
  - Custom exceptions for API rate limiting and invalid series errors [file:tradingagents/dataflows/fred_common.py:52-67](tradingagents/dataflows/fred_common.py)
  - FredRateLimitError exception with retry_after metadata for client-side rate limit handling
  - FredInvalidSeriesError exception with series_id tracking for debugging invalid requests
  - Retry logic with exponential backoff for transient API failures [file:tradingagents/dataflows/fred_common.py:146-250](tradingagents/dataflows/fred_common.py)
  - get_api_key() function for secure FRED_API_KEY environment variable retrieval [file:tradingagents/dataflows/fred_common.py:74-83](tradingagents/dataflows/fred_common.py)
  - Date formatting utility for converting various date formats to FRED-compatible YYYY-MM-DD [file:tradingagents/dataflows/fred_common.py:90-144](tradingagents/dataflows/fred_common.py)
  - Request wrapper _make_fred_request() with retry logic and exponential backoff (up to 3 attempts with 1-2-4s delays)
  - Local file caching with 24-hour TTL to reduce API quota consumption [file:tradingagents/dataflows/fred_common.py:42-48](tradingagents/dataflows/fred_common.py)
  - Interest rates function get_interest_rates() for Federal Funds Rate data [file:tradingagents/dataflows/fred.py:104-142](tradingagents/dataflows/fred.py)
  - Treasury rates function get_treasury_rates() for 2Y/5Y/10Y/30Y yield curves [file:tradingagents/dataflows/fred.py:143-185](tradingagents/dataflows/fred.py)
  - Money supply functions get_money_supply() for M1/M2 monetary aggregates [file:tradingagents/dataflows/fred.py:186-228](tradingagents/dataflows/fred.py)
  - Economic growth function get_gdp() for nominal and real GDP data [file:tradingagents/dataflows/fred.py:229-271](tradingagents/dataflows/fred.py)
  - Inflation measurement functions get_inflation() for CPI and PCE indices [file:tradingagents/dataflows/fred.py:272-314](tradingagents/dataflows/fred.py)
  - Labor market function get_unemployment() for unemployment rate data [file:tradingagents/dataflows/fred.py:315-352](tradingagents/dataflows/fred.py)
  - Generic series function get_fred_series() for accessing any FRED series by ID [file:tradingagents/dataflows/fred.py:353-396](tradingagents/dataflows/fred.py)
  - All functions return pandas DataFrames with 'date' and 'value' columns on success, error strings on failure
  - Optional date range filtering (start_date, end_date) in YYYY-MM-DD format
  - Automatic caching control via use_cache parameter
  - Comprehensive docstrings with examples for all functions and utilities
  - Unit test suite for core utilities covering caching, retry logic, and date formatting [file:tests/unit/dataflows/test_fred_common.py](tests/unit/dataflows/test_fred_common.py) (594 lines, 40 tests)
  - Unit test suite for data retrieval functions covering all economic data functions [file:tests/unit/dataflows/test_fred.py](tests/unit/dataflows/test_fred.py) (634 lines, 42 tests)
  - Integration test suite for FRED API with live endpoint testing [file:tests/integration/dataflows/test_fred_integration.py](tests/integration/dataflows/test_fred_integration.py) (560 lines, 26 tests)
  - Test coverage including rate limit handling, caching behavior, and date range filtering
  - Total: 108 tests added for FRED API feature

- Benchmark data retrieval and analysis (Issue #10)
  - Benchmark data module for SPY, sector ETF, and analysis functions [file:tradingagents/dataflows/benchmark.py](tradingagents/dataflows/benchmark.py) (441 lines)
  - Sector ETF mappings for all 11 SPDR sector funds (communication, consumer discretionary/staples, energy, financials, healthcare, industrials, materials, real estate, technology, utilities) [file:tradingagents/dataflows/benchmark.py:48-59](tradingagents/dataflows/benchmark.py)
  - get_benchmark_data() function for fetching OHLCV data via yfinance with date validation [file:tradingagents/dataflows/benchmark.py:67-115](tradingagents/dataflows/benchmark.py)
  - get_spy_data() convenience wrapper for S&P 500 benchmark data [file:tradingagents/dataflows/benchmark.py:117-136](tradingagents/dataflows/benchmark.py)
  - get_sector_etf_data() function for retrieving sector-specific benchmark data with sector validation [file:tradingagents/dataflows/benchmark.py:138-186](tradingagents/dataflows/benchmark.py)
  - calculate_relative_strength() function with IBD-style weighted ROC formula [file:tradingagents/dataflows/benchmark.py:188-285](tradingagents/dataflows/benchmark.py)
  - Relative strength calculation using weighted periods (40% 63-day, 20% 126-day, 20% 189-day, 20% 252-day ROC)
  - Customizable ROC periods with default IBD-style weighting
  - Data alignment via inner join with validation for overlapping dates
  - calculate_rolling_correlation() function for time-series correlation analysis [file:tradingagents/dataflows/benchmark.py:287-349](tradingagents/dataflows/benchmark.py)
  - Configurable rolling window sizes with default 60-day window
  - Comprehensive validation for data alignment and minimum data requirements
  - calculate_beta() function for volatility and systematic risk measurement [file:tradingagents/dataflows/benchmark.py:351-441](tradingagents/dataflows/benchmark.py)
  - Beta calculation using covariance-variance approach with optional smoothing
  - Optional rolling beta calculation with customizable window (default 252 days)
  - Markdown rolling window implementation for efficient computation
  - All functions return DataFrames/Series/floats on success, error strings on failure
  - Comprehensive error handling with descriptive messages and validation logic
  - Comprehensive docstrings with examples for all public functions
  - Unit test suite for benchmark functions [file:tests/unit/dataflows/test_benchmark.py](tests/unit/dataflows/test_benchmark.py) (753 lines, 28 tests)
  - Integration test suite for benchmark workflows [file:tests/integration/dataflows/test_benchmark_integration.py](tests/integration/dataflows/test_benchmark_integration.py) (593 lines, 7 tests)
  - Test coverage includes data fetching, sector validation, relative strength calculation, correlation analysis, and beta calculation
  - Total: 35 tests added for benchmark data feature

- Multi-timeframe OHLCV aggregation functions (Issue #9)
  - Multi-timeframe aggregation module for daily to weekly/monthly resampling [file:tradingagents/dataflows/multi_timeframe.py](tradingagents/dataflows/multi_timeframe.py) (320 lines)
  - Core OHLCV aggregation validation function _validate_ohlcv_dataframe() [file:tradingagents/dataflows/multi_timeframe.py:38-75](tradingagents/dataflows/multi_timeframe.py)
  - Core resampling function _resample_ohlcv() with proper aggregation rules [file:tradingagents/dataflows/multi_timeframe.py:78-139](tradingagents/dataflows/multi_timeframe.py)
  - OHLCV aggregation rules: Open=first, High=max, Low=min, Close=last, Volume=sum [file:tradingagents/dataflows/multi_timeframe.py:105-111](tradingagents/dataflows/multi_timeframe.py)
  - Weekly aggregation function aggregate_to_weekly() with configurable week anchor [file:tradingagents/dataflows/multi_timeframe.py:142-220](tradingagents/dataflows/multi_timeframe.py)
  - Support for Sunday/Monday week anchors with automatic day-of-week mapping [file:tradingagents/dataflows/multi_timeframe.py:180-201](tradingagents/dataflows/multi_timeframe.py)
  - Month boundary handling for weeks spanning multiple months
  - Monthly aggregation function aggregate_to_monthly() with period end/start labeling [file:tradingagents/dataflows/multi_timeframe.py:223-320](tradingagents/dataflows/multi_timeframe.py)
  - Support for month-end (ME) and month-start (MS) labels via period_end parameter
  - Timezone preservation for both UTC and localized datetime indices
  - Input validation with descriptive error messages for missing/invalid data
  - OHLCV value rounding to 2 decimal places for data consistency
  - Return type: DataFrame on success, error string on validation failure
  - Comprehensive docstrings with examples for all public functions
  - Unit test suite for aggregation functions [file:tests/unit/dataflows/test_multi_timeframe.py](tests/unit/dataflows/test_multi_timeframe.py) (29 tests)
  - Integration test suite for multi-timeframe workflows [file:tests/integration/dataflows/test_multi_timeframe_integration.py](tests/integration/dataflows/test_multi_timeframe_integration.py) (13 tests)
  - Test coverage includes validation, weekly aggregation (multiple anchors), monthly aggregation, timezone handling, and partial period aggregation
  - Total: 42 tests added for multi-timeframe aggregation feature

- User model enhancement with profile and API key management (Issue #3)
  - Extended User model with tax_jurisdiction and timezone fields [file:tradingagents/api/models/user.py:47-54](tradingagents/api/models/user.py)
  - Tax jurisdiction field supporting country (e.g., "US", "AU") and state/province level codes (e.g., "US-CA", "AU-NSW")
  - IANA timezone identifier field (e.g., "America/New_York", "Australia/Sydney") with automatic validation
  - Email verification status tracking via is_verified boolean field [file:tradingagents/api/models/user.py:60-64](tradingagents/api/models/user.py)
  - Secure API key management with bcrypt hashing and unique constraints [file:tradingagents/api/models/user.py:55-59](tradingagents/api/models/user.py)
  - API key service module with generate_api_key(), hash_api_key(), and verify_api_key() functions [file:tradingagents/api/services/api_key_service.py](tradingagents/api/services/api_key_service.py)
  - API key generation using secrets.token_urlsafe() with 256-bit entropy and 'ta_' prefix
  - Bcrypt-based API key hashing using pwdlib.PasswordHash for secure storage
  - Constant-time verification to prevent timing attacks on API keys
  - Timezone validator using IANA zoneinfo database [file:tradingagents/api/services/validators.py:134-191](tradingagents/api/services/validators.py)
  - Tax jurisdiction validator supporting 50+ country codes and state/province subdivisions [file:tradingagents/api/services/validators.py:193-283](tradingagents/api/services/validators.py)
  - Utility functions get_available_timezones() and get_available_tax_jurisdictions() for UI dropdowns [file:tradingagents/api/services/validators.py:285-333](tradingagents/api/services/validators.py)
  - Database migration 002_add_user_profile_fields.py with proper defaults and constraints [file:migrations/versions/002_add_user_profile_fields.py](migrations/versions/002_add_user_profile_fields.py)
  - Migration rollback support for reversible schema changes
  - Comprehensive docstrings and security considerations for all functions

- Portfolio model for managing trading portfolios (Issue #4: DB-3)
  - Portfolio model with support for LIVE, PAPER, and BACKTEST portfolio types [file:tradingagents/api/models/portfolio.py](tradingagents/api/models/portfolio.py)
  - PortfolioType enum for type-safe portfolio categorization [file:tradingagents/api/models/portfolio.py:95-107](tradingagents/api/models/portfolio.py)
  - PreciseNumeric custom SQLAlchemy type decorator for Decimal(19,4) precision [file:tradingagents/api/models/portfolio.py:63-92](tradingagents/api/models/portfolio.py)
  - High-precision monetary value handling (19 total digits, 4 decimal places) for initial_capital and current_value fields
  - Automatic current_value default to initial_capital on portfolio creation
  - Unique constraint on (user_id, name) to prevent duplicate portfolio names per user
  - Check constraints for non-negative capital and value amounts
  - Composite indexes for efficient queries: (user_id, is_active) and (user_id, portfolio_type)
  - Relationship to User model with cascade delete behavior
  - Currency code field with ISO 4217 validation (3-letter codes, e.g., AUD, USD)
  - Portfolio status tracking via is_active boolean field with default True
  - Comprehensive validators for currency normalization, portfolio type validation, and business rule enforcement [file:tradingagents/api/models/portfolio.py:249-296](tradingagents/api/models/portfolio.py)
  - Event listener validation (before_flush) for cross-field and database constraint checks [file:tradingagents/api/models/portfolio.py:300-347](tradingagents/api/models/portfolio.py)
  - User model updated with portfolios relationship for one-to-many portfolio association [file:tradingagents/api/models/user.py:72-76](tradingagents/api/models/user.py)
  - Database migration 003_add_portfolio_model.py with comprehensive schema definition [file:migrations/versions/003_add_portfolio_model.py](migrations/versions/003_add_portfolio_model.py)
  - Migration with proper upgrade and downgrade functions for reversible schema changes
  - Comprehensive unit and integration test suites [file:tests/unit/api/test_portfolio_model.py](tests/unit/api/test_portfolio_model.py) [file:tests/integration/api/test_portfolio_integration.py](tests/integration/api/test_portfolio_integration.py)
  - Unit tests covering field validation, defaults, constraints, and enum handling
  - Integration tests for relationships, cascade delete, and concurrent operations

- Settings model for user preferences and risk management (Issue #5: DB-4)
  - Settings model for managing user trading preferences, risk tolerance, and alert configurations [file:tradingagents/api/models/settings.py](tradingagents/api/models/settings.py)
  - RiskProfile enum for user risk tolerance profiles (CONSERVATIVE, MODERATE, AGGRESSIVE) [file:tradingagents/api/models/settings.py:70-82](tradingagents/api/models/settings.py)
  - One-to-one relationship with User model with cascade delete behavior
  - Risk management fields: risk_score (0-10 scale), risk_profile, max_position_pct (0-100), max_portfolio_risk_pct (0-100)
  - Investment horizon field in years for long-term portfolio planning
  - Alert preferences JSON field for configurable email/SMS/push notifications
  - Unique constraint on user_id enforcing one settings record per user
  - Check constraints for valid numeric ranges: risk_score 0-10, position/portfolio risk 0-100, horizon >= 0
  - Automatic timestamps via TimestampMixin (created_at, updated_at)
  - Validators for risk_profile enum normalization and type safety [file:tradingagents/api/models/settings.py:246-279](tradingagents/api/models/settings.py)
  - Event listener validation (before_flush) for business rule enforcement [file:tradingagents/api/models/settings.py:284-313](tradingagents/api/models/settings.py)
  - User model updated with settings relationship for one-to-one association [file:tradingagents/api/models/user.py](tradingagents/api/models/user.py)
  - Database migration 004_add_settings_model.py with comprehensive schema definition [file:migrations/versions/004_add_settings_model.py](migrations/versions/004_add_settings_model.py)
  - Migration with proper upgrade and downgrade functions for reversible schema changes
  - Comprehensive unit test suite covering field validation, defaults, constraints, and enum handling [file:tests/unit/api/test_settings_model.py](tests/unit/api/test_settings_model.py)
  - Integration test suite for relationships, cascade delete, and concurrent operations [file:tests/integration/api/test_settings_integration.py](tests/integration/api/test_settings_integration.py)

- Test fixtures directory with centralized mock data (Issue #51)
  - FixtureLoader class for loading JSON fixtures with automatic datetime parsing [file:tests/fixtures/__init__.py](tests/fixtures/__init__.py)
  - Stock data fixtures: US market OHLCV, Chinese market OHLCV, standardized data [file:tests/fixtures/stock_data/](tests/fixtures/stock_data/)
  - Metadata fixtures: Complete analysis, partial analysis, batch analysis, error scenarios [file:tests/fixtures/metadata/analysis_metadata.json](tests/fixtures/metadata/analysis_metadata.json)
  - Report section fixtures: Market, sentiment, news, fundamentals, investment plans [file:tests/fixtures/report_sections/complete_reports.json](tests/fixtures/report_sections/complete_reports.json)
  - API response fixtures: OpenAI embeddings (single, batch, error responses) [file:tests/fixtures/api_responses/openai_embeddings.json](tests/fixtures/api_responses/openai_embeddings.json)
  - Configuration fixtures: Vendor-specific and LLM provider configurations [file:tests/fixtures/configurations/default_config.json](tests/fixtures/configurations/default_config.json)
  - Comprehensive FixtureLoader class with convenience functions and edge case support
  - DataFrame conversion utilities for stock data with automatic datetime indexing
  - UTF-8 encoding support for Chinese market data with column standardization
  - Updated docs/testing/writing-tests.md with fixtures section and usage examples [file:docs/testing/writing-tests.md](docs/testing/writing-tests.md)
  - Fixture-based testing best practices documentation
- DeepSeek API support for LLM provider integration (Issue #41)
  - DeepSeek provider integration using ChatOpenAI with base_url pointing to DeepSeek API [file:tradingagents/graph/trading_graph.py:105-145](tradingagents/graph/trading_graph.py)
  - DEEPSEEK_API_KEY environment variable handling with validation and helpful error messages
  - Support for DeepSeek models: deepseek-chat and deepseek-reasoner with custom attribution headers
  - Embedding fallback chain for providers without native embeddings (OpenAI -> HuggingFace -> disable memory) [file:tradingagents/agents/utils/memory.py:16-57](tradingagents/agents/utils/memory.py)
  - Optional HuggingFace sentence-transformers integration (all-MiniLM-L6-v2 model) for offline embeddings
  - Graceful degradation with informative warnings when embedding backends unavailable
  - Comprehensive test suite for DeepSeek integration [file:tests/integration/test_deepseek.py](tests/integration/test_deepseek.py)
- Test directory restructuring into unit/integration/e2e (Issue #50)
  - Organized tests into unit/, integration/, and e2e/ subdirectories by test type
  - Unit tests (5 files) - Fast, isolated tests: conftest_hierarchy, documentation_structure, exceptions, logging_config, report_exporter
  - Integration tests (3 files) - Component interaction tests: akshare, cli_error_handling, openrouter
  - End-to-end tests - Complete workflow tests with dedicated e2e/README.md guidelines
  - Hierarchical conftest.py structure for each test directory with type-specific fixtures
  - Updated pytest.ini with test discovery paths (tests, tests/unit, tests/integration, tests/e2e)
  - Custom markers registered: unit, integration, e2e, llm, chromadb, slow, requires_api_key
  - Updated docs/testing/README.md with new directory structure diagram and fixture organization
  - Improved test isolation with directory-specific fixtures and configurations
- pytest conftest.py hierarchy for organized test fixtures (Issue #49)
  - Root-level conftest.py with shared fixtures (environment variables, LangChain/ChromaDB mocking, configuration)
  - Unit-level conftest.py with data vendor mocking (akshare, yfinance, sample DataFrames)
  - Integration-level conftest.py with live ChromaDB and temporary directory fixtures
  - Fixture scope management (function, session, module) for test isolation and performance
  - Comprehensive docstrings for all fixtures with usage examples and scope documentation
  - pytest.ini configuration with custom markers (unit, integration, e2e, llm, chromadb, slow, requires_api_key)
  - Test suite validating fixture accessibility across test directories [file:tests/test_conftest_hierarchy.py](tests/test_conftest_hierarchy.py)
  - Updated testing documentation with conftest.py hierarchy section [file:docs/testing/README.md](docs/testing/README.md)
  - Fixture usage examples in writing-tests.md [file:docs/testing/writing-tests.md](docs/testing/writing-tests.md)
- Comprehensive documentation structure (Issue #52)
  - Organized `docs/` directory with structured documentation sections
  - Quick start guide at `docs/QUICKSTART.md`
  - Architecture documentation in `docs/architecture/` (multi-agent-system, data-flow, llm-integration)
  - API reference documentation in `docs/api/` (trading-graph, agents, dataflows)
  - Developer guides in `docs/guides/` (adding-new-analyst, adding-llm-provider, adding-data-vendor, configuration)
  - Testing documentation in `docs/testing/` (README, running-tests, writing-tests)
  - Development setup guide in `docs/development/`
  - Central documentation index at `docs/README.md` with navigation and key concepts
  - Updated PROJECT.md DOCUMENTATION MAP section to reference new docs/ structure
  - Added Documentation section to README.md with links to key guides
- Export reports to file with metadata (Issue #21)
  - YAML frontmatter formatting for report metadata [file:tradingagents/utils/report_exporter.py:63-111](tradingagents/utils/report_exporter.py)
  - Report creation with combined YAML frontmatter and markdown content [file:tradingagents/utils/report_exporter.py:112-136](tradingagents/utils/report_exporter.py)
  - Safe filename generation with date prefixes and sanitization [file:tradingagents/utils/report_exporter.py:137-185](tradingagents/utils/report_exporter.py)
  - JSON metadata serialization with datetime handling and directory creation [file:tradingagents/utils/report_exporter.py:186-220](tradingagents/utils/report_exporter.py)
  - Comprehensive report generation combining multiple sections with table of contents [file:tradingagents/utils/report_exporter.py:221-325](tradingagents/utils/report_exporter.py)
  - Support for organizing report sections by team (Analyst, Research, Trading, Portfolio)
  - Datetime-to-ISO-string conversion for YAML/JSON serialization
  - Helper functions for basic YAML formatting when PyYAML is unavailable
  - Comprehensive test suite for all report export functions [file:tests/test_report_exporter.py](tests/test_report_exporter.py)
  - Public API exports in utils/__init__.py for easy access
- Rate limit error handling for LLM APIs (Issue #39)
  - Unified exception hierarchy for handling rate limit errors across providers (OpenAI, Anthropic, OpenRouter) [file:tradingagents/utils/exceptions.py](tradingagents/utils/exceptions.py)
  - Dual-output logging configuration supporting both terminal and file outputs [file:tradingagents/utils/logging_config.py](tradingagents/utils/logging_config.py)
  - Automatic rotating log files with 5MB rotation and 3 backups
  - Terminal logging at INFO level and file logging at DEBUG level
  - API key sanitization in log messages to prevent credential leaks
  - Error recovery utilities for saving partial analysis state on errors [file:tradingagents/utils/error_recovery.py](tradingagents/utils/error_recovery.py)
  - User-friendly error message formatting for rate limit errors [file:tradingagents/utils/error_messages.py](tradingagents/utils/error_messages.py)
  - Comprehensive test suite for exceptions and logging configuration [file:tests/test_exceptions.py](tests/test_exceptions.py) [file:tests/test_logging_config.py](tests/test_logging_config.py)
- AKShare data vendor integration for US and Chinese stock market data (Issue #16)
  - Unified AKShare vendor module with support for both US and Chinese markets [file:tradingagents/dataflows/akshare.py](tradingagents/dataflows/akshare.py)
  - Date format conversion utility for YYYYMMDD compatibility [file:tradingagents/dataflows/akshare.py:34-67](tradingagents/dataflows/akshare.py)
  - Exponential backoff retry mechanism with configurable attempts and delays [file:tradingagents/dataflows/akshare.py:70-108](tradingagents/dataflows/akshare.py)
  - US stock data retrieval via `get_akshare_stock_data_us()` [file:tradingagents/dataflows/akshare.py:114-211](tradingagents/dataflows/akshare.py)
  - Chinese stock data retrieval via `get_akshare_stock_data_cn()` [file:tradingagents/dataflows/akshare.py:213-320](tradingagents/dataflows/akshare.py)
  - Auto-market detection with `get_akshare_stock_data()` for automatic routing [file:tradingagents/dataflows/akshare.py:322-372](tradingagents/dataflows/akshare.py)
  - Rate limit error handling via `AKShareRateLimitError` exception with vendor fallback [file:tradingagents/dataflows/akshare.py:28-30](tradingagents/dataflows/akshare.py)
  - Integration with interface.py vendor routing system [file:tradingagents/dataflows/interface.py](tradingagents/dataflows/interface.py)
  - Comprehensive test suite for all AKShare functions [file:tests/test_akshare.py](tests/test_akshare.py)
- OpenRouter API provider support for unified access to multiple LLM models
  - Support for `provider/model-name` format (e.g., `anthropic/claude-sonnet-4.5`)
  - Proper API key handling with OPENROUTER_API_KEY environment variable
  - Custom headers for OpenRouter attribution (HTTP-Referer, X-Title)
  - Embedding fallback to OpenAI when using OpenRouter (since OpenRouter lacks embeddings)
  - Comprehensive test suite for OpenRouter provider integration [file:tests/test_openrouter.py](tests/test_openrouter.py)
- Expanded .env.example with all supported LLM provider API keys
- Detailed LLM Provider Options section in README.md with examples for:
  - OpenAI (default)
  - Anthropic
  - OpenRouter (new)
  - Google Generative AI
  - Ollama (local)
- OpenRouter configuration example in Python usage section
- Documentation updates in PROJECT.md for OpenRouter support

### Changed
- Updated trading_graph.py LLM provider initialization to handle OpenRouter separately with proper API key and header management [file:tradingagents/graph/trading_graph.py:75-105](tradingagents/graph/trading_graph.py)
- Enhanced memory.py embedding logic to support OpenRouter's embedding fallback behavior [file:tradingagents/agents/utils/memory.py:6-27](tradingagents/agents/utils/memory.py)
- Main.py now includes OpenRouter configuration example (commented out) for easy reference

### Fixed
- ChromaDB collection persistence issue by using `get_or_create_collection()` instead of `create_collection()` to prevent "collection already exists" errors and enable persistent memory across application restarts [file:tradingagents/agents/utils/memory.py:29](tradingagents/agents/utils/memory.py) (Issue #30)
- Improved error messages for missing OPENROUTER_API_KEY when using openrouter provider
- Better embedding client initialization for different LLM providers

---

## [1.0.0] - 2025-01-01 (Example - Update with actual release date)

### Added
- Initial multi-agent trading framework release
- Support for multiple LLM providers
- Analyst team (fundamental, sentiment, news, technical)
- Researcher debate mechanism
- Risk management workflow
- CLI interface
- Integration with financial data APIs