Metadata-Version: 2.4
Name: wickra-shazam
Version: 0.1.3
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Rust
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Dist: pytest>=7 ; extra == 'test'
Provides-Extra: test
License-File: LICENSE-APACHE
License-File: LICENSE-MIT
Summary: The data-driven history-fingerprint match core: build a Shazam from a spec, index an asset's history, match the current fingerprint against it.
Keywords: trading,fingerprint,similarity,pattern-matching,finance
Home-Page: https://wickra.org
Author-email: kingchenc <support@wickra.org>
License-Expression: MIT OR Apache-2.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/wickra-lib/wickra-shazam
Project-URL: Issues, https://github.com/wickra-lib/wickra-shazam/issues
Project-URL: Repository, https://github.com/wickra-lib/wickra-shazam

<p align="center">
  <a href="https://wickra.org"><img src="https://raw.githubusercontent.com/wickra-lib/.github/main/profile/wickra-banner.webp?v=514-7" alt="Wickra Shazam — match an asset's current microstructure fingerprint against its entire history" width="100%"></a>
</p>

[![Built on Wickra](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-shazam/built-on.svg)](https://github.com/wickra-lib/wickra)
[![Status](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-shazam/status.svg)](https://github.com/wickra-lib/wickra-shazam)
[![CI](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-shazam/ci.svg)](https://github.com/wickra-lib/wickra-shazam/actions/workflows/ci.yml)
[![CodeQL](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-shazam/codeql.svg)](https://github.com/wickra-lib/wickra-shazam/actions/workflows/codeql.yml)
[![codecov](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-shazam/codecov.svg)](https://codecov.io/gh/wickra-lib/wickra-shazam)
[![GitHub release](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-shazam/release.svg)](https://github.com/wickra-lib/wickra-shazam/releases/latest)
[![crates.io](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-shazam/crates.svg)](https://crates.io/crates/wickra-shazam)
[![PyPI](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-shazam/pypi.svg)](https://pypi.org/project/wickra-shazam/)
[![npm](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-shazam/npm.svg)](https://www.npmjs.com/package/wickra-shazam)
[![NuGet](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-shazam/nuget.svg)](https://www.nuget.org/packages/Wickra.Shazam)
[![Maven Central](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-shazam/maven.svg)](https://central.sonatype.com/artifact/org.wickra/wickra-shazam)
[![Go module](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-shazam/go.svg)](https://pkg.go.dev/github.com/wickra-lib/wickra-shazam-go)
[![R-universe](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-shazam/r-universe.svg)](https://wickra-lib.r-universe.dev)
[![License: MIT OR Apache-2.0](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-shazam/license.svg)](#license)
[![OpenSSF Scorecard](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-shazam/scorecard.svg)](https://scorecard.dev/viewer/?uri=github.com/wickra-lib/wickra-shazam)
[![OpenSSF Best Practices](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-shazam/best-practices.svg)](https://www.bestpractices.dev)
[![Build provenance](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-shazam/provenance.svg)](https://github.com/wickra-lib/wickra-shazam/attestations)
[![Docs](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-shazam/docs.svg)](https://shazam.wickra.org)
[![Verified across 10 languages](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-shazam/verified.svg)](golden/)
[![Live demo](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-shazam/live-demo.svg)](https://live.wickra.org)

---

**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](https://backtest-live.wickra.org)**;
> one StrategySpec side by side in Python, Rust, JS and Go — **[playground.wickra.org](https://playground.wickra.org)**;
> all 514 indicators of the core over a real Binance feed — **[live.wickra.org](https://live.wickra.org)**. Zero backend, all of them.

**Part of the [Wickra ecosystem](#ecosystem):** the same data-driven core and ten-language binding surface also power [wickra-exchange](https://github.com/wickra-lib/wickra-exchange), [wickra-backtest](https://github.com/wickra-lib/wickra-backtest), [wickra-terminal](https://github.com/wickra-lib/wickra-terminal) and 20 more — see [the full list](https://github.com/wickra-lib).

Wickra Shazam turns an asset's **whole history** into a rolling index of
fixed-dimension **microstructure fingerprints** — a vector built from the full
[Wickra](https://github.com/wickra-lib/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`](crates/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.

```bash
# 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](ROADMAP.md).

## Documentation

- [Architecture](ARCHITECTURE.md) — the core, the data-driven boundary, the binding surface.
- Guides under [`docs/`](docs): [Fingerprints & FingerprintSpec](docs/FINGERPRINTS.md) · [Features](docs/FEATURES.md) · [Similarity & metrics](docs/SIMILARITY.md) · [Labels](docs/LABELS.md) · [Cookbook](docs/Cookbook.md) · [Internals](docs/ARCHITECTURE.md).
- [ROADMAP.md](ROADMAP.md) · [BENCHMARKS.md](BENCHMARKS.md) · [THREAT_MODEL.md](THREAT_MODEL.md) · [SECURITY.md](SECURITY.md).

## Quickstart

```bash
# 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.

```json
{
  "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:

```jsonc
{ "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`.

```python
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`](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/`](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

```bash
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](#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](BENCHMARKS.md).

## Ecosystem

Part of the [Wickra](https://github.com/wickra-lib/wickra) family — each one a
data-driven core with a CLI and the same ten-language binding surface:

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

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
Commits are signed and in English; open a PR against `main`.

## Security

See [SECURITY.md](SECURITY.md) and [THREAT_MODEL.md](THREAT_MODEL.md). Report
vulnerabilities privately — never in a public issue.

## License

Licensed under either of

- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
  <http://www.apache.org/licenses/LICENSE-2.0>)
- MIT license ([LICENSE-MIT](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.

---

<p align="center">
  <a href="https://github.com/wickra-lib/wickra-shazam">
    <img alt="GitHub stars" src="https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-shazam/stars.svg">
  </a>
  <a href="https://github.com/wickra-lib/wickra-shazam/network/members">
    <img alt="GitHub forks" src="https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-shazam/forks.svg">
  </a>
  <a href="https://github.com/wickra-lib/wickra-shazam/issues">
    <img alt="GitHub issues" src="https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-shazam/issues.svg">
  </a>
</p>

<p align="center">
  Built on <a href="https://github.com/wickra-lib/wickra">Wickra</a>. If it saved you time, the cheapest way to say thanks is to ⭐ the repo.
</p>

<p align="center">
  <img alt="wickra-shazam star history" width="640"
       src="https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-shazam/star-history.svg">
</p>

