# Neural Network Models Prediction Overview

## Executive Summary

This document provides a comprehensive overview of what each neural network model in the trading system predicts. All models receive standardized `BaseDataInput` (7,870 or 22,880 features) and produce `ModelOutput` with consistent structure.

---

## Model Categories

### 1. CNN Models (Convolutional Neural Networks)
**Purpose**: Pattern recognition from multi-timeframe OHLCV data

### 2. RL Models (Reinforcement Learning / DQN)
**Purpose**: Sequential decision-making with Q-learning

### 3. Transformer Models
**Purpose**: Long-range temporal dependencies and attention mechanisms

### 4. COB RL Models
**Purpose**: Order book microstructure analysis

---

## 1. StandardizedCNN

**Location**: `NN/models/standardized_cnn.py`  
**Input**: `BaseDataInput` (7,870 or 22,880 features)  
**Output**: `ModelOutput` with trading action predictions

### Predictions:

| Prediction | Type | Description |
|------------|------|-------------|
| **Action** | `str` | Primary trading action: `'BUY'`, `'SELL'`, or `'HOLD'` |
| **Action Probabilities** | `Dict[str, float]` | Probability for each action: `{'BUY': 0.65, 'SELL': 0.15, 'HOLD': 0.20}` |
| **Buy Probability** | `float` | Confidence in BUY action (0.0 to 1.0) |
| **Sell Probability** | `float` | Confidence in SELL action (0.0 to 1.0) |
| **Hold Probability** | `float` | Confidence in HOLD action (0.0 to 1.0) |
| **Confidence** | `float` | Overall confidence in prediction (0.0 to 1.0) |
| **Predicted Returns** | `List[float]` | Expected returns for 4 timeframes: `[1s, 1m, 1h, 1d]` |
| **Predicted Return 1s** | `float` | Expected return over next second |
| **Predicted Return 1m** | `float` | Expected return over next minute |
| **Predicted Return 1h** | `float` | Expected return over next hour |
| **Predicted Return 1d** | `float` | Expected return over next day |
| **Extrema Detected** | `str` | Market extrema detection: `'bottom'`, `'top'`, or `'neither'` |
| **Price Direction** | `str` | Price movement direction: `'up'`, `'down'`, or `'sideways'` |
| **Market Conditions** | `Dict[str, str]` | Market analysis: `{'volatility': 'high', 'risk': 'medium'}` |

### Output Structure:
```python
ModelOutput(
    model_type='cnn',
    model_name='standardized_cnn_v1',
    symbol='ETH/USDT',
    timestamp=datetime.now(),
    confidence=0.85,
    predictions={
        'action': 'BUY',
        'buy_probability': 0.65,
        'sell_probability': 0.15,
        'hold_probability': 0.20,
        'action_probabilities': [0.65, 0.15, 0.20],
        'predicted_returns': [0.001, 0.005, 0.02, 0.05],
        'predicted_return_1s': 0.001,
        'predicted_return_1m': 0.005,
        'predicted_return_1h': 0.02,
        'predicted_return_1d': 0.05,
        'extrema_detected': 'bottom',
        'price_direction': 'up',
        'market_conditions': {'volatility': 'high', 'risk': 'medium'}
    },
    hidden_states={...},  # For cross-model feeding
    metadata={...}
)
```

---

## 2. EnhancedCNN

**Location**: `NN/models/enhanced_cnn.py`  
**Input**: Feature vector (state tensor)  
**Output**: Q-values, extrema predictions, price direction, advanced predictions

### Predictions:

