engine/strategies/

kelly.rs

use super::Strategy;
use crate::types::{Observation, Order, OrderRequest, Side};
use std::collections::VecDeque;

/// Parameters for the Kelly criterion optimal strategy.
///
/// The strategy targets a growth-optimal (Kelly) inventory position
/// by biasing quotes toward accumulating q* = mu / (gamma * sigma^2).
#[derive(Clone, Debug)]
pub struct KellyParameters {
    /// Risk aversion parameter. Maps CARA to Kelly: gamma = 1 / q*_scale.
    pub gamma: f64,
    /// Order book liquidity decay parameter.
    pub k: f64,
    /// Base fill rate.
    pub a: f64,
    /// Trading horizon in seconds.
    pub t_horizon: f64,
    /// Base half-spread to use when q = q* and time_remaining = 0.
    /// Overrides the AS formula and allows tuning to the data source spread.
    pub base_half_spread: f64,
    /// Maximum absolute target inventory (clamp). Prevents extreme
    /// positions when drift estimates are noisy.
    pub max_position: f64,
    /// Minimum estimate standard deviation to avoid division by zero.
    pub min_sigma: f64,
}

/// Kelly criterion market-making strategy (CARA-based approximation).
///
/// **Approximation, not a rigorous solution.** This strategy uses the CARA
/// (exponential) utility ansatz from the Avellaneda-Stoikov model and shifts
/// the reservation price toward the Kelly target inventory q* = mu/(gamma*sigma^2).
/// It does not solve the true log-utility HJB. The Kelly target matches the
/// CARA-optimal position to first order, but the spread dynamics and
/// value-function curvature are CARA, not log-utility.
///
/// A rigorous Kelly HJB solver (log-utility without the CARA separation) is
/// planned for a future phase. See `reference/optimal_criteria.md`.
pub struct KellyStrategy {
    pub params: KellyParameters,
    price_history: VecDeque<f64>,
    window_size: usize,
    mu_est: f64,
    sigma_est: f64,
    start_time: Option<f64>,
    order_counter: u64,
}

impl KellyStrategy {
    pub fn new(params: KellyParameters) -> Self {
        Self {
            params,
            price_history: VecDeque::new(),
            window_size: 100,
            mu_est: 0.0,
            sigma_est: 0.0,
            start_time: None,
            order_counter: 0,
        }
    }

    pub fn with_window_size(mut self, window_size: usize) -> Self {
        self.window_size = window_size;
        self
    }

    fn update_estimates(&mut self, price: f64) {
        self.price_history.push_back(price);
        if self.price_history.len() > self.window_size {
            self.price_history.pop_front();
        }

        if self.price_history.len() < 3 {
            return;
        }

        let mut log_returns = Vec::with_capacity(self.price_history.len() - 1);
        for i in 0..self.price_history.len() - 1 {
            let r = (self.price_history[i + 1] / self.price_history[i]).ln();
            log_returns.push(r);
        }

        let mean = log_returns.iter().sum::<f64>() / log_returns.len() as f64;
        let variance = log_returns.iter().map(|r| (r - mean).powi(2)).sum::<f64>()
            / (log_returns.len() - 1) as f64;
        let sigma_step = variance.sqrt();

        let alpha = 0.1;
        self.mu_est = (1.0 - alpha) * self.mu_est + alpha * mean;
        self.sigma_est = (1.0 - alpha) * self.sigma_est + alpha * sigma_step;
    }

    fn target_inventory(&self) -> f64 {
        let sigma = self.sigma_est.max(self.params.min_sigma);
        let target = self.mu_est / (self.params.gamma * sigma * sigma);
        target.clamp(-self.params.max_position, self.params.max_position)
    }
}

impl Strategy for KellyStrategy {
    fn on_tick(&mut self, obs: &Observation, requests: &mut Vec<OrderRequest>) {
        if self.start_time.is_none() {
            self.start_time = Some(obs.timestamp);
        }

        let elapsed = obs.timestamp - self.start_time.unwrap();
        let time_remaining = (self.params.t_horizon - elapsed).max(0.0);

        if time_remaining <= 0.0 {
            requests.push(OrderRequest::CancelAll);
            return;
        }

        let mid = obs.mid_price();
        self.update_estimates(mid);

        let q = obs.portfolio.position;
        let q_target = self.target_inventory();
        let sigma = self.sigma_est.max(self.params.min_sigma);

        // Reservation price targeting q* instead of 0:
        //   r = mid - gamma * sigma^2 * (T - t) * (q - q*)
        let reservation_price =
            mid - self.params.gamma * sigma.powi(2) * time_remaining * (q - q_target);

        // Half-spread: inventory-risk term + configurable base spread.
        // When q == q* (target), the reservation-price adjustment vanishes
        // and the spread reverts to base_half_spread.
        let spread_adjustment = self.params.gamma * sigma.powi(2) * time_remaining;
        let half_spread = (spread_adjustment + 2.0 * self.params.base_half_spread) / 2.0;

        let bid_price = reservation_price - half_spread;
        let ask_price = reservation_price + half_spread;

        self.order_counter += 1;
        let bid_id = self.order_counter;
        self.order_counter += 1;
        let ask_id = self.order_counter;

        requests.push(OrderRequest::CancelAll);
        requests.push(OrderRequest::New(Order::new(
            bid_id,
            Side::Buy,
            bid_price,
            1.0,
        )));
        requests.push(OrderRequest::New(Order::new(
            ask_id,
            Side::Sell,
            ask_price,
            1.0,
        )));
    }

