foxhunt/TRADING_AGENT_FEATURE_CODE_REFERENCES.md

Trading Agent Service: Feature Usage - Code References

Date: 2025-10-17
Purpose: Exact line numbers and code snippets for feature integration

---

1. Asset Scoring - assets.rs (Lines 13-299)

AssetScore Structure Definition (Lines 13-40)

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct AssetScore {
    /// Trading symbol
    pub symbol: String,

    /// ML model prediction score (0.0-1.0)
    /// Weight: 40%
    pub ml_score: f64,

    /// Momentum factor score (0.0-1.0)
    /// Weight: 30%
    pub momentum_score: f64,

    /// Value factor score (0.0-1.0)
    /// Weight: 20%
    pub value_score: f64,

    /// Quality/liquidity factor score (0.0-1.0)
    /// Weight: 10%
    pub quality_score: f64,

    /// Final composite score (weighted average)
    pub composite_score: f64,

    /// Per-model prediction scores (DQN, PPO, MAMBA2, TFT)
    pub model_scores: HashMap<String, f64>,
}

Composite Score Calculation (Lines 49-78)

/// Create a new asset score with calculated composite
pub fn new(
    symbol: String,
    ml_score: f64,
    momentum_score: f64,
    value_score: f64,
    quality_score: f64,
) -> Self {
    // Clamp all scores to valid range
    let ml = Self::clamp_score(ml_score);
    let momentum = Self::clamp_score(momentum_score);
    let value = Self::clamp_score(value_score);
    let quality = Self::clamp_score(quality_score);

    // Calculate weighted composite score
    let composite = ml * Self::ML_WEIGHT           // 0.40
        + momentum * Self::MOMENTUM_WEIGHT         // 0.30
        + value * Self::VALUE_WEIGHT               // 0.20
        + quality * Self::LIQUIDITY_WEIGHT;        // 0.10

    Self {
        symbol,
        ml_score: ml,
        momentum_score: momentum,
        value_score: value,
        quality_score: quality,
        composite_score: composite,
        model_scores: HashMap::new(),
    }
}

Momentum Score Calculation (Lines 214-238)

/// Calculate momentum score from price data
pub fn calculate_momentum_score(returns: &[f64], lookback_periods: usize) -> f64 {
    if returns.is_empty() || lookback_periods == 0 {
        return 0.5; // Neutral
    }

    let relevant_returns: Vec<f64> = returns
        .iter()
        .rev()
        .take(lookback_periods)
        .copied()
        .collect();

    if relevant_returns.is_empty() {
        return 0.5;
    }

    // Calculate cumulative return
    let cumulative_return: f64 = relevant_returns.iter().product();

    // Normalize to 0.0-1.0 range using sigmoid
    // Positive returns -> score > 0.5, negative returns -> score < 0.5
    let score = 1.0 / (1.0 + (-cumulative_return).exp());

    score.clamp(0.0, 1.0)
}

Value Score Calculation (Lines 241-262)

/// Calculate value score from fundamental metrics
pub fn calculate_value_score(
    price: f64,
    fair_value: f64,
    volatility: f64,
) -> f64 {
    if price <= 0.0 || fair_value <= 0.0 {
        return 0.5; // Neutral
    }

    // Calculate discount/premium
    let discount = (fair_value - price) / fair_value;

    // Adjust for volatility (higher vol = less confident in valuation)
    let volatility_adj = 1.0 - (volatility / 2.0).min(0.5);

    // Normalize to 0.0-1.0 range
    // Discount (undervalued) -> score > 0.5
    // Premium (overvalued) -> score < 0.5
    let raw_score = 0.5 + (discount * volatility_adj);

    raw_score.clamp(0.0, 1.0)
}

Liquidity/Quality Score Calculation (Lines 265-299)

/// Calculate liquidity/quality score
pub fn calculate_liquidity_score(
    avg_volume: f64,
    spread_bps: f64,
    market_cap: Option<f64>,
) -> f64 {
    // Volume score (higher is better)
    let volume_score = if avg_volume > 0.0 {
        (avg_volume.ln() / 20.0).min(1.0) // Log scale, cap at 1.0
    } else {
        0.0
    };

    // Spread score (lower spread is better)
    let spread_score = if spread_bps > 0.0 {
        (1.0 / (1.0 + spread_bps)).min(1.0)
    } else {
        0.0
    };

    // Market cap score (if available)
    let cap_score = market_cap
        .map(|cap| {
            if cap > 0.0 {
                (cap.ln() / 30.0).min(1.0) // Log scale
            } else {
                0.0
            }
        })
        .unwrap_or(0.5); // Neutral if not available

    // Weighted average: volume 40%, spread 40%, cap 20%
    let score = volume_score * 0.40 + spread_score * 0.40 + cap_score * 0.20;

    score.clamp(0.0, 1.0)
}