| Prediction | Type | Description |
|------------|------|-------------|
| **Q-Values** | `torch.Tensor` | Q-values for each action (used by DQN agent) |
| **Action** | `int` | Selected action index: `0=BUY`, `1=SELL` |
| **Action Probabilities** | `List[float]` | Probability distribution over actions |
| **Confidence** | `float` | Confidence in selected action (0.0 to 1.0) |
| **Price Direction** | `Dict[str, float]` | `{'direction': -1.0 to 1.0, 'confidence': 0.0 to 1.0}` |
| **Extrema Predictions** | `torch.Tensor` | Bottom/top/neither detection probabilities |
| **Volatility Prediction** | `str` | `'Very Low'`, `'Low'`, `'Medium'`, `'High'`, `'Very High'` |
| **Support/Resistance** | `str` | `'Strong Support'`, `'Weak Support'`, `'Neutral'`, `'Weak Resistance'`, `'Strong Resistance'`, `'Breakout'` |
| **Market Regime** | `str` | `'Bull Trend'`, `'Bear Trend'`, `'Sideways'`, `'Volatile Up'`, `'Volatile Down'`, `'Accumulation'`, `'Distribution'` |
| **Risk Assessment** | `str` | `'Low Risk'`, `'Medium Risk'`, `'High Risk'`, `'Extreme Risk'` |

### Output Structure:
```python
# Returns tuple: (action_idx, confidence, action_probs)
action_idx = 0  # BUY
confidence = 0.87
action_probs = [0.87, 0.13]  # [BUY, SELL]

# Additional predictions available via advanced_predictions:
{
    'volatility': 'High',
    'support_resistance': 'Strong Support',
    'market_regime': 'Bull Trend',
    'risk_assessment': 'Medium Risk'
}
```

---

## 3. DQN Agent (Deep Q-Network)

**Location**: `NN/models/dqn_agent.py`  
**Input**: State vector (from BaseDataInput feature vector)  
**Output**: Trading action with Q-value estimates

### Predictions:

| Prediction | Type | Description |
|------------|------|-------------|
| **Action** | `int` | Trading action: `0=BUY`, `1=SELL` (2-action system) |
| **Q-Values** | `torch.Tensor` | Expected future rewards for each action |
| **Confidence** | `float` | Confidence in selected action (0.0 to 1.0) |
| **Action Probabilities** | `List[float]` | Probability distribution: `[buy_prob, sell_prob]` |
| **Price Direction** | `Dict[str, float]` | Price movement prediction with confidence |
| **Market Regime** | `str` | Current market regime classification |
| **Volatility Prediction** | `float` | Predicted volatility level |

### Output Structure:
```python
# Returns action index
action = 0  # BUY action

# Additional context available:
{
    'action': 0,
    'confidence': 0.82,
    'action_probs': [0.82, 0.18],
    'q_values': [2.5, -1.2],  # Expected rewards
    'price_direction': {'direction': 0.7, 'confidence': 0.85},
    'market_regime': 'bull_trend',
    'volatility': 0.65
}
```

---

## 4. COB RL Model (MassiveRLNetwork)

**Location**: `NN/models/cob_rl_model.py`  
**Input**: COB (Consolidated Order Book) features  
**Output**: Price direction prediction based on order book microstructure

### Predictions:

| Prediction | Type | Description |
|------------|------|-------------|
| **Predicted Direction** | `int` | Price direction: `0=DOWN`, `1=SIDEWAYS`, `2=UP` |
| **Direction Text** | `str` | Human-readable: `'DOWN'`, `'SIDEWAYS'`, or `'UP'` |
| **Confidence** | `float` | Confidence in direction prediction (0.0 to 1.0) |
| **Value** | `float` | State value estimate (for RL) |
| **Probabilities** | `List[float]` | Probability distribution: `[down_prob, sideways_prob, up_prob]` |

### Output Structure:
```python
{
    'predicted_direction': 2,  # UP
    'direction_text': 'UP',
    'confidence': 0.78,
    'value': 1.5,
    'probabilities': [0.10, 0.12, 0.78]  # [DOWN, SIDEWAYS, UP]
}
```

---

## 5. EnhancedCNNModel (OHLCV Predictor)

**Location**: `NN/models/cnn_model.py`  
**Input**: Feature matrix (multi-timeframe OHLCV data)  
**Output**: Future OHLCV predictions and market regime

### Predictions:

| Prediction | Type | Description |
|------------|------|-------------|
| **OHLCV Prediction** | `torch.Tensor` | Predicted future OHLCV values: `[open, high, low, close, volume]` |
| **Confidence** | `float` | Confidence in OHLCV prediction (0.0 to 1.0) |
| **Market Regime** | `Dict[str, float]` | Regime probabilities: `{'bull': 0.6, 'bear': 0.2, 'sideways': 0.2}` |
| **Volatility** | `float` | Predicted volatility level |
| **Regime Stability** | `float` | Confidence in regime classification (0.0 to 1.0) |

### Output Structure:
```python
{
    'ohlcv': [2025.0, 2030.0, 2020.0, 2028.0, 1500.0],  # [O, H, L, C, V]
    'confidence': 0.85,
    'regime': {'bull': 0.6, 'bear': 0.2, 'sideways': 0.2},
    'volatility': 0.45,
    'regime_stability': 0.78
}
```

---

## 6. Advanced Trading Transformer

**Location**: `NN/models/advanced_transformer_trading.py`  
**Input**: Multi-modal data (price, COB, technical indicators, market data)  
**Output**: Comprehensive trading predictions with uncertainty estimation, next candle predictions, pivot point predictions, and trend-based actions

### Predictions:

| Prediction | Type | Description |
|------------|------|-------------|
| **Action Logits** | `torch.Tensor` | Raw logits for each action |
| **Action Probabilities** | `torch.Tensor` | Softmax probabilities: `[BUY, SELL, HOLD]` |
| **Confidence** | `float` | Prediction confidence (if enabled) |
| **Uncertainty Mean** | `float` | Mean uncertainty estimate (if enabled) |
| **Uncertainty Std** | `float` | Uncertainty standard deviation (if enabled) |
| **Price Prediction** | `torch.Tensor` | Predicted future price (auxiliary task) |
| **Volatility Prediction** | `torch.Tensor` | Predicted volatility |
| **Trend Strength** | `torch.Tensor` | Trend strength prediction |
| **Regime Probabilities** | `torch.Tensor` | Market regime probabilities over time |
| **Next Candles** | `Dict[str, torch.Tensor]` | **NEW**: OHLCV predictions for each timeframe (`1s`, `1m`, `1h`, `1d`) |
| **Next Pivots** | `Dict[str, Dict]` | **NEW**: Next pivot point predictions for L1-L5 levels with price, type (high/low), and confidence |
| **Trend Vector** | `Dict` | **NEW**: Trend vector calculated from pivot predictions (angle, steepness, direction) |
| **Trend-Based Action** | `Dict` | **NEW**: Trading action (BUY/SELL/HOLD) based on trend steepness and angle |