    fn as_any(&self) -> &dyn std::any::Any {
        self
    }
    fn as_any_mut(&mut self) -> &mut dyn std::any::Any {
        self
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::types::PortfolioSnapshot;

    fn make_obs(timestamp: f64, mid: f64, position: f64) -> Observation {
        Observation {
            timestamp,
            best_bid: mid - 0.05,
            best_ask: mid + 0.05,
            last_price: Some(mid),
            portfolio: PortfolioSnapshot {
                cash: 10000.0,
                position,
            },
            volatility: None,
            drift: None,
            parameters: None,
        }
    }

    fn default_params() -> KellyParameters {
        KellyParameters {
            gamma: 0.1,
            k: 1.5,
            a: 140.0,
            t_horizon: 1000.0,
            base_half_spread: 0.05,
            max_position: 10.0,
            min_sigma: 1e-6,
        }
    }

    #[test]
    fn test_happy_path_places_orders() {
        let mut strategy = KellyStrategy::new(default_params());
        let obs = make_obs(0.0, 100.0, 0.0);
        let mut requests = Vec::new();
        strategy.on_tick(&obs, &mut requests);

        assert_eq!(requests.len(), 3);
        assert!(matches!(requests[0], OrderRequest::CancelAll));
        // bid below ask
        let bid = match &requests[1] {
            OrderRequest::New(o) => {
                assert_eq!(o.side, Side::Buy);
                o.limit_price
            }
            _ => panic!("Expected New bid"),
        };
        let ask = match &requests[2] {
            OrderRequest::New(o) => {
                assert_eq!(o.side, Side::Sell);
                o.limit_price
            }
            _ => panic!("Expected New ask"),
        };
        assert!(bid < ask, "bid={bid} must be below ask={ask}");
    }

    #[test]
    fn test_zero_drift_gives_symmetric_quotes() {
        // Feed flat prices: no drift, no volatility
        let mut strategy = KellyStrategy::new(default_params());
        for i in 0..20 {
            let obs = make_obs(i as f64, 100.0, 0.0);
            let mut requests = Vec::new();
            strategy.on_tick(&obs, &mut requests);
        }

        // After estimation settles, mu ~ 0, sigma ~ 0 -> target = 0
        let target = strategy.target_inventory();
        assert!(target.abs() < 1e-6);
    }

    #[test]
    fn test_positive_drift_targets_long_position() {
        let mut strategy = KellyStrategy::new(default_params());
        // Rising prices: 100 * (1.001)^t
        for i in 0..100 {
            let price = 100.0 * 1.001_f64.powi(i);
            let obs = make_obs(i as f64, price, 0.0);
            let mut requests = Vec::new();
            strategy.on_tick(&obs, &mut requests);
        }

        // Positive drift -> target should be positive
        assert!(strategy.mu_est > 0.0, "Expected positive drift estimate");
        let target = strategy.target_inventory();
        assert!(target > 0.0, "Expected positive target, got {target}");
    }

    #[test]
    fn test_negative_drift_targets_short_position() {
        let mut strategy = KellyStrategy::new(default_params());
        // Falling prices: 100 * 0.999^t
        for i in 0..100 {
            let price = 100.0 * 0.999_f64.powi(i);
            let obs = make_obs(i as f64, price, 0.0);
            let mut requests = Vec::new();
            strategy.on_tick(&obs, &mut requests);
        }

        // Negative drift -> target should be negative
        assert!(strategy.mu_est < 0.0, "Expected negative drift estimate");
        let target = strategy.target_inventory();
        assert!(target < 0.0, "Expected negative target, got {target}");
    }

    #[test]
    fn test_target_clamped_to_max_position() {
        let mut strategy = KellyStrategy::new(default_params());
        // Very rapid rise to produce a large drift estimate
        for i in 0..100 {
            let price = 100.0 * 1.01_f64.powi(i);
            let obs = make_obs(i as f64, price, 0.0);
            let mut requests = Vec::new();
            strategy.on_tick(&obs, &mut requests);
        }

        let target = strategy.target_inventory();
        assert!(
            target.abs() <= strategy.params.max_position + 1e-9,
            "target={target} exceeds max_position={}",
            strategy.params.max_position
        );
    }

    #[test]
    fn test_cancels_all_when_horizon_elapsed() {
        let mut params = default_params();
        params.t_horizon = 0.0;
        let mut strategy = KellyStrategy::new(params);
        let obs = make_obs(0.0, 100.0, 0.0);
        let mut requests = Vec::new();
        strategy.on_tick(&obs, &mut requests);

        assert_eq!(requests.len(), 1);
        assert!(matches!(requests[0], OrderRequest::CancelAll));
    }
}