---

2. ML Feature Extraction - common/src/ml_strategy.rs (Lines 64-900+)

MLFeatureExtractor Structure (Lines 65-129)

/// Feature extraction for ML models
#[derive(Debug, Clone)]
pub struct MLFeatureExtractor {
    /// Lookback window for features
    pub lookback_periods: usize,
    /// Price history buffer
    price_history: Vec<f64>,
    /// Volume history buffer
    volume_history: Vec<f64>,
    /// High/low price history for oscillators (simulated from close price)
    high_low_history: Vec<(f64, f64)>,
    /// EMA-9 state
    ema_9: Option<f64>,
    /// EMA-21 state
    ema_21: Option<f64>,
    /// EMA-50 state
    ema_50: Option<f64>,
    /// On-Balance Volume (OBV) cumulative value
    obv: f64,
    /// VWAP cumulative price*volume sum
    vwap_pv_sum: f64,
    /// VWAP cumulative volume sum
    vwap_volume_sum: f64,
    /// RSI average gain (14-period EMA)
    rsi_avg_gain: Option<f64>,
    /// RSI average loss (14-period EMA)
    rsi_avg_loss: Option<f64>,
    /// MACD EMA-12
    macd_ema_12: Option<f64>,
    /// MACD EMA-26
    macd_ema_26: Option<f64>,
    /// MACD Signal EMA-9
    macd_signal: Option<f64>,
    /// Stochastic %K history for %D calculation
    stoch_k_history: Vec<f64>,
    /// ADX (Average Directional Index) for trend strength
    adx: Option<f64>,
    /// +DI (Positive Directional Indicator)
    plus_di: Option<f64>,
    /// -DI (Negative Directional Indicator)
    minus_di: Option<f64>,
    /// Smoothed +DM (for incremental ADX calculation)
    plus_dm_smooth: Option<f64>,
    /// Smoothed -DM (for incremental ADX calculation)
    minus_dm_smooth: Option<f64>,
    /// ATR (Average True Range) for ADX calculation
    atr: Option<f64>,
    /// Rolling volatility history for percentile calculation
    volatility_history: Vec<f64>,
    /// Rolling volume history for percentile calculation (separate from main volume buffer)
    volume_percentile_buffer: Vec<f64>,
    /// Return history for autocorrelation calculation
    returns_history: Vec<f64>,
    /// Momentum ROC(5) history for acceleration calculation
    momentum_roc_5_history: Vec<f64>,
    /// Momentum ROC(10) history for acceleration calculation
    momentum_roc_10_history: Vec<f64>,
    /// Acceleration history for jerk calculation
    acceleration_history: Vec<f64>,
    /// Price highs for divergence detection (last 20 periods)
    price_highs: Vec<f64>,
    /// Momentum highs for divergence detection (last 20 periods)
    momentum_highs: Vec<f64>,
    /// Historical momentum values for regime classification (last 100 periods)
    momentum_regime_history: Vec<f64>,
}

Feature Extraction Main Function (Lines 170-220)

