gogo2/.kiro/specs/multi-modal-trading-system/requirements.md

Requirements Document

Introduction

The Multi-Modal Trading System is an advanced algorithmic trading platform that combines Convolutional Neural Networks (CNN) and Reinforcement Learning (RL) models orchestrated by a decision-making module. The system processes multi-timeframe and multi-symbol market data (primarily ETH and BTC) to generate trading actions. The system is designed to adapt to current market conditions through continuous learning from past experiences, with the CNN module trained on historical data to predict pivot points and the RL module optimizing trading decisions based on these predictions and market data.

Requirements

Requirement 1: Data Collection and Processing

User Story: As a trader, I want the system to collect and process multi-timeframe and multi-symbol market data, so that the models have comprehensive market information for making accurate trading decisions.

Acceptance Criteria

0. NEVER USE GENERATED/SYNTHETIC DATA or mock implementations and UI. If somethings is not implemented yet, it should be obvious.
1. WHEN the system starts THEN it SHALL collect and process data for both ETH and BTC symbols.
2. WHEN collecting data THEN the system SHALL store the following for the primary symbol (ETH):
   • 300 seconds of raw tick data - price and COB snapshot for all prices +- 1% on fine reslolution buckets (1$ for ETH, 10$ for BTC)
   • 300 seconds of 1-second OHLCV data + 1s aggregated COB data
   • 300 bars of OHLCV + indicators for each timeframe (1s, 1m, 1h, 1d)
