From 56b35bd3620dc2277061972f136611ed881a618f Mon Sep 17 00:00:00 2001
From: Dobromir Popov <dobromir.popov@gateway.one>
Date: Wed, 23 Jul 2025 13:48:31 +0300
Subject: [PATCH] more design

---
 .../multi-modal-trading-system/design.md      | 62 ++++++++++++++++++-
 1 file changed, 61 insertions(+), 1 deletion(-)

diff --git a/.kiro/specs/multi-modal-trading-system/design.md b/.kiro/specs/multi-modal-trading-system/design.md
index 66fc386..3498d6c 100644
--- a/.kiro/specs/multi-modal-trading-system/design.md
+++ b/.kiro/specs/multi-modal-trading-system/design.md
@@ -162,6 +162,18 @@ The Orchestrator subscribes to the Data Provider and manages multiple data strea
 - Maintains full base dataframe that stays current for any model requesting data
 - Handles data synchronization across different refresh rates
 
+**Enhanced 1s Timeseries Data Combination**:
+- Combines OHLCV data with COB (Cumulative Order Book) data for 1s timeframes
+- Implements price bucket aggregation: ±20 buckets around current price
+  - ETH: $1 bucket size (e.g., $3000-$3040 range = 40 buckets) when current price is 3020
+  - BTC: $10 bucket size (e.g., $50000-$50400 range = 40 buckets) when price is 50200
+- Creates unified base data input that includes:
+  - Traditional OHLCV metrics (Open, High, Low, Close, Volume)
+  - Order book depth and liquidity at each price level
+  - Bid/ask imbalances for the +-5 buckets with Moving Averages for 5,15, and 60s
+  - Volume-weighted average prices within buckets
+  - Order flow dynamics and market microstructure data
+
 ##### 2. Model Inference Coordination
 
 The Orchestrator coordinates inference across all models in the system:
@@ -185,14 +197,18 @@ The Orchestrator maintains a centralized store for all model outputs and manages
 **Output Storage**:
 - Stores CNN predictions, confidence scores, and hidden layer states
 - Stores RL action recommendations and value estimates
+- Stores outputs from all models in extensible format supporting future models (LSTM, Transformer, etc.)
 - Maintains historical output sequences for temporal analysis
 - Implements efficient retrieval mechanisms for real-time access
+- Uses standardized ModelOutput format for easy extension and cross-model compatibility
 
 **Cross-Model Feeding**:
 - Feeds CNN hidden layer states into RL model inputs
 - Provides CNN predictions as context for RL decision-making
+- Includes "last predictions" from each available model as part of base data input
 - Stores model outputs that become inputs for subsequent inference cycles
 - Manages circular dependencies and feedback loops between models
+- Supports dynamic model addition without requiring system architecture changes
 
 ##### 4. Training Pipeline Management
 
@@ -412,6 +428,20 @@ class TradingAction:
 
 ### Model Predictions
 
+```python
+@dataclass
+class ModelOutput:
+    """Extensible model output format supporting all model types"""
+    model_type: str  # 'cnn', 'rl', 'lstm', 'transformer', 'orchestrator'
+    model_name: str  # Specific model identifier
+    symbol: str
+    timestamp: datetime
+    confidence: float
+    predictions: Dict[str, Any]  # Model-specific predictions
+    hidden_states: Optional[Dict[str, Any]] = None  # For cross-model feeding
+    metadata: Dict[str, Any] = field(default_factory=dict)  # Additional info
+```
+
 ```python
 @dataclass
 class CNNPrediction:
@@ -432,7 +462,37 @@ class RLPrediction:
     expected_reward: float
 ```
 
-## Error Handling
+### Enhanced Base Data Input
+
+```python
+@dataclass
+class BaseDataInput:
+    """Unified base data input for all models"""
+    symbol: str
+    timestamp: datetime
+    ohlcv_data: Dict[str, OHLCVBar]  # Multi-timeframe OHLCV
+    cob_data: Optional[Dict[str, float]] = None  # COB buckets for 1s timeframe
+    technical_indicators: Dict[str, float] = field(default_factory=dict)
+    pivot_points: List[PivotPoint] = field(default_factory=list)
+    last_predictions: Dict[str, ModelOutput] = field(default_factory=dict)  # From all models
+    market_microstructure: Dict[str, Any] = field(default_factory=dict)  # Order flow, etc.
+```
+
+### COB Data Structure
+
+```python
+@dataclass
+class COBData:
+    """Cumulative Order Book data for price buckets"""
+    symbol: str
+    timestamp: datetime
+    current_price: float
+    bucket_size: float  # $1 for ETH, $10 for BTC
+    price_buckets: Dict[float, Dict[str, float]]  # price -> {bid_volume, ask_volume, etc.}
+    bid_ask_imbalance: Dict[float, float]  # price -> imbalance ratio
+    volume_weighted_prices: Dict[float, float]  # price -> VWAP within bucket
+    order_flow_metrics: Dict[str, float]  # Various order flow indicators
+```
 
 ### Data Collection Errors