rangebar 11.6.1__tar.gz → 12.0.0__tar.gz

{rangebar-11.6.1 → rangebar-12.0.0}/.mise.toml

@@ -1,4 +1,40 @@
 [env]
+# =============================================================================
+# SSoT: Minimum Thresholds by Asset Class (Issue #62)
+# =============================================================================
+# These are the canonical values for threshold validation. Change here, affects
+# all entry points (Python API + Rust core).
+#
+# Values are in decimal basis points (dbps): 1000 dbps = 1%
+# Research: docs/research/2026-02-03-cfm-optimal-threshold-gemini-3-pro.md
+#
+# Resolution order (highest priority first):
+#   1. Per-symbol: RANGEBAR_MIN_THRESHOLD_<SYMBOL>
+#   2. Asset-class: RANGEBAR_<ASSET_CLASS>_MIN_THRESHOLD
+#   3. Fallback defaults in code (with warning)
+
+# Crypto: Default minimum (1% - cannot overcome trading costs below this)
+# CFM formula validates this as "conservative guardrails"
+RANGEBAR_CRYPTO_MIN_THRESHOLD = "1000"
+
+# Forex: Default minimum (tighter spreads allow lower)
+RANGEBAR_FOREX_MIN_THRESHOLD = "50"
+
+# Equities: Default minimum
+RANGEBAR_EQUITIES_MIN_THRESHOLD = "100"
+
+# Unknown: Fallback (no enforcement)
+RANGEBAR_UNKNOWN_MIN_THRESHOLD = "1"
+
+# =============================================================================
+# Per-Symbol Overrides (Optional - uncomment to enable)
+# =============================================================================
+# Override specific symbols when research justifies different thresholds:
+#
+# RANGEBAR_MIN_THRESHOLD_BTCUSDT = "1500"   # BTC needs higher threshold
+# RANGEBAR_MIN_THRESHOLD_XAUUSD = "200"     # Gold needs higher than forex
+# RANGEBAR_MIN_THRESHOLD_EURUSD = "25"      # EUR/USD can go lower
+
 # =============================================================================
 # GitHub Account Isolation (CRITICAL for multi-account setups)
 # =============================================================================

{rangebar-11.6.1 → rangebar-12.0.0}/CHANGELOG.md

