wickra-shazam 0.1.3

---

Point at live data → "that's the May-2021 crash setup". Match the current microstructure fingerprint of an asset against its entire history.

▶ Live demos: the backtester compiled to WebAssembly, an equity curve building bar by bar — backtest-live.wickra.org; one StrategySpec side by side in Python, Rust, JS and Go — playground.wickra.org; all 514 indicators of the core over a real Binance feed — live.wickra.org. Zero backend, all of them.

Part of the Wickra ecosystem: the same data-driven core and ten-language binding surface also power wickra-exchange, wickra-backtest, wickra-terminal and 20 more — see the full list.

Wickra Shazam turns an asset's whole history into a rolling index of fixed-dimension microstructure fingerprints — a vector built from the full Wickra feature space (indicators, price, and microstructure: order-book imbalance, funding, open interest, liquidations, footprint) — and matches the current fingerprint against that entire index to name the regime. It is pattern/regime recognition over the full feature space, not price alone.

• The fingerprint is data — a serde FingerprintSpec (an ordered feature list + window + normalize + metric), not Rust closures, so it crosses the C ABI and WASM unchanged. A fixed dimension N is what makes it deterministic.
• Deterministic core — indexing and matching are byte-identical across all ten languages and between the parallel (rayon) and sequential (WASM) builds.
• Three operations, one core — index(history, spec) builds the rolling index, match_current(index, current, k) finds the k most similar historical fingerprints, and a label attaches a human name ("may_2021_crash") to a match.

The core is one library (wickra-shazam-core), usable from Rust, Python, Node.js, WASM, C, C++, C#, Go, Java and R over a JSON-over-C-ABI boundary, plus a reference CLI.

# Index a history and match the current state, human-readable table:
cargo run -p wickra-shazam -- --spec golden/specs/crash_setup.json \
  --history golden/data/history/sym-01.csv --current golden/data/current/sym-01.csv

# Raw MatchReport JSON (the same bytes every binding returns), top 5 matches:
cargo run -p wickra-shazam -- --spec golden/specs/price_euclid.json \
  --history golden/data/history/sym-01.csv --k 5 --format json

Status

0.1.3 — the current release. The core, the CLI, all ten language bindings, the byte-exact golden corpus, property + fuzz tests, benchmarks and one runnable example per language are in place and green across the full CI matrix (10 languages × 3 OS); What comes next is in ROADMAP.md.

Documentation

• Architecture — the core, the data-driven boundary, the binding surface.
• Guides under docs/: Fingerprints & FingerprintSpec · Features · Similarity & metrics · Labels · Cookbook · Internals.
• ROADMAP.md · BENCHMARKS.md · THREAT_MODEL.md · SECURITY.md.

Quickstart

# Index a history and match the current state, human-readable table:
cargo run -p wickra-shazam -- --spec golden/specs/crash_setup.json \
  --history golden/data/history/sym-01.csv --current golden/data/current/sym-01.csv

# Raw MatchReport JSON (the same bytes every binding returns), top 5 matches:
cargo run -p wickra-shazam -- --spec golden/specs/price_euclid.json \
  --history golden/data/history/sym-01.csv --k 5 --format json

--current defaults to the last window bars of --history. Attach a label to a historical bar with --label <ts>=<name> (repeatable) and it comes back on any match at that timestamp.

FingerprintSpec / features

A spec is a JSON (or TOML) document: an ordered features list, a window, a normalize mode and a metric. The feature order is the vector's axis order and never changes within an index, so the dimension N = features.len() * window is fixed and the fingerprint is fully deterministic.

{
  "features": [
    { "kind": "indicator", "name": "Rsi", "params": [14] },
    { "kind": "indicator", "name": "Sma", "params": [20] },
    { "kind": "indicator", "name": "Atr", "params": [14] },
    { "kind": "price", "field": "close" },
    { "kind": "price", "field": "volume" }
  ],
  "window": 1,
  "normalize": "z_score",
  "metric": "cosine"
}