### Output Structure:
```python
{
    'action_logits': tensor([2.5, -1.2, 0.3]),
    'action_probs': tensor([0.82, 0.08, 0.10]),  # [BUY, SELL, HOLD]
    'confidence': 0.82,
    'uncertainty_mean': 0.15,
    'uncertainty_std': 0.05,
    'price_prediction': tensor([2028.5]),
    'volatility_prediction': tensor([0.45]),
    'trend_strength_prediction': tensor([0.75]),
    'regime_probs': tensor([...]),  # Temporal regime probabilities
    
    # NEW: Next candle predictions for each timeframe
    'next_candles': {
        '1s': tensor([2025.0, 2030.0, 2020.0, 2028.0, 1500.0]),  # [O, H, L, C, V]
        '1m': tensor([2028.0, 2035.0, 2025.0, 2032.0, 5000.0]),
        '1h': tensor([2030.0, 2040.0, 2028.0, 2038.0, 15000.0]),
        '1d': tensor([2035.0, 2050.0, 2030.0, 2045.0, 50000.0])
    },
    
    # NEW: Next pivot point predictions for L1-L5
    'next_pivots': {
        'L1': {
            'price': tensor([2020.0]),
            'type_prob_high': tensor([0.65]),
            'type_prob_low': tensor([0.35]),
            'pivot_type': tensor([0]),  # 0=high, 1=low
            'confidence': tensor([0.85])
        },
        'L2': {...},
        'L3': {...},
        'L4': {...},
        'L5': {...}
    },
    
    # NEW: Trend vector analysis
    'trend_vector': {
        'pivot_prices': tensor([2020.0, 2025.0, 2030.0, 2035.0, 2040.0]),  # L1-L5 prices
        'price_delta': tensor([20.0]),  # Price change from L1 to L5
        'time_delta': tensor([4.0]),  # Time change
        'calculated_angle': tensor([1.373]),  # Trend angle in radians (~78.7 degrees)
        'calculated_steepness': tensor([20.4]),  # Trend steepness magnitude
        'calculated_direction': tensor([1.0]),  # 1=up, -1=down
        'vector': tensor([[20.0, 4.0]])  # [price_delta, time_delta]
    },
    
    # NEW: Trend-based trading action
    'trend_based_action': {
        'logits': tensor([[2.5, 0.3, 0.8]]),  # [BUY, SELL, HOLD]
        'probabilities': tensor([[0.82, 0.08, 0.10]]),
        'action_idx': tensor([0]),  # 0=BUY, 1=SELL, 2=HOLD
        'trend_angle_degrees': tensor([78.7]),  # Trend angle in degrees
        'trend_steepness': tensor([20.4])
    },
    
    # Trend analysis (predicted)
    'trend_analysis': {
        'angle_radians': tensor([1.373]),
        'steepness': tensor([20.4]),
        'direction': tensor([0.95])  # -1 to 1 (down to up)
    }
}
```

### Helper Method: `extract_predictions()`

The model includes a helper method `extract_predictions()` that converts raw tensor outputs to user-friendly dictionaries:

```python
# Usage example
outputs = model.forward(price_data, cob_data, tech_data, market_data)
predictions = model.extract_predictions(outputs, denormalize_prices=denorm_func)

# predictions structure:
{
    'next_candles': {
        '1s': {'open': 2025.0, 'high': 2030.0, 'low': 2020.0, 'close': 2028.0, 'volume': 1500.0},
        '1m': {...},
        '1h': {...},
        '1d': {...}
    },
    'next_pivots': {
        'L1': {'price': 2020.0, 'type': 'high', 'type_prob_high': 0.65, 'type_prob_low': 0.35, 'confidence': 0.85},
        'L2': {...},
        'L3': {...},
        'L4': {...},
        'L5': {...}
    },
    'trend_vector': {
        'pivot_prices': [2020.0, 2025.0, 2030.0, 2035.0, 2040.0],  # L1-L5
        'angle_radians': 1.373,
        'angle_degrees': 78.7,
        'steepness': 20.4,
        'direction': 'up',
        'price_delta': 20.0
    },
    'trend_based_action': {
        'action': 'BUY',
        'action_idx': 0,
        'probabilities': {'BUY': 0.82, 'SELL': 0.08, 'HOLD': 0.10},
        'trend_angle_degrees': 78.7,
        'trend_steepness': 20.4
    }
}
```

### Trend-Based Trading Logic:

The transformer model now includes sophisticated trend-based trading logic:

1. **Pivot Prediction**: Predicts next pivot points for L1-L5 levels with price, type (high/low), and confidence
2. **Trend Vector Calculation**: Calculates trend vector from pivot predictions:
   - Trend angle: Angle of trend line in radians/degrees
   - Trend steepness: Magnitude of price change over time
   - Direction: Upward (>0), downward (<0), or sideways (≈0)
3. **Trade Action Logic**:
   - **Steep upward trend** (>45°): Suggests BUY action
   - **Steep downward trend** (<-45°): Suggests SELL action
   - **Shallow trend** (between -45° and 45°): Suggests HOLD action
   - Action confidence scales with trend steepness

This enables the model to generate trend lines from pivot predictions and make trading decisions based on the predicted price movement steepness and angle.

---

## 7. Orchestrator (Ensemble Decision Maker)

