kestrel-chartkit 0.1.0

High-performance Rust technical analysis library for indicator math, market regime classification, composite scoring, and SVG visualization.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145

#[cfg(feature = "serde")]
use serde::{Deserialize, Serialize};

use crate::model::MarketRegime;

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(
    feature = "serde",
    derive(Serialize, Deserialize),
    serde(rename_all = "snake_case")
)]
pub enum VolatilityRegime {
    High,
    Normal,
    Low,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(
    feature = "serde",
    derive(Serialize, Deserialize),
    serde(rename_all = "snake_case")
)]
pub enum OpeningType {
    InsideValue,
    OutsideValue,
    Unknown,
}

/// Permission grade for one side of the playbook (plan Anhang F/Anhang G "Permission als
/// eigene, dem Playbook vorgelagerte Ebene"). A `Preferred`/`Neutral` state never *mandates*
/// a trade — see "Bias ≠ Signal" in the plan; it only says which scenarios are in scope.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(
    feature = "serde",
    derive(Serialize, Deserialize),
    serde(rename_all = "snake_case")
)]
pub enum PlaybookState {
    Preferred,
    Neutral,
    Suppressed,
    NotAllowed,
}

/// Leithierarchie state (plan Anhang F): `Market State → Expected Playbook → Location →
/// Trigger → Trade Geometry → Historical Edge`. `regime` reuses `model::MarketRegime`
/// (`BullishExpansion`/`BearishExpansion`/`Consolidation`/`Transition`) instead of a
/// second, competing Bull/Bear/Balance enum.
#[derive(Debug, Clone, Copy, PartialEq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub struct MarketStateOutput {
    pub regime: MarketRegime,
    pub volatility_regime: VolatilityRegime,
    /// 0.0..1.0, analog `trend_quality` in `indicator::swing_structure`.
    pub trend_stability: f64,
    /// 0.0..1.0
    pub balance_probability: f64,
    /// Opening Range size vs. the last ~20 sessions, 0.0..1.0.
    pub opening_range_percentile: f64,
    pub opening_type: OpeningType,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
pub struct ExpectedPlaybook {
    pub continuation_long: PlaybookState,
    pub continuation_short: PlaybookState,
    pub reversal_long: PlaybookState,
    pub reversal_short: PlaybookState,
}

/// Derive the Expected-Playbook permission grades from regime + trend stability. Follows
/// "Bias ≠ Signal" (plan Anhang F, achtes Video): a regime only limits which scenarios are
/// preferred/allowed, it never forces a trade — the lower-timeframe trigger still decides.
pub fn derive_playbook(regime: MarketRegime, trend_stability: f64) -> ExpectedPlaybook {
    let strong = trend_stability >= 0.5;
    match regime {
        MarketRegime::BullishExpansion => ExpectedPlaybook {
            continuation_long: if strong {
                PlaybookState::Preferred
            } else {
                PlaybookState::Neutral
            },
            continuation_short: PlaybookState::NotAllowed,
            reversal_long: PlaybookState::NotAllowed,
            reversal_short: PlaybookState::Suppressed,
        },
        MarketRegime::BearishExpansion => ExpectedPlaybook {
            continuation_long: PlaybookState::NotAllowed,
            continuation_short: if strong {
                PlaybookState::Preferred
            } else {
                PlaybookState::Neutral
            },
            reversal_long: PlaybookState::Suppressed,
            reversal_short: PlaybookState::NotAllowed,
        },
        MarketRegime::Consolidation => ExpectedPlaybook {
            continuation_long: PlaybookState::NotAllowed,
            continuation_short: PlaybookState::NotAllowed,
            reversal_long: PlaybookState::Preferred,
            reversal_short: PlaybookState::Preferred,
        },
        // "Strukturbruch ≠ Trendwechsel" (plan Anhang D, achtes Video): a broken trend is
        // neutral/transitional until re-acceptance confirms a new direction, so nothing gets
        // `Preferred` yet.
        MarketRegime::Transition => ExpectedPlaybook {
            continuation_long: PlaybookState::Suppressed,
            continuation_short: PlaybookState::Suppressed,
            reversal_long: PlaybookState::Neutral,
            reversal_short: PlaybookState::Neutral,
        },
    }
}

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

    #[test]
    fn strong_bull_regime_prefers_continuation_long_only() {
        let pb = derive_playbook(MarketRegime::BullishExpansion, 0.8);
        assert_eq!(pb.continuation_long, PlaybookState::Preferred);
        assert_eq!(pb.continuation_short, PlaybookState::NotAllowed);
        assert_eq!(pb.reversal_long, PlaybookState::NotAllowed);
    }

    #[test]
    fn balance_regime_prefers_both_reversal_sides() {
        let pb = derive_playbook(MarketRegime::Consolidation, 0.9);
        assert_eq!(pb.reversal_long, PlaybookState::Preferred);
        assert_eq!(pb.reversal_short, PlaybookState::Preferred);
        assert_eq!(pb.continuation_long, PlaybookState::NotAllowed);
    }

    #[test]
    fn transition_regime_never_prefers_anything() {
        let pb = derive_playbook(MarketRegime::Transition, 1.0);
        assert_ne!(pb.continuation_long, PlaybookState::Preferred);
        assert_ne!(pb.continuation_short, PlaybookState::Preferred);
        assert_ne!(pb.reversal_long, PlaybookState::Preferred);
        assert_ne!(pb.reversal_short, PlaybookState::Preferred);
    }
}