• indicator — any PascalCase Wickra indicator resolved from the registry by name + params (Rsi, Sma, Atr, Macd, …), with an optional field to pick a sub-output of a multi-output indicator.
• price — a raw OHLCV field (open/high/low/close/volume).
• microstructure — an order-book / flow feature (imbalance, funding, open interest, liquidations, footprint), resolved from the same registry.
• window — how many consecutive bars are stacked into one fingerprint (1 = the current bar only; > 1 = a short shape).

Similarity & metrics

The metric decides how two fingerprints are compared. Similarity is always mapped to [0, 1] (1 = identical) and rounded deterministically:

• cosine — cosine of the angle between the flat vectors, mapped from [-1, 1] to [0, 1] via (cos + 1) / 2. Scale-insensitive; good with z_score normalization.
• euclid — 1 / (1 + d) where d is the L2 distance. Scale-sensitive; pair with min_max or z_score to weight features evenly.
• dtw — dynamic time warping over the per-bar feature vectors of a window > 1 spec, tolerant of small time shifts between two shapes. With window == 1 it is identical to euclid.

normalize (none · z_score · min_max) is fitted once over the whole index and reused for the current fingerprint, so history and query live on the same axes.

Labels

A label attaches a human-readable name to a historical timestamp; when a match lands on that bar the name rides along in the report:

{ "cmd": "label", "ts": 1700216000, "label": "may_2021_crash" }
// → a later match at ts 1700216000 comes back as
//   { "ts": 1700216000, "similarity": 0.98, "label": "may_2021_crash" }

Use in any language

The same Shazam handle — construct from a JSON spec, drive with command(json) -> json, read version — is reachable from every binding. The commands are set_spec, index, match, label, reset and version; index returns {"indexed":N} and match returns a MatchReport that is byte-identical to the CLI's --format json.

from wickra_shazam import Shazam
s = Shazam('{"features":[{"kind":"price","field":"close"}],'
           '"window":1,"metric":"euclid"}')
s.command('{"cmd":"index","history":[/* candles */]}')
report = s.command('{"cmd":"match","current":[/* candles */],"k":5}')  # JSON MatchReport

The C ABI hub (bindings/c) backs C, C++, C#, Go, Java and R; Rust, Python, Node.js and WASM are native. See each bindings/<lang>/README.md and the runnable examples/.

Project layout

crates/shazam-core     the deterministic core (FingerprintSpec, index, match_current, labels)
crates/shazam-cli      the CLI (bin: wickra-shazam)
crates/shazam-bench    criterion benchmarks
bindings/{python,node,wasm,c,go,csharp,java,r}   the ten-language surface
golden/                CSV histories, current windows, specs, and byte-exact expected reports
fuzz/                  cargo-fuzz targets (spec_parse, build_index, match_index, normalize_metric)
examples/              one runnable "index a history and match the current state" example per language

Building everything from source

cargo build --workspace
cargo test  --workspace --all-features
cargo test  --workspace --no-default-features   # sequential (WASM) index/match path
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo run -p wickra-shazam -- --spec golden/specs/crash_setup.json \
  --history golden/data/history/sym-01.csv

Each binding builds from its own directory — see the per-binding READMEs under bindings/.

Testing

Run the suites with the commands in Building everything from source.

• wickra-shazam-core — unit tests per feature axis, normalisation and metric, the index and search path, the parallel-versus-sequential parity, property tests over histories and the command envelope, and the operating-mode check (a label sent before index and one sent after yield the same match report; re-indexing keeps it). The golden fixtures in golden/ are the anchor: the same (spec, history, current) triple must match to the same report bytes here as in every binding.
• Every binding asserts the same golden bytes and the same operating-mode equivalence. That is the whole cross-language claim, so it is checked the same way in each one rather than approximated per language: Python with pytest (and a plain runner on 3.9), Node with node --test, WASM through the nodejs build, C and C++ through ctest, C# with dotnet test, Go with go test, Java with JUnit, and R with the shipped tests/smoke.R plus the repository's run_tests.R.
• Examples — every example under examples/ runs in CI and is held to the version and the matches it prints.
• Fuzz — fuzz/ holds libFuzzer targets over spec parsing, metric normalisation, the index build and the match; CI runs each for a short smoke.

Requirements

