hyper_agent_ai/

prompt_builder.rs

use hyper_market::market_data::PositionInfo;
use hyper_strategy::rule_engine::SignalSummary;
use hyper_strategy::strategy_config::Playbook;

// ---------------------------------------------------------------------------
// Types
// ---------------------------------------------------------------------------

/// All the inputs needed to build the user prompt for Claude.
#[derive(Debug, Clone)]
pub struct PromptParams {
    /// Current market regime (e.g., "bull", "bear", "high_vol").
    pub current_regime: String,
    /// How long the current regime has been active, in seconds.
    pub regime_duration_secs: u64,
    /// Whether the regime just changed this iteration.
    pub regime_changed: bool,
    /// Previous regime name (only meaningful when `regime_changed` is true).
    pub previous_regime: Option<String>,
    /// Formatted market data string (from `format_context_for_claude`).
    pub market_data: String,
    /// Formatted technical indicators string (from `format_technical_summary`).
    pub technical_summary: String,
    /// Signal summary from the rule engine.
    pub signal_summary: SignalSummary,
    /// Current open positions.
    pub positions: Vec<PositionInfo>,
    /// The active playbook for the current regime.
    pub playbook: Playbook,
    /// Optional funding rate info (pre-fetched for perpetual contracts).
    pub funding_rate: Option<FundingRateInfo>,
}

/// Pre-fetched funding rate information for a perpetual contract.
#[derive(Debug, Clone)]
pub struct FundingRateInfo {
    /// Current funding rate as a decimal (e.g., 0.0001 = 0.01%).
    pub rate: f64,
    /// Annualized funding rate as a decimal.
    pub annualized_rate: f64,
}

// ---------------------------------------------------------------------------
// System prompt
// ---------------------------------------------------------------------------

const BASE_SYSTEM_PROMPT: &str = "你是一個加密貨幣交易 AI 助手。";

/// Build the system prompt by combining the base prompt with the playbook's
/// custom system prompt.
pub fn build_system_prompt(playbook: &Playbook) -> String {
    if playbook.system_prompt.is_empty() {
        BASE_SYSTEM_PROMPT.to_string()
    } else {
        format!("{}\n{}", BASE_SYSTEM_PROMPT, playbook.system_prompt)
    }
}

// ---------------------------------------------------------------------------
// User prompt
// ---------------------------------------------------------------------------

/// Build the full user prompt from all available context.
pub fn build_user_prompt(params: &PromptParams) -> String {
    let mut sections: Vec<String> = Vec::with_capacity(8);

    // --- Regime section ---
    sections.push(build_regime_section(params));

    // --- Market data ---
    sections.push(format!("## 市場數據\n{}", params.market_data));

    // --- Technical indicators ---
    sections.push(format!("## 技術指標\n{}", params.technical_summary));

    // --- Signals ---
    sections.push(build_signals_section(params));

    // --- Funding rate ---
    if let Some(ref fr) = params.funding_rate {
        sections.push(build_funding_rate_section(fr));
    }

    // --- Positions ---
    sections.push(build_positions_section(&params.positions));

    // --- Risk constraints ---
    sections.push(build_risk_section(params));

    // --- Final instruction ---
    sections.push("請給出你的交易決策。".to_string());

    sections.join("\n\n")
}

// ---------------------------------------------------------------------------
// Section builders
// ---------------------------------------------------------------------------

fn build_regime_section(params: &PromptParams) -> String {
    let mut lines = Vec::new();
    lines.push("## 當前市場狀態".to_string());
    lines.push(format!(
        "Regime: {} (持續 {})",
        params.current_regime,
        format_duration(params.regime_duration_secs),
    ));

    if params.regime_changed {
        if let Some(ref prev) = params.previous_regime {
            lines.push(format!("!! 剛從 {} 切換，注意過渡期風險", prev,));
        }
    }

    if params.current_regime == "high_vol" {
        lines.push("!! 當前處於高波動 regime，請特別注意風控，減少倉位規模".to_string());
    }

    lines.join("\n")
}