/// Extract features from market data
pub fn extract_features(&mut self, price: f64, volume: f64, timestamp: DateTime<Utc>) -> Vec<f64> {
    // Update price and volume history
    self.price_history.push(price);
    self.volume_history.push(volume);
    
    // Simulate high/low with 0.1% spread (typical intraday range)
    self.high_low_history.push((price * 1.001, price * 0.999));

    // Keep only the required lookback periods
    if self.price_history.len() > self.lookback_periods {
        self.price_history.remove(0);
    }
    if self.volume_history.len() > self.lookback_periods {
        self.volume_history.remove(0);
    }
    if self.high_low_history.len() > self.lookback_periods {
        self.high_low_history.remove(0);
    }

    // Calculate EMAs with exponential smoothing
    // EMA_today = (Price_today * α) + (EMA_yesterday * (1 - α))
    // α = 2 / (period + 1)
    
    let alpha_9 = 2.0 / (9.0 + 1.0); // α = 0.2
    let alpha_21 = 2.0 / (21.0 + 1.0); // α ≈ 0.0909
    let alpha_50 = 2.0 / (50.0 + 1.0); // α ≈ 0.0392
    
    // Update EMA-9
    self.ema_9 = Some(match self.ema_9 {
        Some(prev_ema) => price * alpha_9 + prev_ema * (1.0 - alpha_9),
        None => price, // Initialize with first price
    });
    
    // Update EMA-21
    self.ema_21 = Some(match self.ema_21 {
        Some(prev_ema) => price * alpha_21 + prev_ema * (1.0 - alpha_21),
        None => price, // Initialize with first price
    });
    
    // Update EMA-50
    self.ema_50 = Some(match self.ema_50 {
        Some(prev_ema) => price * alpha_50 + prev_ema * (1.0 - alpha_50),
        None => price, // Initialize with first price
    });

Price Features (Indices 0-2, Lines 220-262)

    let mut features = Vec::new();

    if self.price_history.len() >= 2 {
        // [INDEX 0] Price momentum (returns)
        let current_price = self.price_history.last().copied().unwrap_or(0.0);
        let prev_price = self.price_history.get(self.price_history.len() - 2).copied().unwrap_or(current_price);
        let price_return = if prev_price != 0.0 {
            (current_price - prev_price) / prev_price
        } else {
            0.0
        };
        features.push(price_return);

        // [INDEX 1] Short-term moving average
        if self.price_history.len() >= 5 {
            let short_ma: f64 = self.price_history.iter().rev().take(5).sum::<f64>() / 5.0;
            let ma_ratio = if short_ma != 0.0 { current_price / short_ma - 1.0 } else { 0.0 };
            features.push(ma_ratio);
        } else {
            features.push(0.0);
        }

        // [INDEX 2] Price volatility (rolling standard deviation)
        if self.price_history.len() >= 10 {
            let recent_returns: Vec<f64> = self.price_history
                .windows(2)
                .rev()
                .take(9)
                .map(|w| (w[1] - w[0]) / w[0])
                .collect();

            let mean_return = recent_returns.iter().sum::<f64>() / recent_returns.len() as f64;
            let variance = recent_returns.iter()
                .map(|&r| (r - mean_return).powi(2))
                .sum::<f64>() / recent_returns.len() as f64;
            let volatility = variance.sqrt();
            features.push(volatility);
        } else {
            features.push(0.0);
        }
    } else {
        features.extend_from_slice(&[0.0, 0.0, 0.0]);
    }

Volume Features (Indices 3-4, Lines 264-285)

    // Volume features
    if self.volume_history.len() >= 2 {
        let current_volume = self.volume_history.last().copied().unwrap_or(0.0);
        let prev_volume = self.volume_history.get(self.volume_history.len() - 2).copied().unwrap_or(current_volume);
        
        // [INDEX 3] Volume ratio
        let volume_ratio = if prev_volume != 0.0 {
            current_volume / prev_volume - 1.0
        } else {
            0.0
        };
        features.push(volume_ratio);

        // [INDEX 4] Volume moving average
        if self.volume_history.len() >= 5 {
            let volume_ma = self.volume_history.iter().rev().take(5).sum::<f64>() / 5.0;
            let volume_ma_ratio = if volume_ma != 0.0 { current_volume / volume_ma - 1.0 } else { 0.0 };
            features.push(volume_ma_ratio);
        } else {
            features.push(0.0);
        }
    } else {
        features.extend_from_slice(&[0.0, 0.0]);
    }

Time Features (Indices 5-6, Lines 287-291)

    // Add time-based features
    // [INDEX 5] Hour (normalized)
    let hour = timestamp.hour() as f64 / 24.0; // Normalized hour
    features.push(hour);
    
    // [INDEX 6] Day of week (normalized)
    let day_of_week = timestamp.weekday().num_days_from_monday() as f64 / 6.0; // Normalized day
    features.push(day_of_week);

ADX Feature (Index 18, Lines 600+)

    // [INDEX 18] ADX (14-period Average Directional Index)
    // Formula: Wilder's smoothing of DX, measures trend strength

Bollinger Bands Feature (Index 19, Lines 660+)

    // [INDEX 19] Bollinger Bands Position (20-period)
    // Formula: (price - middle) / (upper - lower)
    // Range: [-1, 1] (clamped)

Technical Indicators (Indices 20-25, Lines 700+)

    // [INDEX 20-21] Stochastic %K and %D
    // [INDEX 22] CCI (20-period)
    // [INDEX 23] RSI (14-period)
    // [INDEX 24-25] MACD and MACD Signal

---

3. Asset Selection Service - service.rs (Lines 223-240)

Current Placeholder Implementation

async fn select_assets(
    &self,
    _request: Request<SelectAssetsRequest>,
) -> Result<Response<SelectAssetsResponse>, Status> {
    info!("SelectAssets called (placeholder)");

    Ok(Response::new(SelectAssetsResponse {
        assets: vec![],
        metrics: Some(SelectionMetrics {
            assets_evaluated: 0,
            assets_selected: 0,
            avg_composite_score: 0.0,
            min_score: 0.0,
            max_score: 0.0,
        }),
        timestamp: chrono::Utc::now().timestamp_nanos_opt().unwrap_or(0),
    }))
}

Status: Returns empty vector (no feature extraction, no scoring)

---

4. Portfolio Allocation - allocation.rs (Lines 1-6)

//! Portfolio Allocation Logic
//!
//! Determines position sizes and weights across selected assets.

// Stub implementation - to be filled in future agents

Status: Complete stub, no implementation

---

5. Shared ML Strategy - common/src/ml_strategy.rs (Lines 24-62)

MLPrediction Structure

/// ML prediction result
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct MLPrediction {
    /// Model identifier
    pub model_id: String,
    /// Prediction value (0.0-1.0)
    pub prediction_value: f64,
    /// Confidence score (0.0-1.0)
    pub confidence: f64,
    /// Features used for prediction
    pub features: Vec<f64>,
    /// Prediction timestamp
    pub timestamp: DateTime<Utc>,
    /// Inference latency in microseconds
    pub inference_latency_us: u64,
}

---

6. Wave A Technical Indicators - 26-Dimensional Feature Vector

Complete Feature Index Map (Lines 170-900+)

Index	Feature	Location	Type	Range
0	price_return	Line 231	Price	±0.05
1	short_ma_ratio	Line 237	Price	±0.02
2	volatility	Line 256	Price	[0, ∞)
3	volume_ratio	Line 273	Volume	±2.0
4	volume_ma_ratio	Line 278	Volume	±1.0
5	hour	Line 290	Time	[0, 1]
6	day_of_week	Line 291	Time	[0, 1]
7	williams_r	Line 311	Tech	[-1, 1]
8	roc	Line 330	Tech	[-1, 1]
9	ultimate_oscillator	Line 385	Tech	[-1, 1]
10	obv	Line 408	Tech	[-1, 1]
11	mfi	Line 455	Tech	[-1, 1]
12	vwap_ratio	Line 485	Tech	[-1, 1]
13	ema_9_norm	Line 494	Tech	[-1, 1]
14	ema_21_norm	Line 499	Tech	[-1, 1]
15	ema_50_norm	Line 504	Tech	[-1, 1]
16	ema_9_21_cross	Line 510	Tech	{-1, +1}
17	ema_21_50_cross	Line 511	Tech	{-1, +1}
18	adx	Line 610	Tech	[0, 1]
19	bollinger_position	Line 664	Tech	[-1, 1]
20	stochastic_k	Line 706	Tech	[0, 1]
21	stochastic_d	Line 718	Tech	[0, 1]
22	cci	Line 785	Tech	[-1, 1]
23	rsi	Line 829	Tech	[0, 1]
24	macd	Line 881	Tech	[-1, 1]
25	macd_signal	Line 887	Tech	[-1, 1]

---

7. Production ML Features - ml/src/features/extraction.rs

256-Dimensional Feature Vector

/// Feature extraction result: 256-dimensional feature vector per bar
pub type FeatureVector = [f64; 256];

/// Feature Breakdown:
/// - Features 0-4: OHLCV (5)
/// - Features 5-14: Technical indicators (10)
/// - Features 15-74: Price patterns (60)
/// - Features 75-114: Volume patterns (40)
/// - Features 115-164: Microstructure proxies (50)
///   - [115]: Roll Measure
///   - [116]: Amihud Illiquidity
/// - Features 165-174: Time-based (10)
/// - Features 175-255: Statistical (81)

---

Summary: Feature Flow Disconnection

Current Feature Sources (NOT connected to Trading Agent):

1. common/src/ml_strategy.rs:

   • Function: MLFeatureExtractor::extract_features()
   • Output: Vec with 26 elements
   • Usage: Model inference (DQN/PPO/MAMBA2/TFT)
   • NOT used: Asset selection scoring

2. ml/src/features/extraction.rs:

   • Function: extract_ml_features()
   • Output: Vec with 256 dimensions
   • Usage: Model training only
   • NOT used: Asset selection or allocation

Current Asset Scoring (Feature-blind):

1. services/trading_agent_service/src/assets.rs:
   • Uses pre-calculated inputs (returns, price, volume, market_cap)
   • NOT extracting features from common::ml_strategy
   • NOT extracting features from ml::features

Integration Needed:

• Connect select_assets() to MLFeatureExtractor
• Map 26-dim features → composite scores
• Implement portfolio allocation algorithms