3. WHEN collecting data THEN the system SHALL store similar data for the reference symbol (BTC).
4. WHEN processing data THEN the system SHALL calculate standard technical indicators for all timeframes.
5. WHEN processing data THEN the system SHALL calculate pivot points for all timeframes according to the specified methodology.
6. WHEN new data arrives THEN the system SHALL update its data cache in real-time.
7. IF tick data is not available THEN the system SHALL substitute with the lowest available timeframe data.
8. WHEN normalizing data THEN the system SHALL normalize to the max and min of the highest timeframe to maintain relationships between different timeframes.
9. data is cached for longer (let's start with double the model inputs so 600 bars) to support performing backtesting when we know the current predictions outcomes so we can generate test cases.
10. In general all models have access to the whole data we collect in a central data provider implementation. only some are specialized. All models should also take as input the last output of evey other model (also cached in the data provider). there should be a room for adding more models in the other models data input so we can extend the system without having to loose existing models and trained W&B

Requirement 2: CNN Model Implementation

User Story: As a trader, I want the system to implement a CNN model that can identify patterns and predict pivot points across multiple timeframes, so that I can anticipate market direction changes.

Acceptance Criteria

1. WHEN the CNN model is initialized THEN it SHALL accept multi-timeframe and multi-symbol data as input.
2. WHEN processing input data THEN the CNN model SHALL output predicted pivot points for each timeframe (1s, 1m, 1h, 1d).
3. WHEN predicting pivot points THEN the CNN model SHALL provide both the predicted pivot point value and the timestamp when it is expected to occur.
4. WHEN a pivot point is detected THEN the system SHALL trigger a training round for the CNN model using historical data.
5. WHEN training the CNN model THEN the system SHALL use programmatically calculated pivot points from historical data as ground truth.
6. WHEN outputting predictions THEN the CNN model SHALL include a confidence score for each prediction.
7. WHEN calculating pivot points THEN the system SHALL implement both standard pivot points and the recursive Williams market structure pivot points as described.
8. WHEN processing data THEN the CNN model SHALL make available its hidden layer states for use by the RL model.

Requirement 3: RL Model Implementation

User Story: As a trader, I want the system to implement an RL model that can learn optimal trading strategies based on market data and CNN predictions, so that the system can adapt to changing market conditions.

Acceptance Criteria

1. WHEN the RL model is initialized THEN it SHALL accept market data, CNN predictions, and CNN hidden layer states as input.
2. WHEN processing input data THEN the RL model SHALL output trading action recommendations (buy/sell).
3. WHEN evaluating trading actions THEN the RL model SHALL learn from past experiences to adapt to the current market environment.
4. WHEN making decisions THEN the RL model SHALL consider the confidence levels of CNN predictions.
5. WHEN uncertain about market direction THEN the RL model SHALL learn to avoid entering positions.
6. WHEN training the RL model THEN the system SHALL use a reward function that incentivizes high risk/reward setups.
7. WHEN outputting trading actions THEN the RL model SHALL provide a confidence score for each action.
8. WHEN a trading action is executed THEN the system SHALL store the input data for future training.

Requirement 4: Orchestrator Implementation

User Story: As a trader, I want the system to implement an orchestrator that can make final trading decisions based on inputs from both CNN and RL models, so that the system can make more balanced and informed trading decisions.

Acceptance Criteria

1. WHEN the orchestrator is initialized THEN it SHALL accept inputs from both CNN and RL models.
2. WHEN processing model inputs THEN the orchestrator SHALL output final trading actions (buy/sell).
3. WHEN making decisions THEN the orchestrator SHALL consider the confidence levels of both CNN and RL models.
4. WHEN uncertain about market direction THEN the orchestrator SHALL learn to avoid entering positions.
5. WHEN implementing the orchestrator THEN the system SHALL use a Mixture of Experts (MoE) approach to allow for future model integration.
6. WHEN outputting trading actions THEN the orchestrator SHALL provide a confidence score for each action.
7. WHEN a trading action is executed THEN the system SHALL store the input data for future training.
8. WHEN implementing the orchestrator THEN the system SHALL allow for configurable thresholds for entering and exiting positions.

Requirement 5: Training Pipeline

User Story: As a developer, I want the system to implement a unified training pipeline for both CNN and RL models, so that the models can be trained efficiently and consistently.

Acceptance Criteria

1. WHEN training models THEN the system SHALL use a unified data provider to prepare data for all models.
2. WHEN a pivot point is detected THEN the system SHALL trigger a training round for the CNN model.
3. WHEN training the CNN model THEN the system SHALL use programmatically calculated pivot points from historical data as ground truth.
4. WHEN training the RL model THEN the system SHALL use a reward function that incentivizes high risk/reward setups.
5. WHEN training models THEN the system SHALL run the training process on the server without requiring the dashboard to be open.
6. WHEN training models THEN the system SHALL provide real-time feedback on training progress through the dashboard.
7. WHEN training models THEN the system SHALL store model checkpoints for future use.
8. WHEN training models THEN the system SHALL provide metrics on model performance.

Requirement 6: Dashboard Implementation

User Story: As a trader, I want the system to implement a comprehensive dashboard that displays real-time data, model predictions, and trading actions, so that I can monitor the system's performance and make informed decisions.

Acceptance Criteria

1. WHEN the dashboard is initialized THEN it SHALL display real-time market data for all symbols and timeframes.
2. WHEN displaying market data THEN the dashboard SHALL show OHLCV charts for all timeframes.
3. WHEN displaying model predictions THEN the dashboard SHALL show CNN pivot point predictions and confidence levels.
4. WHEN displaying trading actions THEN the dashboard SHALL show RL and orchestrator trading actions and confidence levels.
5. WHEN displaying system status THEN the dashboard SHALL show training progress and model performance metrics.
6. WHEN implementing controls THEN the dashboard SHALL provide start/stop toggles for all system processes.
7. WHEN implementing controls THEN the dashboard SHALL provide sliders to adjust buy/sell thresholds for the orchestrator.
8. WHEN implementing the dashboard THEN the system SHALL ensure all processes run on the server without requiring the dashboard to be open.

Requirement 7: Risk Management

User Story: As a trader, I want the system to implement risk management features, so that I can protect my capital from significant losses.

Acceptance Criteria

1. WHEN implementing risk management THEN the system SHALL provide configurable stop-loss functionality.
2. WHEN a stop-loss is triggered THEN the system SHALL automatically close the position.
3. WHEN implementing risk management THEN the system SHALL provide configurable position sizing based on risk parameters.
4. WHEN implementing risk management THEN the system SHALL provide configurable maximum drawdown limits.
5. WHEN maximum drawdown limits are reached THEN the system SHALL automatically stop trading.
6. WHEN implementing risk management THEN the system SHALL provide real-time risk metrics through the dashboard.
7. WHEN implementing risk management THEN the system SHALL allow for different risk parameters for different market conditions.
8. WHEN implementing risk management THEN the system SHALL provide alerts for high-risk situations.

Requirement 8: System Architecture and Integration

User Story: As a developer, I want the system to implement a clean and modular architecture, so that the system is easy to maintain and extend.

Acceptance Criteria

1. WHEN implementing the system architecture THEN the system SHALL use a unified data provider to prepare data for all models.
2. WHEN implementing the system architecture THEN the system SHALL use a modular approach to allow for easy extension.
3. WHEN implementing the system architecture THEN the system SHALL use a clean separation of concerns between data collection, model training, and trading execution.
4. WHEN implementing the system architecture THEN the system SHALL use a unified interface for all models.
5. WHEN implementing the system architecture THEN the system SHALL use a unified interface for all data providers.
6. WHEN implementing the system architecture THEN the system SHALL use a unified interface for all trading executors.
7. WHEN implementing the system architecture THEN the system SHALL use a unified interface for all risk management components.
8. WHEN implementing the system architecture THEN the system SHALL use a unified interface for all dashboard components.

Requirement 9: Model Inference Data Validation and Storage

User Story: As a trading system developer, I want to ensure that all model predictions include complete input data validation and persistent storage, so that I can verify models receive correct inputs and track their performance over time.

Acceptance Criteria

1. WHEN a model makes a prediction THEN the system SHALL validate that the input data contains complete OHLCV dataframes for all required timeframes
2. WHEN input data is incomplete THEN the system SHALL log the missing components and SHALL NOT proceed with prediction
3. WHEN input validation passes THEN the system SHALL store the complete input data package with the prediction in persistent storage
4. IF input data dimensions are incorrect THEN the system SHALL raise a validation error with specific details about expected vs actual dimensions
5. WHEN a model completes inference THEN the system SHALL store the complete input data, model outputs, confidence scores, and metadata in a persistent inference history
6. WHEN storing inference data THEN the system SHALL include timestamp, symbol, input features, prediction outputs, and model internal states
7. IF inference history storage fails THEN the system SHALL log the error and continue operation without breaking the prediction flow

Requirement 10: Inference-Training Feedback Loop

User Story: As a machine learning engineer, I want the system to automatically train models using their previous inference data compared to actual market outcomes, so that models continuously improve their accuracy through real-world feedback.

Acceptance Criteria

1. WHEN sufficient time has passed after a prediction THEN the system SHALL evaluate the prediction accuracy against actual price movements
2. WHEN a prediction outcome is determined THEN the system SHALL create a training example using the stored inference data and actual outcome
3. WHEN training examples are created THEN the system SHALL feed them back to the respective models for learning
4. IF the prediction was accurate THEN the system SHALL reinforce the model's decision pathway through positive training signals
5. IF the prediction was inaccurate THEN the system SHALL provide corrective training signals to help the model learn from mistakes
6. WHEN the system needs training data THEN it SHALL retrieve the last inference data for each model to compare predictions against actual market outcomes
7. WHEN models are trained on inference feedback THEN the system SHALL track and report accuracy improvements or degradations over time

Requirement 11: Inference History Management and Monitoring

User Story: As a system administrator, I want comprehensive logging and monitoring of the inference-training feedback loop with configurable retention policies, so that I can track model learning progress and manage storage efficiently.

Acceptance Criteria

1. WHEN inference data is stored THEN the system SHALL log the storage operation with data completeness metrics and validation results
2. WHEN training occurs based on previous inference THEN the system SHALL log the training outcome and model performance changes
3. WHEN the system detects data flow issues THEN it SHALL alert administrators with specific error details and suggested remediation
4. WHEN inference history reaches configured limits THEN the system SHALL archive or remove oldest entries based on retention policy
5. WHEN storing inference data THEN the system SHALL compress data to minimize storage footprint while maintaining accessibility
6. WHEN retrieving historical inference data THEN the system SHALL provide efficient query mechanisms by symbol, timeframe, and date range
7. IF storage space is critically low THEN the system SHALL prioritize keeping the most recent and most valuable training examples