rangebar 11.7.0__tar.gz → 12.0.1__tar.gz

{rangebar-11.7.0 → rangebar-12.0.1}/.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.7.0 → rangebar-12.0.1}/CHANGELOG.md

@@ -1,3 +1,28 @@
+# [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)
 
 

{rangebar-11.7.0 → rangebar-12.0.1}/CLAUDE.md

@@ -135,16 +135,16 @@ mise run bench:validate     # Verify 1M ticks < 100ms
 
 | Feature                | Formula                                     | Range        |
 | ---------------------- | ------------------------------------------- | ------------ |
-| `duration_us`          | (close_time - open_time) \* 1000            | [0, +inf)    |
+| `duration_us`          | close_time - open_time                      | [0, +inf)    |
 | `ofi`                  | (buy_vol - sell_vol) / total                | [-1, 1]      |
-| `vwap_close_deviation` | (close - vwap) / range                      | ~[-1, 1]     |
+| `vwap_close_deviation` | (close - vwap) / (high - low)               | ~[-1, 1]     |
 | `price_impact`         | abs(close - open) / volume                  | [0, +inf)    |
 | `kyle_lambda_proxy`    | ((close-open)/open) / (imbalance/total_vol) | (-inf, +inf) |
 | `trade_intensity`      | trades / duration_sec                       | [0, +inf)    |
 | `volume_per_trade`     | volume / trade_count                        | [0, +inf)    |
 | `aggression_ratio`     | buy_count / sell_count                      | [0, 100]     |
 | `aggregation_density`  | individual_count / agg_count                | [1, +inf)    |
