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 dimensionNis 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 thekmost 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
- 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 byname+params(Rsi,Sma,Atr,Macd, …), with an optionalfieldto 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 withz_scorenormalization.euclid—1 / (1 + d)wheredis the L2 distance. Scale-sensitive; pair withmin_maxorz_scoreto weight features evenly.dtw— dynamic time warping over the per-bar feature vectors of awindow > 1spec, tolerant of small time shifts between two shapes. Withwindow == 1it is identical toeuclid.
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 beforeindexand one sent after yield the samematchreport; re-indexing keeps it). The golden fixtures ingolden/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++ throughctest, C# withdotnet test, Go withgo test, Java with JUnit, and R with the shippedtests/smoke.Rplus the repository'srun_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_stdartifact - wickra-embed — allocation-free,
no_stdstreaming 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.
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)
| 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)
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.