fn build_signals_section(params: &PromptParams) -> String {
    let mut lines = Vec::new();
    lines.push(format!(
        "## 規則引擎訊號（{} playbook）",
        params.current_regime
    ));

    if params.signal_summary.triggered_signals.is_empty() {
        lines.push("目前沒有觸發任何規則訊號，請根據上述市場數據和技術指標自行判斷。".to_string());
    } else {
        for eval in &params.signal_summary.evaluations {
            let status = if eval.triggered {
                "TRIGGERED"
            } else {
                "not triggered"
            };
            lines.push(format!(
                "- {} {} {}: value={:.4} [{}]",
                eval.rule.indicator,
                eval.rule.condition,
                eval.rule.threshold,
                eval.current_value,
                status,
            ));
        }
        lines.push(format!(
            "\n觸發的訊號: {}",
            params.signal_summary.triggered_signals.join(", "),
        ));
    }

    lines.join("\n")
}

fn build_positions_section(positions: &[PositionInfo]) -> String {
    let mut lines = Vec::new();
    lines.push("## 當前持倉".to_string());

    if positions.is_empty() {
        lines.push("目前沒有持倉。".to_string());
    } else {
        for pos in positions {
            let mut entry = format!(
                "- {}: {} {:.6} @ ${:.2}, PnL: ${:.2}, Leverage: {:.1}x",
                pos.symbol, pos.side, pos.size, pos.entry_price, pos.unrealized_pnl, pos.leverage,
            );
            if let Some(liq) = pos.liquidation_price {
                entry.push_str(&format!(", Liq: ${:.2}", liq));
            }
            lines.push(entry);
        }
    }

    lines.join("\n")
}

fn build_funding_rate_section(fr: &FundingRateInfo) -> String {
    let mut lines = Vec::new();
    lines.push("## 資金費率 (Funding Rate)".to_string());
    lines.push(format!("- 當前費率: {:.4}%", fr.rate * 100.0));
    lines.push(format!("- 年化費率: {:.2}%", fr.annualized_rate * 100.0));
    if fr.rate > 0.0 {
        lines.push("- 方向: 多頭支付空頭（看多情緒偏高）".to_string());
    } else if fr.rate < 0.0 {
        lines.push("- 方向: 空頭支付多頭（看空情緒偏高）".to_string());
    } else {
        lines.push("- 方向: 中性".to_string());
    }
    if fr.rate.abs() > 0.0005 {
        lines.push("!! 資金費率偏高，持倉過夜成本顯著，請納入考量".to_string());
    }
    lines.join("\n")
}

fn build_risk_section(params: &PromptParams) -> String {
    let mut lines = Vec::new();
    lines.push(format!("## 風控限制（{} 設定）", params.current_regime));
    lines.push(format!("- 最大持倉: {}", params.playbook.max_position_size));
    if let Some(sl) = params.playbook.stop_loss_pct {
        lines.push(format!("- 止損: {}%", sl));
    }
    if let Some(tp) = params.playbook.take_profit_pct {
        lines.push(format!("- 止盈: {}%", tp));
    }

    lines.join("\n")
}

// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------

/// Format a duration in seconds into a human-readable string.
fn format_duration(secs: u64) -> String {
    if secs < 60 {
        format!("{}s", secs)
    } else if secs < 3600 {
        format!("{}m", secs / 60)
    } else if secs < 86400 {
        let h = secs / 3600;
        let m = (secs % 3600) / 60;
        if m == 0 {
            format!("{}h", h)
        } else {
            format!("{}h{}m", h, m)
        }
    } else {
        let d = secs / 86400;
        let h = (secs % 86400) / 3600;
        if h == 0 {
            format!("{}d", d)
        } else {
            format!("{}d{}h", d, h)
        }
    }
}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

#[cfg(test)]
mod tests {
    use super::*;
    use hyper_strategy::rule_engine::{RuleEvaluation, SignalSummary};
    use hyper_strategy::strategy_config::TaRule;

    fn sample_playbook() -> Playbook {
        Playbook {
            rules: vec![],
            entry_rules: vec![],
            exit_rules: vec![],
            system_prompt: "You are a bull-market trading agent.".to_string(),
            max_position_size: 1000.0,
            stop_loss_pct: Some(5.0),
            take_profit_pct: Some(10.0),
            timeout_secs: None,
            side: None,
        }
    }

    fn sample_playbook_no_prompt() -> Playbook {
        Playbook {
            rules: vec![],
            entry_rules: vec![],
            exit_rules: vec![],
            system_prompt: String::new(),
            max_position_size: 500.0,
            stop_loss_pct: None,
            take_profit_pct: None,
            timeout_secs: None,
            side: None,
        }
    }