@@ -1,3 +1,35 @@
+# [12.0.0](https://github.com/terrylica/rangebar-py/compare/v11.7.0...v12.0.0) (2026-02-03)
+
+
+### Features
+
+* **threshold:** enforce configurable minimum threshold for crypto (Issue [#64](https://github.com/terrylica/rangebar-py/issues/64)) ([4030c7d](https://github.com/terrylica/rangebar-py/commit/4030c7dc9e6789a4c9ae11f21c03261dc56e6c95))
+
+
+### BREAKING CHANGES
+
+* **threshold:** ThresholdError raised for crypto symbols with threshold < 1000 dbps
+
+- Add threshold.py module with hierarchical SSoT configuration
+- Per-symbol override: RANGEBAR_MIN_THRESHOLD_<SYMBOL>
+- Asset-class default: RANGEBAR_<ASSET_CLASS>_MIN_THRESHOLD
+- Default crypto minimum: 1000 dbps (1%) per CFM research
+- Add validation to all Python entry points (21 locations)
+- Add validation to Rust checkpoint restoration (lib.rs, processor.rs)
+- Add NDJSON logging and Pushover alerts for violations
+- Add cache purge script for invalidating low-threshold data
+- Add 32 comprehensive tests for threshold enforcement
+
+SRED-Type: applied-research
+SRED-Claim: THRESHOLD
+
+# [11.7.0](https://github.com/terrylica/rangebar-py/compare/v11.6.1...v11.7.0) (2026-02-02)
+
+
+### Features
+
+* **intrabar:** add 22 intra-bar microstructure features (Issue [#59](https://github.com/terrylica/rangebar-py/issues/59)) ([4200631](https://github.com/terrylica/rangebar-py/commit/4200631576269ad90b957f6c250e07866d30c3e4))
+
 ## [11.6.1](https://github.com/terrylica/rangebar-py/compare/v11.6.0...v11.6.1) (2026-02-02)
 
 

{rangebar-11.6.1 → rangebar-12.0.0}/Cargo.lock

@@ -3430,7 +3430,7 @@ dependencies = [
 
 [[package]]
 name = "rangebar"
-version = "11.6.1"
+version = "12.0.0"
 dependencies = [
  "chrono",
  "insta",
@@ -3452,7 +3452,7 @@ dependencies = [
 
 [[package]]
 name = "rangebar-batch"
-version = "11.6.1"
+version = "12.0.0"
 dependencies = [
  "polars",
  "rangebar-core",
@@ -3464,7 +3464,7 @@ dependencies = [
 
 [[package]]
 name = "rangebar-cli"
-version = "11.6.1"
+version = "12.0.0"
 dependencies = [
  "chrono",
  "clap",
@@ -3489,7 +3489,7 @@ dependencies = [
 
 [[package]]
 name = "rangebar-config"
-version = "11.6.1"
+version = "12.0.0"
 dependencies = [
  "chrono",
  "config",
@@ -3501,7 +3501,7 @@ dependencies = [
 
 [[package]]
 name = "rangebar-core"
-version = "11.6.1"
+version = "12.0.0"
 dependencies = [
  "ahash",
  "arrow",
@@ -3518,7 +3518,7 @@ dependencies = [
 
 [[package]]
 name = "rangebar-io"
-version = "11.6.1"
+version = "12.0.0"
 dependencies = [
  "polars",
  "rangebar-core",
@@ -3528,7 +3528,7 @@ dependencies = [
 
 [[package]]
 name = "rangebar-providers"
-version = "11.6.1"
+version = "12.0.0"
 dependencies = [
  "chrono",
  "csv",
@@ -3548,7 +3548,7 @@ dependencies = [
 
 [[package]]
 name = "rangebar-py"
-version = "11.6.1"
+version = "12.0.0"
 dependencies = [
  "arrow",
  "arrow-array",
@@ -3567,7 +3567,7 @@ dependencies = [
 
 [[package]]
 name = "rangebar-streaming"
-version = "11.6.1"
+version = "12.0.0"
 dependencies = [
  "async-trait",
  "chrono",

{rangebar-11.6.1 → rangebar-12.0.0}/Cargo.toml

@@ -10,7 +10,7 @@ resolver = "2"
 [workspace.package]
 # CRITICAL: Prevent crates.io publishing - this is a PyPI-only project
 publish = false
-version = "11.6.1"
+version = "12.0.0"
 authors = ["Terry Li <terry@eonlabs.com>"]
 categories = ["algorithms", "data-structures", "finance"]
 documentation = "https://docs.rs/rangebar"
@@ -97,7 +97,7 @@ criterion = { version = "0.5", features = ["html_reports"] }
 
 [package]
 name = "rangebar-py"
-version = "11.6.1"
+version = "12.0.0"
 edition = "2021"
 authors = ["Terry Li"]
 license = "MIT"

{rangebar-11.6.1 → rangebar-12.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rangebar
-Version: 11.6.1
+Version: 12.0.0
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Financial and Insurance Industry
 Classifier: License :: OSI Approved :: MIT License

{rangebar-11.6.1 → rangebar-12.0.0}/crates/rangebar-core/src/checkpoint.rs

@@ -243,6 +243,14 @@ pub enum CheckpointError {
     /// Checkpoint serialization/deserialization error
     #[error("Checkpoint serialization error: {message}")]
     SerializationError { message: String },
+
+    /// Invalid threshold in checkpoint (Issue #62: crypto minimum threshold enforcement)
+    #[error("Invalid threshold in checkpoint: {threshold} dbps. Valid range: {min_threshold}-{max_threshold} dbps")]
+    InvalidThreshold {
+        threshold: u32,
+        min_threshold: u32,
+        max_threshold: u32,
+    },
 }
 
 /// Price window for computing position verification hash

rangebar-12.0.0/crates/rangebar-core/src/intrabar/drawdown.rs

@@ -0,0 +1,174 @@
+//! Max drawdown and max runup computation for TMAEG calculation.
+//!
+//! Issue #59: Intra-bar microstructure features for large range bars.
+//!
+//! ORIGIN: trading-fitness/packages/metrics-rust/src/ith_rolling.rs:79-142
+//! COPIED: 2026-02-02
+//! MODIFICATIONS: Extracted as standalone functions for intra-bar use
+//!
+//! These functions compute the Maximum Drawdown and Maximum Runup which are used
+//! as the TMAEG (Target Maximum Acceptable Excess Gain) threshold for ITH analysis.
+//!
+//! # Key Design Decision: TMAEG = Max Drawdown / Max Runup
+//!
+//! This approach is elegant because:
+//! 1. TMAEG is derived directly from the window's own extremes
+//! 2. No arbitrary parameters or percentile tuning
+//! 3. Epochs trigger when gains exceed the maximum adverse movement
+//! 4. Mathematically symmetric: drawdown ↔ runup
+
+/// Compute Maximum Drawdown for Bull ITH TMAEG.
+///
+/// Maximum Drawdown = 1 - (trough / peak)
+///
+/// This is the simplest, most mathematically pure definition:
+/// - An epoch triggers when excess gain exceeds the maximum adverse movement
+/// - No arbitrary parameters, no percentile tuning
+/// - TMAEG is derived directly from the window's own extremes
+///
+/// # Arguments
+/// * `window` - Normalized price window (first value = 1.0 recommended)
+///
+/// # Returns
+/// Maximum drawdown as a fraction [0, 1). Returns `f64::EPSILON` for windows < 2.
+pub fn compute_max_drawdown(window: &[f64]) -> f64 {
+    if window.len() < 2 {
+        return f64::EPSILON;
+    }
+
+    let mut running_max = window[0];
+    let mut max_drawdown = 0.0;
+
+    for &val in window.iter().skip(1) {
+        if val > running_max {
+            running_max = val;
+        }
+        if running_max > 0.0 && val.is_finite() {
+            let drawdown = 1.0 - val / running_max;
+            if drawdown > max_drawdown {
+                max_drawdown = drawdown;
+            }
+        }
+    }
+
+    // Ensure a minimum threshold to avoid division issues
+    max_drawdown.max(f64::EPSILON)
+}
+
+/// Compute Maximum Runup for Bear ITH TMAEG.
+///
+/// Maximum Runup = 1 - (trough / peak) where we track the inverse:
+/// - Running minimum (trough)
+/// - Then measure how much price rises from that trough
+///
+/// This is the symmetric counterpart to Maximum Drawdown:
+/// - Drawdown: how much price falls from peak (adverse for longs)
+/// - Runup: how much price rises from trough (adverse for shorts)
+///
+/// # Arguments
+/// * `window` - Normalized price window (first value = 1.0 recommended)
+///
+/// # Returns
+/// Maximum runup as a fraction [0, 1). Returns `f64::EPSILON` for windows < 2.
+pub fn compute_max_runup(window: &[f64]) -> f64 {
+    if window.len() < 2 {
+        return f64::EPSILON;
+    }
+
+    let mut running_min = window[0];
+    let mut max_runup = 0.0;
+
+    for &val in window.iter().skip(1) {
+        if val < running_min {
+            running_min = val;
+        }
+        if val > 0.0 && running_min > 0.0 && val.is_finite() {
+            // Runup = how much price has risen from the trough
+            // Formula: 1 - (trough / current) = (current - trough) / current
+            let runup = 1.0 - running_min / val;
+            if runup > max_runup {
+                max_runup = runup;
+            }
+        }
+    }
+
+    // Ensure a minimum threshold to avoid division issues
+    max_runup.max(f64::EPSILON)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_max_drawdown_uptrend() {
+        // Pure uptrend should have zero drawdown
+        let prices = vec![1.0, 1.01, 1.02, 1.03, 1.04, 1.05];
+        let dd = compute_max_drawdown(&prices);
+        assert!(dd < 0.001, "Pure uptrend should have near-zero drawdown");
+    }
+
+    #[test]
+    fn test_max_drawdown_downtrend() {
+        // Decline from 1.0 to 0.8 = 20% drawdown
+        let prices = vec![1.0, 0.95, 0.9, 0.85, 0.8];
+        let dd = compute_max_drawdown(&prices);
+        assert!(
+            (dd - 0.2).abs() < 0.01,
+            "Expected 20% drawdown, got {}",
+            dd
+        );
+    }
+
+    #[test]
+    fn test_max_drawdown_recovery() {
+        // Peak at 1.1, trough at 0.9, max DD = 1 - 0.9/1.1 ≈ 18.2%
+        let prices = vec![1.0, 1.1, 1.0, 0.9, 1.0, 1.1];
+        let dd = compute_max_drawdown(&prices);
+        assert!(
+            (dd - 0.182).abs() < 0.01,
+            "Expected ~18.2% drawdown, got {}",
+            dd
+        );
+    }
+
+    #[test]
+    fn test_max_runup_downtrend() {
+        // Pure downtrend should have zero runup
+        let prices = vec![1.0, 0.99, 0.98, 0.97, 0.96, 0.95];
+        let ru = compute_max_runup(&prices);
+        assert!(ru < 0.001, "Pure downtrend should have near-zero runup");
+    }
+
+    #[test]
+    fn test_max_runup_uptrend() {
+        // Rise from 1.0 to 1.25 = 1 - 1.0/1.25 = 20% runup
+        let prices = vec![1.0, 1.05, 1.1, 1.15, 1.2, 1.25];
+        let ru = compute_max_runup(&prices);
+        assert!((ru - 0.2).abs() < 0.01, "Expected 20% runup, got {}", ru);
+    }
+
+    #[test]
+    fn test_max_runup_recovery() {
+        // Trough at 0.9, peak at 1.1, max RU = 1 - 0.9/1.1 ≈ 18.2%
+        let prices = vec![1.0, 0.9, 0.95, 1.0, 1.05, 1.1];
+        let ru = compute_max_runup(&prices);
+        assert!(
+            (ru - 0.182).abs() < 0.01,
+            "Expected ~18.2% runup, got {}",
+            ru
+        );
+    }
+
+    #[test]
+    fn test_empty_window() {
+        assert_eq!(compute_max_drawdown(&[]), f64::EPSILON);
+        assert_eq!(compute_max_runup(&[]), f64::EPSILON);
+    }
+
+    #[test]
+    fn test_single_element() {
+        assert_eq!(compute_max_drawdown(&[1.0]), f64::EPSILON);
+        assert_eq!(compute_max_runup(&[1.0]), f64::EPSILON);
+    }
+}