• Rust 1.86+ — the workspace MSRV; the Node binding needs Rust 1.88.
• Python 3.9+ — the Python binding.
• Node 22+ — the Node binding.
• Go 1.23+ — the Go binding.
• Java 22+ — the Java binding.
• R 4.1+ — the R package.
• .NET 8+ — the C# binding.
• A C11 / C++17 compiler with CMake 3.15+ for the C and C++ examples.

See each bindings/<lang>/README.md for the per-language build and install.

Benchmarks

crates/shazam-bench measures build_index scaling by history length and feature count, and match_index by index size and metric (cosine / euclid / dtw), parallel vs sequential. See BENCHMARKS.md.

Ecosystem

Part of the Wickra family — each one a data-driven core with a CLI and the same ten-language binding surface:

• wickra — main library (Rust core + Python / Node.js / WASM bindings + a C ABI for C / C++ / C# / Go / Java / R)
• wickra-playground — a polyglot strategy playground: one StrategySpec live side by side in Python, Rust, JS and Go, entirely in the browser
• wickra-exchange — unified market-data + execution across ten crypto exchanges
• wickra-backtest — event-driven backtester over the Wickra core
• wickra-terminal — the trading terminal: a TUI and a browser renderer over the stack
• wickra-screener — parallel multi-symbol screening over 514 streaming indicators
• wickra-xray — market-microstructure explorer: footprint, order-book heatmap, liquidation map, funding/OI divergence
• wickra-radar — perp-universe alert radar: OI delta, funding flip, book imbalance, liquidation clusters, OI/price divergence
• wickra-copilot — local market copilot grounded in real order-book, liquidation and funding microstructure
• wickra-benchmark — reproducible, golden-verified benchmark suite — recompute any (strategy, dataset, report) in ten languages and confirm it byte-for-byte
• wickra-strategy-ci — Jest for trading strategies: golden-pin the report, catch regressions in CI, property-test against fuzzed data
• wickra-verify — confirm or refute a claimed backtest report against its strategy and data, in ten languages
• wickra-proof — Proof-of-Backtest: deterministic (spec, data) → report + blake3 hash, recomputable byte-for-byte in ten languages
• wickra-zk — prove a backtest zero-knowledge — on-chain-verifiable performance without revealing the data or the strategy
• wickra-impact — the backtester that knows you would have moved the market: agent-based fills on the real historical L2 order book
• wickra-darwin — evolutionary strategy search at millions of backtests per second, mutating and crossing JSON specs across the 514-indicator space
• wickra-gym — a Gymnasium-compatible, microstructure-aware backtest environment with O(1) steps for deterministic RL rollouts
• wickra-feature-store — OHLCV and microstructure streams into ML-ready feature matrices over 514 O(1) streaming indicators
• wickra-genome — a vector database of the whole market: every asset a 514-dim live vector, for similarity search, clustering and anomaly detection
• wickra-timemachine — scrub the whole market like a video — every symbol, full order book, rewound to any moment via deterministic re-fold
• wickra-synth — deterministic synthetic market microstructure: OHLCV, order book, trades and funding from a single seed
• wickra-compile — compile a strategy spec into a standalone deployable: a WASM module, a self-contained binary, or a no_std artifact
• wickra-embed — allocation-free, no_std streaming indicators for bare-metal and HFT, byte-for-byte identical to the core
• wickra-pico — the O(1) indicator core running bare-metal on a $5 Raspberry Pi Pico — the LED blinks on the EMA cross

Docs at docs.wickra.org; the marketing site and in-browser demo at wickra.org.

Contributing

See CONTRIBUTING.md and CODE_OF_CONDUCT.md. Commits are signed and in English; open a PR against main.

Security

See SECURITY.md and THREAT_MODEL.md. Report vulnerabilities privately — never in a public issue.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option. Use it, fork it, modify it, redistribute it — commercially or not — file issues, send pull requests; all welcome.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Disclaimer

Wickra Shazam is analysis software: it computes similarity between market states. A historical match is a statistical resemblance, not a prediction and not financial advice — the past setup did not have to repeat, and neither does this one. It places no orders. Trading carries risk of loss; review the code and use at your own discretion.

---

Built on Wickra. If it saved you time, the cheapest way to say thanks is to ⭐ the repo.