    fn sample_signal_summary_with_triggers() -> SignalSummary {
        SignalSummary {
            symbol: "BTC-USD".to_string(),
            timestamp: 1700000000,
            current_regime: "bull".to_string(),
            regime_changed: false,
            evaluations: vec![
                RuleEvaluation {
                    rule: TaRule {
                        indicator: "RSI".to_string(),
                        params: vec![14.0],
                        condition: "gt".to_string(),
                        threshold: 70.0,
                        threshold_upper: None,
                        signal: "overbought".to_string(),
                        action: None,
                    },
                    current_value: 75.0,
                    triggered: true,
                    signal: "overbought".to_string(),
                },
                RuleEvaluation {
                    rule: TaRule {
                        indicator: "ADX".to_string(),
                        params: vec![14.0],
                        condition: "gt".to_string(),
                        threshold: 25.0,
                        threshold_upper: None,
                        signal: "strong_trend".to_string(),
                        action: None,
                    },
                    current_value: 20.0,
                    triggered: false,
                    signal: "strong_trend".to_string(),
                },
            ],
            triggered_signals: vec!["overbought".to_string()],
        }
    }

    fn sample_signal_summary_no_triggers() -> SignalSummary {
        SignalSummary {
            symbol: "BTC-USD".to_string(),
            timestamp: 1700000000,
            current_regime: "neutral".to_string(),
            regime_changed: false,
            evaluations: vec![],
            triggered_signals: vec![],
        }
    }

    fn sample_positions() -> Vec<PositionInfo> {
        vec![PositionInfo {
            symbol: "BTC-USD".to_string(),
            side: "long".to_string(),
            size: 0.5,
            entry_price: 60000.0,
            unrealized_pnl: 1500.0,
            leverage: 5.0,
            liquidation_price: Some(48000.0),
        }]
    }

    fn sample_prompt_params() -> PromptParams {
        PromptParams {
            current_regime: "bull".to_string(),
            regime_duration_secs: 7200,
            regime_changed: false,
            previous_regime: None,
            market_data: "Mark Price: $65000.00".to_string(),
            technical_summary: "Trend: SMA20=64000 EMA12=64500".to_string(),
            signal_summary: sample_signal_summary_with_triggers(),
            positions: sample_positions(),
            playbook: sample_playbook(),
            funding_rate: None,
        }
    }

    // --- build_system_prompt tests ---

    #[test]
    fn test_system_prompt_with_playbook() {
        let pb = sample_playbook();
        let result = build_system_prompt(&pb);
        assert!(result.contains(BASE_SYSTEM_PROMPT));
        assert!(result.contains("bull-market trading agent"));
    }

    #[test]
    fn test_system_prompt_without_playbook_prompt() {
        let pb = sample_playbook_no_prompt();
        let result = build_system_prompt(&pb);
        assert_eq!(result, BASE_SYSTEM_PROMPT);
    }

    #[test]
    fn test_system_prompt_base_always_present() {
        let pb = sample_playbook();
        let result = build_system_prompt(&pb);
        assert!(result.starts_with(BASE_SYSTEM_PROMPT));
    }

    // --- format_duration tests ---

    #[test]
    fn test_format_duration_seconds() {
        assert_eq!(format_duration(30), "30s");
        assert_eq!(format_duration(0), "0s");
        assert_eq!(format_duration(59), "59s");
    }

    #[test]
    fn test_format_duration_minutes() {
        assert_eq!(format_duration(60), "1m");
        assert_eq!(format_duration(120), "2m");
        assert_eq!(format_duration(3599), "59m");
    }

    #[test]
    fn test_format_duration_hours() {
        assert_eq!(format_duration(3600), "1h");
        assert_eq!(format_duration(7200), "2h");
        assert_eq!(format_duration(5400), "1h30m");
    }

    #[test]
    fn test_format_duration_days() {
        assert_eq!(format_duration(86400), "1d");
        assert_eq!(format_duration(90000), "1d1h");
    }

    // --- build_regime_section tests ---

    #[test]
    fn test_regime_section_normal() {
        let params = sample_prompt_params();
        let section = build_regime_section(&params);
        assert!(section.contains("bull"));
        assert!(section.contains("2h"));
        assert!(!section.contains("切換"));
    }

