Metadata-Version: 2.4
Name: wickra-synth
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
Classifier: Topic :: Scientific/Engineering
Requires-Dist: pytest>=7 ; extra == 'test'
Provides-Extra: test
License-File: LICENSE-APACHE
License-File: LICENSE-MIT
Summary: Deterministic synthetic market microstructure (OHLCV, order book, trades, funding) from a seed, byte-identical across languages.
Keywords: trading,synthetic,microstructure,simulation,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-synth
Project-URL: Issues, https://github.com/wickra-lib/wickra-synth/issues
Project-URL: Repository, https://github.com/wickra-lib/wickra-synth

<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 Synth — deterministic synthetic market microstructure: OHLCV, order book, trades and funding from a single seed, byte-identical across ten languages" width="100%"></a>
</p>

[![Built on Wickra](https://img.shields.io/badge/built%20on-wickra-3b82f6)](https://github.com/wickra-lib/wickra)
[![Status](https://img.shields.io/badge/status-pre--release-orange)](https://github.com/wickra-lib/wickra-synth)
[![CI](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-synth/ci.svg)](https://github.com/wickra-lib/wickra-synth/actions/workflows/ci.yml)
[![CodeQL](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-synth/codeql.svg)](https://github.com/wickra-lib/wickra-synth/actions/workflows/codeql.yml)
[![codecov](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-synth/codecov.svg)](https://codecov.io/gh/wickra-lib/wickra-synth)
[![GitHub release](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-synth/release.svg)](https://github.com/wickra-lib/wickra-synth/releases/latest)
[![crates.io](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-synth/crates.svg)](https://crates.io/crates/wickra-synth)
[![PyPI](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-synth/pypi.svg)](https://pypi.org/project/wickra-synth/)
[![npm](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-synth/npm.svg)](https://www.npmjs.com/package/wickra-synth)
[![NuGet](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-synth/nuget.svg)](https://www.nuget.org/packages/Wickra.Synth)
[![Maven Central](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-synth/maven.svg)](https://central.sonatype.com/artifact/org.wickra/wickra-synth)
[![Go module](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-synth/go.svg)](https://pkg.go.dev/github.com/wickra-lib/wickra-synth-go)
[![R-universe](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-synth/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-synth/license.svg)](#license)
[![OpenSSF Scorecard](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-synth/scorecard.svg)](https://scorecard.dev/viewer/?uri=github.com/wickra-lib/wickra-synth)
[![OpenSSF Best Practices](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-synth/best-practices.svg)](https://www.bestpractices.dev)
[![Build provenance](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-synth/provenance.svg)](https://github.com/wickra-lib/wickra-synth/attestations)
[![Docs](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-synth/docs.svg)](https://synth.wickra.org)
[![Verified across 10 languages](https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-synth/verified.svg)](golden/)

---

**Deterministic synthetic market microstructure — OHLCV, order book, trades and funding from a single seed, byte-identical across ten languages.**

> **▶ 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 Synth is one data-driven core, `wickra-synth-core`: a serde **`GenSpec`**
describes a market regime, a fixed **portable PRNG** (SplitMix64 seeding
xoshiro256++) drives it, and the core emits **OHLCV candles** plus **order-book
snapshots**, **trades** and **funding samples** — realistic synthetic
microstructure for tests, training and demos. Because the RNG lives **only in
the Rust core** and is portable-deterministic, a given seed yields the
**byte-for-byte identical** stream on every platform and through every language
binding. The output mirrors the JSON shapes of the rest of the ecosystem, so it
drops straight into backtests, screeners and RL environments.

Because the spec is **data, not code**, the exact same generation crosses the C
ABI and WASM unchanged. The core is exposed as a **JSON-over-C-ABI data API**
(`Synth::command_json`) in **Rust, Python, Node.js, WASM, C, C++, C#, Go, Java
and R**, so a developer in any language draws the same synthetic market.

## Status

**0.1.3 — the current release.** The core, the reference CLI, the ten-language
binding surface, the golden corpus and the full CI matrix are in place; the
generation model and command protocol are pinned by golden tests.

## Documentation

- [ARCHITECTURE.md](docs/ARCHITECTURE.md) — workspace layout and the
  core-only-randomness design.
- [GENSPEC.md](docs/GENSPEC.md) — the input specification, its fields and every
  validation rule.
- [PROTOCOL.md](docs/PROTOCOL.md) — the `command_json` boundary all ten
  bindings forward to.
- [REGIMES.md](docs/REGIMES.md) — the trend / range / crash / vol price-path formulas.
- [MICROSTRUCTURE.md](docs/MICROSTRUCTURE.md) — order book, trades and funding.
- [DETERMINISM.md](docs/DETERMINISM.md) — the PRNG and the fixed draw-order contract.
- [Cookbook.md](docs/Cookbook.md) — practical recipes.

## Quickstart

```bash
cargo install wickra-synth
wickra-synth --seed 42 --bars 20 --format json
```

Twenty bars of OHLCV, an order book, trades and funding, from nothing but the
number 42 — and the same twenty bars on every platform and in every one of
the ten languages below. The spec that shaped them is JSON, so the same seed
and spec reproduce the same market from any binding.

## Use in any language

Every binding forwards the same `command_json` string to the Rust core, so all
ten draw **byte-identical** synthetic markets for a given seed.

```python
from wickra_synth import Synth
import json

synth = Synth('{"seed":42,"bars":20,"start_price":100.0,'
              '"regimes":[{"kind":"trend","len":20,"drift":0.002,"vol":0.01}],'
              '"microstructure":{"book_depth":5,"spread_bps":4.0,"trade_rate":8.0}}')
out = json.loads(synth.command('{"cmd":"generate"}'))
print(len(out["candles"]))  # 20
```

Runnable examples for all ten languages — each printing the same first three
candles — live in [`examples/`](examples/).

## Project layout

```
crates/synth-core     the engine: GenSpec, the PRNG, the walk, the microstructure
crates/synth-cli      wickra-synth, the reference consumer
crates/synth-bench    criterion benchmarks
bindings/c            the C ABI hub (cdylib + staticlib) plus the C++ hull
bindings/python       PyO3 / maturin, abi3-py39
bindings/node         napi-rs, per-platform npm packages
bindings/wasm         wasm-bindgen
bindings/csharp       P/Invoke over the hub
bindings/go           cgo over the hub
bindings/java         Foreign Function & Memory API over the hub
bindings/r            .Call glue over the hub
golden/               specs + blessed outputs, the cross-language contract
examples/             one runnable example per language
fuzz/                 cargo-fuzz targets for parse, generate, PRNG and FFI
docs/                 the deep dives; see docs/README.md
```

Six of the ten reaches go through one C ABI (`bindings/c`), which is why there
is exactly one place a marshalling bug can live rather than six.

## Building everything from source

The core and the CLI need only cargo:

```bash
cargo build --workspace
cargo test  --workspace
```

The bindings each need their own toolchain, and the six that go through the C
ABI need it built first:

```bash
cargo build --release -p wickra-synth-c          # the hub the six link against

cd bindings/python && maturin develop --release  # Python
cd bindings/node   && npm install && npx napi build --platform --release
cd bindings/wasm   && wasm-pack build --target nodejs
dotnet build bindings/csharp/WickraSynth -c Release
mvn -f bindings/java package
R CMD INSTALL bindings/r                         # WKSYNTH_INC/WKSYNTH_LIB, see below
cmake -S examples/c -B examples/c/build && cmake --build examples/c/build
```

The R binding downloads a matching prebuilt C ABI by default. To build it
against the one in your tree instead, set `WKSYNTH_INC` to
`bindings/c/include` and `WKSYNTH_LIB` to `target/release`.

## Testing

```bash
cargo test --workspace --all-features
cargo test --workspace --no-default-features
```

Beyond the unit tests, four suites are worth knowing about:

- **Golden** — every binding replays `golden/specs` and must reproduce
  `golden/expected` byte for byte. That is the cross-language guarantee, and it
  is checked in all ten reaches, not asserted in the README.
- **RNG vectors** — fixed SplitMix64 and xoshiro256++ reference values. If
  these move, every seed in the world moves with them.
- **Stream equals batch** — the reassembled event stream equals the batch
  output, so the two paths cannot drift apart.
- **Property tests** — random specs stay finite and well formed, and the same
  seed gives the same bytes.

Per-binding commands are in [CONTRIBUTING.md](CONTRIBUTING.md); the
`scripts/check_*.py` family holds the version, licence, link and binding-surface
invariants that no compiler checks.

## Requirements

The core needs nothing but a Rust toolchain — no system libraries, no BLAS, no
Python at build time. Each binding adds only its own runtime:

| Reach | Floor | Where it is declared |
|-------|-------|----------------------|
| Rust (workspace) | 1.86 | `Cargo.toml`, `rust-version` |
| Rust (Node binding build) | 1.88 | `bindings/node/Cargo.toml` — napi-build needs it |
| Python | 3.9 | `bindings/python/pyproject.toml`, `requires-python` (abi3) |
| Node.js | 22 | `bindings/node/package.json`, `engines.node` |
| .NET | 8.0 | `bindings/csharp/WickraSynth/WickraSynth.csproj` |
| Go | 1.23 | `bindings/go/go.mod` |
| Java | 22 | `bindings/java/pom.xml` — the Foreign Function & Memory API |
| R | 4.1 | `bindings/r/DESCRIPTION`, `Depends` |

`scripts/check_version_sync.py` holds these numbers against the manifests, so a
floor that moves in one place and not the other is a failing check rather than a
support question.

## Benchmarks

Per-generation throughput is tracked in [BENCHMARKS.md](BENCHMARKS.md) and
measured by the `synth-bench` crate (`cargo bench -p synth-bench`). A shallow
book with light trade flow generates roughly 4.3 million candles per second; the
microstructure, not the price walk, is what the time goes on.

## Ecosystem

Wickra Synth is one repository in a family that shares a core and a
ten-language binding surface:

- [**wickra**](https://github.com/wickra-lib/wickra) — 514 streaming
  indicators, the core everything else is built on.
- [**wickra-backtest**](https://github.com/wickra-lib/wickra-backtest) — a
  streaming-native backtester where backtest and live are the same code path.
- [**wickra-screener**](https://github.com/wickra-lib/wickra-screener) — scan
  thousands of symbols against data-driven conditions.
- [**wickra-exchange**](https://github.com/wickra-lib/wickra-exchange) — one
  typed API over the ten largest crypto exchanges.
- [**wickra-terminal**](https://github.com/wickra-lib/wickra-terminal) — a
  streaming trading terminal over the same core.

Synth is the one that needs no market data at all: it is where the others get a
reproducible market to test against. The full list is at
[github.com/wickra-lib](https://github.com/wickra-lib).

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).

## Security

See [SECURITY.md](SECURITY.md) and [THREAT_MODEL.md](THREAT_MODEL.md). Note the
PRNG is a fast non-cryptographic generator for reproducible simulation — it is
**not** suitable for any security or cryptographic purpose.

## 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-synth` generates **synthetic** market data for testing, training and
demonstration. It is not real market data and is not financial advice; it comes
with no warranty.

---

<p align="center">
  <a href="https://github.com/wickra-lib/wickra-synth">
    <img alt="GitHub stars" src="https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-synth/stars.svg">
  </a>
  <a href="https://github.com/wickra-lib/wickra-synth/network/members">
    <img alt="GitHub forks" src="https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-synth/forks.svg">
  </a>
  <a href="https://github.com/wickra-lib/wickra-synth/issues">
    <img alt="GitHub issues" src="https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-synth/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-synth star history" width="640"
       src="https://raw.githubusercontent.com/wickra-lib/.github/main/profile/badges/wickra-synth/star-history.svg">
</p>