-| `turnover_imbalance`   | (buy_turn - sell_turn) / volume             | [-1, 1]      |
+| `turnover_imbalance`   | (buy_turn - sell_turn) / total_turnover     | [-1, 1]      |
 
 **Full details**: [crates/CLAUDE.md](/crates/CLAUDE.md#microstructure-features-v70)
 

{rangebar-11.7.0 → rangebar-12.0.1}/Cargo.lock

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

{rangebar-11.7.0 → rangebar-12.0.1}/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.7.0"
+version = "12.0.1"
 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.7.0"
+version.workspace = true
 edition = "2021"
 authors = ["Terry Li"]
 license = "MIT"

{rangebar-11.7.0 → rangebar-12.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rangebar
-Version: 11.7.0
+Version: 12.0.1
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Financial and Insurance Industry
 Classifier: License :: OSI Approved :: MIT License
@@ -37,9 +37,11 @@ Project-URL: Documentation, https://github.com/terrylica/rangebar-py#readme
 Project-URL: Repository, https://github.com/terrylica/rangebar-py
 Project-URL: Upstream (Rust), https://github.com/terrylica/rangebar
 
+[//]: # SSoT-OK
+
 # rangebar-py
 
-Python bindings for the [rangebar](https://github.com/terrylica/rangebar-py/tree/main/crates) Rust crates via PyO3/maturin.
+High-performance range bar construction for quantitative trading, with Python bindings via PyO3/maturin.
 
 [![PyPI](https://img.shields.io/pypi/v/rangebar.svg)](https://pypi.org/project/rangebar/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/terrylica/rangebar-py/blob/main/LICENSE)
@@ -85,6 +87,45 @@ bt = Backtest(df, MyStrategy, cash=10000, commission=0.0002)
 stats = bt.run()
 ```
 
+## Minimum Threshold Enforcement (v12.0+)
+
+**Breaking change in v12.0**: Crypto symbols now enforce a minimum threshold of 1000 dbps (1%) by default. Thresholds below this cannot overcome trading costs sufficiently for crypto assets.
+
+```python
+from rangebar import get_range_bars, ThresholdError
+
+# This raises ThresholdError for crypto (below 1000 dbps minimum)
+try:
+    df = get_range_bars("BTCUSDT", "2024-01-01", "2024-01-31", threshold_decimal_bps=250)
+except ThresholdError as e:
+    print(e)  # Threshold 250 dbps below minimum 1000 dbps for crypto symbol 'BTCUSDT'
+
+# Use valid threshold for crypto (>= 1000 dbps)
+df = get_range_bars("BTCUSDT", "2024-01-01", "2024-01-31", threshold_decimal_bps=1000)
+
+# Forex allows lower thresholds (minimum 50 dbps)
+df = get_range_bars("EURUSD", "2024-01-01", "2024-01-31", threshold_decimal_bps=50, source="exness")
+```
+
+**Override for research/testing**:
+
+```bash
+# Lower crypto minimum for research
+RANGEBAR_CRYPTO_MIN_THRESHOLD=100 python my_research_script.py
+
+# Override specific symbol
+RANGEBAR_MIN_THRESHOLD_BTCUSDT=250 python btc_analysis.py
+```
+
+**Default minimums by asset class**:
+
+| Asset Class | Minimum   | Env Var                           |
+| ----------- | --------- | --------------------------------- |
+| Crypto      | 1000 dbps | `RANGEBAR_CRYPTO_MIN_THRESHOLD`   |
+| Forex       | 50 dbps   | `RANGEBAR_FOREX_MIN_THRESHOLD`    |
+| Equities    | 100 dbps  | `RANGEBAR_EQUITIES_MIN_THRESHOLD` |
+| Unknown     | 1 dbps    | `RANGEBAR_UNKNOWN_MIN_THRESHOLD`  |
+
 ## API Reference
 
 ### get_range_bars (Date-Bounded)
@@ -94,28 +135,28 @@ The entry point for date-bounded range bar generation with automatic data fetchi
 ```python
 from rangebar import get_range_bars
 
-# Basic usage - Binance spot
-df = get_range_bars("BTCUSDT", "2024-01-01", "2024-06-30")
+# Basic usage - Binance spot (crypto requires threshold >= 1000 dbps)
+df = get_range_bars("BTCUSDT", "2024-01-01", "2024-06-30", threshold_decimal_bps=1000)
 
-# Using threshold presets
-df = get_range_bars("BTCUSDT", "2024-01-01", "2024-03-31", threshold_decimal_bps="tight")
+# Using threshold presets (only "macro" and "wide" valid for crypto)
+df = get_range_bars("BTCUSDT", "2024-01-01", "2024-03-31", threshold_decimal_bps="macro")
 
 # Binance USD-M Futures
-df = get_range_bars("BTCUSDT", "2024-01-01", "2024-03-31", market="futures-um")
+df = get_range_bars("BTCUSDT", "2024-01-01", "2024-03-31", market="futures-um", threshold_decimal_bps=1000)
 
-# With microstructure data (vwap, buy_volume, sell_volume)
-df = get_range_bars("BTCUSDT", "2024-01-01", "2024-01-31", include_microstructure=True)
+# With microstructure features (62 total columns)
+df = get_range_bars("BTCUSDT", "2024-01-01", "2024-01-31", threshold_decimal_bps=1000, include_microstructure=True)
 ```
 
 **Parameters**:
 
-- `symbol`: Trading symbol (e.g., "BTCUSDT", "ETHUSDT")
+- `symbol`: Trading symbol (e.g., "BTCUSDT", "ETHUSDT", "EURUSD")
 - `start_date`: Start date in YYYY-MM-DD format
 - `end_date`: End date in YYYY-MM-DD format
-- `threshold_decimal_bps`: Threshold in decimal basis points or preset name (default: 250 = 25bps = 0.25%)
+- `threshold_decimal_bps`: Threshold in decimal basis points or preset name (default: 250, but crypto requires >= 1000)
 - `source`: Data source - "binance" or "exness" (default: "binance")
 - `market`: Market type - "spot", "futures-um"/"um", "futures-cm"/"cm" (default: "spot")
-- `include_microstructure`: Include vwap, buy_volume, sell_volume columns (default: False)
+- `include_microstructure`: Include 57 microstructure feature columns (default: False)
 - `use_cache`: Cache tick data locally (default: True)
 
 **Returns**: pandas DataFrame with DatetimeIndex and columns `Open`, `High`, `Low`, `Close`, `Volume`
@@ -128,21 +169,21 @@ Get exactly N range bars - useful for ML training, walk-forward optimization, an
 from rangebar import get_n_range_bars
 
 # Get last 10,000 bars for ML training
-df = get_n_range_bars("BTCUSDT", n_bars=10000)
+df = get_n_range_bars("BTCUSDT", n_bars=10000, threshold_decimal_bps=1000)
 assert len(df) == 10000
 
 # Get 5,000 bars ending at specific date
-df = get_n_range_bars("BTCUSDT", n_bars=5000, end_date="2024-06-01")
+df = get_n_range_bars("BTCUSDT", n_bars=5000, end_date="2024-06-01", threshold_decimal_bps=1000)
 
 # With safety limit (won't fetch more than 30 days of data)
-df = get_n_range_bars("BTCUSDT", n_bars=1000, max_lookback_days=30)
+df = get_n_range_bars("BTCUSDT", n_bars=1000, max_lookback_days=30, threshold_decimal_bps=1000)
 ```
 
 **Parameters**:
 
 - `symbol`: Trading symbol (e.g., "BTCUSDT")
 - `n_bars`: Number of bars to retrieve (must be > 0)
-- `threshold_decimal_bps`: Threshold in decimal basis points or preset name (default: 250)
+- `threshold_decimal_bps`: Threshold in decimal basis points or preset name (default: 250, but crypto requires >= 1000)
 - `end_date`: End date (YYYY-MM-DD) or None for most recent data
 - `source`: Data source - "binance" or "exness" (default: "binance")
 - `market`: Market type (default: "spot")
@@ -162,29 +203,96 @@ df = get_n_range_bars("BTCUSDT", n_bars=1000, max_lookback_days=30)
 
 Use string presets for common threshold values:
 
-| Preset       | Value | Percentage    | Use Case         |
-| ------------ | ----- | ------------- | ---------------- |
-| `"micro"`    | 10    | 0.01% (1bps)  | Scalping         |
-| `"tight"`    | 50    | 0.05% (5bps)  | Day trading      |
-| `"standard"` | 100   | 0.1% (10bps)  | Swing trading    |
-| `"medium"`   | 250   | 0.25% (25bps) | Default          |
-| `"wide"`     | 500   | 0.5% (50bps)  | Position trading |
-| `"macro"`    | 1000  | 1% (100bps)   | Long-term        |
+| Preset       | Value | Percentage    | Crypto | Forex | Use Case         |
+| ------------ | ----- | ------------- | ------ | ----- | ---------------- |
+| `"micro"`    | 10    | 0.01% (1bps)  | No     | No    | Scalping         |
+| `"tight"`    | 50    | 0.05% (5bps)  | No     | Yes   | Day trading      |
+| `"standard"` | 100   | 0.1% (10bps)  | No     | Yes   | Swing trading    |
+| `"medium"`   | 250   | 0.25% (25bps) | No     | Yes   | Default          |
+| `"wide"`     | 500   | 0.5% (50bps)  | No     | Yes   | Position trading |
+| `"macro"`    | 1000  | 1% (100bps)   | Yes    | Yes   | Long-term        |
 
 ```python
 from rangebar import get_range_bars, THRESHOLD_PRESETS
 
-# Using preset string
-df = get_range_bars("BTCUSDT", "2024-01-01", "2024-01-31", threshold_decimal_bps="tight")
+# Using preset string (only "macro" valid for crypto)
+df = get_range_bars("BTCUSDT", "2024-01-01", "2024-01-31", threshold_decimal_bps="macro")
 
-# Or numeric value
-df = get_range_bars("BTCUSDT", "2024-01-01", "2024-01-31", threshold_decimal_bps=50)
+# Forex allows all presets
+df = get_range_bars("EURUSD", "2024-01-01", "2024-01-31", threshold_decimal_bps="tight", source="exness")
 
 # View all presets
 print(THRESHOLD_PRESETS)
 # {'micro': 10, 'tight': 50, 'standard': 100, 'medium': 250, 'wide': 500, 'macro': 1000}
 ```
 
+### Threshold Validation Utilities (v12.0+)
+
+```python
+from rangebar import (
+    ThresholdError,
+    get_min_threshold,
+    get_min_threshold_for_symbol,
+    resolve_and_validate_threshold,
+    clear_threshold_cache,
+    detect_asset_class,
+    AssetClass,
+)
+
+# Get minimum threshold for asset class
+crypto_min = get_min_threshold(AssetClass.CRYPTO)  # 1000
+forex_min = get_min_threshold(AssetClass.FOREX)    # 50
+
+# Get minimum threshold for specific symbol
+btc_min = get_min_threshold_for_symbol("BTCUSDT")  # 1000
+eur_min = get_min_threshold_for_symbol("EURUSD")   # 50
+
+# Validate and resolve threshold (raises ThresholdError if invalid)
+threshold = resolve_and_validate_threshold("BTCUSDT", "macro")  # 1000
+
+# Detect asset class
+assert detect_asset_class("BTCUSDT") == AssetClass.CRYPTO
+assert detect_asset_class("EURUSD") == AssetClass.FOREX
+
+# Clear cache after changing env vars at runtime
+clear_threshold_cache()
+```
+
+### Microstructure Features (v7.0+)
+
+When `include_microstructure=True`, the DataFrame includes 57 feature columns (62 total with OHLCV) organized into three categories:
+
+**Base Microstructure (15 columns)**:
+
+- `vwap`, `buy_volume`, `sell_volume`, `individual_trade_count`, `agg_record_count`
+- `duration_us`, `ofi`, `vwap_close_deviation`, `price_impact`, `kyle_lambda_proxy`
+- `trade_intensity`, `volume_per_trade`, `aggression_ratio`, `aggregation_density`, `turnover_imbalance`
+
+**Intra-Bar Features (22 columns, Issue #59)** - Computed from trades WITHIN each bar:
+
+- Epoch analysis: `intra_bull_epoch_density`, `intra_bear_epoch_density`, `intra_bull_excess_gain`, `intra_bear_excess_gain`, `intra_bull_cv`, `intra_bear_cv`
+- Price path: `intra_max_drawdown`, `intra_max_runup`
+- Volume/trade: `intra_trade_count`, `intra_ofi`, `intra_duration_us`, `intra_intensity`
+- Advanced: `intra_vwap_position`, `intra_count_imbalance`, `intra_kyle_lambda`, `intra_burstiness`
+- Statistical: `intra_volume_skew`, `intra_volume_kurt`, `intra_kaufman_er`, `intra_garman_klass_vol`, `intra_hurst`, `intra_permutation_entropy`
+
+**Inter-Bar Features (16 columns, Issue #59)** - Computed from lookback window BEFORE each bar:
+
+- `lookback_trade_count`, `lookback_ofi`, `lookback_duration_us`, `lookback_intensity`
+- `lookback_vwap_raw`, `lookback_vwap_position`, `lookback_count_imbalance`, `lookback_kyle_lambda`
+- `lookback_burstiness`, `lookback_volume_skew`, `lookback_volume_kurt`, `lookback_price_range`
+- `lookback_kaufman_er`, `lookback_garman_klass_vol`, `lookback_hurst`, `lookback_permutation_entropy`
+
+```python
+from rangebar import get_range_bars, MICROSTRUCTURE_COLUMNS, INTRA_BAR_FEATURE_COLUMNS, INTER_BAR_FEATURE_COLUMNS
+
+df = get_range_bars("BTCUSDT", "2024-01-01", "2024-01-07", threshold_decimal_bps=1000, include_microstructure=True)
+
+print(f"Base microstructure: {len(MICROSTRUCTURE_COLUMNS)} columns")
+print(f"Intra-bar features: {len(INTRA_BAR_FEATURE_COLUMNS)} columns")
+print(f"Inter-bar features: {len(INTER_BAR_FEATURE_COLUMNS)} columns")
+```
+
 ### Configuration Constants
 
 ```python
@@ -213,7 +321,10 @@ from rangebar import process_trades_to_dataframe
 # Load your own trade data
 trades = pd.read_csv("BTCUSDT-aggTrades.csv")
 
-# Convert to range bars
+# Convert to range bars (symbol required for threshold validation)
+df = process_trades_to_dataframe(trades, threshold_decimal_bps=1000, symbol="BTCUSDT")
+
+# Without symbol, no asset-class validation (use for custom data)
 df = process_trades_to_dataframe(trades, threshold_decimal_bps=250)
 ```
 
@@ -227,11 +338,11 @@ from rangebar import process_trades_polars
 
 # LazyFrame - predicates pushed to I/O layer (10-100x memory reduction)
 lazy_df = pl.scan_parquet("trades/*.parquet").filter(pl.col("timestamp") >= start_ts)
-bars = process_trades_polars(lazy_df, threshold_decimal_bps=250)
+bars = process_trades_polars(lazy_df, threshold_decimal_bps=1000, symbol="BTCUSDT")
 
 # Or with eager DataFrame
 df = pl.read_parquet("trades.parquet")
-bars = process_trades_polars(df)
+bars = process_trades_polars(df, threshold_decimal_bps=1000, symbol="BTCUSDT")
 ```
 
 **Performance benefits**:
@@ -249,10 +360,32 @@ Memory-safe processing for large datasets:
 from rangebar import process_trades_chunked
 
 # Process 10M+ trades without OOM
-for bars_df in process_trades_chunked(iter(trades), chunk_size=50_000):
+for bars_df in process_trades_chunked(iter(trades), chunk_size=50_000, symbol="BTCUSDT", threshold_decimal_bps=1000):
     process_batch(bars_df)
 ```
 
+### Streaming API
+
+Real-time range bar generation from Binance WebSocket:
+
+```python
+from rangebar import stream_binance_live, ReconnectionConfig
+
+# Basic streaming (uses threshold_bps, not threshold_decimal_bps)
+async for bar in stream_binance_live("BTCUSDT", threshold_bps=1000):
+    print(f"New bar: {bar}")
+
+# With reconnection configuration
+reconnect_config = ReconnectionConfig(
+    max_retries=5,
+    initial_delay_s=1.0,
+    max_delay_s=60.0,
+    backoff_factor=2.0,
+)
+async for bar in stream_binance_live("BTCUSDT", threshold_bps=1000, reconnect_config=reconnect_config):
+    process_bar(bar)
+```
+
 ## Requirements
 
 **Runtime**: Python >= 3.13, pandas >= 2.0, numpy >= 1.24, polars >= 1.0
@@ -264,13 +397,15 @@ for bars_df in process_trades_chunked(iter(trades), chunk_size=50_000):
 ## Architecture
 
 ```
-rangebar (Rust crate)
-    ↓ Cargo dependency
-rangebar-py (this package)
-    ├── src/lib.rs (PyO3 bindings)
-    └── python/rangebar/ (Python API)
-    ↓ pip install
-Python applications
+rangebar-py/
+├── crates/                    8 Rust crates (core algorithm)
+│   └── rangebar-core/         Core processor, microstructure features
+├── src/lib.rs                 PyO3 bindings
+├── python/rangebar/           Python API layer
+│   ├── clickhouse/            ClickHouse cache
+│   ├── validation/            Microstructure validation
+│   └── threshold.py           Threshold validation (v12.0+)
+└── pyproject.toml             Maturin config
 ```
 
 ## Development
@@ -283,14 +418,38 @@ maturin develop --features data-providers
 pytest tests/
 ```
 
+## Migration from v11.x to v12.0
+
+**Breaking changes**:
+
+1. **ThresholdError** raised for crypto symbols with threshold < 1000 dbps
+2. Presets "micro", "tight", "standard", "medium" will error for crypto symbols
+3. Checkpoints with low thresholds fail to restore
+
+**Migration options**:
+
+```python
+# Option 1: Use valid threshold for crypto
+df = get_range_bars("BTCUSDT", "2024-01-01", "2024-01-31", threshold_decimal_bps=1000)
+
+# Option 2: Override minimum via environment variable
+import os
+os.environ["RANGEBAR_CRYPTO_MIN_THRESHOLD"] = "250"
+from rangebar import clear_threshold_cache
+clear_threshold_cache()
+
+# Option 3: Use "macro" preset (1000 dbps)
+df = get_range_bars("BTCUSDT", "2024-01-01", "2024-01-31", threshold_decimal_bps="macro")
+```
+
 ## Documentation
 
-| Document                                                                                                | Description           |
-| ------------------------------------------------------------------------------------------------------- | --------------------- |
-| [Examples](https://github.com/terrylica/rangebar-py/tree/main/examples)                                 | Usage examples        |
-| [CLAUDE.md](https://github.com/terrylica/rangebar-py/blob/main/CLAUDE.md)                               | Project context       |
-| [Architecture](https://github.com/terrylica/rangebar-py/blob/main/docs/ARCHITECTURE.md)                 | System design         |
-| [Performance Guide](https://github.com/terrylica/rangebar-py/blob/main/docs/development/PERFORMANCE.md) | Benchmark methodology |
+| Document                                                                                                | Description                  |
+| ------------------------------------------------------------------------------------------------------- | ---------------------------- |
+| [API Reference](https://github.com/terrylica/rangebar-py/blob/main/docs/api.md)                         | Full API documentation       |
+| [Architecture](https://github.com/terrylica/rangebar-py/blob/main/docs/ARCHITECTURE.md)                 | System design                |
+| [Performance Guide](https://github.com/terrylica/rangebar-py/blob/main/docs/development/PERFORMANCE.md) | Benchmark methodology        |
+| [CLAUDE.md](https://github.com/terrylica/rangebar-py/blob/main/CLAUDE.md)                               | AI assistant project context |
 
 ## License
 
@@ -300,7 +459,7 @@ MIT License. See [LICENSE](https://github.com/terrylica/rangebar-py/blob/main/LI
 
 ```bibtex
 @software{rangebar-py,
-  title = {rangebar-py: Python bindings for range bar construction},
+  title = {rangebar-py: High-performance range bar construction for quantitative trading},
   author = {Terry Li},
   url = {https://github.com/terrylica/rangebar-py}
 }