    #[test]
    fn test_regime_section_with_change() {
        let mut params = sample_prompt_params();
        params.regime_changed = true;
        params.previous_regime = Some("bear".to_string());
        let section = build_regime_section(&params);
        assert!(section.contains("剛從 bear 切換"));
        assert!(section.contains("過渡期風險"));
    }

    #[test]
    fn test_regime_section_high_vol_warning() {
        let mut params = sample_prompt_params();
        params.current_regime = "high_vol".to_string();
        let section = build_regime_section(&params);
        assert!(section.contains("高波動"));
        assert!(section.contains("風控"));
    }

    // --- build_signals_section tests ---

    #[test]
    fn test_signals_section_with_triggers() {
        let params = sample_prompt_params();
        let section = build_signals_section(&params);
        assert!(section.contains("bull playbook"));
        assert!(section.contains("TRIGGERED"));
        assert!(section.contains("overbought"));
        assert!(section.contains("not triggered"));
    }

    #[test]
    fn test_signals_section_no_triggers() {
        let mut params = sample_prompt_params();
        params.signal_summary = sample_signal_summary_no_triggers();
        let section = build_signals_section(&params);
        assert!(section.contains("沒有觸發任何規則訊號"));
        assert!(section.contains("自行判斷"));
    }

    // --- build_positions_section tests ---

    #[test]
    fn test_positions_section_with_positions() {
        let positions = sample_positions();
        let section = build_positions_section(&positions);
        assert!(section.contains("BTC-USD"));
        assert!(section.contains("long"));
        assert!(section.contains("60000"));
        assert!(section.contains("Liq: $48000"));
    }

    #[test]
    fn test_positions_section_empty() {
        let section = build_positions_section(&[]);
        assert!(section.contains("沒有持倉"));
    }

    #[test]
    fn test_positions_section_no_liquidation() {
        let positions = vec![PositionInfo {
            symbol: "ETH-USD".to_string(),
            side: "short".to_string(),
            size: 2.0,
            entry_price: 3000.0,
            unrealized_pnl: -50.0,
            leverage: 3.0,
            liquidation_price: None,
        }];
        let section = build_positions_section(&positions);
        assert!(section.contains("ETH-USD"));
        assert!(section.contains("short"));
        assert!(!section.contains("Liq:"));
    }

    // --- build_risk_section tests ---

    #[test]
    fn test_risk_section_full() {
        let params = sample_prompt_params();
        let section = build_risk_section(&params);
        assert!(section.contains("bull 設定"));
        assert!(section.contains("最大持倉: 1000"));
        assert!(section.contains("止損: 5%"));
        assert!(section.contains("止盈: 10%"));
    }

    #[test]
    fn test_risk_section_no_stop_loss_or_take_profit() {
        let mut params = sample_prompt_params();
        params.playbook = sample_playbook_no_prompt();
        let section = build_risk_section(&params);
        assert!(section.contains("最大持倉: 500"));
        assert!(!section.contains("止損"));
        assert!(!section.contains("止盈"));
    }

    // --- build_user_prompt integration tests ---

    #[test]
    fn test_user_prompt_contains_all_sections() {
        let params = sample_prompt_params();
        let prompt = build_user_prompt(&params);
        assert!(prompt.contains("## 當前市場狀態"));
        assert!(prompt.contains("## 市場數據"));
        assert!(prompt.contains("## 技術指標"));
        assert!(prompt.contains("## 規則引擎訊號"));
        assert!(prompt.contains("## 當前持倉"));
        assert!(prompt.contains("## 風控限制"));
        assert!(prompt.contains("請給出你的交易決策"));
    }

    #[test]
    fn test_user_prompt_regime_change_with_high_vol() {
        let mut params = sample_prompt_params();
        params.current_regime = "high_vol".to_string();
        params.regime_changed = true;
        params.previous_regime = Some("bull".to_string());
        let prompt = build_user_prompt(&params);
        assert!(prompt.contains("剛從 bull 切換"));
        assert!(prompt.contains("高波動"));
    }

    #[test]
    fn test_user_prompt_no_positions_no_signals() {
        let mut params = sample_prompt_params();
        params.positions = vec![];
        params.signal_summary = sample_signal_summary_no_triggers();
        let prompt = build_user_prompt(&params);
        assert!(prompt.contains("沒有持倉"));
        assert!(prompt.contains("沒有觸發任何規則訊號"));
    }

