wickra_zhibiao_quantginger/README.md

# Wickra

Streaming-first technical indicators — Rust core, **514 indicators** across 24
families. Each indicator is a state machine that updates in O(1) per new data
point, so live trading bots and historical backtests share the exact same
implementation.

```rust
use wickra::{Indicator, Sma};

let mut sma = Sma::new(14)?;
let prices = [1.0, 2.0, 3.0, 4.0, 5.0];
let out: Vec<Option<f64>> = prices.iter().map(|p| sma.update(*p)).collect();
assert_eq!(out, vec![None, None, Some(2.0), Some(3.0), Some(4.0)]);
```

## Indicator catalog

Every indicator lives in
[`crates/wickra-core/src/indicators/`](crates/wickra-core/src/indicators/) as
one self-contained `.rs` file. For a compact, family-grouped index of all 514
indicators — public struct name, the file's own one-line intent, and a direct
link to the implementation — see [`INDICATORS.md`](INDICATORS.md).

Regenerate the catalog after editing the indicator list:

```bash
python scripts/gen_indicators_index.py
```

The catalog is the recommended entry point for an AI agent that needs to look
up what indicators exist and pick one to translate (for example into another
framework's indicator contract); the agent opens only the `.rs` files it
actually needs.

## Indicator families

The canonical taxonomy lives in the `FAMILIES` constant at
[`crates/wickra-core/src/indicators/mod.rs`](crates/wickra-core/src/indicators/mod.rs)
and is enforced by an `assert_eq!(total, 514)` test in the same file.

| Family | Count | Examples |
|---|---:|---|
| Moving Averages | 26 | SMA, EMA, HMA, KAMA, ALMA, JMA, FRAMA, Holt-Winters |
| Momentum Oscillators | 34 | RSI, StochRSI, ConnorsRSI, Williams %R, MFI, CCI, QQE |
| Trend & Directional | 28 | MACD, ADX (+DI/-DI), Aroon, Vortex, Choppiness Index |
| Price Oscillators | 14 | PPO, DPO, Coppock, Zero-Lag MACD, STC |
| Volatility & Bands | 25 | ATR, Bollinger Bands, Keltner, Yang-Zhang, Garman-Klass |
| Bands & Channels | 16 | MA Envelope, STARC Bands, VWAP StdDev Bands, TTM Squeeze |
| Trailing Stops | 19 | Parabolic SAR, SuperTrend, Chandelier Exit, Kase DevStop |
| Volume | 26 | OBV, VWAP, CMF, Klinger VO, Anchored VWAP, Twiggs Money Flow |
| Price Statistics | 55 | Linear Regression, Hurst, Z-Score, Cointegration, GARCH, Kalman Hedge Ratio |
| Ehlers / Cycle (DSP) | 29 | MAMA, Hilbert Transform, Decycler, Roofing Filter, Even Better Sinewave |
| Pivots & S/R | 12 | Classic/Fibonacci/Camarilla/Woodie/DeMark pivots, ZigZag |
| DeMark | 19 | TD Sequential, TD Setup, TD Combo, TD Countdown |
| Ichimoku & Charts | 7 | Ichimoku Kinko Hyo, Heikin-Ashi, Three Line Break |
| Candlestick Patterns | 66 | Doji, Hammer, Engulfing, Marubozu, Harami, Tweezer, 60+ more |
| Microstructure | 20 | Order-Book Imbalance, Kyle's Lambda, VPIN, Roll Measure |
| Derivatives | 17 | Funding Rate, OI Delta, Long/Short Ratio, Liquidation Features |
| Market Profile | 10 | Value Area, Volume Profile, TPO Profile, Initial Balance |
| Risk / Performance | 28 | Sharpe, Sortino, Calmar, Omega, Max Drawdown, VaR, CVaR, Kelly |
| Alt-Chart Bars | 10 | Renko, Kagi, Point & Figure, Range/Tick/Volume/Dollar/Imbalance Bars |
| Market Breadth | 15 | A/D Line, McClellan Oscillator, TRIN, Breadth Thrust |
| Seasonality & Session | 12 | Session VWAP, Turn-of-Month, Day-of-Week Profile |
| Chart Patterns | 8 | Double/Triple Top-Bottom, H&S, Triangle, Wedge, Cup & Handle |
| Harmonic Patterns | 8 | Gartley, Butterfly, Bat, Crab, Shark, Cypher, Three Drives |
| Fibonacci | 10 | Retracement, Extension, Projection, Fan, Arcs, Channel, Time Zones |
| **Total** | **514** | |

Every candlestick pattern emits a signed per-bar value — `+1.0` bullish,
`−1.0` bearish, `0.0` none — so the family drops straight into a feature matrix
as one column each.

## Rust API

```rust
use wickra::{Indicator, BatchExt, Chain, Ema, Rsi, Sma};

// Batch and streaming share the same trait.
let mut sma = Sma::new(14)?;
let out: Vec<Option<f64>> = sma.batch(&[1.0, 2.0, 3.0, 4.0, 5.0]);

let mut rsi = Rsi::new(14)?;
for price in live_feed {
    if let Some(v) = rsi.update(price) {
        println!("RSI = {v}");
    }
}

// Compose: RSI(7) on top of EMA(14).
let mut chain = Chain::new(Ema::new(14)?, Rsi::new(7)?);
chain.update(price);
```

`wickra-core` is `unsafe`-forbidden. The `wickra` facade crate is what
`use wickra::...` resolves to; everything below also re-exports from
`wickra_core::*` if you want to depend on the core directly.

## Live data

`wickra-data` ships a complete, dependency-free data layer:

- streaming OHLCV CSV reader (`CandleReader`)
- tick-to-candle aggregator with arbitrary timeframes (`TickAggregator`)
- candle resampler for multi-timeframe analysis (`Resampler`)
- live Binance Spot WebSocket kline feed (`BinanceFeed`, feature `live-binance`)
- historical Binance REST kline fetcher (`fetch_binance_klines`) — native HTTP + JSON

```rust
use wickra::{Indicator, Rsi};
use wickra_data::live::binance::{BinanceKlineStream, Interval};

let mut stream = BinanceKlineStream::connect(&["BTCUSDT".into()], Interval::OneMinute).await?;
let mut rsi = Rsi::new(14)?;
while let Some(event) = stream.next_event().await? {
    if event.is_closed {
        if let Some(v) = rsi.update(event.candle.close) {
            println!("RSI = {v:.2}");
        }
    }
}
```

## Crates

| Crate | Purpose |
|---|---|
| `wickra` | Top-level facade re-exporting `wickra-core`. What `use wickra::...` resolves to. |
| `wickra-core` | Core engine + all 514 indicators + the `Indicator` trait. |
| `wickra-data` | CSV reader, tick aggregator, resampler, Binance live + historical feeds. |
| `wickra-bench` | Internal cross-library benchmark harness (not published). |

## Project layout

```
wickra/
├── crates/
│   ├── wickra/                facade crate
│   ├── wickra-core/           core engine + 514 indicators
│   ├── wickra-data/           CSV / aggregator / Binance live + REST
│   └── wickra-bench/          internal cross-library benchmark harness
├── docs/                      in-repo docs (see docs/README.md)
├── LICENSES/                  per-license texts
├── scripts/
│   └── gen_indicators_index.py
├── Cargo.toml                 workspace manifest
├── Cargo.lock
├── INDICATORS.md              auto-generated compact catalog
├── README.md
├── LICENSE-APACHE
└── LICENSE-MIT
```

## Building & testing

```bash
# Build the whole workspace
cargo build --workspace

# Run all tests (unit + the cross-indicator invariants harness)
cargo test --workspace

# Lint as CI does
cargo clippy --workspace --all-targets -- -D warnings

# Wickra's own regression benchmarks
cargo bench -p wickra
```

## Adding an indicator

1. Implement the `Indicator` trait in
   `crates/wickra-core/src/indicators/<name>.rs`.
2. Wire it into `indicators/mod.rs` (the `mod <name>;` declaration and the
   `FAMILIES` array — keeping the per-family count in sync).
3. Add reference-value tests, a `batch == streaming` equivalence test, and
   (where it makes sense) a proptest.
4. Re-run `python scripts/gen_indicators_index.py` to refresh `INDICATORS.md`.
   The script also enforces the 514-indicator invariant via the FAMILIES
   total.

## License

Licensed under either of

- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- MIT license ([LICENSE-MIT](LICENSE-MIT))

at your option.

## Disclaimer

Wickra is an indicator toolkit, not a trading system. Values it computes are
deterministic transforms of the input data — they are not financial advice and
they do not predict the market. Any use of this library in a production
trading context is at your own risk.