**Location**: `core/orchestrator.py`  
**Input**: Aggregates predictions from all models  
**Output**: Final trading decision with weighted confidence

### Predictions:

| Prediction | Type | Description |
|------------|------|-------------|
| **Final Action** | `str` | Ensemble decision: `'BUY'`, `'SELL'`, or `'HOLD'` |
| **Ensemble Confidence** | `float` | Weighted average confidence across models |
| **Model Contributions** | `Dict[str, float]` | Each model's contribution to final decision |
| **Consensus Score** | `float` | Agreement level among models (0.0 to 1.0) |
| **Risk Assessment** | `str` | Overall risk level: `'low'`, `'medium'`, `'high'` |

### Output Structure:
```python
Prediction(
    action='BUY',
    confidence=0.83,
    probabilities={'BUY': 0.83, 'SELL': 0.10, 'HOLD': 0.07},
    timeframe='1m',
    timestamp=datetime.now(),
    model_name='orchestrator_ensemble',
    metadata={
        'model_contributions': {
            'cnn': 0.35,
            'dqn': 0.40,
            'transformer': 0.25
        },
        'consensus_score': 0.78,
        'risk_assessment': 'medium'
    }
)
```

---

## Common Prediction Format

All models return standardized `ModelOutput`:

```python
@dataclass
class ModelOutput:
    model_type: str              # 'cnn', 'rl', 'transformer', 'orchestrator'
    model_name: str              # Specific model identifier
    symbol: str                  # Trading symbol (e.g., 'ETH/USDT')
    timestamp: datetime          # Prediction timestamp
    confidence: float            # Overall confidence (0.0 to 1.0)
    predictions: Dict[str, Any]  # Model-specific predictions
    hidden_states: Optional[Dict[str, Any]]  # For cross-model feeding
    metadata: Dict[str, Any]     # Additional information
```

---

## Prediction Summary Table

| Model | Primary Prediction | Secondary Predictions | Use Case |
|-------|-------------------|----------------------|----------|
| **StandardizedCNN** | BUY/SELL/HOLD action | Returns (1s/1m/1h/1d), extrema, direction | Pattern recognition, multi-timeframe analysis |
| **EnhancedCNN** | Q-values (BUY/SELL) | Volatility, regime, risk, support/resistance | RL base network, comprehensive market analysis |
| **DQN Agent** | BUY/SELL action | Q-values, price direction, regime | Sequential decision-making, position management |
| **COB RL** | Price direction (UP/DOWN/SIDEWAYS) | Confidence, state value | Order book microstructure analysis |
| **EnhancedCNNModel** | Future OHLCV values | Market regime, volatility | Price forecasting, regime detection |
| **Transformer** | BUY/SELL/HOLD with uncertainty | Price prediction, volatility, trend strength, **next candles (1s/1m/1h/1d), next pivots (L1-L5), trend vector, trend-based action** | Long-range dependencies, uncertainty-aware trading, **trend-based decision making** |
| **Orchestrator** | Final ensemble decision | Consensus score, model contributions | Combining all models for optimal decision |

---

## Key Takeaways

1. **All models predict trading actions** (BUY/SELL/HOLD) with confidence scores
2. **Specialized predictions** complement action predictions:
   - Price direction and returns
   - Market regime and volatility
   - Support/resistance levels
   - Risk assessment
   - Uncertainty estimation (Transformer)
3. **Cross-model feeding** enabled via `hidden_states` for ensemble learning
4. **Standardized output format** ensures consistent integration across models
5. **Orchestrator** combines all predictions for final decision with weighted confidence

---

## References

- **Model Interfaces**: `NN/models/model_interfaces.py`
- **Data Models**: `core/data_models.py`
- **Orchestrator**: `core/orchestrator.py`
- **Standardized CNN**: `NN/models/standardized_cnn.py`
- **DQN Agent**: `NN/models/dqn_agent.py`
- **Transformer**: `NN/models/advanced_transformer_trading.py`