    #[test]
    fn test_user_prompt_market_data_included() {
        let params = sample_prompt_params();
        let prompt = build_user_prompt(&params);
        assert!(prompt.contains("Mark Price: $65000.00"));
    }

    #[test]
    fn test_user_prompt_technical_summary_included() {
        let params = sample_prompt_params();
        let prompt = build_user_prompt(&params);
        assert!(prompt.contains("SMA20=64000"));
    }

    // --- Edge-case tests ---

    #[test]
    fn test_regime_changed_without_previous() {
        let mut params = sample_prompt_params();
        params.regime_changed = true;
        params.previous_regime = None;
        let section = build_regime_section(&params);
        assert!(!section.contains("剛從"));
    }

    #[test]
    fn test_multiple_positions() {
        let positions = vec![
            PositionInfo {
                symbol: "BTC-USD".to_string(),
                side: "long".to_string(),
                size: 0.1,
                entry_price: 60000.0,
                unrealized_pnl: 200.0,
                leverage: 3.0,
                liquidation_price: Some(45000.0),
            },
            PositionInfo {
                symbol: "ETH-USD".to_string(),
                side: "short".to_string(),
                size: 1.0,
                entry_price: 3500.0,
                unrealized_pnl: -80.0,
                leverage: 5.0,
                liquidation_price: None,
            },
        ];
        let section = build_positions_section(&positions);
        assert!(section.contains("BTC-USD"));
        assert!(section.contains("ETH-USD"));
        assert!(section.contains("long"));
        assert!(section.contains("short"));
    }

    #[test]
    fn test_multiple_triggered_signals() {
        let mut params = sample_prompt_params();
        params.signal_summary.triggered_signals =
            vec!["overbought".to_string(), "strong_trend".to_string()];
        params.signal_summary.evaluations[1].triggered = true;
        let section = build_signals_section(&params);
        assert!(section.contains("overbought, strong_trend"));
    }

    // --- Funding rate section tests ---

    #[test]
    fn test_funding_rate_section_positive() {
        let fr = FundingRateInfo {
            rate: 0.0001,
            annualized_rate: 0.0001 * 3.0 * 365.0,
        };
        let section = build_funding_rate_section(&fr);
        assert!(section.contains("資金費率"));
        assert!(section.contains("0.0100%"));
        assert!(section.contains("多頭支付空頭"));
    }

    #[test]
    fn test_funding_rate_section_negative() {
        let fr = FundingRateInfo {
            rate: -0.0002,
            annualized_rate: -0.0002 * 3.0 * 365.0,
        };
        let section = build_funding_rate_section(&fr);
        assert!(section.contains("空頭支付多頭"));
    }

    #[test]
    fn test_funding_rate_section_zero() {
        let fr = FundingRateInfo {
            rate: 0.0,
            annualized_rate: 0.0,
        };
        let section = build_funding_rate_section(&fr);
        assert!(section.contains("中性"));
    }

    #[test]
    fn test_funding_rate_section_high_rate_warning() {
        let fr = FundingRateInfo {
            rate: 0.001,
            annualized_rate: 0.001 * 3.0 * 365.0,
        };
        let section = build_funding_rate_section(&fr);
        assert!(section.contains("費率偏高"));
    }

    #[test]
    fn test_funding_rate_section_normal_no_warning() {
        let fr = FundingRateInfo {
            rate: 0.0001,
            annualized_rate: 0.0001 * 3.0 * 365.0,
        };
        let section = build_funding_rate_section(&fr);
        assert!(!section.contains("費率偏高"));
    }

    #[test]
    fn test_user_prompt_with_funding_rate() {
        let mut params = sample_prompt_params();
        params.funding_rate = Some(FundingRateInfo {
            rate: 0.00015,
            annualized_rate: 0.00015 * 3.0 * 365.0,
        });
        let prompt = build_user_prompt(&params);
        assert!(prompt.contains("資金費率"));
        assert!(prompt.contains("0.0150%"));
    }

    #[test]
    fn test_user_prompt_without_funding_rate() {
        let params = sample_prompt_params();
        let prompt = build_user_prompt(&params);
        assert!(!prompt.contains("資金費率"));
    }
}