Skip to main content

Wickra Shazam — match an asset's current microstructure fingerprint against its entire history

Built on Wickra Status CI CodeQL codecov GitHub release crates.io PyPI npm NuGet Maven Central Go module R-universe License: MIT OR Apache-2.0 OpenSSF Scorecard OpenSSF Best Practices Build provenance Docs Verified across 10 languages Live demo


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.2.1 — 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

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.87+ — 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 495 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 495-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 495 O(1) streaming indicators
  • wickra-genome — a vector database of the whole market: every asset a 495-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

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.


GitHub stars GitHub forks GitHub issues

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

wickra-shazam star history

Metadata

Release files for wickra-shazam 0.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for wickra-shazam 0.2.1
File Size Uploaded Provenance Actions
wickra_shazam-0.2.1.tar.gz 83.2 kB Without provenance Details for wickra_shazam-0.2.1.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for wickra-shazam 0.2.1
File Actions
wickra_shazam-0.2.1-cp39-abi3-win_arm64.whl CPython 3.9 abi3 Windows ARM64 Details for wickra_shazam-0.2.1-cp39-abi3-win_arm64.whl
wickra_shazam-0.2.1-cp39-abi3-win_amd64.whl CPython 3.9 abi3 Windows x86-64 Details for wickra_shazam-0.2.1-cp39-abi3-win_amd64.whl
wickra_shazam-0.2.1-cp39-abi3-musllinux_1_2_x86_64.whl CPython 3.9 abi3 Linux musl 1.2+ x86-64 Details for wickra_shazam-0.2.1-cp39-abi3-musllinux_1_2_x86_64.whl
wickra_shazam-0.2.1-cp39-abi3-musllinux_1_2_aarch64.whl CPython 3.9 abi3 Linux musl 1.2+ ARM64 Details for wickra_shazam-0.2.1-cp39-abi3-musllinux_1_2_aarch64.whl
wickra_shazam-0.2.1-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl CPython 3.9 abi3 Linux glibc 2.17+ x86-64 Details for wickra_shazam-0.2.1-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
wickra_shazam-0.2.1-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl CPython 3.9 abi3 Linux glibc 2.17+ ARM64 Details for wickra_shazam-0.2.1-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
wickra_shazam-0.2.1-cp39-abi3-macosx_11_0_arm64.whl CPython 3.9 abi3 macOS 11.0+ ARM64 Details for wickra_shazam-0.2.1-cp39-abi3-macosx_11_0_arm64.whl
wickra_shazam-0.2.1-cp39-abi3-macosx_10_12_x86_64.whl CPython 3.9 abi3 macOS 10.12+ x86-64 Details for wickra_shazam-0.2.1-cp39-abi3-macosx_10_12_x86_64.whl

Total release size: 5.6 MB

Release files / wickra_shazam-0.2.1.tar.gz

Download URL wickra_shazam-0.2.1.tar.gz
Size 83.2 kB
Tags Source
SHA-256 checksum
How to use checksums
95815360b7a6a373b2bca289a25741823fe449d2cdf23abc7b778e55e1bb4073
BLAKE2b-256 checksum
How to use checksums
09d73f47ed36105f95f7a18860e5c2cf0264616398b11786fd842865276e8946
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.15.0

Release files / wickra_shazam-0.2.1-cp39-abi3-win_arm64.whl

Download URL wickra_shazam-0.2.1-cp39-abi3-win_arm64.whl
Size 525.5 kB
Tags CPython 3.9 Windows ARM64 abi3
SHA-256 checksum
How to use checksums
30233c3c4c2d9822881308a397b5a3961f74670ceaf64b5cac69c46b3d4956ca
BLAKE2b-256 checksum
How to use checksums
f952cba73d62a8e4344e0358a032aec01c1633f26f45c0d8b55521bc7d2c779d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.15.0

Release files / wickra_shazam-0.2.1-cp39-abi3-win_amd64.whl

Download URL wickra_shazam-0.2.1-cp39-abi3-win_amd64.whl
Size 602.1 kB
Tags CPython 3.9 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
b2b714ee7032a123b5250bf956661f185a9b577eeed1455ac0ffd83cfa5001c7
BLAKE2b-256 checksum
How to use checksums
dcdf1ae776810ed42f384b5691cf0f6a7cb34b8be354bd4a0d46b7fbe7ad9129
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.15.0

Release files / wickra_shazam-0.2.1-cp39-abi3-musllinux_1_2_x86_64.whl

Download URL wickra_shazam-0.2.1-cp39-abi3-musllinux_1_2_x86_64.whl
Size 942.2 kB
Tags CPython 3.9 Linux musl 1.2+ x86-64 abi3
SHA-256 checksum
How to use checksums
8447bc2260f275466deccc0e6c05cd0c0ee8a78b86fc5d0a429e3d0eda6b0ebe
BLAKE2b-256 checksum
How to use checksums
0d9883e8d9dca475469cfec1c46098bb42d7bd71752692e6ea8730df64ee86d6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.15.0

Release files / wickra_shazam-0.2.1-cp39-abi3-musllinux_1_2_aarch64.whl

Download URL wickra_shazam-0.2.1-cp39-abi3-musllinux_1_2_aarch64.whl
Size 830.9 kB
Tags CPython 3.9 Linux musl 1.2+ ARM64 abi3
SHA-256 checksum
How to use checksums
44eec1d1900e3d3e0ccc84c554f33c60b2193686802cdaabf0c51af3fc65aba4
BLAKE2b-256 checksum
How to use checksums
c15e412f1a292c9d368093f0bf1d69a46f8b9516343ebcd40b25db2c24295027
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.15.0

Release files / wickra_shazam-0.2.1-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL wickra_shazam-0.2.1-cp39-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 725.1 kB
Tags CPython 3.9 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
42197b814bc81ef2d0199698159bb28e8cb8fade183a21499ac2514bc850a93a
BLAKE2b-256 checksum
How to use checksums
1feddaaaf8c81894022792ebcdd8279a27c54f29e1b1dea2a8d6e7f76f768353
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.15.0

Release files / wickra_shazam-0.2.1-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL wickra_shazam-0.2.1-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Size 652.6 kB
Tags CPython 3.9 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
9065c45a00af0ac90d927dac7179c9e8b188d40975e05297ca343978d276f344
BLAKE2b-256 checksum
How to use checksums
2ea8afc89330484dd302428f6c682eff64acdf2e6f9c2104f8bdb2869a1fff6d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.15.0

Release files / wickra_shazam-0.2.1-cp39-abi3-macosx_11_0_arm64.whl

Download URL wickra_shazam-0.2.1-cp39-abi3-macosx_11_0_arm64.whl
Size 586.2 kB
Tags CPython 3.9 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
505da3874fdf9fb582c6c16d9fc0b50b0614899d50d66ee7a8926d232f7be691
BLAKE2b-256 checksum
How to use checksums
49ca6ca7340871a3882f8abc36922d03130105a0a6354efdf4a482c1eb396bb8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.15.0

Release files / wickra_shazam-0.2.1-cp39-abi3-macosx_10_12_x86_64.whl

Download URL wickra_shazam-0.2.1-cp39-abi3-macosx_10_12_x86_64.whl
Size 683.9 kB
Tags CPython 3.9 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
a21c92002ef6c54cc3c7477368d6db20a11ea1b4f4a07108b2b41d73a52cdf52
BLAKE2b-256 checksum
How to use checksums
7a14be4e0076dd83656a5d8b679aaa3b4b8aba7176d5b15e425c4b3719b23c73
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via maturin/1.15.0

Security for wickra-shazam 0.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page